README

audio

GoDoc

audio is a generic Go package designed to define a common interface to analyze and/or process audio data.

At the heart of the package is the Buffer interface and its implementations:

  • FloatBuffer
  • Float32Buffer
  • IntBuffer

Decoders, encoders, processors, analyzers and transformers can be written to accept or return these types and share a common interface.

The idea is that audio libraries can define this interface or its implementations as input and return an audio.Buffer interface allowing all audio libraries to be chainable.

Performance

The buffer implementations are designed so a buffer can be reused and mutated avoiding allocation penalties.

It is recommended to avoid using Float32Buffer unless performance is critical. The major drawback of using float32s is that the Go stdlib was designed to work with float64 and therefore the access to standard packages is limited.

Usage

Examples of how to use this interface is available under the go-audio organization.

Expand ▾ Collapse ▴

Documentation

Overview

    Package audio defines a common interface to analyze and/or process audio data.

    At the heart of the package is the Buffer interface and its implementations: FloatBuffer and IntBuffer. Decoders, encoders, processors, analyzers and transformers can be written to accept or return these types and share a common interface.

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    
    	// FormatMono22500 is mono 22.5kHz format.
    	FormatMono22500 = &Format{
    		NumChannels: 1,
    		SampleRate:  22500,
    	}
    	// FormatMono44100 is mono 8bit 44.1kHz format.
    	FormatMono44100 = &Format{
    		NumChannels: 1,
    		SampleRate:  44100,
    	}
    	// FormatMono48000 is mono 48kHz format.
    	FormatMono48000 = &Format{
    		NumChannels: 1,
    		SampleRate:  48000,
    	}
    	// FormatMono96000 is mono 96kHz format.
    	FormatMono96000 = &Format{
    		NumChannels: 1,
    		SampleRate:  96000,
    	}
    
    	// FormatStereo22500 is stereo 22.5kHz format.
    	FormatStereo22500 = &Format{
    		NumChannels: 2,
    		SampleRate:  22500,
    	}
    	// FormatStereo44100 is stereo 8bit 44.1kHz format.
    	FormatStereo44100 = &Format{
    		NumChannels: 2,
    		SampleRate:  44100,
    	}
    	// FormatStereo48000 is stereo 48kHz format.
    	FormatStereo48000 = &Format{
    		NumChannels: 2,
    		SampleRate:  48000,
    	}
    	// FormatStereo96000 is stereo 96kHz format.
    	FormatStereo96000 = &Format{
    		NumChannels: 2,
    		SampleRate:  96000,
    	}
    )
    View Source
    var (
    	// ErrInvalidBuffer is a generic error returned when trying to read/write to an invalid buffer.
    	ErrInvalidBuffer = errors.New("invalid buffer")
    )

    Functions

    func IEEEFloatToInt

    func IEEEFloatToInt(b [10]byte) int

      IEEEFloatToInt converts a 10 byte IEEE float into an int.

      func Int24BETo32

      func Int24BETo32(bytes []byte) int32

        Int24BETo32 converts an int24 value from 3 bytes into an int32 value

        func Int24LETo32

        func Int24LETo32(bytes []byte) int32

          Int24LETo32 converts an int24 value from 3 bytes into an int32 value

          func Int32toInt24BEBytes

          func Int32toInt24BEBytes(n int32) []byte

            Int32toInt24BEBytes converts an int32 into a big endian 3 byte int24 representation

            func Int32toInt24LEBytes

            func Int32toInt24LEBytes(n int32) []byte

              Int32toInt24LEBytes converts an int32 into a little endian 3 byte int24 representation

              func IntMaxSignedValue

              func IntMaxSignedValue(b int) int

                IntMaxSignedValue returns the max value of an integer based on its memory size

                func IntToIEEEFloat

                func IntToIEEEFloat(i int) [10]byte

                  IntToIEEEFloat converts an int into a 10 byte IEEE float.

                  func Uint24to32

                  func Uint24to32(bytes []byte) uint32

                    Uint24to32 converts a 3 byte uint23 into a uint32 BigEndian!

                    func Uint32toUint24Bytes

                    func Uint32toUint24Bytes(n uint32) []byte

                      Uint32toUint24Bytes converts a uint32 into a 3 byte uint24 representation

                      Types

                      type Buffer

                      type Buffer interface {
                      	// PCMFormat is the format of buffer (describing the buffer content/format).
                      	PCMFormat() *Format
                      	// NumFrames returns the number of frames contained in the buffer.
                      	NumFrames() int
                      	// AsFloatBuffer returns a float 64 buffer from this buffer.
                      	AsFloatBuffer() *FloatBuffer
                      	// AsFloat32Buffer returns a float 32 buffer from this buffer.
                      	AsFloat32Buffer() *Float32Buffer
                      	// AsIntBuffer returns an int buffer from this buffer.
                      	AsIntBuffer() *IntBuffer
                      	// Clone creates a clean clone that can be modified without
                      	// changing the source buffer.
                      	Clone() Buffer
                      }

                        Buffer is the representation of an audio buffer.

                        type Float32Buffer

                        type Float32Buffer struct {
                        	// Format is the representation of the underlying data format
                        	Format *Format
                        	// Data is the buffer PCM data as floats
                        	Data []float32
                        	// SourceBitDepth helps us know if the source was encoded on
                        	// 8, 16, 24, 32, 64 bits.
                        	SourceBitDepth int
                        }

                          Float32Buffer is an audio buffer with its PCM data formatted as float32.

                          func (*Float32Buffer) AsFloat32Buffer

                          func (buf *Float32Buffer) AsFloat32Buffer() *Float32Buffer

                            AsFloat32Buffer implements the Buffer interface and returns itself.

                            func (*Float32Buffer) AsFloatBuffer

                            func (buf *Float32Buffer) AsFloatBuffer() *FloatBuffer

                              AsFloatBuffer implements the Buffer interface and returns a float64 version of itself.

                              func (*Float32Buffer) AsIntBuffer

                              func (buf *Float32Buffer) AsIntBuffer() *IntBuffer

                                AsIntBuffer returns a copy of this buffer but with data truncated to Ints. It is usually recommended to apply a transforms when going from a 24bit source to an int (16bit destination). Look at transforms.PCMScaleF32() for instance

                                func (*Float32Buffer) Clone

                                func (buf *Float32Buffer) Clone() Buffer

                                  Clone creates a clean clone that can be modified without changing the source buffer.

                                  func (*Float32Buffer) NumFrames

                                  func (buf *Float32Buffer) NumFrames() int

                                    NumFrames returns the number of frames contained in the buffer.

                                    func (*Float32Buffer) PCMFormat

                                    func (buf *Float32Buffer) PCMFormat() *Format

                                      PCMFormat returns the buffer format information.

                                      type FloatBuffer

                                      type FloatBuffer struct {
                                      	// Format is the representation of the underlying data format
                                      	Format *Format
                                      	// Data is the buffer PCM data as floats
                                      	Data []float64
                                      }

                                        FloatBuffer is an audio buffer with its PCM data formatted as float64.

                                        func (*FloatBuffer) AsFloat32Buffer

                                        func (buf *FloatBuffer) AsFloat32Buffer() *Float32Buffer

                                          AsFloat32Buffer implements the Buffer interface and returns a float 32 version of itself.

                                          func (*FloatBuffer) AsFloatBuffer

                                          func (buf *FloatBuffer) AsFloatBuffer() *FloatBuffer

                                            AsFloatBuffer implements the Buffer interface and returns itself.

                                            func (*FloatBuffer) AsIntBuffer

                                            func (buf *FloatBuffer) AsIntBuffer() *IntBuffer

                                              AsIntBuffer returns a copy of this buffer but with data truncated to Ints.

                                              func (*FloatBuffer) Clone

                                              func (buf *FloatBuffer) Clone() Buffer

                                                Clone creates a clean clone that can be modified without changing the source buffer.

                                                func (*FloatBuffer) NumFrames

                                                func (buf *FloatBuffer) NumFrames() int

                                                  NumFrames returns the number of frames contained in the buffer.

                                                  func (*FloatBuffer) PCMFormat

                                                  func (buf *FloatBuffer) PCMFormat() *Format

                                                    PCMFormat returns the buffer format information.

                                                    type Format

                                                    type Format struct {
                                                    	// NumChannels is the number of channels contained in the data
                                                    	NumChannels int
                                                    	// SampleRate is the sampling rate in Hz
                                                    	SampleRate int
                                                    }

                                                      Format is a high level representation of the underlying data.

                                                      type IntBuffer

                                                      type IntBuffer struct {
                                                      	// Format is the representation of the underlying data format
                                                      	Format *Format
                                                      	// Data is the buffer PCM data as ints
                                                      	Data []int
                                                      	// SourceBitDepth helps us know if the source was encoded on
                                                      	// 8, 16, 24, 32, 64 bits.
                                                      	SourceBitDepth int
                                                      }

                                                        IntBuffer is an audio buffer with its PCM data formatted as int.

                                                        func (*IntBuffer) AsFloat32Buffer

                                                        func (buf *IntBuffer) AsFloat32Buffer() *Float32Buffer

                                                          AsFloat32Buffer returns a copy of this buffer but with data converted to float 32.

                                                          func (*IntBuffer) AsFloatBuffer

                                                          func (buf *IntBuffer) AsFloatBuffer() *FloatBuffer

                                                            AsFloatBuffer returns a copy of this buffer but with data converted to floats.

                                                            func (*IntBuffer) AsIntBuffer

                                                            func (buf *IntBuffer) AsIntBuffer() *IntBuffer

                                                              AsIntBuffer implements the Buffer interface and returns itself.

                                                              func (*IntBuffer) Clone

                                                              func (buf *IntBuffer) Clone() Buffer

                                                                Clone creates a clean clone that can be modified without changing the source buffer.

                                                                func (*IntBuffer) NumFrames

                                                                func (buf *IntBuffer) NumFrames() int

                                                                  NumFrames returns the number of frames contained in the buffer.

                                                                  func (*IntBuffer) PCMFormat

                                                                  func (buf *IntBuffer) PCMFormat() *Format

                                                                    PCMFormat returns the buffer format information.

                                                                    type PCMBuffer

                                                                    type PCMBuffer struct {
                                                                    	// Format describes the format of the buffer data.
                                                                    	Format *Format
                                                                    	// I8 is a store for audio sample data as integers.
                                                                    	I8 []int8
                                                                    	// I16 is a store for audio sample data as integers.
                                                                    	I16 []int16
                                                                    	// I32 is a store for audio sample data as integers.
                                                                    	I32 []int32
                                                                    	// F32 is a store for audio samples data as float64.
                                                                    	F32 []float32
                                                                    	// F64 is a store for audio samples data as float64.
                                                                    	F64 []float64
                                                                    	// DataType indicates the primary format used for the underlying data.
                                                                    	// The consumer of the buffer might want to look at this value to know what store
                                                                    	// to use to optimaly retrieve data.
                                                                    	DataType PCMDataFormat
                                                                    	// SourceBitDepth helps us know if the source was encoded on
                                                                    	// 1 (int8), 2 (int16), 3(int24), 4(int32), 8(int64) bytes.
                                                                    	SourceBitDepth uint8
                                                                    }

                                                                      PCMBuffer encapsulates uncompressed audio data and provides useful methods to read/manipulate this PCM data. It's a more flexible buffer type allowing the developer to handle different kind of buffer data formats and convert between underlying types.

                                                                      func (*PCMBuffer) AsF32

                                                                      func (b *PCMBuffer) AsF32() (out []float32)

                                                                        AsF32 returns the buffer's samples as float32 sample values. If the buffer isn't in this format, a copy is created and converted. Note that converting might result in unexpected truncations.

                                                                        func (*PCMBuffer) AsF64

                                                                        func (b *PCMBuffer) AsF64() (out []float64)

                                                                          AsF64 returns the buffer's samples as float64 sample values. If the buffer isn't in this format, a copy is created and converted. Note that converting might result in unexpected truncations.

                                                                          func (*PCMBuffer) AsFloat32Buffer

                                                                          func (b *PCMBuffer) AsFloat32Buffer() *Float32Buffer

                                                                            AsFloat32Buffer implements the Buffer interface and returns a float 32 version of itself.

                                                                            func (*PCMBuffer) AsFloatBuffer

                                                                            func (b *PCMBuffer) AsFloatBuffer() *FloatBuffer

                                                                              AsFloatBuffer returns a copy of this buffer but with data converted to floats.

                                                                              func (*PCMBuffer) AsI16

                                                                              func (b *PCMBuffer) AsI16() (out []int16)

                                                                                AsI16 returns the buffer's samples as int16 sample values. If the buffer isn't in this format, a copy is created and converted. Note that converting might result in loss of resolution.

                                                                                func (*PCMBuffer) AsI32

                                                                                func (b *PCMBuffer) AsI32() (out []int32)

                                                                                  AsI32 returns the buffer's samples as int32 sample values. If the buffer isn't in this format, a copy is created and converted. Note that converting a float to an int might result in unexpected truncations.

                                                                                  func (*PCMBuffer) AsI8

                                                                                  func (b *PCMBuffer) AsI8() (out []int8)

                                                                                    AsI8 returns the buffer's samples as int8 sample values. If the buffer isn't in this format, a copy is created and converted. Note that converting might result in loss of resolution.

                                                                                    func (*PCMBuffer) AsInt

                                                                                    func (b *PCMBuffer) AsInt() (out []int)

                                                                                      AsInt returns the buffer content as integers (int32s). It's recommended to avoid this method since it creates an extra copy of the buffer content.

                                                                                      func (*PCMBuffer) AsIntBuffer

                                                                                      func (b *PCMBuffer) AsIntBuffer() *IntBuffer

                                                                                        AsIntBuffer returns a copy of this buffer but with data truncated to Ints.

                                                                                        func (*PCMBuffer) Clone

                                                                                        func (b *PCMBuffer) Clone() Buffer

                                                                                          Clone creates a clean clone that can be modified without changing the source buffer.

                                                                                          func (*PCMBuffer) Len

                                                                                          func (b *PCMBuffer) Len() int

                                                                                            Len returns the length of the underlying data.

                                                                                            func (*PCMBuffer) NumFrames

                                                                                            func (b *PCMBuffer) NumFrames() int

                                                                                              NumFrames returns the number of frames contained in the buffer.

                                                                                              func (*PCMBuffer) PCMFormat

                                                                                              func (b *PCMBuffer) PCMFormat() *Format

                                                                                                PCMFormat returns the buffer format information.

                                                                                                func (*PCMBuffer) SwitchPrimaryType

                                                                                                func (b *PCMBuffer) SwitchPrimaryType(t PCMDataFormat)

                                                                                                  SwitchPrimaryType is a convenience method to switch the primary data type. Use this if you process/swap a different type than the original type. Notes that conversion might be lossy if you switch to a lower resolution format.

                                                                                                  type PCMDataFormat

                                                                                                  type PCMDataFormat uint8

                                                                                                    PCMDataFormat is an enum type to indicate the underlying data format used.

                                                                                                    const (
                                                                                                    	// DataTypeUnknown refers to an unknown format
                                                                                                    	DataTypeUnknown PCMDataFormat = iota
                                                                                                    	// DataTypeI8 indicates that the content of the audio buffer made of 8-bit integers.
                                                                                                    	DataTypeI8
                                                                                                    	// DataTypeI16 indicates that the content of the audio buffer made of 16-bit integers.
                                                                                                    	DataTypeI16
                                                                                                    	// DataTypeI32 indicates that the content of the audio buffer made of 32-bit integers.
                                                                                                    	DataTypeI32
                                                                                                    	// DataTypeF32 indicates that the content of the audio buffer made of 32-bit floats.
                                                                                                    	DataTypeF32
                                                                                                    	// DataTypeF64 indicates that the content of the audio buffer made of 64-bit floats.
                                                                                                    	DataTypeF64
                                                                                                    )