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 ALawToInt16(s uint8) int16
- func Copy(dst Writer, src Reader) (written int64, err error)
- func Float64ToInt16(s float64) int16
- func Float64ToInt32(s float64) int32
- func Float64ToUint8(s float64) uint8
- func Int16ToALaw(s int16) uint8
- func Int16ToFloat64(s int16) float64
- func Int16ToMuLaw(s int16) uint8
- func Int32ToFloat64(s int32) float64
- func MuLawToInt16(s uint8) int16
- func RegisterFormat(name, magic string, newDecoder func(r interface{}) (Decoder, error))
- func Uint8ToFloat64(s uint8) float64
- type ALaw
- 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 float64, 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 float64)
- func (b *Buffer) WriteTo(w Writer) (n int64, err error)
- type Config
- type Decoder
- type Encoder
- type Float32
- type Float64
- type Int16
- type Int32
- type MuLaw
- type ReadSeeker
- type Reader
- type ReaderFrom
- type Slice
- type Uint8
- 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 ALawToInt16 ¶
ALawToInt16 converts an ALaw encoded audio sample to an Int16 encoded audio sample.
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 Float64ToInt16 ¶
Float64ToInt16 converts a Float64 encoded audio sample to Int16.
func Float64ToInt32 ¶
Float64ToInt32 converts a Float64 encoded audio sample to Int32.
func Float64ToUint8 ¶
Float64ToUint8 converts a Float64 encoded audio sample to Uint8.
func Int16ToALaw ¶
Int16ToALaw converts an Int16 encoded audio sample to an ALaw encoded audio sample.
func Int16ToFloat64 ¶
Int16ToFloat64 converts a Int16 encoded audio sample to Float64.
func Int16ToMuLaw ¶
Int16ToMuLaw converts from a Int16 encoded audio sample to an MuLaw encoded audio sample.
func Int32ToFloat64 ¶
Int32ToFloat64 converts a Int32 encoded audio sample to Float64.
func MuLawToInt16 ¶
MuLawToInt16 converts from an MuLaw encoded audio sample to an Int16 encoded audio sample.
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.
func Uint8ToFloat64 ¶
Uint8ToFloat64 converts a Uint8 encoded audio sample to Float64.
Types ¶
type ALaw ¶
type ALaw []uint8
ALaw represents a slice of ALaw encoded audio samples.
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 Float32 ¶
type Float32 []float32
Float32 represents a slice of 32-bit floating-point linear PCM encoded audio samples, in the range of -1 to +1.
type Float64 ¶
type Float64 []float64
Float64 represents a slice of 64-bit floating-point linear PCM encoded audio samples, in the range of -1 to +1.
type Int16 ¶
type Int16 []int16
Int16 represents a signed 16-bit linear PCM encoded audio sample.
type Int32 ¶
type Int32 []int32
Int32 represents a signed 32-bit linear PCM encoded audio sample.
type MuLaw ¶
type MuLaw []uint8
MuLaw represents a slice of MuLaw encoded audio samples.
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 Float64
// encoded audio sample, s.
//
// If the slice's audio samples are not stored in Float64 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 float64)
// At returns the Float64 encoded audio sample at the specified index in
// the slice.
//
// If the slice's audio samples are not stored in Float64 encoding, then
// the sample should be converted to Float64 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) float64
// 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(MuLaw, 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.(MuLaw)
if !ok {
// Create a new slice of the target encoding and copy the samples over
// because src is not MuLaw encoded.
dst = make(MuLaw, src.Len())
src.CopyTo(dst)
}
type Uint8 ¶
type Uint8 []uint8
Uint8 represents a unsigned 8-bit linear PCM encoded audio sample.
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
Directories