Video File Input

Introduction

The Video File Input plays a video file (and its audio) as a live source in your project. It accepts MP4, MOV, MKV, MXF, and other common containers carrying H.264, HEVC, or ProRes; the file is decoded continuously and presented to the rest of the engine just like any other input — chained through operators, mixed with other inputs, and routed to targets.

When the host has a supported NVIDIA GPU, the input uses NVDEC (hardware decoding) to offload work from the CPU. That keeps the per-frame cost low enough to run several files at once at high resolutions; the exact codec / resolution combinations the card can accelerate are documented in NVIDIA's compatibility matrix. For codecs the card can't accelerate, the input transparently falls back to a multi-threaded CPU decoder.

Composer only supports a 48 kHz audio sample rate; files with embedded audio at any other sample rate will be rejected.

What it's typically used for

• Pre-recorded interstitials and packages — opener stings, sponsor reels, transitions between live segments. Pair AutoPlay = true with a single-shot end-of-file behaviour to roll a clip the moment a scene cuts in.
• Looping backgrounds — set PlayBackEndCondition to loop and let the file run forever behind layers above it.
• Cued playouts — AutoPlay = false, drive PlayCommand from a script, hotkey, Stream Deck, or HTTP call to start the clip on cue.
• Playlists — swap SourceUrl from a script and let AutoPlayOnMediaChange start the next clip without an extra PlayCommand round-trip.
• Per-segment playback — the Segment group's InTime / OutTime pair lets you play only a slice of a long file (e.g. one act of a recording) without re-encoding.

How playback is controlled

Three command properties drive playback: PlayCommand, PauseCommand, StopCommand. They're invokable from the property panel, from a script, from the HTTP API, or via a Connector. The property MediaPlayerState reflects the current state (NoMedia / Parsing / Playing / Paused / Stopped / error variants); CurrentTime and TimeLeft track the playhead. End-of-file behaviour (PlayBackEndCondition) decides whether the file loops, holds on the last frame, stops, or fires the PlayBackEndOfFileCallback script function.

SourceUrl is locked while playback is Playing — to swap files mid-stream from a script, call SetSourceUrl(uri) (or SetObjectProperty(input, "SourceUrl", path) from the Script Engine), which unlocks the property automatically.

For end-to-end examples — driving the input from a Script Engine script, from the HTTP API, and from the Runtime API — see the worked examples at the bottom of this page.

Video File Input - Settings

Configuration

Configuration — playback options, end-of-file behaviour, and decoder settings.

Log

Log — recent events from the input.

Segment

Segment — play only part of the file, defined by an in and out time code.

Script Engine Functions (optional)

Script Engine Functions (optional) — names of script functions called on input events.

Performance and properties

Performance and properties — runtime stats and metadata about the loaded file.

Inherits from: AbstractInput, AbstractAudioProcessing, AbstractAudioMetering.

See also: Video File Input in Script Engine Objects.

Shared input properties

Every input — regardless of source type — exposes the following property groups. They are surfaced in the property panel only when Show advanced options is enabled on the input.

Icon

• Icon text — short text shown on the input's icon in the Inputs list. Useful as a quick visual label (channel number, mic name, camera position) to tell otherwise-similar inputs apart at a glance. Empty by default; has no effect on rendering or routing.

Audio mixer

• Hide in audio mixer — when on, hides the input from the audio mixer view without disabling its audio. Useful for de-cluttering the mixer while keeping the audio routed (e.g. fixed background music, ambient beds, pre-aligned playout). [default=false]

Render Options

• Invisible (Do not render in scene) — when on, the input is skipped during rendering and produces no picture on any layer or scene. Audio routing is unaffected. Toggle from a script for cued-in / cued-out behaviour during a show. [default=false]
• Do not render input — disables the input's internal render entirely (no decode or capture work is done). Stronger than Invisible: that one renders but doesn't display; this one stops the input from doing any work at all. Useful for reducing CPU / network load on heavy sources (e.g. high-bitrate RTMP / SRT streams, large media files) when the input is temporarily not needed. Audio meters are cleared while disabled. [default=false]
• Do not render input controller — chooses what drives the Do not render input flag. Let Composer decide (the default) hands control to the project-level Render Tuning optimiser, which automatically pauses inputs that aren't used by any active scene. Manual Configuration ignores Render Tuning and lets the Do not render input toggle control the flag directly — use this to keep a network source warm even when it's currently off-air, or to take a heavy input down by hand regardless of scene activity. [default=Let Composer decide]

Optional TAGS

• TAGS — one or more free-form tag words used to classify this input (typically space- or comma-separated). Picked up by Composer's Smart Search to filter or find inputs by category — e.g. camera, music, interview, sponsor. Has no effect on rendering.

Audio configuration and processing options

For inputs capable of processing audio, additional audio configuration and processing options are available through the audio mixer and the Channel Strip Inspector.

