FFix.Discovery (ffix v0.2.0)

Copy Markdown View Source

Inspect the codecs, formats, and filters available in an FFmpeg installation.

Use discovery to check a deployment's capabilities or build an option picker. Each query runs the selected FFmpeg executable and returns {:ok, metadata} or {:error, error}.

alias FFix.Discovery
{:ok, encoders} = Discovery.list(:encoder)
Enum.any?(encoders, fn encoder -> "libx264" in encoder.names end)

{:ok, details} = Discovery.help(:encoder, "libx264")
Enum.flat_map(details.option_sections, fn section -> section.options end)

list/2 returns a catalog. help/3 retrieves options and properties for one component. version/1 identifies the build; store it alongside results when saving a capability snapshot. Use FFix.Discovery.Parser to parse saved FFmpeg help text yourself.

Registration and usability

A listed hardware encoder may still need a compatible device and driver. Test the intended command on the target machine before relying on it.

Discovery describes the executable. To inspect tracks inside a media file, use ffprobe.

Query options

All query functions accept:

  • :ffmpeg — executable path/name; defaults to FFMPEG_BIN, then ffmpeg on PATH.
  • :timeout — non-negative milliseconds or :infinity; defaults to 10_000.
  • :max_output — non-negative capture limit in bytes; defaults to 8_388_608.

A help/3 query first checks the catalog, then requests help. Limits apply to each process. See FFix.Discovery.Error for failures and captured diagnostics.

Summary

Types

option()
result(value)

Functions

help(kind, name, options \\ [])

Fetches options and properties for a registered component or format alias.

kinds()

Returns the catalog kinds accepted by list/2. This is the list of query types supported by FFix.

list(kind, options \\ [])

Lists the entries in an FFmpeg capability catalog.

shared(options \\ [])

Fetches general codec, format, and I/O options from FFmpeg's full help.

version(options \\ [])

Returns the FFmpeg version, build configuration, library versions, original text, and resolved executable path.

Types

option()

@type option() ::
  {:ffmpeg, String.t()}
  | {:timeout, timeout()}
  | {:max_output, non_neg_integer()}

result(value)

@type result(value) :: {:ok, value} | {:error, FFix.Discovery.Error.t()}

Functions

help(kind, name, options \\ [])

@spec help(atom(), String.t(), [option()]) :: result(map())

Fetches options and properties for a registered component or format alias.

FFix.Discovery.help(:muxer, "mp4")

Supported kinds are :encoder, :decoder, :muxer, :demuxer, :filter, :bitstream_filter, and :protocol. Inspect a device backend through its :demuxer or :muxer entry.

Help contains ordered option_sections and properties; see FFix.Discovery.Parser for their representation. A component may have an empty option list. Errors distinguish an absent registration (:not_found) from a registration whose help is unavailable (:help_unavailable).

kinds()

@spec kinds() :: [atom()]

Returns the catalog kinds accepted by list/2. This is the list of query types supported by FFix.

list(kind, options \\ [])

@spec list(atom(), [option()]) :: result([map()])

Lists the entries in an FFmpeg capability catalog.

FFix.Discovery.list(:filter)
FFix.Discovery.list(:muxer, ffmpeg: "/usr/local/bin/ffmpeg")

Component catalogs: :encoder, :decoder, :codec, :muxer, :demuxer, :format, :device, :filter, :bitstream_filter, and :protocol. Other catalogs: :pixel_format, :sample_format, :channel, :channel_layout, :hardware_acceleration, :disposition, and :color.

Entries contain a names list, retaining aliases, plus the catalog's properties. Names are scoped by kind: input-format aliases need not be output-format aliases. :device lists supported device backends rather than connected physical devices.

shared(options \\ [])

@spec shared([option()]) :: result([map()])

Fetches general codec, format, and I/O options from FFmpeg's full help.

Returns separate sections for AVCodecContext, AVFormatContext, AVIOContext, and URLContext. Keep section names when displaying options: the same option name may have different meanings in different sections.

version(options \\ [])

@spec version([option()]) :: result(map())

Returns the FFmpeg version, build configuration, library versions, original text, and resolved executable path.