@spec concat([input_source()], Path.t(), [concat_opt()]) ::
  {:ok, concat_stats()} | {:error, Exmpeg.Error.t()}

Joins inputs into a single output without re-encoding.

Every input must share the same stream layout (same number of streams and same codec id per stream index). Mismatches return {:error, %Error{reason: :invalid_request}}.

PTS / DTS values are shifted by the cumulative duration of preceding inputs so the resulting timeline is monotonic.

Returns

%{packets_written: 3456, inputs_joined: 3, streams_copied: 2, duration_s: 6.04}

@spec extract_audio(input_source(), Path.t(), [extract_audio_opt()]) ::
  {:ok, extract_audio_stats()} | {:error, Exmpeg.Error.t()}

Decodes the best audio stream of input and writes it to output.

The encoder is picked from the output extension:

Options

• :sample_rate - target sample rate in Hz (default: source). For codecs that only accept a fixed list of rates (libopus snaps to [8000, 12000, 16000, 24000, 48000]), the closest supported rate is used.
• :channels - 1 for mono or 2 for stereo. Defaults to the source layout when the source is mono or stereo; sources with more channels (5.1, 7.1, ...) require an explicit value and otherwise return :invalid_request.
• :bitrate - target bitrate in bps. Ignored by lossless codecs (pcm_s16le, flac); used as a quality hint for the lossy codecs.

Returns

%{
  sample_rate: 16_000,
  channels: 1,
  samples_written: 32_322,
  duration_s: 2.020125,
  codec: "pcm_s16le"
}

@spec extract_frame(input_source(), Path.t(), [extract_frame_opt()]) ::
  {:ok, extract_frame_stats()} | {:error, Exmpeg.Error.t()}

Decodes one video frame from input at :timestamp_s (default 0.0) and writes it as an image at output.

The output codec is inferred from the extension:

• .jpg / .jpeg -> MJPEG
• .png -> PNG
• .bmp -> BMP
• .webp -> WebP

Options

• :timestamp_s - capture point in seconds (default 0.0). The decoder seeks to the preceding keyframe and decodes forward, so the actually-returned timestamp may be a few hundred milliseconds early or late depending on the GOP structure. The exact pts of the returned frame is reported in the result map.
• :width / :height - resize to this size in pixels. When only one dimension is given the other is computed to preserve the source aspect ratio. Both are rounded down to the nearest even value so the encoder's pixel format requirements are met.

Returns

%{width: 1280, height: 720, timestamp_s: 1.501, pts_known: true, codec: "mjpeg"}

@spec load_buffer(binary()) :: {:ok, Exmpeg.Buffer.t()} | {:error, Exmpeg.Error.t()}

Loads binary into a reusable Exmpeg.Buffer for in-memory input.

The bytes are copied once into a refcounted native resource. Passing the returned buffer to several operations (e.g. probe/1 then transcode/3, or as repeated concat/3 inputs) reuses that one copy instead of re-copying the binary on every call, which {:memory, _} does. Prefer this over {:memory, _} when the same bytes feed more than one call.

{:ok, buf} = Exmpeg.load_buffer(File.read!("clip.mp4"))
{:ok, info} = Exmpeg.probe(buf)
{:ok, _} = Exmpeg.extract_audio(buf, "out.opus")

@spec probe(input_source()) ::
  {:ok, Exmpeg.MediaInfo.t()} | {:error, Exmpeg.Error.t()}

Probes path and returns container / stream metadata.

Reads the file with avformat_open_input + avformat_find_stream_info, so the result reflects what the FFmpeg demuxer actually sees - not what the file extension suggests.

@spec remux(input_source(), Path.t(), [remux_opt()]) ::
  {:ok, remux_stats()} | {:error, Exmpeg.Error.t()}

Stream-copies input to output without re-encoding.

Every input stream is added to the output container with codec parameters preserved verbatim. The output container is inferred from the file extension (.mp4, .mkv, .mov, ...). A muxer / codec combination that the FFmpeg build does not support returns {:error, %Error{reason: :unsupported}}.

Options

• :start_s - drop packets whose pts is earlier than this offset (in seconds). The result is not keyframe-aligned: video that does not start on a keyframe will be unplayable until the next keyframe.
• :duration_s - stop after this many seconds past :start_s.

Returns

A stats map of what the muxer accepted:

%{packets_written: 1234, packets_dropped: 0, streams_copied: 2}

@spec transcode(input_source(), Path.t(), [transcode_opt()]) ::
  {:ok, transcode_stats()} | {:error, Exmpeg.Error.t()}

Re-encodes input to output with per-stream codec selection.

Each stream is either copied or re-encoded based on the corresponding :video_codec / :audio_codec option. "copy" (or an omitted option) preserves the source codec; any other value is resolved through avcodec_find_encoder_by_name - if FFmpeg wasn't built with that encoder, the call returns {:error, %Error{reason: :unsupported}}.

Options

• :video_codec / :audio_codec - encoder short name (default "copy").
• :video_bitrate / :audio_bitrate - target bitrate in bps.
• :width / :height - output video size in pixels. Specifying one derives the other from the source aspect ratio. Always rounded down to the nearest even value.
• :fps - target framerate as {num, den}. Defaults to the source.
• :sample_rate - target audio sample rate in Hz.
• :channels - 1 (mono) or 2 (stereo). A mono or stereo source is carried through when omitted; a source with more than 2 channels (5.1, 7.1, ...) requires an explicit value rather than being silently downmixed, and returns {:error, %Error{reason: :invalid_request}} otherwise. Applies only when the audio stream is re-encoded.

Returns

%{
  streams_copied: 0,
  streams_reencoded: 2,
  packets_written: 312,
  duration_s: 2.04
}

@spec version() ::
  {:ok,
   %{
     avformat: String.t(),
     avcodec: String.t(),
     avutil: String.t(),
     license: String.t(),
     configuration: String.t()
   }}
  | {:error, Exmpeg.Error.t()}

Returns the version of every FFmpeg sub-library this NIF is linked against, plus the ./configure flags used to build them.

iex> {:ok, %{avformat: avformat}} = Exmpeg.version()
iex> String.match?(avformat, ~r/^\d+\.\d+\.\d+$/)
true