locmaf

README

LOCMAF

Reference implementation of LOCMAF (Low Overhead CMAF for MOQ) — a compact CMAF packaging for MoQ Transport, including DRM-protected content. Sample-level objects with a delta moof as small as 2 bytes, reconstructed into functionally lossless CMAF chunks at the receiver.

• Specification: draft-einarsson-moq-locmaf (source: Eyevinn/locmaf-id)
• Explainer site and slides: https://locmaf.dev (source in web/)
• Packaging version: locmafVersion "0.3"

Layout

locmaf/          package locmaf — codec: EncodeCanonical, Decode, ReconstructCanonical
├── vi64/        MOQT vi64 varints + zigzag (stdlib-only)
├── cmd/locmaf/  CLI: align, vectors, verify, dump (planned)
├── testdata/    golden canonical-encoding vectors (planned)
└── web/         locmaf.dev site (separate stub module, not part of the Go module)

The codec implements packaging version 0.3: the element sequence (genBox / full / delta headers), vi64 integers, full 32-bit sample_flags, derived-only delta BMDT, scheme-agnostic CENC carriage, and the canonical reconstruction (byte-exact moof rebuild including senc/saiz/saio).

Related

• Eyevinn/moqlivemock — MoQ test service (publisher/subscriber) using this packaging
• Eyevinn/warp-player — browser MoQ player with LOCMAF and EME/DRM support
• Live demo: https://moqlivemock.demo.osaas.io

License

MIT — see LICENSE.

Documentation

Overview

Package locmaf implements LOCMAF (Low Overhead CMAF for MOQ), a compact CMAF packaging for MoQ Transport defined by the Internet-Draft draft-einarsson-moq-locmaf.

A LOCMAF Object payload is a self-delimiting element sequence: zero or more genBox elements (pre-moof boxes such as styp, prft, and emsg, carried verbatim), exactly one full or delta moof header, and the raw mdat payload — or, alternatively, a single rawBoxes element carrying complete ISO BMFF boxes verbatim. The receiver reconstructs a functionally lossless CMAF chunk; a normative canonical reconstruction makes conformant receivers byte-identical, enabling golden-vector conformance testing.

This module is the reference implementation. EncodeCanonical produces canonical LOCMAF Objects from CMAF moof boxes (choosing full or delta headers per the canonical rules), EncodeRaw wraps complete boxes as a rawBoxes Object, Decode applies deltas and deletions against the in-group State and yields the chunk's EffectiveValues (or the raw boxes verbatim), and ReconstructCanonical builds the byte-exact canonical CMAF chunk from the effective values. AppendFramed and NextFramed implement the length-prefixed self-framed carriage used outside MOQT (the .locmaf file format). The vi64 subpackage implements the MOQT variable-length integer encoding and the zigzag signed variant that LOCMAF uses.

Specification: https://datatracker.ietf.org/doc/draft-einarsson-moq-locmaf/

Index

• Constants
• Variables
• func AppendFramed(dst, obj []byte) []byte
• func EncodeCanonical(genBoxes []GenBox, moof *mp4.MoofBox, mdatPayload []byte, prev *State, ...) ([]byte, error)
• func EncodeRaw(boxes []byte, prev *State) ([]byte, error)
• func NextFramed(data []byte) (obj, rest []byte, err error)
• func ReconstructCanonical(moov *mp4.MoovBox, eff *EffectiveValues) ([]byte, error)
• type EffectiveValues
  • func Decode(payload []byte, prev *State, moov *mp4.MoovBox) (*EffectiveValues, []byte, error)
  • func ExtractEffective(genBoxes []GenBox, moof *mp4.MoofBox, mdatPayload []byte, moov *mp4.MoovBox) (*EffectiveValues, error)
• type GenBox
• type State
  • func NewState() *State
  • func (s *State) Reset()

Constants

const (
	ElementTypeGenBox      uint64 = 1
	ElementTypeFullHeader  uint64 = 2
	ElementTypeDeltaHeader uint64 = 3
	ElementTypeRawBoxes    uint64 = 4
)

Element types. Each element of a LOCMAF Object payload begins with an element_type vi64; the mdat payload that follows the header element is untagged. A rawBoxes element is the sole element of its Object. An unknown element type is not self-delimiting and rejects the whole Object.

const Version = "0.3"

Version is the LOCMAF packaging version implemented by this package, announced in the CMSF catalog Track entry as locmafVersion.

Variables

var (
	ErrMalformed = errors.New("locmaf: malformed object")
	ErrBadSource = errors.New("locmaf: source not expressible in LOCMAF")
)

Sentinel errors. Wire-level violations that a receiver MUST reject wrap ErrMalformed; source content that cannot be expressed in LOCMAF wraps ErrBadSource.

Functions

func AppendFramed

func AppendFramed(dst, obj []byte) []byte

AppendFramed appends one LOCMAF Object to dst, prefixed by its vi64 length, and returns the extended slice.

func EncodeCanonical

func EncodeCanonical(genBoxes []GenBox, moof *mp4.MoofBox, mdatPayload []byte,
	prev *State, moov *mp4.MoovBox) ([]byte, error)

