m4a

README

go-m4a

Pure-Go MP4/M4A muxer and demuxer for AAC-LC, Opus, and FLAC audio. No cgo and no external binaries. It is the container half that codecs like go-aac deliberately leave to an external muxer: go-aac's pcm package notes that sample-accurate trimming of the encoder priming "requires a container with an edit list (MP4)", and points at an external muxer as the escape hatch. go-m4a is that muxer, plus the matching demuxer.

Write an .m4a/.mp4 from AAC-LC, Opus, or FLAC access units, with an edit list that trims the encoder priming so playback is gapless and sample-accurate. Read one back into access units that decode with go-aac, go-opus, go-flac, ffmpeg, QuickTime, or any compatible decoder. The core m4a package is codec-agnostic and stdlib-only; optional aacm4a, opusm4a, and flacm4a subpackages bridge the matching codec libraries, so a consumer that only muxes or demuxes pulls no codec.

Note on interop: Opus-in-MP4 is a niche encapsulation (browsers and hardware players prefer Ogg Opus or WebM), and FLAC-in-MP4 buys nothing over native .flac. Their value here is a pure-Go alternative to ffmpeg -c:a libopus/flac and API symmetry with the AAC path, not broad playback compatibility.

Status

The writer and reader dispatch on the codec, so all three share the same ftyp | mdat | moov plumbing, sample tables, and edit list; only the sample entry and its codec-specific box differ.

• AAC-LC (mp4a + esds): the original path. Output is validated with ffprobe and decodes byte-for-byte back to the source through ffmpeg (a go-aac-encoded chirp round-trips at cross-correlation 1.0 at lag 0). The reader tolerates the extra boxes real encoders emit (free, udta, meta, sgpd, sbgp), expands arbitrary multi-chunk stsc tables, and reads ffmpeg and Apple afconvert files.
• Opus (Opus + dOps): each MP4 sample is one Opus packet; the dOps pre-skip drives the same edit-list priming trim as AAC. The emitted dOps is byte-identical to ffmpeg's, ffmpeg reads the container, and an encode/decode round-trip through go-opus preserves the signal.
• FLAC (fLaC + dfLa): each MP4 sample is one native FLAC frame, with the 34-byte STREAMINFO in dfLa; no edit list (FLAC has no priming). Reads ffmpeg-produced files and round-trips bit-exact (lossless) through go-flac.

Parsing is bounds-checked throughout and never panics on malformed input.

Scope: non-fragmented MP4, a single audio track, mono or stereo, 44.1/48 kHz (Opus is always 48 kHz). Out of scope (the reader returns a typed ErrUnsupported, never crashes): fragmented MP4, video or multiple audio tracks, other codecs, HE-AAC, surround, and writing metadata tags. See the open issues for the tracked extensions (non-48 kHz Opus input, high sample rates, more than two channels).

Install

go get github.com/tphakala/go-m4a

The core m4a package is stdlib-only. The optional aacm4a, opusm4a, and flacm4a subpackages wire the container to go-aac, go-opus, and go-flac; each pulls in its codec module, so import only the ones you use.

Usage

m4a: the container

WriterConfig.Codec selects the codec (the zero value is CodecAACLC, so existing AAC callers are unchanged). AAC-LC access units are a fixed 1024 samples each, so WriteFrame suffices; Opus packets and FLAC frames vary in length, so those use WriteFrameDuration(au, sampleDuration). The reader reports Info.Codec and a generic Info.CodecConfig (the ASC, the dOps body, or the STREAMINFO).

Write AAC-LC access units (from any source) into an .m4a:

import "github.com/tphakala/go-m4a"

w, err := m4a.NewWriter(f, m4a.WriterConfig{
    SampleRate:  48000,
    Channels:    1,
    ASC:         asc,   // 2-byte AudioSpecificConfig, e.g. aac.Encoder.AudioSpecificConfig()
    MediaLength: nSamples, // source samples per channel, for a sample-accurate edit list
})
for _, au := range accessUnits {
    if err := w.WriteFrame(au); err != nil { /* ... */ }
}
err = w.Close() // patches the mdat size and writes moov

