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, so 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, so 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, because 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%, so 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