Build ffmpeg filtergraphs and commands from Elixir.

The usual workflow is:

• pass input sources to command/3
• build streams with generated FFix.Filter helpers
• map streams to outputs with output/2
• serialize with to_argv/1 or execute with run/2

use FFix imports the top-level helpers plus generated filter functions. Callbacks receive and return ordinary Elixir values. Examples in this module assume use FFix; without it, call FFix.command/3, FFix.output/2, and FFix.Filter functions directly.

Quick Start

command/3 is the usual entry point. Pass an input source, build filtered streams in the first callback, and map streams to an output target in the second callback:

command(
  "input.mp4",
  fn src ->
    src[:video] |> crop(w: 720, h: 720)
  end,
  fn cropped, src ->
    output("square.mp4", video: cropped, audio: src[:audio])
  end
)

This reads input.mp4, crops the video stream, maps the original audio stream, and writes square.mp4.

Choosing an API Layer

• FFix.command/3 is the main API for building ffmpeg commands.
• FFix.Command is for constructing or transforming command structs.
• FFix.Graph is for parsing, serializing, or reusing filtergraphs.
• FFix.Runner is the execution boundary for running commands and streaming events.

Command Model

A command has three parts:

• input - where media comes from, such as "input.mp4" or :stdin
• graph - stream selection and filters; filters become -filter_complex
• output - stream mappings, output options, and the output target

In FFix, a file path is not itself a stream. The graph callback receives an input value, and you select streams from it:

src[:video]
src[:audio]
src[audio: 1]

Filters consume streams and produce new streams:

cropped = src[:video] |> crop(w: 720, h: 720)

output/2 declares an ffmpeg output. The first argument is the output target or file, and video:, audio:, or sources: decide which streams are mapped into it.

output("square.mp4", video: cropped, audio: src[:audio])

The flow is:

input source        graph callback                output callback
------------        --------------                ---------------
"input.mp4"  --->   src[:video] |> crop(...) ---> video: cropped
                    src[:audio] ---------------> audio: src[:audio]

output target: "square.mp4"

FFix builds an Elixir command model and translates it to ffmpeg argv. ffmpeg still does the demuxing, decoding, filtering, encoding, and muxing.

The quick-start example is shaped like this ffmpeg command:

ffmpeg -i input.mp4 \
  -filter_complex '[0:v]crop=w=720:h=720[out0]' \
  -map '[out0]' \
  -map 0:a \
  square.mp4

Labels such as [out0] are generated by FFix; they are implementation details, not names you normally need to manage.

When no filtering is needed, return input streams directly:

command(
  "input.mp4",
  fn src ->
    [src[:video], src[:audio]]
  end,
  fn [video, audio] ->
    output("copy.mp4", video: video, audio: audio, c: :copy)
  end
)

Command Callbacks

The graph callback receives inputs in the shape you passed, with sources normalized to %FFix.Command.Input{} values. The output callback receives graph exports in the same shape returned by the graph callback.

For multiple graph results, return a list. The output callback can return one output or a list of outputs, so one ffmpeg command can write multiple targets:

command(
  "input.mp4",
  fn src ->
    [
      src[:video] |> scale(w: 1280, h: -1),
      src[:video] |> fps(fps: 1)
    ]
  end,
  fn [main, preview], src ->
    [
      output("main.mp4", video: main, audio: src[:audio]),
      output("thumb-%03d.jpg", video: preview, f: :image2)
    ]
  end
)

Use keyword lists or maps when names make a larger graph easier to read:

command(
  [src: input("input.mp4")],
  fn inputs ->
    [
      main: inputs[:src][:video] |> scale(w: 1280, h: -1)
    ]
  end,
  fn [main: main], inputs ->
    output("out.mp4",
      video: main,
      audio: inputs[:src][:audio],
      "c:v": :libx264,
      "c:a": :aac
    )
  end
)

Input and graph shapes are preserved at the callback boundary:

• term -> term
• [term] -> [term]
• keyword -> keyword
• map -> map

A graph callback may also return a %FFix.Graph{} when you need graph settings or terminals. An outputs callback may accept one argument for graph exports or two arguments for graph exports and inputs.

Options

Put each kind of option where ffmpeg expects it:

command(
  input("input.mp4", ss: "00:00:05"),
  fn src ->
    src[:video] |> scale(w: 1280, h: -1)
  end,
  fn video, src ->
    output("out.mp4",
      video: video,
      audio: src[:audio],
      "c:v": :libx264,
      "c:a": :aac,
      movflags: [:faststart]
    )
  end,
  global: [y: true, loglevel: :error]
)

This maps to the usual ffmpeg placement:

global options -> before inputs
input options  -> before -i
filter options -> inside -filter_complex
output options -> before the output target

Output options are intentionally ffmpeg-shaped and flat for now. Encoding and muxer options such as "c:v", "c:a", f:, and movflags: belong in output/2.

Copying is still ffmpeg's rule: direct input streams can usually be copied, but filtered streams must be encoded again. When mixing them, set codecs per stream:

output("out.mp4",
  video: scaled,
  audio: src[:audio],
  "c:v": :libx264,
  "c:a": :copy
)

Output Mapping

Use video: and audio: for common mappings:

output("out.mp4", video: main, audio: src[:audio])

Use sources: when -map ordering matters:

output("archive.mkv",
  sources: [main, src[audio: 1], src[audio: 0]]
)

Output options are intentionally ffmpeg-shaped. Keys are rendered as CLI option names, so stream-specific options can use quoted atoms or strings such as "c:v" and "metadata:s:a:0".

Boundaries

validate!/1 performs structural checks only. It does not probe media files or ask ffmpeg to validate the command.

to_argv/1 is the canonical serialization boundary. to_shell_string/1 is useful for logs, but argv should be preferred when executing.