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.

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 — 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