audio.v1: azul3d.org/audio.v1 Index | Files

package audio

import "azul3d.org/audio.v1"

Package audio implements various audio types and interfaces.

This package aims to be like the 'image' package, except for audio.

Index

Package Files

alaw.go audio.go buffer.go doc.go float.go format.go io.go mulaw.go pcm.go slice.go

Variables

var EOS = errors.New("end of stream")

EOS is the error returned by Read when no more input is available. Functions should return EOS only to signal a graceful end of input. If the EOS occurs unexpectedly in a structured data stream, the appropriate error is either ErrUnexpectedEOS or some other error giving more detail.

var ErrFormat = errors.New("audio: unknown format")

ErrFormat specifies an error where the format of the audio data is unknown of by the registered formats of this package.

var ErrInvalidData = errors.New("audio: input data is invalid or corrupt")

ErrInvalidData represents an error for decoding input data that is invalidd or corrupted for some reason.

var ErrShortWrite = errors.New("short write")

ErrShortWrite means that a write accepted fewer bytes than requested but failed to return an explicit error.

var ErrUnexpectedEOS = errors.New("unexpected end of stream")

ErrUnexpectedEOS means that EOS was encountered in the middle of reading a fixed-size block or data structure.

func Copy Uses

func Copy(dst Writer, src Reader) (written int64, err error)

Copy copies from src to dst until either EOS is reached on src or an error occurs. It returns the number of samples copied and the first error encountered while copying, if any.

A successful Copy returns err == nil, not err == EOS. Because Copy is defined to read from src until EOS, it does not treat an EOS from Read as an error to be reported.

If src implements the WriterTo interface, the copy is implemented by calling src.WriteTo(dst). Otherwise, if dst implements the ReaderFrom interface, the copy is implemented by calling dst.ReadFrom(src).

func RegisterFormat Uses

func RegisterFormat(name, magic string, newDecoder func(r interface{}) (Decoder, error))

RegisterFormat registers an image format for use by NewDecoder().

Name is the name of the format, like "wav" or "ogg".

Magic is the magic prefix that identifies the format's encoding. The magic string can contain "?" wildcards that each match any one byte.

newDecoder is the function that returns either [Decoder, nil] or [nil, ErrInvalidData] upon being called where the returned decoder is used to decode the io.Reader or io.ReadSeeker's encoded audio data.

type ALaw Uses

type ALaw uint8

ALaw represents an uint8 alaw encoded audio sample.

func PCM16ToALaw Uses

func PCM16ToALaw(s PCM16) ALaw

PCM16ToALaw converts an PCM16 encoded audio sample to an ALaw encoded audio sample.

type ALawSamples Uses

type ALawSamples []ALaw

ALawSamples represents an slice of ALaw encoded audio samples.

func (ALawSamples) At Uses

func (p ALawSamples) At(i int) F64

Implements Slice interface.

func (ALawSamples) Cap Uses

func (p ALawSamples) Cap() int

Implements Slice interface.

func (ALawSamples) CopyTo Uses

func (p ALawSamples) CopyTo(dst Slice) int

Implements Slice interface.

func (ALawSamples) Len Uses

func (p ALawSamples) Len() int

Implements Slice interface.

func (ALawSamples) Make Uses

func (p ALawSamples) Make(length, capacity int) Slice

Implements Slice interface.

func (ALawSamples) Set Uses

func (p ALawSamples) Set(i int, s F64)

Implements Slice interface.

func (ALawSamples) Slice Uses

func (p ALawSamples) Slice(low, high int) Slice

Implements Slice interface.

type Buffer Uses

type Buffer struct {
    // contains filtered or unexported fields
}

A Buffer is a variable-sized buffer of audio samples with Read and Write methods. Buffers must be allocated via the NewBuffer function.

func NewBuffer Uses

func NewBuffer(buf Slice) *Buffer

NewBuffer creates and initializes a new Buffer using buf as its initial contents. The buffer will internally use the given slice, buf, which also defines the sample storage type. NewBuffer is intended to prepare a Buffer to read existing data. It can also be used to size the internal buffer for writing. To do that, buf should have the desired capacity but a length of zero.

func (*Buffer) Grow Uses

func (b *Buffer) Grow(n int)

Grow grows the buffer's capacity, if necessary, to guarantee space for another n samples. After Grow(n), at least n samples can be written to the buffer without another allocation. If n is negative, Grow will panic.

