FFix - build ffmpeg commands and filter graphs in Elixir

Your Libraries & OS Mentoring Libraries
, ,
1

Hi everyone,

I made a small Elixir library called FFix.

FFix helps you build ffmpeg commands and filter graphs using Elixir data and functions, instead of manually joining long -filter_complex, -map, and option strings.

It does not try to hide ffmpeg. Filter names, options, stream mappings, codecs, and muxer options are still ffmpeg-shaped. FFix just gives you a nicer way to compose and inspect them from Elixir.

Examples

Examples assume import FFix and import FFix.Filter.

cmd =
  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
  )

FFix.to_argv(cmd)

This builds a command like:

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

A more useful example is when the filter graph starts branching.

This creates a vertical video from a normal landscape video. It splits the video into two branches: one branch becomes a blurred background, and the other is scaled and placed on top.

cmd =
  command(
    "input.mp4",
    fn src ->
      [bg_src, fg_src] = split(src[:video], outputs: 2)

      bg =
        bg_src
        |> scale(w: 1080, h: 1920, force_original_aspect_ratio: :increase)
        |> crop(w: 1080, h: 1920)
        |> gblur(sigma: 30)

      fg =
        fg_src
        |> scale(w: 1080, h: -1)

      bg
      |> overlay(fg, x: expr("(W-w)/2"), y: expr("(H-h)/2"))
    end,
    fn video, src ->
      output("vertical.mp4",
        video: video,
        audio: src[:audio],
        "c:v": :libx264,
        "c:a": :copy,
        shortest: true
      )
    end
  )

The same thing in raw ffmpeg form is roughly:

ffmpeg -i input.mp4 \
  -filter_complex "\
[0:v]split=outputs=2[bg_src][fg_src];\
[bg_src]scale=w=1080:h=1920:force_original_aspect_ratio=increase,crop=w=1080:h=1920,gblur=sigma=30[bg];\
[fg_src]scale=w=1080:h=-1[fg];\
[bg][fg]overlay=x=(W-w)/2:y=(H-h)/2[outv]" \
  -map "[outv]" \
  -map 0:a \
  -c:v libx264 \
  -c:a copy \
  -shortest \
  vertical.mp4

FFix is mostly useful when these commands are not static strings, and you need to build them from user input, stored config, templates, or application logic.

It also supports streaming. For example, this reads WAV data through stdin and streams MP3 data back through stdout:

cmd =
  command(
    input(:stdin, f: :wav),
    fn src ->
      src[:audio]
    end,
    fn audio ->
      output(:stdout,
        audio: audio,
        f: :mp3,
        "c:a": :libmp3lame
      )
    end
  )

cmd
|> FFix.stream!(stdin: File.stream!("input.wav", [], 8192))
|> Stream.filter(fn
  {:stdout, _chunk} -> true
  _event -> false
end)
|> Stream.map(fn {:stdout, chunk} -> chunk end)
|> Enum.into(File.stream!("output.mp3", [:write, :binary]))

And one command can write multiple outputs. For example, generate MP4 and WebM versions from the same input:

cmd =
  command(
    "input.mov",
    fn src ->
      [src[:video], src[:audio]]
    end,
    fn [video, audio] ->
      [
        output("video.mp4",
          video: video,
          audio: audio,
          "c:v": :libx264,
          "c:a": :aac,
          movflags: [:faststart]
        ),

        output("video.webm",
          video: video,
          audio: audio,
          "c:v": :"libvpx-vp9",
          "c:a": :libopus
        )
      ]
    end
  )

Some things FFix supports today:

  • Build ffmpeg commands and filter graphs with Elixir data/functions instead of raw string assembly.
  • Generated helpers and docs for ffmpeg filters like scale, crop, overlay, drawtext, fps, etc.
  • Named graph outputs, multiple inputs/outputs, and stream selectors like src[:video], src[:audio], src[audio: 1].
  • Parsing and serializing filter graphs.
  • to_argv/1 for the command boundary, plus a thin runner for stdin/stdout streaming, collected results, progress events, and ffmpeg logs.

For more details, the docs have the full API and more examples. There is an intro Livebook too.

The goal is to stay close to ffmpeg and keep the core simple. FFix models commands and filter graphs as normal Elixir data, and only serializes them to ffmpeg syntax at the boundary. I’ve used some version of this library for my own ffmpeg tasks for a few years. It was sitting in my backlog for a long time, so I finally cleaned it up and organised it with some help from an LLM agent.

Feedback is very welcome, especially on the API shape and scope.

Install:

def deps do
  [
    {:ffix, "~> 0.1.0"}
  ]
end

Note: ffmpeg must be available at compile time, because FFix generates filter helpers/docs from local ffmpeg metadata.

Links:

13 Likes
2

Uses pipes to pass arguments to ffmpeg is a nice way.

1 Like