source

source(
  path: String,
  #{
    cache?: String,
    fps?: Rational,
    vfr?: String,
    format?: String,
    track?: Int,
    threads?: Int,
  }
)

Creates a clip from an FFMS2-backed video source.

Relative source paths and relative cache paths resolve against the script directory when one is known. If the source file does not report a usable frame rate, you must supply fps. When format is omitted, PixelFlow preserves the source track’s native format when it maps to PixelFlow’s supported FFMS2 source format subset. Sources whose timestamps drift away from the reported or explicit CFR schedule are normalized to CFR by default; timestamp rounding from coarse container time bases is tolerated. vfr: "passthrough" is reserved but unsupported. When you do not set cache, PixelFlow derives a default .ffms2.pfidx path automatically. If FFMS2 rejects a matching cache because it was generated by an incompatible FFMS2/FFmpeg/libav version, PixelFlow treats it as stale, rebuilds it, and overwrites the cache.

FFMS2 sources declare random-access scheduling to PixelFlow, but the current FFMS2 executor still uses one active source request per source node. PixelFlow starts those limit-one source requests in increasing frame-number order so parallel render workers do not turn sequential source-only renders into random seeks. The threads option controls FFMS2 decoder threads.

Examples

output = source("input.mkv")

output = source(
    "input.mkv",
    #{
        cache: "custom.ffms2.pfidx",
        fps: 24000/1001,
        format: "yuv420p10",
        track: 0,
        threads: 4,
        vfr: "normalize",
    },
)

output = source("input.mkv", #{ threads: 0 })

Input

A source file path plus optional FFMS2 indexing and decode options.

Output

A CFR clip decoded from the selected video track in the native or requested pixel format.

source() prepopulates all PixelFlow core metadata keys. When FFMS2 reports a supported value, frames include core:matrix, core:transfer, core:primaries, core:range, core:chroma_siting, core:field_order, core:frame_number, core:duration, and core:source_path. Unsupported or unspecified source values remain none.

Options

• cache (String) – Override the cache file path used for the FFMS2 index.
• fps (Rational) – Override the source frame rate used for output timing and VFR detection; required when the file does not provide a usable one.
• vfr (String, default: implicit CFR normalization) – Select VFR handling; only "normalize" is accepted explicitly. Detection compares source timestamps against the reported or explicit CFR schedule with tolerance for container timestamp rounding.
• format (String, default: omitted/native) – Select the output pixel format from the FFMS2 source() pixel format subset. When omitted, PixelFlow preserves the detected native source format if it maps to that subset. If the native format is unsupported, pass format to request conversion to a supported format.
• track (Int) – Select a specific zero-based video track; when omitted, PixelFlow uses the first indexed video track.
• threads (Int, default: auto-detected available CPU parallelism) – Set FFMS2 decode threads. Use 0 to request the same auto-detected default.