README
¶
Azul3D audio package.
See documentation online: http://www.azul3d.org/packages.html
Documentation
¶
Overview ¶
Package audio implements various audio types and interfaces.
This package aims to be like the 'image' package, except for audio.
Index ¶
- Variables
- func Copy(dst Writer, src Reader) (written int64, err error)
- func RegisterFormat(name, magic string, newDecoder func(r interface{}) (Decoder, error))
- type ALaw
- type ALawSamples
- type Buffer
- func (b *Buffer) Grow(n int)
- func (b *Buffer) Len() int
- func (b *Buffer) Next(n int) Slice
- func (b *Buffer) Read(p Slice) (n int, err error)
- func (b *Buffer) ReadFrom(r Reader) (n int64, err error)
- func (b *Buffer) ReadSample() (c F64, err error)
- func (b *Buffer) Reset()
- func (b *Buffer) Samples() Slice
- func (b *Buffer) Seek(offset uint64) error
- func (b *Buffer) Truncate(n int)
- func (b *Buffer) Write(p Slice) (n int, err error)
- func (b *Buffer) WriteSample(c F64)
- func (b *Buffer) WriteTo(w Writer) (n int64, err error)
- type Config
- type Decoder
- type Encoder
- type F32
- type F32Samples
- type F64
- type F64Samples
- type MuLaw
- type MuLawSamples
- type PCM16
- type PCM16Samples
- type PCM32
- type PCM32Samples
- type PCM8
- type PCM8Samples
- type ReadSeeker
- type Reader
- type ReaderFrom
- type Slice
- type Writer
- type WriterTo
Constants ¶
This section is empty.
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 invalid 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.
Functions ¶
func Copy ¶
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 ¶
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.
Types ¶
type ALaw ¶
type ALaw uint8
ALaw represents an uint8 alaw encoded audio sample.
func PCM16ToALaw ¶
PCM16ToALaw converts an PCM16 encoded audio sample to an ALaw encoded audio sample.
type ALawSamples ¶
type ALawSamples []ALaw
ALawSamples represents an slice of ALaw encoded audio samples.
func (ALawSamples) Make ¶
func (p ALawSamples) Make(length, capacity int) Slice
Implements Slice interface.
func (ALawSamples) Slice ¶
func (p ALawSamples) Slice(low, high int) Slice
Implements Slice interface.
type Buffer ¶
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 ¶
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 ¶
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 ¶
Len returns the number of samples of the unread portion of the buffer; b.Len() == b.Samples().Len().
func (*Buffer) Next ¶
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 ¶
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 ¶
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 ¶
ReadSample reads and returns the next sample from the buffer. If no sample is available, it returns error EOS.
func (*Buffer) Reset ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
WriteSample appends the sample c to the buffer, growing the buffer as needed.
type Config ¶
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.
type Decoder ¶
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 ¶
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 ¶
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 incomplete.
//
// 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 ¶
type F32 float32
F32 represents a 32-bit floating-point linear audio sample in the range of -1 to +1.
type F32Samples ¶
type F32Samples []F32
F32Samples represents a slice of F32 encoded audio samples.
func (F32Samples) Make ¶
func (p F32Samples) Make(length, capacity int) Slice
Implements Slice interface.
func (F32Samples) Slice ¶
func (p F32Samples) Slice(low, high int) Slice
Implements Slice interface.
type F64 ¶
type F64 float64
F64 represents a 64-bit floating-point linear audio sample in the range of -1 to +1.
func PCM16ToF64 ¶
PCM16ToF64 converts a PCM16 encoded audio sample to F64.
func PCM32ToF64 ¶
PCM32ToF64 converts a PCM32 encoded audio sample to F64.
type F64Samples ¶
type F64Samples []F64
F64Samples represents a slice of F64 encoded audio samples.
func (F64Samples) Make ¶
func (p F64Samples) Make(length, capacity int) Slice
Implements Slice interface.
func (F64Samples) Slice ¶
func (p F64Samples) Slice(low, high int) Slice
Implements Slice interface.
type MuLaw ¶
type MuLaw uint8
MuLaw represents an uint8 mulaw encoded audio sample.
func PCM16ToMuLaw ¶
PCM16ToMuLaw converts from a PCM16 encoded audio sample to an MuLaw encoded audio sample.
type MuLawSamples ¶
type MuLawSamples []MuLaw
MuLawSamples represents an slice of MuLaw encoded audio samples.
func (MuLawSamples) CopyTo ¶
func (p MuLawSamples) CopyTo(dst Slice) int
Implements Slice interface.
func (MuLawSamples) Make ¶
func (p MuLawSamples) Make(length, capacity int) Slice
Implements Slice interface.
func (MuLawSamples) Slice ¶
func (p MuLawSamples) Slice(low, high int) Slice
Implements Slice interface.
type PCM16 ¶
type PCM16 int16
PCM16 represents a signed 16-bit linear PCM audio sample.
func ALawToPCM16 ¶
ALawToPCM16 converts an ALaw encoded audio sample to an PCM16 encoded audio sample.
func F64ToPCM16 ¶
F64ToPCM16 converts a F64 encoded audio sample to PCM16.
func MuLawToPCM16 ¶
MuLawToPCM16 converts from an MuLaw encoded audio sample to an PCM16 encoded audio sample.
type PCM16Samples ¶
type PCM16Samples []PCM16
PCM16Samples represents a slice of PCM16 encoded audio samples.
func (PCM16Samples) CopyTo ¶
func (p PCM16Samples) CopyTo(dst Slice) int
Implements Slice interface.
func (PCM16Samples) Make ¶
func (p PCM16Samples) Make(length, capacity int) Slice
Implements Slice interface.
func (PCM16Samples) Slice ¶
func (p PCM16Samples) Slice(low, high int) Slice
Implements Slice interface.
type PCM32 ¶
type PCM32 int32
PCM32 represents a signed 32-bit linear PCM audio sample.
func F64ToPCM32 ¶
F64ToPCM32 converts a F64 encoded audio sample to PCM32.
type PCM32Samples ¶
type PCM32Samples []PCM32
PCM32Samples represents a slice of PCM32 encoded audio samples.
func (PCM32Samples) CopyTo ¶
func (p PCM32Samples) CopyTo(dst Slice) int
Implements Slice interface.
func (PCM32Samples) Make ¶
func (p PCM32Samples) Make(length, capacity int) Slice
Implements Slice interface.
func (PCM32Samples) Slice ¶
func (p PCM32Samples) Slice(low, high int) Slice
Implements Slice interface.
type PCM8Samples ¶
type PCM8Samples []PCM8
PCM8Samples represents a slice of PCM8 encoded audio samples.
func (PCM8Samples) Make ¶
func (p PCM8Samples) Make(length, capacity int) Slice
Implements Slice interface.
func (PCM8Samples) Slice ¶
func (p PCM8Samples) Slice(low, high int) Slice
Implements Slice interface.
type ReadSeeker ¶
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 ¶
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 ¶
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 ¶
type Slice interface {
// Len returns the number of elements in the slice.
//
// Equivalent slice syntax:
//
// len(b)
Len() int
// Cap returns the number of elements in the slice.
//
// Equivalent 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.
//
// Equivalent 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.
//
// Equivalent 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.
//
// Equivalent 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. Equivalent 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 ¶
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 ¶
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.
Source Files