ExCubecl.Media (ExCubecl v0.4.0)

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)

Summary

Types

source()

stream_info()

Functions

close(src)

Closes the media source and releases all associated resources.

open(path)

Opens a media source for reading.

read_frame(src, atom)

Reads the next decoded frame from the media source.

streams(src)

Returns metadata for all streams in the media source.

Types

source()

@type source() :: reference()

stream_info()

@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()
}

Functions

close(src)

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

Closes the media source and releases all associated resources.

open(path)

@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(src, atom)

@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(src)

@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).