# `FFix.Discovery`
[🔗](https://github.com/akash-akya/ffix/blob/v0.2.0/lib/ffix/discovery.ex#L1)

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 {: .info}
> 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](https://ffmpeg.org/ffprobe.html).

## 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.

# `option`

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

# `result`

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

# `help`

```elixir
@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`

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

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

# `list`

```elixir
@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`

```elixir
@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`

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

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

---

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