title: Command, Input, Output and FrameJob fields description: Every field of afmpeg's job types: what it means, what it defaults to, the builder option that sets it, and what is rejected. date: 2026-08-02 tags: [reference, command, job-spec, fields] authors: [Matt Cockayne matt@phpboyscout.uk]

Command, Input, Output and FrameJob fields¶

The declarative job types and every field on them. A Command is plain data: fill the struct directly, or build it with NewCommand and the functional options. Both produce the same value, and JobSpec() renders either to the JSON the ffmpeg-wasi engine consumes.

Task-shaped versions of this material live in the how-to guides; this page is the field list.

Command¶

type Command struct {
    Inputs        []Input
    FilterComplex string
    Outputs       []Output
}

JobSpec() is pure (no I/O), so it is safe to render and log a job before running it. RunJob(ctx, fs, cmd) is Run with the rendered spec.

Input¶

type Input struct {
    Path    string
    Concat  []string
    Seek    *Seek
    Format  string
    Options map[string]string
}

An option key the demuxer does not consume is an error from the engine, not a silent no-op. A misspelled pixel_fmt fails the job rather than producing wrong output.

Seek¶

type Seek struct {
    Start float64 // seconds
    Mode  string  // SeekFast (default when empty) or SeekAccurate
}

SeekAccurate cannot feed a copied stream. A stream copy can only cut on keyframes, so Command.JobSpec() rejects the combination before the engine sees it:

afmpeg: output "out.mp4" maps copied stream "0:v" from an accurate-seek input
(copy cuts on keyframes; use SeekFast)

Output¶

type Output struct {
    Path             string
    Map              []string
    VideoCodec       string
    AudioCodec       string
    SubtitleCodec    string
    Options          map[string]string
    BitstreamFilters map[string]string
    Duration         float64
    End              float64
    CopyTS           bool
    Format           string
    FormatOptions    map[string]string
    Metadata         map[string]string
    Chapters         string
    StreamMetadata   map[string]StreamMeta
}

Fields with no builder option are set on the struct. Both forms are first-class. The builder covers the common ones, the struct covers all of them.

Option names¶

Options, FormatOptions and Input.Options are libav option dictionaries. They are not ffmpeg command-line flags, and the two vocabularies differ in ways that are easy to miss:

An option name that no encoder on the output has fails the job rather than being ignored, so a misspelling is loud. Two things that check cannot cover:

• Options reaches every encoder the output opens. On an output with both VideoCodec and AudioCodec, {"crf": "23"} is offered to the audio encoder too, and aac refuses it, so the job fails even though the option was meant for the video encoder. Address it with VideoOptions instead (spec 0045).
• A generic option set on the wrong kind is accepted and does nothing. Every encoder inherits the whole generic AVCodecContext table, so g (a GOP size) in AudioOptions passes the check and has no effect. The check catches unknown names, not wrong kinds. Addressing the option to the right map is the only thing that prevents it.

StreamMeta¶

type StreamMeta struct {
    Language    string            // e.g. "eng"
    Disposition []string          // e.g. {"default", "forced"}
    Tags        map[string]string // arbitrary per-stream tags
}

Applied to the output stream before the header is written.

CodecCopy¶

afmpeg.CodecCopy is the string "copy". Set it on VideoCodec, AudioCodec or SubtitleCodec and name the source stream in Map, and the packets pass through untouched, with no decode and no encode.

What Command.JobSpec() rejects¶

Validation happens in Go, before the engine is invoked. Three things fail here:

Everything else (an unknown codec, a map entry naming a stream that does not exist, a filtergraph that will not parse) is the engine's to reject, and comes back as a non-zero Result.ExitCode with the detail in Result.Stderr.

FrameJob¶

The frames op: pull still images out of one video input, without hand-tuning an fps/select graph into the image2 muxer.

type FrameJob struct {
    Input   string
    Format  string
    Options map[string]string
    Select  FrameSelect
    Path    string
    Codec   string
    Scale   string
    Count   int
}

An empty Path fails before the engine is reached: afmpeg: FrameJob.Path (output template) is required.

FrameSelect, exactly one¶

type FrameSelect struct {
    Timestamp      *float64
    Timestamps     []float64
    Interval       float64
    SceneThreshold *float64
    Thumbnail      bool
}

Setting none or more than one fails in Go:

afmpeg: FrameSelect must set exactly one of
Timestamp/Timestamps/Interval/SceneThreshold/Thumbnail

See also¶

• Compose a command with the builder
• Results, probes and progress values: what comes back
• Limitations: what these types deliberately cannot express