EncodeCanonical encodes one CMAF chunk as a canonical LOCMAF Object: the genBox elements, one full or delta header, and the mdat payload.

The header type follows the canonical rule: a full header when prev holds no in-group reference (the first chunk of a group) or when the source BMDT diverges from the delta derivation (a timeline discontinuity re-anchors with a full header); a delta header otherwise. prev is mutated to reflect the just-emitted chunk; it must not be nil.

func EncodeRaw

func EncodeRaw(boxes []byte, prev *State) ([]byte, error)

EncodeRaw encodes complete ISO BMFF boxes, carried verbatim, as a rawBoxes LOCMAF Object — the escape from the moof-header model for content LOCMAF does not otherwise carry: an in-band CMAF Header (ftyp + moov) in self-framed carriage, or a chunk whose moof falls outside the LOCMAF field model. boxes must be one or more complete boxes, each carrying its actual size in the 32-bit size field (the ISO size escapes 0 and 1 are not allowed). The element carries no length of its own — the Object length delimits it. A rawBoxes Object resets the in-group delta chain, so prev is Reset and the next EncodeCanonical chunk in the group emits a full header; prev must not be nil.

func NextFramed

func NextFramed(data []byte) (obj, rest []byte, err error)

NextFramed splits data into its first length-prefixed LOCMAF Object and the remaining bytes. Callers loop until rest is empty; obj is a subslice of data.

func ReconstructCanonical

func ReconstructCanonical(moov *mp4.MoovBox, eff *EffectiveValues) ([]byte, error)

ReconstructCanonical builds the canonical CMAF chunk bytes — each genBox wrapped as an ISO box, the moof, and the mdat — from the chunk's effective values and the CMAF Header's moov.

Types

type EffectiveValues

type EffectiveValues struct {
	SampleCount            int
	BMDT                   uint64
	SampleDescriptionIndex uint32

	// Per-sample vectors, each SampleCount long.
	Durations []uint32
	Sizes     []uint32
	Flags     []uint32
	CTOs      []int32

	// CENC per-sample auxiliary information. IVs is the concatenation
	// of per-sample initialization vectors, PerSampleIVSize bytes each.
	// HasSubsamples reports whether the effective subsample map is
	// present; when true, SubsampleCounts has SampleCount entries and
	// ClearBytes/ProtectedBytes are flattened in chunk order.
	PerSampleIVSize uint8
	IVs             []byte
	HasSubsamples   bool
	SubsampleCounts []uint16
	ClearBytes      []uint16
	ProtectedBytes  []uint32

	// GenBoxes render before the moof, in order. MdatPayload is the raw
	// sample data (a subslice of the decoded object payload).
	GenBoxes    []GenBox
	MdatPayload []byte
}

EffectiveValues is a decoded chunk's meaning: the per-sample vectors after applying deltas, deletions, and the sample-size and BMDT derivations. It is the only chunk-derived input to ReconstructCanonical; the remaining inputs come from the CMAF Header.

func Decode

func Decode(payload []byte, prev *State, moov *mp4.MoovBox) (*EffectiveValues, []byte, error)

Decode decodes one LOCMAF Object payload, using prev as the in-group reference for delta chunks. For a moof-carrying Object it returns the chunk's effective values and a nil raw slice; for a rawBoxes Object it returns nil effective values and the carried boxes verbatim (a subslice of payload), which are also their own canonical form. prev is mutated to reflect the decoded Object (a full header resets it first; a rawBoxes Object resets it, so the next moof-carrying Object must be full); it must not be nil. Callers use one State per MOQT group, in object order, and Reset it (or use a fresh one) at every group boundary.

On error, prev is Reset: a malformed Object is a loss of in-group sync, so subsequent delta chunks are rejected until the next full header or rawBoxes Object re-anchors, matching the receiver rule for gaps.

func ExtractEffective

func ExtractEffective(genBoxes []GenBox, moof *mp4.MoofBox, mdatPayload []byte,
	moov *mp4.MoovBox) (*EffectiveValues, error)

ExtractEffective derives a chunk's effective values directly from a source CMAF moof — resolving per-sample trun values against the tfhd and trex defaults exactly as EncodeCanonical does, with no wire round-trip. An interop harness uses it to reconstruct canonical bytes straight from source CMAF and compare them against the encode-then-decode path.

type GenBox

type GenBox struct {
	Name    string
	Payload []byte
}

GenBox is one generic pre-moof box carried verbatim: the ISO box type FourCC and the box contents without the 8-byte ISO box header. For a uuid box the 16-byte usertype is the first 16 bytes of Payload.

type State

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

State carries the per-group in-group reference that both encoder and decoder consult for delta chunks. Callers keep one State per MOQT group and Reset it (or use a fresh one) when a new group begins. A full header resets it implicitly on both sides.

func NewState

func NewState() *State

NewState returns an empty State.

func (*State) Reset

func (s *State) Reset()

Reset empties the State so the next chunk is encoded as (or must be) a full header, e.g. at the start of a new MOQT group.