# `ExCubecl.Media`
[🔗](https://github.com/ohhi-vn/ex_cubecl/blob/v0.4.0/lib/ex_cubecl/media.ex#L1)

Media I/O — open, inspect, read frames, and close media sources.

Supports files, RTMP streams, HLS playlists, and camera devices.
Under the hood, FFmpeg (via Rust NIFs) handles demuxing and decoding.

## Examples

    {:ok, src} = ExCubecl.Media.open("input.mp4")
    {:ok, src} = ExCubecl.Media.open("rtmp://live/stream")

    ExCubecl.Media.streams(src)
    # => [%{index: 0, type: :video, codec: :h264, fps: 30, width: 1920, height: 1080},
    #     %{index: 1, type: :audio, codec: :aac, sample_rate: 44100, channels: 2}]

    {:ok, frame} = ExCubecl.Media.read_frame(src, :video)
    {:ok, samples} = ExCubecl.Media.read_frame(src, :audio)

    :ok = ExCubecl.Media.close(src)

# `source`

```elixir
@type source() :: reference()
```

# `stream_info`

```elixir
@type stream_info() :: %{
  index: non_neg_integer(),
  type: :video | :audio,
  codec: atom(),
  fps: float(),
  width: non_neg_integer(),
  height: non_neg_integer(),
  sample_rate: non_neg_integer(),
  channels: non_neg_integer()
}
```

# `close`

```elixir
@spec close(source()) :: :ok | {:error, term()}
```

Closes the media source and releases all associated resources.

# `open`

```elixir
@spec open(String.t()) :: {:ok, source()} | {:error, term()}
```

Opens a media source for reading.

Accepts file paths, URLs (RTMP, HLS), or device identifiers.

## Examples

    {:ok, src} = ExCubecl.Media.open("input.mp4")
    {:ok, src} = ExCubecl.Media.open("rtmp://live/stream")

# `read_frame`

```elixir
@spec read_frame(source(), :video | :audio) ::
  {:ok, ExCubecl.VideoFrame.t() | ExCubecl.AudioSamples.t()} | {:error, term()}
```

Reads the next decoded frame from the media source.

Pass `:video` to get a `VideoFrame`, or `:audio` to get `AudioSamples`.

## Examples

    {:ok, %VideoFrame{} = frame} = ExCubecl.Media.read_frame(src, :video)
    {:ok, %AudioSamples{} = samples} = ExCubecl.Media.read_frame(src, :audio)

# `streams`

```elixir
@spec streams(source()) :: {:ok, [stream_info()]} | {:error, term()}
```

Returns metadata for all streams in the media source.

Each stream map contains `:index`, `:type`, `:codec`, and type-specific fields
(`:width`/`:height`/`:fps` for video, `:sample_rate`/`:channels` for audio).

---

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