# `MOQX.Catalog`
[🔗](https://github.com/dmorn/moqx/blob/main/lib/moqx/catalog.ex#L1)

Decodes CMSF catalog payloads and provides track discovery helpers.

A CMSF catalog is a UTF-8 JSON payload retrieved via `MOQX.Helpers.fetch_catalog/2`.
This module parses those raw bytes into an inspectable Elixir structure.

## Example

    {:ok, ref} = MOQX.Helpers.fetch_catalog(subscriber, namespace: "moqtail")
    {:ok, catalog} = MOQX.Helpers.await_catalog(ref, 5_000)

    catalog
    |> MOQX.Catalog.video_tracks()
    |> Enum.map(& &1.name)
    #=> ["259", "260", "261"]

The `raw` field on both `MOQX.Catalog` and `MOQX.Catalog.Track` preserves
the original JSON map for forward compatibility with fields not yet modeled
as struct keys.

# `t`

```elixir
@type t() :: %MOQX.Catalog{
  raw: map(),
  supports_delta_updates: boolean() | nil,
  tracks: [MOQX.Catalog.Track.t()],
  version: integer() | nil
}
```

# `audio_tracks`

```elixir
@spec audio_tracks(t()) :: [MOQX.Catalog.Track.t()]
```

Returns all audio tracks.

# `decode`

```elixir
@spec decode(binary()) :: {:ok, t()} | {:error, String.t()}
```

Decodes a raw CMSF catalog binary into a `%MOQX.Catalog{}`.

Accepts the raw bytes delivered by `{:moqx_fetch_object, ...}` messages.
Returns `{:ok, catalog}` on success or `{:error, reason}` on failure.

## Example

    {:ok, catalog} = MOQX.Catalog.decode(payload)
    MOQX.Catalog.video_tracks(catalog)

# `decode!`

```elixir
@spec decode!(binary()) :: t()
```

Bang variant of `decode/1`. Raises on invalid input.

# `get_track`

```elixir
@spec get_track(t(), String.t()) :: MOQX.Catalog.Track.t() | nil
```

Finds a track by exact name. Returns `nil` if not found.

# `tracks`

```elixir
@spec tracks(t()) :: [MOQX.Catalog.Track.t()]
```

Returns all tracks in the catalog.

# `tracks_by_role`

```elixir
@spec tracks_by_role(t(), String.t()) :: [MOQX.Catalog.Track.t()]
```

Returns tracks matching the given role string (e.g. `"video"`, `"audio"`).

# `video_tracks`

```elixir
@spec video_tracks(t()) :: [MOQX.Catalog.Track.t()]
```

Returns all video tracks.

---

*Consult [api-reference.md](api-reference.md) for complete listing*