NewWriter needs an io.WriteSeeker because the streamed mdat size is patched once at Close. The edit list trims WriterConfig.EncoderDelay priming samples (default 1024, go-aac's measured value); set EncoderDelay: m4a.NoEdit to omit the edit list.

Read an .m4a back into access units:

r, err := m4a.NewReader(f) // io.ReadSeeker
info := r.Info()           // SampleRate, Channels, ASC, FrameCount, EncoderDelay, Duration
for {
    au, err := r.ReadFrame()
    if err == io.EOF { break }
    if err != nil { /* ... */ }
    // hand au to your AAC decoder
}

Reader.RawStream() returns an io.Reader that frames each access unit exactly as go-aac's pcm.WithRawStream expects, so the two libraries plug together with no glue, allocation-free per frame. For callers that want the bytes directly without the io.Reader framing, Reader.ReadFrameInto(dst) fills a reused buffer instead of allocating one per frame like ReadFrame does (it returns the required length with io.ErrShortBuffer if dst is too small).

aacm4a: the go-aac bridge

The aacm4a subpackage is the one-call path for callers that have interleaved integer PCM and want an .m4a, or have an .m4a and want PCM:

import (
    aacpcm "github.com/tphakala/go-aac/pcm"
    "github.com/tphakala/go-m4a/aacm4a"
)

// Encode interleaved little-endian PCM to a gapless AAC-LC .m4a.
err := aacm4a.EncodeInterleaved(f, aacpcm.Config{
    SampleRate: 48000, BitDepth: 16, Channels: 1, Bitrate: 96000,
}, pcmBytes)

// Decode an .m4a to interleaved S16 PCM with go-aac.
dec, info, err := aacm4a.NewDecoder(f) // *aacpcm.Decoder, m4a.Info, error
_, err = io.Copy(pcmOut, dec)

The go-aac decoder is not edit-list aware: NewDecoder emits every decoded sample, including both the leading priming and the trailing final-frame padding. For sample-accurate output, skip info.EncoderDelay leading samples per channel, then keep only info.Duration-worth of samples (Duration * SampleRate per channel) and discard the rest.

opusm4a and flacm4a: the go-opus and go-flac bridges

The same one-call shape wraps Opus (48 kHz interleaved S16) and FLAC (interleaved 16- or 24-bit):

import (
    "github.com/tphakala/go-m4a/opusm4a"
    "github.com/tphakala/go-m4a/flacm4a"
)

// Opus: gapless (the pre-skip and trailing padding are trimmed by the edit list).
err := opusm4a.EncodeInterleaved(f, opusm4a.Config{SampleRate: 48000, Channels: 2, Bitrate: 96000}, pcm)
pcmOut, info, err := opusm4a.DecodeInterleaved(r) // []byte, m4a.Info, error

// FLAC: lossless, so the decode is bit-identical to the input.
err = flacm4a.EncodeInterleaved(f, flacm4a.Config{SampleRate: 44100, Channels: 1, BitDepth: 16, CompressionLevel: 5}, pcm)
pcmOut, info, err = flacm4a.DecodeInterleaved(r)

As with aacm4a, opusm4a.DecodeInterleaved returns every decoded sample, including the Opus pre-skip priming and the trailing padding, so trim info.EncoderDelay leading samples then keep info.Duration-worth for sample-accurate output. flacm4a needs no trimming (FLAC has no priming).

Gapless playback and the edit list

A lossy encoder emits priming before the first real sample and pads the final frame: AAC-LC primes 1024 samples (go-aac), Opus 312 at 48 kHz (dOps pre-skip). go-m4a writes an elst edit list whose media_time skips the priming and whose segment_duration (set from WriterConfig.MediaLength) excludes the trailing padding, so a compliant player presents exactly the original audio. The reader surfaces the edit list as Info.EncoderDelay and Info.Duration. FLAC is lossless and has no priming, so no edit list is written.

License

MIT. See LICENSE. go-m4a is clean-room container code and does not include any code ported from FFmpeg, so it is not bound by go-aac's LGPL.

Documentation

Overview

Package m4a muxes AAC-LC, Opus, or FLAC access units into an MP4/M4A container and demuxes them back out. It is the container half that codecs like go-aac deliberately leave to an external muxer: an edit list (elst) trims the encoder priming so the written file is sample-accurate and gapless. The public surface is stdlib-only; the codec bridges (aacm4a, opusm4a, flacm4a) are optional subpackages. The ISO-BMFF byte mechanics live in the internal/box package, whose layout is fixed by docs/box-layout.md.

Index

• Constants
• Variables
• type Codec
  • func (c Codec) String() string
• type Info
• type Reader
  • func NewReader(r io.ReadSeeker) (*Reader, error)
  • func (rd *Reader) ASC() []byte
  • func (rd *Reader) Info() Info
  • func (rd *Reader) RawStream() io.Reader
  • func (rd *Reader) ReadFrame() ([]byte, error)
  • func (rd *Reader) ReadFrameInto(dst []byte) (int, error)
• type Writer
  • func NewWriter(w io.WriteSeeker, cfg WriterConfig) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) WriteFrame(au []byte) error
  • func (w *Writer) WriteFrameDuration(au []byte, sampleDuration uint32) error