func (*Buffer) Len Uses

func (b *Buffer) Len() int

Len returns the number of samples of the unread portion of the buffer; b.Len() == b.Samples().Len().

func (*Buffer) Next Uses

func (b *Buffer) Next(n int) Slice

Next returns a slice containing the next n samples from the buffer, advancing the buffer as if the samples had been returned by Read. If there are fewer than n samples in the buffer, Next returns the entire buffer. The slice is only valid until the next call to a read or write method.

func (*Buffer) Read Uses

func (b *Buffer) Read(p Slice) (n int, err error)

Read reads the next p.Len() samples from the buffer or until the buffer is drained. The return value n is the number of samples read. If the buffer has no data to return, err is EOS (unless len(p) is zero); otherwise it is nil.

func (*Buffer) ReadFrom Uses

func (b *Buffer) ReadFrom(r Reader) (n int64, err error)

ReadFrom reads data from r until EOS and appends it to the buffer, growing the buffer as needed. The return value n is the number of samples read. Any error except EOS encountered during the read is also returned.

func (*Buffer) ReadSample Uses

func (b *Buffer) ReadSample() (c F64, err error)

ReadSample reads and returns the next sample from the buffer. If no sample is available, it returns error EOS.

func (*Buffer) Reset Uses

func (b *Buffer) Reset()

Reset resets the buffer so it has no content. b.Reset() is the same as b.Truncate(0).

func (*Buffer) Samples Uses

func (b *Buffer) Samples() Slice

Samples returns a slice of the unread portion of the buffer. If the caller changes the contents of the returned slice, the contents of the buffer will change provided there are no intervening method calls on the Buffer.

func (*Buffer) Seek Uses

func (b *Buffer) Seek(offset uint64) error

Seek seeks to the specified sample number, relative to the start of the stream. As such, subsequent Read() calls on the Buffer, begin reading at the specified sample.

If offset > b.Len(), then the offset is unchanged and the seek operation fails returning error == EOS.

func (*Buffer) Truncate Uses

func (b *Buffer) Truncate(n int)

Truncate discards all but the first n unread samples from the buffer. It panics if n is negative or greater than the length of the buffer.

func (*Buffer) Write Uses

func (b *Buffer) Write(p Slice) (n int, err error)

Write appends the contents of p to the buffer, growing the buffer as needed. The return value n is the length of p; err is always nil.

func (*Buffer) WriteSample Uses

func (b *Buffer) WriteSample(c F64)

WriteSample appends the sample c to the buffer, growing the buffer as needed.

func (*Buffer) WriteTo Uses

func (b *Buffer) WriteTo(w Writer) (n int64, err error)

WriteTo writes data to w until the buffer is drained or an error occurs. The return value n is the number of samples written; it always fits into an int, but it is int64 to match the WriterTo interface. Any error encountered during the write is also returned.

type Config Uses

type Config struct {
    // SampleRate is the number of audio samples that the stream is played or
    // recorded at.
    //
    // E.g. 44100 would be compact disc quality.
    SampleRate int

    // Channels is the number of channels the stream contains.
    Channels int
}

Config represents an audio stream's configuration, like its sample rate and number of interleaved channels.

func (Config) String Uses

func (c Config) String() string

String returns an string representation of this audio config.

type Decoder Uses

type Decoder interface {
    ReadSeeker

    // Config returns the audio stream configuration of this decoder. It may
    // block until at least the configuration part of the stream has been read.
    Config() Config
}

Decoder is the generic audio decoder interface, for use with the RegisterFormat() function.

func NewDecoder Uses

func NewDecoder(r interface{}) (Decoder, string, error)

NewDecoder returns a decoder which can be used to decode the encoded audio data stored in the io.Reader or io.ReadSeeker, 'r'.

The string returned is the format name used during format registration.

Format registration is typically done by the init method of the codec- specific package.

type Encoder Uses

type Encoder interface {
    Writer

    // Close closes the audio encoder, and finalizes the encoding process.
    // It must be called or else the encoding process may not finish, and
    // the encoded data may be uncomplete.
    //
    // Writing data to a closed encoder causes an encoder-specific behavior
    // but most often a panic will occur.
    Close() error
}

Encoder is the generic audio encoder interface.

type F32 Uses

