faad2

README

go-faad2

Pure Go AAC audio decoder using FAAD2 compiled to WebAssembly.

Features

• Pure Go - No CGO dependencies, cross-compiles easily
• M4A/MP4 support - Built-in demuxer for M4A files with seeking and metadata
• ADTS support - Decode raw AAC streams (ADTS format)
• Low-level API - Decode raw AAC frames directly

Installation

go get github.com/llehouerou/go-faad2

Usage

Decode M4A file

file, _ := os.Open("audio.m4a")
defer file.Close()

reader, _ := faad2.OpenM4A(file)
defer reader.Close()

fmt.Printf("Sample rate: %d, Channels: %d, Duration: %v\n",
    reader.SampleRate(), reader.Channels(), reader.Duration())

pcm := make([]int16, 4096)
for {
    n, err := reader.Read(pcm)
    if err == io.EOF {
        break
    }
    // Process pcm[:n]
}

Seeking and position

reader, _ := faad2.OpenM4A(file)

// Seek to 30 seconds
reader.Seek(30 * time.Second)

// Get current position
fmt.Printf("Position: %v\n", reader.Position())

Extract metadata

reader, _ := faad2.OpenM4A(file)
meta := reader.Metadata()

fmt.Printf("Title: %s\n", meta.Title)
fmt.Printf("Artist: %s\n", meta.Artist)
fmt.Printf("Album: %s\n", meta.Album)

Decode ADTS stream (raw AAC)

file, _ := os.Open("audio.aac")
reader, _ := faad2.OpenADTS(file)
defer reader.Close()

pcm := make([]int16, 4096)
for {
    n, err := reader.Read(pcm)
    if err == io.EOF {
        break
    }
    // Process pcm[:n]
}

Decode raw AAC frames (low-level)

decoder, _ := faad2.NewDecoder()
defer decoder.Close()

// Initialize with AAC codec config (from ADTS or MP4 esds)
decoder.Init(codecConfig)

// Decode frames
pcm, _ := decoder.Decode(aacFrame)

Building the WASM binary

The WASM binary is pre-built and embedded in the library. To rebuild it:

# Requires Emscripten (available in nix devShell)
make wasm

Development

# Enter development shell (requires Nix with flakes)
nix develop

# Run checks (format, lint, test)
make check

# Install git hooks
make install-hooks

License

GPL-2.0-or-later (required by FAAD2)

Credits

• FAAD2 - AAC decoder
• wazero - WebAssembly runtime
• go-mp4 - MP4 parser

Documentation

Index

• Variables
• func ParseADTSHeader(data []byte) (sampleRate uint32, channels uint8, frameLength uint16, err error)
• type ADTSReader
  • func OpenADTS(r io.Reader) (*ADTSReader, error)
  • func (ar *ADTSReader) Channels() uint8
  • func (ar *ADTSReader) Close() error
  • func (ar *ADTSReader) FramesRead() int64
  • func (ar *ADTSReader) Read(pcm []int16) (int, error)
  • func (ar *ADTSReader) SampleRate() uint32
• type Decoder
  • func NewDecoder() (*Decoder, error)
  • func (d *Decoder) Channels() uint8
  • func (d *Decoder) Close() error
  • func (d *Decoder) Decode(aacFrame []byte) ([]int16, error)
  • func (d *Decoder) Init(config []byte) error
  • func (d *Decoder) SampleRate() uint32
• type M4AReader
  • func OpenM4A(r io.ReadSeeker) (*M4AReader, error)
  • func (m *M4AReader) Channels() uint8
  • func (m *M4AReader) Close() error
  • func (m *M4AReader) Duration() time.Duration
  • func (m *M4AReader) Metadata() Metadata
  • func (m *M4AReader) Position() time.Duration
  • func (m *M4AReader) Read(pcm []int16) (int, error)
  • func (m *M4AReader) SampleRate() uint32
  • func (m *M4AReader) Seek(position time.Duration) error
• type Metadata

Variables

var (
	// ErrInvalidADTS is returned when the ADTS stream is invalid.
	ErrInvalidADTS = errors.New("faad2: invalid ADTS stream")

	// ErrADTSSyncNotFound is returned when no ADTS sync word is found.
	ErrADTSSyncNotFound = errors.New("faad2: ADTS sync word not found")
)