• type WriterConfig

Constants

const DefaultEncoderDelay = 1024

DefaultEncoderDelay is the number of leading priming samples an AAC-LC encoder emits before the first real sample. It is go-aac's measured low-level encoder priming (one 1024-sample frame) and is the value used when WriterConfig leaves EncoderDelay at zero.

const DefaultOpusPreSkip = 312

DefaultOpusPreSkip is the pre-skip an Opus encoder emits before the first real sample, in samples at the 48 kHz Opus timescale. It is go-opus's measured value (Encoder.PreSkip) and the value used when a CodecOpus WriterConfig leaves OpusPreSkip at zero.

const NoEdit = -1

NoEdit is the WriterConfig.EncoderDelay sentinel that suppresses the edit list entirely: the writer emits no edts/elst and presents every decoded sample.

Variables

var (
	// ErrCorrupt indicates a malformed container: a truncated box, a size field
	// that overflows the stream, a missing required box (moov, stbl, esds), or
	// an inconsistent sample table.
	ErrCorrupt = errors.New("go-m4a: corrupt container")

	// ErrUnsupported indicates a well-formed MP4 that falls outside the v1
	// scope: fragmented input, no AAC-LC audio track, a non-mp4a codec, or an
	// object type other than AAC-LC.
	ErrUnsupported = errors.New("go-m4a: unsupported container")

	// ErrClosed is returned by WriteFrame and Close once the Writer has been
	// closed. A second Close, or any WriteFrame after Close, reports this
	// instead of panicking.
	ErrClosed = errors.New("go-m4a: writer is closed")
)

Package-wide sentinel errors. They are returned wrapped (via fmt.Errorf with %w) so callers can match with errors.Is while still getting a descriptive message. The Reader shares these with the Writer, so they live here rather than beside a single implementation.

Types

type Codec

type Codec uint8

Codec identifies the audio codec of a track. It is the discriminator the reader reports in Info.Codec and the writer selects with WriterConfig.Codec. The zero value is CodecAACLC, so existing writers that set only ASC keep muxing AAC-LC.

const (
	// CodecAACLC is MPEG-4 AAC-LC, carried in an mp4a sample entry with an esds
	// box holding the AudioSpecificConfig. It is the zero value and the default.
	CodecAACLC Codec = iota
	// CodecOpus is Opus, carried in an Opus sample entry with a dOps
	// OpusSpecificBox, per the Encapsulation of Opus in ISOBMFF.
	CodecOpus
	// CodecFLAC is FLAC, carried in a fLaC sample entry with a dfLa FLACSpecificBox
	// holding the STREAMINFO metadata block, per the Encapsulation of FLAC in
	// ISOBMFF.
	CodecFLAC
)

func (Codec) String

func (c Codec) String() string

String returns the codec's short name.

type Info

type Info struct {
	// SampleRate is the audio sample rate in Hz, derived from the ASC and, when
	// the ASC does not carry an explicit rate, the mp4a AudioSampleEntry.
	SampleRate int

	// Channels is the channel count, normally 1 (mono) or 2 (stereo).
	Channels int

	// Codec identifies the audio codec of the selected track: CodecAACLC,
	// CodecOpus, or CodecFLAC.
	Codec Codec

	// ASC is the MPEG-4 AudioSpecificConfig from the esds DecoderSpecificInfo,
	// suitable for go-aac's pcm.WithRawStream. It is set only for AAC-LC; it is nil
	// for Opus and FLAC. Info returns a fresh copy.
	ASC []byte

	// CodecConfig is the codec-specific configuration recovered from the sample
	// entry: the AudioSpecificConfig for AAC-LC (same bytes as ASC), the
	// OpusSpecificBox (dOps) body for Opus, or the FLAC STREAMINFO metadata block
	// for FLAC. It is what a codec bridge passes to its decoder. Info returns a
	// fresh copy.
	CodecConfig []byte

	// FrameCount is the number of access units (MP4 "samples") in the track.
	FrameCount int

	// EncoderDelay is the leading priming sample count taken verbatim from the
	// edit list media_time. It is 0 when there is no edit list or the first edit
	// is an empty edit (media_time -1).
	EncoderDelay int64

	// Duration is the track presentation duration after the edit list.
	Duration time.Duration

	// Brand is the ftyp major brand.
	Brand string
}