type F32 float32

F32 represents a 32-bit floating-point linear audio sample in the range of -1 to +1.

type F32Samples Uses

type F32Samples []F32

F32Samples represents a slice of F32 encoded audio samples.

func (F32Samples) At Uses

func (p F32Samples) At(i int) F64

Implements Slice interface.

func (F32Samples) Cap Uses

func (p F32Samples) Cap() int

Implements Slice interface.

func (F32Samples) CopyTo Uses

func (p F32Samples) CopyTo(dst Slice) int

Implements Slice interface.

func (F32Samples) Len Uses

func (p F32Samples) Len() int

Implements Slice interface.

func (F32Samples) Make Uses

func (p F32Samples) Make(length, capacity int) Slice

Implements Slice interface.

func (F32Samples) Set Uses

func (p F32Samples) Set(i int, s F64)

Implements Slice interface.

func (F32Samples) Slice Uses

func (p F32Samples) Slice(low, high int) Slice

Implements Slice interface.

type F64 Uses

type F64 float64

F64 represents a 64-bit floating-point linear audio sample in the range of -1 to +1.

func PCM16ToF64 Uses

func PCM16ToF64(s PCM16) F64

PCM16ToF64 converts a PCM16 encoded audio sample to F64.

func PCM32ToF64 Uses

func PCM32ToF64(s PCM32) F64

PCM32ToF64 converts a PCM32 encoded audio sample to F64.

func PCM8ToF64 Uses

func PCM8ToF64(s PCM8) F64

PCM8ToF64 converts a PCM8 encoded audio sample to F64.

type F64Samples Uses

type F64Samples []F64

F32Samples represents a slice of F32 encoded audio samples.

func (F64Samples) At Uses

func (p F64Samples) At(i int) F64

Implements Slice interface.

func (F64Samples) Cap Uses

func (p F64Samples) Cap() int

Implements Slice interface.

func (F64Samples) CopyTo Uses

func (p F64Samples) CopyTo(dst Slice) int

Implements Slice interface.

func (F64Samples) Len Uses

func (p F64Samples) Len() int

Implements Slice interface.

func (F64Samples) Make Uses

func (p F64Samples) Make(length, capacity int) Slice

Implements Slice interface.

func (F64Samples) Set Uses

func (p F64Samples) Set(i int, s F64)

Implements Slice interface.

func (F64Samples) Slice Uses

func (p F64Samples) Slice(low, high int) Slice

Implements Slice interface.

type MuLaw Uses

type MuLaw uint8

MuLaw represents an uint8 mulaw encoded audio sample.

func PCM16ToMuLaw Uses

func PCM16ToMuLaw(s PCM16) MuLaw

PCM16ToMuLaw converts from a PCM16 encoded audio sample to an MuLaw encoded audio sample.

type MuLawSamples Uses

type MuLawSamples []MuLaw

MuLawSamples represents an slice of MuLaw encoded audio samples.

func (MuLawSamples) At Uses

func (p MuLawSamples) At(i int) F64

Implements Slice interface.

func (MuLawSamples) Cap Uses

func (p MuLawSamples) Cap() int

Implements Slice interface.

func (MuLawSamples) CopyTo Uses

func (p MuLawSamples) CopyTo(dst Slice) int

Implements Slice interface.

func (MuLawSamples) Len Uses

func (p MuLawSamples) Len() int

Implements Slice interface.

func (MuLawSamples) Make Uses

func (p MuLawSamples) Make(length, capacity int) Slice

Implements Slice interface.

func (MuLawSamples) Set Uses

func (p MuLawSamples) Set(i int, s F64)

Implements Slice interface.

func (MuLawSamples) Slice Uses

func (p MuLawSamples) Slice(low, high int) Slice

Implements Slice interface.

type PCM16 Uses

type PCM16 int16

PCM16 represents a signed 16-bit linear PCM audio sample.

func ALawToPCM16 Uses

func ALawToPCM16(s ALaw) PCM16

ALawToPCM16 converts an ALaw encoded audio sample to an PCM16 encoded audio sample.

func F64ToPCM16 Uses

func F64ToPCM16(s F64) PCM16

F64ToPCM16 converts a F64 encoded audio sample to PCM16.

func MuLawToPCM16 Uses

func MuLawToPCM16(s MuLaw) PCM16