• Audio mixer — monitor levels, adjust gain and pan, mute / solo inputs, and configure auxiliary sends to Audio Channel Strip submix buses, all from a centralised mixer-style interface.
• Channel Strip Inspector — advanced per-strip audio processing for the selected input:
  • Input trim, stereo remapping, and audio delay
  • Channel mapping (8-channel mode unlocks the full MAPPING tab)
  • Gate
  • Low-cut filter
  • Equaliser (5-band parametric)
  • Compressor
  • Sidechain ducking (a second compressor whose gain reduction is driven by another input's level — e.g. dipping music under a voice-over)
  • Limiter

For the full audio signal flow, see Audio processing workflow.

Converting source files for Composer

The Video File Input plays back any container FFmpeg can demux (MP4, MOV, MKV, MXF, …) carrying a supported video codec (H.264, HEVC, ProRes) and AAC or PCM audio. In practice, the format that performs best across the broadest range of hardware is H.264 in MP4, with B-frames disabled, paired with AAC audio. Disabling B-frames keeps every frame independently decodable, which makes seek and loop-rewind responsive, simplifies the decoder buffer, and avoids the rare NVDEC stall that long B-frame chains can trigger.

A canonical FFmpeg conversion command:

ffmpeg -i input.mov \
  -c:v libx264 -preset slow -crf 18 -bf 0 -pix_fmt yuv420p \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4

Pre-rescale to the project's frame rate and resolution

Composer can scale and frame-rate-convert sources on the fly, but doing it on every render tick costs frame budget. When the source clip is significantly larger than the project's resolution or running at a different frame rate, pre-converting to match the project once on disk is much cheaper than asking Composer to do it 60 times per second. Add the appropriate flags:

# Resize to 1920x1080, force 50 fps, keyframes every 2 s for clean looping.
ffmpeg -i input.mov \
  -c:v libx264 -preset slow -crf 18 -bf 0 -pix_fmt yuv420p \
  -vf "scale=1920:1080" -r 50 -g 100 \
  -c:a aac -b:a 192k -ar 48000 \
  -movflags +faststart \
  output.mp4

For the broader performance / source-prep guidance (when to pre-convert, why mid-stream rescaling hurts, choosing CPU vs NVDEC), see Operations & Tuning → Tuning for maximum performance.

Controlling the input from a script

The Script Engine exposes a small set of dedicated Input helpers for media playback. They work for MediaFileInput (Video File Input), AudioFileInput, and CavPlayerInput interchangeably — the helper figures out the type by name.

For setting properties (e.g. SourceUrl, InTime, PlayBackEndCondition) and reading state (CurrentTime, Duration, LoopsPlayed), use the generic property helpers: SetObjectProperty(name, prop, value), GetObjectProperty(input, prop), and GetInputByName(name) (or GetInputById(guid)).

Example — cue a clip and roll it

// Replace the source and start the next clip.
SetObjectProperty("Trailer", "SourceUrl", "C:/Media/sting-out.mp4");
StartMediaPlayBack("Trailer");

// Don't fire anything else until the previous clip is actually rolling.
if (MediaIsPlaying("Trailer")) {
    Log.Info("Trailer rolling.");
}

Example — auto-roll when the source changes

When AutoPlayOnMediaChange is enabled on the input, any change to SourceUrl rolls the new file automatically — no explicit PlayCommand follow-up needed:

// `AutoPlayOnMediaChange` is true on the "Trailer" input.
SetObjectProperty("Trailer", "SourceUrl", "C:/Media/sting-out.mp4");
// Playback begins as soon as the new file finishes parsing.

The same applies when the swap is driven by a Connector or the HTTP API (/api/setproperty?target=Trailer&property=SourceUrl&value=…).

Example — chain into the next clip on end-of-file

Set the input's PlayBackEndOfFileCallback to "OnTrailerEnd" in the property panel (or via SetObjectProperty), then define the function in your script:

// Called by the engine when the Trailer file reaches its end.
function OnTrailerEnd() {
    SetObjectProperty("Trailer", "SourceUrl", "C:/Media/segment-2-bumper.mp4");
    // Give the parser a beat to open the new file before kicking it off.
    ScheduleMediaPlayBack("Trailer", 250);
}

Example — a 5-second pre-roll countdown

// Schedule the clip to start in 5 seconds; cancel if the operator changes their mind.
ScheduleMediaPlayBack("Sting", 5000);

// Cancel everything pending if the operator hits "abort":
function OnAbort() {
    ClearScheduledMediaPlayBacks();
}

For the helper signatures, parameter ranges, and return-value details, see the Input helpers page in the Script Engine manual.

Controlling the input from the HTTP API

Two paths are available depending on what you want to do:

Example — load and play a file in one call

curl "http://localhost:44433/api/media/videofileinput/play?videofileinput=Trailer&sourceuri=C:/Media/sting-out.mp4"

The endpoint resolves the source path through Composer's assets finder (so relative paths are honoured), stops any current playback on the named input, loads the new file, and rolls it. The response body echoes the resolved path on success.

For the per-endpoint reference (parameter shapes, error codes, response payloads), see the HTTP API → Media and HTTP API → Object Management pages.

Runtime API integration

When this input is part of a project that's loaded into a headless Composer Runtime, the Runtime API gates whether the input runs at all. The Runtime API doesn't expose direct media-file controls — for those, use the project HTTP API endpoints above — but the lifecycle endpoints below decide when a Video File Input is alive and ready to receive them.

For the full Runtime API surface (authentication, error model, lifecycle action timeouts, every endpoint's parameter table), see the Runtime API manual.