Info summarizes an MP4/M4A file's single audio track (AAC-LC, Opus, or FLAC), populated by NewReader from the moov metadata. The fields come straight from the file's own sample tables, the codec-specific box (esds, dOps, or dfLa), and the edit list; Codec reports which codec, and CodecConfig carries its configuration.

type Reader

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

Reader demuxes a non-fragmented MP4/M4A file (AAC-LC, Opus, or FLAC) into its access units. NewReader parses the moov metadata up front; ReadFrame then returns each access unit in order by seeking to its computed (offset, size). The reader is not safe for concurrent use, and ReadFrame, RawStream, and their shared cursor advance together.

func NewReader

func NewReader(r io.ReadSeeker) (*Reader, error)

NewReader reads and parses the moov metadata from r and returns a Reader positioned at the first access unit. It locates moov whether it precedes or follows mdat, selects the first "soun" track carrying a supported sample entry (mp4a AAC-LC, Opus, or fLaC), and builds the sample geometry from the stsc/stsz/stco tables. It returns a wrapped ErrCorrupt for malformed input and a wrapped ErrUnsupported for well-formed input outside scope (fragmented files, no supported audio track, an unsupported codec, or an AAC object type that is not MPEG-4 Audio).

func (*Reader) ASC

func (rd *Reader) ASC() []byte

ASC returns a fresh copy of the AudioSpecificConfig, suitable for passing to go-aac's pcm.WithRawStream.

func (*Reader) Info

func (rd *Reader) Info() Info

Info returns a copy of the parsed track summary, including a fresh copy of the ASC so the caller cannot mutate the Reader's state.

func (*Reader) RawStream

func (rd *Reader) RawStream() io.Reader

RawStream returns an io.Reader that emits each access unit framed as a 2-byte big-endian length prefix followed by the access-unit bytes, exactly the framing go-aac's pcm.WithRawStream consumes. It shares the Reader's cursor with ReadFrame and reports ErrUnsupported if any access unit exceeds 65535 bytes (impossible for AAC-LC, guarded regardless).

func (*Reader) ReadFrame

func (rd *Reader) ReadFrame() ([]byte, error)

ReadFrame returns the next access unit in decode order and advances the cursor. It returns io.EOF after the last access unit. A frame whose computed extent falls outside the stream, or a short read, is a wrapped ErrCorrupt.

func (*Reader) ReadFrameInto

func (rd *Reader) ReadFrameInto(dst []byte) (int, error)

ReadFrameInto reads the next access unit into dst and returns its length, advancing the cursor. It is the zero-allocation form of ReadFrame for callers that reuse a buffer across frames. If dst is too small to hold the frame, ReadFrameInto reads nothing, does not advance, and returns the required length with io.ErrShortBuffer, so the caller can grow dst and call again. It returns io.EOF after the last access unit, and a wrapped ErrCorrupt for a frame whose extent falls outside the stream or a short read.

type Writer

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

Writer streams AAC-LC, Opus, or FLAC access units into an MP4/M4A file (selected by WriterConfig.Codec, defaulting to AAC-LC). The on-disk layout is ftyp | mdat | moov: ftyp and the mdat header are written up front, each WriteFrame (or WriteFrameDuration) appends one access unit to the mdat payload, and Close patches the mdat size and writes the moov metadata. It requires an io.WriteSeeker because the mdat size is a placeholder patched once at Close.

func NewWriter

func NewWriter(w io.WriteSeeker, cfg WriterConfig) (*Writer, error)

NewWriter validates cfg for its codec (the AAC-LC ASC against SampleRate and Channels, the Opus rate, or the FLAC STREAMINFO), then writes the ftyp box and the placeholder mdat header to w. It returns an error, prefixed "go-m4a: ", when the writer is nil, the codec configuration is malformed or disagrees with SampleRate or Channels, the sample rate is unsupported, or an initial write fails.