var (
	// ErrInvalidConfig is returned when the AAC codec configuration is invalid.
	ErrInvalidConfig = errors.New("faad2: invalid codec configuration")

	// ErrDecodeFailed is returned when AAC frame decoding fails.
	ErrDecodeFailed = errors.New("faad2: decode failed")

	// ErrOutOfMemory is returned when WASM memory allocation fails.
	ErrOutOfMemory = errors.New("faad2: out of memory")

	// ErrNotInitialized is returned when trying to decode without initialization.
	ErrNotInitialized = errors.New("faad2: decoder not initialized")

	// ErrNotM4A is returned when the input is not a valid M4A/MP4 file.
	ErrNotM4A = errors.New("faad2: not an M4A/MP4 file")

	// ErrNoAudioTrack is returned when no AAC audio track is found.
	ErrNoAudioTrack = errors.New("faad2: no AAC audio track found")

	// ErrUnsupportedCodec is returned when the audio codec is not AAC.
	ErrUnsupportedCodec = errors.New("faad2: unsupported audio codec (not AAC)")
)

Functions

func ParseADTSHeader

func ParseADTSHeader(data []byte) (sampleRate uint32, channels uint8, frameLength uint16, err error)

ParseADTSHeader parses an ADTS header from raw bytes. Useful for inspecting ADTS streams without creating a reader.

Types

type ADTSReader

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

ADTSReader reads and decodes audio from ADTS streams (raw AAC).

func OpenADTS

func OpenADTS(r io.Reader) (*ADTSReader, error)

OpenADTS opens an ADTS stream for audio decoding.

func (*ADTSReader) Channels

func (ar *ADTSReader) Channels() uint8

Channels returns the number of audio channels.

func (*ADTSReader) Close

func (ar *ADTSReader) Close() error

Close releases all resources.

func (*ADTSReader) FramesRead

func (ar *ADTSReader) FramesRead() int64

FramesRead returns the number of AAC frames decoded so far.

func (*ADTSReader) Read

func (ar *ADTSReader) Read(pcm []int16) (int, error)

Read reads decoded PCM samples into the buffer. Returns the number of samples read.

func (*ADTSReader) SampleRate

func (ar *ADTSReader) SampleRate() uint32

SampleRate returns the audio sample rate.

type Decoder

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

Decoder represents an AAC decoder instance.

func NewDecoder

func NewDecoder() (*Decoder, error)

NewDecoder creates a new AAC decoder.

func (*Decoder) Channels

func (d *Decoder) Channels() uint8

Channels returns the number of channels after initialization.

func (*Decoder) Close

func (d *Decoder) Close() error

Close releases decoder resources.

func (*Decoder) Decode

func (d *Decoder) Decode(aacFrame []byte) ([]int16, error)

Decode decodes a single AAC frame and returns PCM samples.

func (*Decoder) Init

func (d *Decoder) Init(config []byte) error

Init initializes the decoder with AAC codec configuration (typically from MP4 esds box or ADTS header).

func (*Decoder) SampleRate

func (d *Decoder) SampleRate() uint32

SampleRate returns the sample rate after initialization.

type M4AReader

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

M4AReader reads and decodes audio from M4A/MP4 files.

func OpenM4A

func OpenM4A(r io.ReadSeeker) (*M4AReader, error)

OpenM4A opens an M4A/MP4 file for audio decoding.

func (*M4AReader) Channels

func (m *M4AReader) Channels() uint8

Channels returns the number of audio channels.

func (*M4AReader) Close

func (m *M4AReader) Close() error

Close releases all resources.

func (*M4AReader) Duration

func (m *M4AReader) Duration() time.Duration

Duration returns the total duration of the audio.

func (*M4AReader) Metadata

func (m *M4AReader) Metadata() Metadata

Metadata returns the file metadata.

func (*M4AReader) Position

func (m *M4AReader) Position() time.Duration

Position returns the current playback position.

func (*M4AReader) Read

func (m *M4AReader) Read(pcm []int16) (int, error)

Read reads decoded PCM samples into the buffer. Returns number of samples read, or io.EOF when done.

func (*M4AReader) SampleRate

func (m *M4AReader) SampleRate() uint32

SampleRate returns the audio sample rate.

func (*M4AReader) Seek

func (m *M4AReader) Seek(position time.Duration) error

Seek seeks to a specific time position. The actual position after seeking may be slightly different due to frame boundaries.

type Metadata

type Metadata struct {
	Title       string
	Artist      string
	Album       string
	Year        int
	TrackNumber int
	Genre       string
}

Metadata contains M4A file metadata.