Canonical representation of a full ffmpeg command.
A command stores global options, ordered inputs, an optional filtergraph, and
ordered outputs. It is still just data until FFix.to_argv/1, FFix.run/1, or
another boundary function serializes it.
Prefer FFix.command/3 for the function-based API. Use this module directly
when you want to construct or transform %FFix.Command{} values in smaller
steps.
Examples
input = FFix.Command.input("input.mp4", ss: "00:00:03", stream_loop: -1)
video = input[:video]
command =
FFix.Command.new(
global: [y: true],
inputs: [input],
outputs: [FFix.Command.output("out.mp4", video, vcodec: :copy)]
)
FFix.to_argv(command)
#=> [
#=> "ffmpeg",
#=> "-y",
#=> "-ss",
#=> "00:00:03",
#=> "-stream_loop",
#=> "-1",
#=> "-i",
#=> "input.mp4",
#=> "-map",
#=> "0:v",
#=> "-vcodec",
#=> "copy",
#=> "out.mp4"
#=> ]Output option keys are rendered as ffmpeg CLI option names. For options with
stream specifiers, use an atom or string key that already contains the
specifier, for example :"c:v" or "metadata:s:a:0".
Summary
Construction
Appends global ffmpeg options to a command.
Returns an empty command.
Builds a command from already-normalized command data.
Inputs
Builds an input declaration.
Builds an input with options, or appends an input to a command.
Appends an input declaration with options to a command.
Filtergraph
Sets the filtergraph for a command.
Outputs
Builds an output declaration from explicit sources.
Builds an output with options, or appends an output to a command.
Appends an output declaration with options to a command.
Validation
Validates command structure.
Serialization
Serializes a command to ffmpeg argv.
Serializes a command as a shell-escaped string for logs and debugging.
Construction
Appends global ffmpeg options to a command.
Global options are rendered before inputs:
FFix.Command.new()
|> FFix.Command.global(y: true, loglevel: :error)@spec new() :: t()
Returns an empty command.
This is useful when building a command step by step with global/2,
input/3, graph/2, and output/4.
Builds a command from already-normalized command data.
This lower-level constructor expects ordered input and output structs. For the
function callback API, use FFix.command/3.
src = FFix.Command.input("input.mp4")
FFix.Command.new(
inputs: [src],
outputs: [FFix.Command.output("out.mp4", src[:video], "c:v": :copy)]
)Inputs
@spec input(FFix.Command.Input.source()) :: FFix.Command.Input.t()
Builds an input declaration.
Input options are rendered before -i:
src = FFix.Command.input("input.mp4", ss: "00:00:03")
src[:video]
src[:audio]Prefer shaping inputs in FFix.command/3 rather than storing labels on the
input itself.
@spec input( FFix.Command.Input.source(), keyword() ) :: FFix.Command.Input.t()
@spec input(t(), FFix.Command.Input.source()) :: t()
Builds an input with options, or appends an input to a command.
Called as input(source, options), it returns an %FFix.Command.Input{}:
src = FFix.Command.input("input.mp4", ss: "00:00:03")Called as input(command, source), it appends an input without options and
returns the updated command:
FFix.Command.new()
|> FFix.Command.input("input.mp4")@spec input(t(), FFix.Command.Input.source(), keyword()) :: t()
Appends an input declaration with options to a command.
FFix.Command.new()
|> FFix.Command.input("input.mp4", ss: "00:00:03")Filtergraph
@spec graph(t(), FFix.Graph.t()) :: t()
Sets the filtergraph for a command.
Outputs
@spec output(FFix.Command.Output.target(), source() | [source()]) :: FFix.Command.Output.t()
Builds an output declaration from explicit sources.
This is lower-level than FFix.output/2: pass graph exports, graph export names,
graph export indexes, or direct input streams explicitly.
src = FFix.Command.input("input.mp4")
FFix.Command.output("copy.mp4", [src[:video], src[:audio]], c: :copy)Output options are rendered after -map entries and before the target.
@spec output(FFix.Command.Output.target(), source() | [source()], keyword()) :: FFix.Command.Output.t()
@spec output(t(), FFix.Command.Output.target(), source() | [source()]) :: t()
Builds an output with options, or appends an output to a command.
Called as output(target, sources, options), it returns an
%FFix.Command.Output{}:
FFix.Command.output("copy.mp4", [src[:video], src[:audio]], c: :copy)Called as output(command, target, sources), it appends an output without
options and returns the updated command.
Appends an output declaration with options to a command.
FFix.Command.new()
|> FFix.Command.input("input.mp4")
|> FFix.Command.output("copy.mp4", 0, c: :copy)Validation
Serialization
Serializes a command to ffmpeg argv.
The returned list is the canonical boundary for executing a command. Prefer it over shell strings when passing argv to another process.
Serializes a command as a shell-escaped string for logs and debugging.
Types
@type source() :: FFix.Graph.Export.t() | FFix.Stream.t() | atom() | non_neg_integer()
@type t() :: %FFix.Command{ global_options: [option()], graph: FFix.Graph.t() | nil, inputs: [FFix.Command.Input.t()], outputs: [FFix.Command.Output.t()] }