Results, probes and progress values¶

What each call returns, field by field, and when a field is zero rather than meaningful.

When is a failure an error, and when is it a Result?¶

This distinction runs through every call, so it is worth stating once:

• A non-zero engine exit is not a Go error. Run/RunJob return a Result with the exit code and the captured output, and a nil error. A bad codec name, an unparseable filtergraph or a missing input all arrive this way.
• Only host-side failures return a non-nil error — module instantiation, the filesystem bridge, a cancelled or expired context, a driver that would not start.
• The typed helpers invert this for convenience. Probe, ProbeInput and Frames turn a non-zero exit into an error, because there is no useful typed value to return. The error carries the last 1,500 bytes of stderr, not the whole log.

So a RunJob caller checks err and res.ExitCode; a Probe caller checks err only.

Result¶

type Result struct {
    ExitCode int
    Stdout   string
    Stderr   string
}

ProcessResult¶

afmpeg.ParseResult(res) decodes Result.Stdout from a process job.

type ProcessResult struct {
    Outputs  []OutputResult
    Analysis []Measurement
}

type OutputResult struct {
    Path      string
    Segmented bool
    Streams   []OutputStream
}

type OutputStream struct {
    Type        string // "video", "audio", …
    Codec       string // the encoder actually used
    Disposition string // "copy" for a stream-copied stream
}

ParseResult on an empty Stdout returns a zero ProcessResult and no error, so it is safe to call on any result. It does not look at the exit code — check that first, because the engine only emits this JSON on success.

Measurement¶

type Measurement struct {
    Time  float64 // seconds into the source
    Key   string  // metadata key, "lavfi." prefix dropped
    Value string  // the filter's own string
}

Keys arrive as the filter names them minus the lavfi. prefix: cropdetect.w, r128.I, silence_start, black_start. Values are the filters' raw strings — parse the numeric ones yourself.

Two behaviours to plan for:

• The series is consecutive-deduplicated per key. A stable measurement such as cropdetect appears once; discrete events such as silence_start / silence_end each appear.
• Some filters log without emitting metadata. ebur128 and astats need their metadata=1 option before anything reaches Analysis — for example ebur128=metadata=1.

Probe¶

type Probe struct {
    Format      string
    DurationSec float64
    StartSec    float64
    Streams     []ProbeStream
    Tags        map[string]string
    Chapters    []Chapter
}

type ProbeStream struct {
    Index       int
    Type        string // "video" or "audio"
    Codec       string
    Width       int    // video
    Height      int    // video
    SampleRate  int    // audio
    Channels    int    // audio
    Language    string
    Disposition []string // set flags: "default", "forced", "attached_pic", …
    Tags        map[string]string
}

type Chapter struct {
    Start float64
    End   float64
    Title string
}

The video and audio fields are mutually irrelevant: Width/Height are zero on an audio stream, SampleRate/Channels are zero on a video stream. Language is commonly und.

Probe(ctx, fs, path) auto-probes. A headerless or raw input only opens with a forced demuxer, so use ProbeInput(ctx, fs, Input{Path: …, Format: …, Options: …}) for those — it forwards Format and Options exactly as a process job would.

Probing needs the ffmpeg-wasi engine: it is the engine's probe op, not something afmpeg computes. A generic wasm module cannot answer it.

FramesResult¶

type FramesResult struct {
    Frames []ExtractedFrame
    Count  int
}

type ExtractedFrame struct {
    Path      string  // the file written, with the template expanded
    Index     int     // 0-based position in this extraction
    Timestamp float64 // source position, in seconds
}

The files are already in the afero.Fs you passed; Frames tells you what they are called and where each came from.

Progress¶

Delivered on the channel you attach with WithProgress(ctx, ch), one value per sample.

type Progress struct {
    Fraction    float64
    Source      FractionSource
    Elapsed     time.Duration
    InputBytes  int64
    InputTotal  int64
    OutputBytes int64
    Frame       int64
    OutTime     time.Duration
    Speed       float64
}

OutputBytes counts bytes written, which is not the same as the output file's final size. An MP4 muxer under +faststart seeks back and rewrites its header, so those bytes are counted twice and OutputBytes finishes a little above the file length.

FractionSource¶

When Fraction is -1¶

Deliberately, in five situations. Each is a case where a number could be produced but would be wrong within a second or two:

1. The first moment of a job on a backend that can deliver engine records — up to a 2-second grace period — rather than showing a byte ratio the engine is about to contradict.
2. Every declared input byte has been read while the job is still encoding. A render whose inputs are small next to its output exhausts them early; -1 beats a full bar for the rest of the run.
3. A purely generative input with no file to measure, on an engine that reports no duration.
4. The engine's out_time has overrun the duration it reported by more than 2% — the job is demonstrably longer than predicted, so the ratio is withheld rather than pinned at 1.0.
5. No statable input at all and no engine duration.

Fraction == 1 is not a completion signal either way — use the invocation's return.

See also¶

• Watch job progress — the task-shaped guide, with a worked loop
• Read analysis-filter measurements
• Error catalogue — the sentinel errors and how to match them