Build and run FFmpeg commands in Elixir.

Use FFix to convert media, extract tracks, choose codecs and containers, or process audio and video with filters. Start with inputs and outputs; add a filter pipeline when you need to change the picture or sound.

You will need FFmpeg on your PATH to run these examples. See FFix.Runner to choose another executable.

Your first command

Extract the first audio track from an interview into a WAV file:

command =
  FFix.input("interview.mp4")
  |> FFix.audio(0)
  |> FFix.output("interview.wav")
  |> FFix.command()

FFix.run!(command)

An input file can contain several streams: video, audio tracks, subtitles, and more. audio(input, 0) selects the first audio stream; indexes start at zero. FFmpeg chooses the WAV format and its default encoder from the filename.

There are two deliberate steps at the end. An output describes what to write and where. A command brings the outputs and their inputs together. Building either is just preparation; run!/2 starts FFmpeg.

Choose a codec and a container

An encoder compresses the media. A muxer packages streams into a container, such as MP4 or Matroska. Here, AAC is the audio codec and MP4 is the container used for the .m4a file:

alias FFix.{Encoder, Muxer}

command =
  FFix.input("interview.wav")
  |> FFix.audio(0)
  |> Encoder.aac(b: "128k")
  |> Muxer.mp4("interview.m4a")
  |> FFix.command()

FFix.run!(command)

b: "128k" sets the audio bitrate to 128 kbit/s. An encoder can be used directly on an input stream: filtering is optional. See FFix.Encoder for quality and bitrate settings, and FFix.Muxer for format-specific options.

Copy streams without re-encoding

When the existing codecs suit the destination, stream copy is faster and preserves the encoded media. This example puts an MP4's first video track and all its audio tracks into a Matroska file:

source = FFix.input("interview.mp4")

output =
  FFix.output(
    [
      FFix.stream_copy(FFix.video(source, 0)),
      FFix.stream_copy(FFix.audio(source, :all))
    ],
    "interview.mkv"
  )

FFix.command(output) |> FFix.run!()

:all selects every stream of that media type. See stream_copy/1 for format compatibility and FFix.Command.Input for selecting optional tracks.

Add a filter

Filters work on decoded pictures or sound. Apply them before choosing the output encoder. Here we resize a video while copying its audio:

alias FFix.{Encoder, Filter, Muxer}
source = FFix.input("interview.mp4")

picture =
  source
  |> FFix.video(0)
  |> Filter.scale(w: 1280, h: -2)
  |> Encoder.libx264(crf: 23, preset: "medium")

output =
  Muxer.mp4(
    [picture, FFix.stream_copy(FFix.audio(source, 0))],
    "interview-small.mp4",
    movflags: [:faststart]
  )

FFix.command(output) |> FFix.run!()

h: -2 keeps the aspect ratio and gives the height an even number of pixels. crf controls video quality; lower values mean higher quality and usually larger files. faststart helps an MP4 begin playing before its download finishes. This example assumes an audio track compatible with MP4; use FFix.Encoder.aac/2 instead of stream copy when you need AAC audio.

Explore FFix.Filter for cropping, overlays, audio processing, and combining streams.

Write several outputs

Pass an ordered list of outputs to command/2. Reuse an input declaration to read it once, even when outputs use different encoders or settings.

This video-only example scales once, then splits the filtered pictures into a full-size rendition and a small preview:

alias FFix.{Encoder, Filter, Muxer}
source = FFix.input("interview.mp4")

[main, preview] =
  source
  |> FFix.video(0)
  |> Filter.scale(w: 1280, h: -2)
  |> Filter.split(outputs: 2)

main_output = Muxer.mp4(Encoder.libx264(main, crf: 20), "main.mp4")

preview_output =
  preview
  |> Filter.scale(w: 320, h: -2)
  |> Encoder.libx264(crf: 28)
  |> Muxer.mp4("preview.mp4")

FFix.command([main_output, preview_output]) |> FFix.run!()

A filtered stream needs a split to feed two branches. Direct input streams can be reused as they are. Outputs can also use entirely different inputs. They still run in one FFmpeg process; use separate commands when jobs need independent cancellation or retries.

Inspect, run, and learn more

Inspect a command before executing it:

FFix.to_shell_string(command)
FFix.to_argv(command)

run/2 returns {:ok, result} or {:error, error}. run!/2 returns the result or raises on execution failure. Both accept runner options such as ffmpeg: "/usr/local/bin/ffmpeg" and stderr: :collect.

• FFix.Command.Input: stream selection and input options.
• FFix.Command.Output: mapping order and named output-option callbacks.
• FFix.Demuxer and FFix.Decoder: explicit input formats and decoding settings.
• FFix.Graph: parse and reuse filtergraphs.
• FFix.Runner: progress events, piping media, and handling failures.
• FFix.Discovery: find the codecs, formats, and filters in your FFmpeg build.

The FFmpeg command guide is a useful companion when you need the meaning of a particular FFmpeg option.