MuLawToPCM16 converts from an MuLaw encoded audio sample to an PCM16 encoded audio sample.

type PCM16Samples Uses

type PCM16Samples []PCM16

PCM16Samples represents a slice of PCM16 encoded audio samples.

func (PCM16Samples) At Uses

func (p PCM16Samples) At(i int) F64

Implements Slice interface.

func (PCM16Samples) Cap Uses

func (p PCM16Samples) Cap() int

Implements Slice interface.

func (PCM16Samples) CopyTo Uses

func (p PCM16Samples) CopyTo(dst Slice) int

Implements Slice interface.

func (PCM16Samples) Len Uses

func (p PCM16Samples) Len() int

Implements Slice interface.

func (PCM16Samples) Make Uses

func (p PCM16Samples) Make(length, capacity int) Slice

Implements Slice interface.

func (PCM16Samples) Set Uses

func (p PCM16Samples) Set(i int, s F64)

Implements Slice interface.

func (PCM16Samples) Slice Uses

func (p PCM16Samples) Slice(low, high int) Slice

Implements Slice interface.

type PCM32 Uses

type PCM32 int32

PCM32 represents a signed 32-bit linear PCM audio sample.

func F64ToPCM32 Uses

func F64ToPCM32(s F64) PCM32

F64ToPCM32 converts a F64 encoded audio sample to PCM32.

type PCM32Samples Uses

type PCM32Samples []PCM32

PCM32Samples represents a slice of PCM32 encoded audio samples.

func (PCM32Samples) At Uses

func (p PCM32Samples) At(i int) F64

Implements Slice interface.

func (PCM32Samples) Cap Uses

func (p PCM32Samples) Cap() int

Implements Slice interface.

func (PCM32Samples) CopyTo Uses

func (p PCM32Samples) CopyTo(dst Slice) int

Implements Slice interface.

func (PCM32Samples) Len Uses

func (p PCM32Samples) Len() int

Implements Slice interface.

func (PCM32Samples) Make Uses

func (p PCM32Samples) Make(length, capacity int) Slice

Implements Slice interface.

func (PCM32Samples) Set Uses

func (p PCM32Samples) Set(i int, s F64)

Implements Slice interface.

func (PCM32Samples) Slice Uses

func (p PCM32Samples) Slice(low, high int) Slice

Implements Slice interface.

type PCM8 Uses

type PCM8 uint8

PCM8 represents an unsigned 8-bit linear PCM audio sample.

func F64ToPCM8 Uses

func F64ToPCM8(s F64) PCM8

F64ToPCM8 converts a F64 encoded audio sample to PCM8.

type PCM8Samples Uses

type PCM8Samples []PCM8

PCM6Samples represents a slice of PCM8 encoded audio samples.

func (PCM8Samples) At Uses

func (p PCM8Samples) At(i int) F64

Implements Slice interface.

func (PCM8Samples) Cap Uses

func (p PCM8Samples) Cap() int

Implements Slice interface.

func (PCM8Samples) CopyTo Uses

func (p PCM8Samples) CopyTo(dst Slice) int

Implements Slice interface.

func (PCM8Samples) Len Uses

func (p PCM8Samples) Len() int

Implements Slice interface.

func (PCM8Samples) Make Uses

func (p PCM8Samples) Make(length, capacity int) Slice

Implements Slice interface.

func (PCM8Samples) Set Uses

func (p PCM8Samples) Set(i int, s F64)

Implements Slice interface.

func (PCM8Samples) Slice Uses

func (p PCM8Samples) Slice(low, high int) Slice

Implements Slice interface.

type ReadSeeker Uses

type ReadSeeker interface {
    Reader

    // Seek seeks to the specified sample number, relative to the start of the
    // stream. As such, subsequent Read() calls on the Reader, begin reading at
    // the specified sample.
    //
    // If any error is returned, it means it was impossible to seek to the
    // specified audio sample for some reason, and that the current playhead is
    // unchanged.
    Seek(sample uint64) error
}

ReadSeeker is the generic seekable audio reader interface.

type Reader Uses

type Reader interface {
    // Read tries to read into the audio slice, b, filling it with at max
    // b.Len() audio samples.
    //
    // Returned is the number of samples that where read into the slice, and
    // an error if any occurred.
    //
    // It is possible for the number of samples read to be non-zero; and for an
    // error to be returned at the same time (E.g. read 300 audio samples, but
    // also encountered EOS).
    Read(b Slice) (read int, e error)
}