func (*Writer) Close

func (w *Writer) Close() error

Close finalizes the file: it patches the streamed mdat largesize, seeks past the payload, and writes the moov metadata (mvhd, trak with tkhd, optional edts/elst, and mdia down to the sample tables). It reports an error if no frames were written or a write fails. After a successful Close a second call returns ErrClosed. A Close that fails on a transient Seek or Write may be retried (WriteFrame stays rejected in between); a Close after a failed WriteFrame returns that latched error and writes nothing.

func (*Writer) WriteFrame

func (w *Writer) WriteFrame(au []byte) error

WriteFrame appends one access unit to the mdat payload using the codec's fixed per-sample duration. It works for AAC-LC, whose every AU is 1024 samples. For Opus and FLAC, whose frames vary in duration, it returns an error directing the caller to WriteFrameDuration. It rejects a nil or empty access unit, and any call after Close.

func (*Writer) WriteFrameDuration

func (w *Writer) WriteFrameDuration(au []byte, sampleDuration uint32) error

WriteFrameDuration appends one access unit to the mdat payload and records its size for the stsz table and sampleDuration (in the media timescale) for the stts table. sampleDuration is the number of samples per channel the access unit decodes to: 1024 for an AAC-LC AU, the packet's 48 kHz sample count for Opus, or the block size for FLAC. It rejects a nil or empty access unit, a zero duration, and any call after Close.

type WriterConfig

type WriterConfig struct {
	// Codec selects the audio codec. The zero value is CodecAACLC, so a config
	// that sets only ASC keeps muxing AAC-LC. For CodecOpus set OpusPreSkip and
	// OpusInputSampleRate (and SampleRate must be 48000); for CodecFLAC set
	// STREAMINFO.
	Codec Codec

	// SampleRate is the audio sample rate in Hz (for example 48000). Required. For
	// AAC-LC it must match the rate encoded in ASC; for Opus it must be 48000 (the
	// fixed Opus container timescale).
	SampleRate int

	// Channels is the channel count, 1 (mono) or 2 (stereo). Required, and for
	// AAC-LC it must match the channel configuration encoded in ASC.
	Channels int

	// ASC is the MPEG-4 AudioSpecificConfig (two bytes for AAC-LC). Required for
	// CodecAACLC; ignored otherwise. The writer copies the bytes verbatim into the
	// esds DecoderSpecificInfo.
	ASC []byte

	// OpusPreSkip is the Opus pre-skip in samples at 48 kHz (go-opus's
	// Encoder.PreSkip). It fills the dOps PreSkip field and the edit-list media
	// time. Used only for CodecOpus; zero selects DefaultOpusPreSkip.
	OpusPreSkip int

	// OpusInputSampleRate is the original source sample rate recorded in the dOps
	// InputSampleRate field (informational; Opus always decodes at 48 kHz). Used
	// only for CodecOpus; zero selects SampleRate.
	OpusInputSampleRate int

	// STREAMINFO is the 34-byte FLAC STREAMINFO metadata block, the payload of the
	// dfLa box (from go-flac's pcm.FrameEncoder.StreamInfoBytes). Required for
	// CodecFLAC; ignored otherwise.
	STREAMINFO []byte

	// EncoderDelay is the number of leading priming samples to trim with an edit
	// list. Zero uses the codec's default priming (DefaultEncoderDelay, 1024, for
	// AAC-LC; the resolved OpusPreSkip, default 312, for Opus; 0 for FLAC); NoEdit
	// writes no edit list at all; a positive value trims exactly that many samples.
	EncoderDelay int

	// MediaLength, when greater than zero, is the number of PCM samples per
	// channel the source contained. It sets the edit-list segment duration
	// exactly, so trailing final-frame padding is also excluded. Zero presents
	// every decoded sample after the priming.
	MediaLength int64

	// Brand overrides the ftyp major brand (default "M4A "). When set it must be
	// exactly four bytes (space-padded, for example "mp42"); NewWriter rejects
	// any other length. The compatible brands always include "M4A ", "mp42", and
	// "isom".
	Brand string
}

WriterConfig configures a Writer. SampleRate and Channels must agree with ASC; NewWriter validates them against it and refuses a mismatch.