MOQX.Catalog (moqx v0.10.0)

A decoded CMSF or HANG catalog.

CMSF preserves the Cloudflare and Moqtail initialization conventions in normalized tracks and the original raw map. HANG uses typed media sections keyed by :audio/:video, with rendition tracks, decoder bytes, container initialization and extension maps. tracks is a flattened view; HANG encoding uses media and extensions, while CMSF encoding uses raw.

HANG is pinned to the specification revision in docs/interop/hang-lite05.md. Unknown codecs and containers are preserved with an explicit metadata status; recognition does not imply playback support. Timeline retrieval and media decoding belong to the caller.

Summary

Types

decode_option()

t()

Functions

decode(payload, options \\ [])

Decodes one supported catalog into protocol-neutral values.

encode(catalog, options \\ [])

Encodes a typed catalog. HANG media fields and extension maps are authoritative.

h264_tracks(catalog)

Returns H.264/AVC tracks ordered from highest to lowest advertised resolution.

select_h264(catalog)

Selects the highest-resolution advertised H.264/AVC track.

track_ref(catalog, track)

Builds the protocol-neutral address of one track in this catalog.

Types

decode_option()

@type decode_option() ::
  {:format, :cloudflare | :moqtail_cmsf | :hang}
  | {:namespace, [binary()]}
  | {:compression, :none | :deflate}
  | {:max_bytes, pos_integer()}
  | {:max_encoded_bytes, pos_integer()}

t()

@type t() :: %MOQX.Catalog{
  common_track_fields: map(),
  extensions: map(),
  format: :cloudflare | :moqtail_cmsf | :hang,
  media: %{optional(:audio | :video) => MOQX.Catalog.Media.t()},
  namespace: [binary()] | nil,
  raw: map(),
  streaming_format: non_neg_integer() | nil,
  streaming_format_version: binary() | nil,
  supports_delta_updates: boolean() | nil,
  tracks: [MOQX.Catalog.Track.t()],
  version: non_neg_integer() | nil
}

Functions

decode(payload, options \\ [])

@spec decode(binary(), [decode_option()]) ::
  {:ok, t()} | {:error, MOQX.Catalog.Error.t()}

Decodes one supported catalog into protocol-neutral values.

Select format: :hang explicitly; CMSF callers may use shape inference. Both encoded input and expanded JSON default to a 1 MiB limit. Override with positive :max_encoded_bytes and :max_bytes. compression: :deflate uses HANG raw DEFLATE sync-flush framing, not gzip or a zlib container. :namespace anchors relative HANG broadcast references. Above-root or unanchored references remain explicit address errors in the track.

encode(catalog, options \\ [])

@spec encode(t(), keyword()) :: {:ok, binary()} | {:error, MOQX.Catalog.Error.t()}

Encodes a typed catalog. HANG media fields and extension maps are authoritative.

h264_tracks(catalog)

@spec h264_tracks(t()) :: [MOQX.Catalog.Track.t()]

Returns H.264/AVC tracks ordered from highest to lowest advertised resolution.

CMSF requires supported packaging and initialization metadata. HANG uses its typed decoder dimensions and known legacy, loc, or cmaf containers; unknown codecs/containers are excluded. This selects advertised metadata, not a guarantee of decoder or MOQX.CMAF.capture/4 support. Ties use bitrate descending, then track name ascending.

select_h264(catalog)

@spec select_h264(t()) ::
  {:ok, MOQX.Catalog.Track.t()} | {:error, :h264_track_not_found}

Selects the highest-resolution advertised H.264/AVC track.

track_ref(catalog, track)

@spec track_ref(t(), MOQX.Catalog.Track.t()) :: MOQX.TrackRef.t() | {:error, atom()}

Builds the protocol-neutral address of one track in this catalog.