Reader is a generic interface which describes any type who can have audio samples read from it into an audio slice.

type ReaderFrom Uses

type ReaderFrom interface {
    ReadFrom(r Reader) (n int64, err error)
}

ReaderFrom is the interface that wraps the ReadFrom method.

ReadFrom reads data from r until EOS or error. The return value n is the number of bytes read. Any error except EOS encountered during the read is also returned.

The Copy function uses ReaderFrom if available.

type Slice Uses

type Slice interface {
    // Len returns the number of elements in the slice.
    //
    // Equivilent slice syntax:
    //
    //  len(b)
    Len() int

    // Cap returns the number of elements in the slice.
    //
    // Equivilent slice syntax:
    //
    //  cap(b)
    Cap() int

    // Set sets the specified index in the slice to the specified F64 encoded
    // audio sample, s.
    //
    // If the slice's audio samples are not stored in F64 encoding, then the
    // sample should be converted to the slice's internal format and then
    // stored.
    //
    // Just like slices, slice indices must be non-negative; and no greater
    // than (Len() - 1), or else a panic may occur.
    //
    // Equivilent slice syntax:
    //
    //  b[index] = s
    //   -> b.Set(index, s)
    //
    Set(index int, s F64)

    // At returns the F64 encoded audio sample at the specified index in the
    // slice.
    //
    // If the slice's audio samples are not stored in F64 encoding, then the
    // sample should be converted to F64 encoding, and subsequently returned.
    //
    // Just like slices, slice indices must be non-negative; and no greater
    // than (Len() - 1), or else a panic may occur.
    //
    // Equivilent slice syntax:
    //
    //  b[index]
    //   -> b.At(index)
    //
    At(index int) F64

    // Slice returns a new slice of the slice, using the low and high
    // parameters.
    //
    // Equivilent slice syntax:
    //
    //  b[low:high]
    //   -> b.Slice(low, high)
    //
    //  b[2:]
    //   -> b.Slice(2, a.Len())
    //
    //  b[:3]
    //   -> b.Slice(0, 3)
    //
    //  b[:]
    //   -> b.Slice(0, a.Len())
    //
    Slice(low, high int) Slice

    // Make creates and returns a new slice of this slices type. This allows
    // allocating a new slice of exactly the same type for lossless copying of
    // data without knowing about the underlying type.
    //
    // It is exactly the same syntax as the make builtin:
    //
    //  make(MuLawSamples, len, cap)
    //
    // Where cap cannot be less than len.
    Make(length, capacity int) Slice

    // CopyTo operates exactly like the copy builtin, but this slice is always
    // the source operand. Equivilent slice syntax:
    //
    //  copy(dst, src)
    //   -> src.CopyTo(dst)
    //
    CopyTo(dst Slice) int
}

Slice is a generic audio slice, it can conceptually be thought of as a slice of some audio encoding type.

Conversion between two encoded audio slices is as simple as:

dst, ok := src.(MuLawSamples)
if !ok {
    // Create a new slice of the target encoding and copy the samples over
    // because src is not MuLaw encoded.
    dst = make(MuLawSamples, src.Len())
    src.CopyTo(dst)
}

type Writer Uses

type Writer interface {
    // Write attempts to write all, b.Len(), samples in the slice to the
    // writer.
    //
    // Returned is the number of samples from the slice that where wrote to
    // the writer, and an error if any occured.
    //
    // If the number of samples wrote is less than buf.Len() then the returned
    // error must be non-nil. If any error occurs it should be considered fatal
    // with regards to the writer: no more data can be subsequently wrote after
    // an error.
    Write(b Slice) (wrote int, err error)
}

Writer is a generic interface which describes any type who can have audio samples written from an audio slice into it.

type WriterTo Uses

type WriterTo interface {
    WriteTo(w Writer) (n int64, err error)
}

WriterTo is the interface that wraps the WriteTo method.

WriteTo writes data to w until there's no more data to write or when an error occurs. The return value n is the number of samples written. Any error encountered during the write is also returned.

The Copy function uses WriterTo if available.

Package audio imports 5 packages (graph) and is imported by 10 packages. Updated 2016-07-15. Refresh now. Tools for package owners.