Video File Input

Video File input properties for Script Engine. Plays back a video file (MP4, MOV, MKV, MXF, etc.) as a video and audio source. Supports H.264, HEVC, and ProRes codecs. Optionally uses NVIDIA's NVDEC to decode video on dedicated GPU silicon, which offloads work from the CPU and typically allows more concurrent video inputs at higher resolutions. Which codecs and resolutions NVDEC can actually accelerate depends on the installed NVIDIA card — see NVIDIA's compatibility matrix for the details: https://developer.nvidia.com/video-encode-decode-support-matrix Includes play / pause / stop, looping or hold-on-end, auto-play on load or on source change, in/out points for playing only a segment of the file, and a callback hook that lets a script react when the file reaches the end.

Property	Type	Access	Description
`ShowAdvancedOptions`	`bool`	`get/set`	Show or hide the input's advanced settings in the editor UI. [default=false].
`SourceUrl`	`Uri?`	`get/set`	Path or URL to the video file to play. Accepts a local file path or a remote URL pointing at any supported video format (MP4, MOV, MKV, MXF, etc.) using H.264, HEVC, or ProRes. Clearing this stops playback. Locked while playback is running — use `SetSourceUrl` from a script if you need to change the source mid-stream regardless of state.
`MediaPlayerState`	`MediaPlayerState`	`get`	Current playback state of the input (read-only). Reflects whether the file is `NoMedia` (nothing loaded), `Parsing` (opening), `Playing`, `Paused`, `Stopped`, or in an error state. Driven indirectly by `PlayCommand`, `PauseCommand`, `StopCommand`, and by `AutoPlay` at load time.
`CurrentTime`	`TimeCode`	`get`	Current playhead position in the file, as a time code (read-only). Updates continuously while the file is playing. Useful from a script to display the playhead, drive other components, or detect when a particular moment in the video has been reached.
`PlayCommand`	`Command`	`get`	Start playing the loaded video file.
`PauseCommand`	`Command`	`get`	Pause playback at the current frame.
`StopCommand`	`Command`	`get`	Stop playback and rewind to the beginning.
`PlayBackEndCondition`	`PlayBackEndCondition`	`get/set`	What to do when playback reaches the end of the file. Choose between stopping, looping back to the start, holding on the last frame, or other supported end-of-file actions. Pick the option that matches how the clip should behave in the production — looping for backgrounds, stopping for cued playouts, etc.
`DisposeLibAvParser`	`bool`	`get/set`	Whether to free file resources when playback stops, to save memory. [default=false]. When true, the file is fully released on stop, freeing memory at the cost of a small reload delay the next time playback starts. Disable to keep the file ready for an instant restart, at the cost of holding its memory while idle.
`SynchronizedPlayback`	`bool`	`get/set`	Whether playback follows the project's master clock. [default=false]. When true, the file's playhead is locked to the project clock, keeping it in step with other synchronised inputs. Useful when several clips need to start and progress together. Leave off for a free-running playhead.
`AutoPlay`	`bool`	`get/set`	Whether the file starts playing as soon as the project loads. [default=true]. When true, playback begins automatically once the source is ready. Disable to require an explicit `PlayCommand`, useful when playback should only start on operator action or via a script trigger.
`AutoPlayOnMediaChange`	`bool`	`get/set`	Whether to start playing automatically when the source URL is changed at runtime. [default=false]. When true, any change to `SourceUrl` immediately starts playback of the new file — whether the change comes from a script, a Connector, or the HTTP API. Useful for playlist-style workflows where setting the next clip should roll it without a separate `PlayCommand`.
`VideoDecoderThreadCount`	`NumDecoderThreads`	`get/set`	Number of CPU threads used for software video decoding. [default=Two]. Higher thread counts speed up decoding of demanding files but use more CPU. Only takes effect when `UseHardwareDecoding` is false (or when hardware decoding falls back to software for the chosen codec).
`UseHardwareDecoding`	`bool`	`get/set`	Use hardware-accelerated decoding (NVDEC) when the file's codec supports it. [default=true]. When true, video decoding runs on dedicated NVIDIA decoder silicon, offloading the main system and typically reducing CPU use significantly. Falls back to software decoding for codecs the card can't accelerate. See `HardwareDecodingUsed` to confirm which path was actually selected for the loaded file.
`HardwareDecodingUsed`	`string`	`get`	Which decoder is currently active for the loaded file (read-only). Reflects whether NVDEC (hardware) or a software decoder is in use. Useful from a script to confirm that hardware decoding actually engaged for the loaded codec, since `UseHardwareDecoding` is a preference and the actual path depends on what the card supports.
`CuePointJson`	`string`	`get/set`	Cue points stored in the file as a JSON string (read/write). Lets a script read out the cue points found in the loaded file, or override them with a custom set. Format follows the standard Vindral cue-point JSON layout. Leave blank to use whatever cue points the file itself contains.
`ComponentLog`	`ComponentLog`	`get`	Recent log lines from the input — source loads, state changes, errors, and warnings (read-only). A short history of the most recent events, useful for diagnosing why a file failed to load, why playback stopped, or why an automatic restart was triggered.
`InTime`	`TimeCode`	`get/set`	Start time within the file, as a time code. [default=0:00:00:00]. Defines the start of a playback segment. Playback begins here, and looping rewinds back here instead of to the start of the file. Leave at 0:00:00:00 to play from the beginning of the file.
`OutTime`	`TimeCode`	`get/set`	End time within the file, as a time code. [default=0:00:00:00]. Defines the end of a playback segment. Combined with `InTime`, lets you play only part of the file. Leave at 0:00:00:00 to play all the way through to the end of the file.
`ResetSegmentCmd`	`Command`	`get`	Reset `InTime` and `OutTime` so the whole file plays from start to end.
`PlayBackEndOfFileCallback`	`string`	`get/set`	Name of a script function to call when the file reaches the end. Lets you react to end-of-file from a Script Engine script — for example to chain into the next clip, fire a transition, or log the event. Leave blank to skip the callback. Has no effect when `PlayBackEndCondition` keeps the file looping forever (the file never reaches a true end-of-file in that case).
`Width`	`int`	`get`	Width of the video in the loaded file, in pixels (read-only).
`Height`	`int`	`get`	Height of the video in the loaded file, in pixels (read-only).
`AverageVideoDecodingTimeMs`	`string`	`get`	Average time spent decoding a video frame, formatted as a millisecond string (read-only). Should stay well below the file's frame interval for smooth playback. Persistently high values indicate the chosen decoder (CPU or hardware) is struggling with the file.
`VideoMemConsumption`	`int`	`get`	Approximate memory currently used for the video buffer, in megabytes (read-only, debug).
`ParsedVideoBufferLengthMs`	`double`	`get`	How much video has been read from the file ahead of the playhead, in milliseconds (read-only, debug).
`ParsedAudioBufferLengthMs`	`double`	`get`	How much audio has been read from the file ahead of the playhead, in milliseconds (read-only, debug).
`VideoBufferLengthMs`	`double`	`get`	How much decoded video is queued ahead of the playhead, in milliseconds (read-only, debug). A persistently low or zero value while playing suggests the decoder can't keep up with real-time playback.
`AudioBufferLengthMs`	`double`	`get`	How much decoded audio is queued ahead of the playhead, in milliseconds (read-only, debug). A persistently low or zero value while playing may produce audible drop-outs.
`Duration`	`TimeCode`	`get`	Total length of the loaded file, as a time code (read-only). Reflects the playable segment when `InTime` and `OutTime` are set, otherwise the file's full duration. Available once the file has finished loading.
`TimeLeft`	`TimeCode`	`get`	Time remaining until the playhead reaches the end of the segment, as a time code (read-only). Counts down toward zero during playback. Useful for showing a "time remaining" readout or for triggering events a fixed amount of time before the end of a clip.
`EndTime`	`DateTime`	`get`	Wall-clock time at which the file is expected to finish playing (read-only). Computed from the current time plus the remaining playback time. Useful for showing a "finishes at HH:MM" indicator alongside the playhead.
`LoopsPlayed`	`int`	`get`	How many times the file has looped since playback started (read-only). Only increments when the end-of-file behaviour is set to loop and the playhead wraps from end back to start. Useful from a script to limit the number of loops or to schedule events on every Nth repeat.
`LibAvInitTimeMs`	`string`	`get`	Time it took to open the video file the first time, in milliseconds (read-only, debug).
`LibAvStopTimeMs`	`string`	`get`	Time it took to release the video file on the most recent stop, in milliseconds (read-only, debug).
`ParserIterations`	`int`	`get`	Number of read iterations performed during the most recent render, internal diagnostic counter (read-only, debug).
`NumFrozenVideoFramesRendered`	`int`	`get`	Number of times the same video frame was repeated because no new frame was ready in time (read-only, debug). A growing value while playing indicates the decoder can't keep up with real-time playback — typically a sign the file is too demanding for the current decoder choice.
`NumAutoRestartsPerformed`	`int`	`get`	Number of times playback restarted automatically after a decode error (read-only). The input retries up to a few times when it hits a recoverable decode error. A non-zero value means the file or pipeline produced errors that the input recovered from on its own — worth investigating if it grows over time.
`CurrentTimeMs`	`double`	`get`	Current playhead position in milliseconds, as a numeric value (read-only, debug). Numeric counterpart to `CurrentTime`, easier to use for arithmetic in scripts.
`TimeToFirstFrameMs`	`double`	`get`	How long it took from `PlayCommand` to the first rendered frame, in milliseconds (read-only, debug). Useful for measuring start-up latency — for example when deciding between hardware and software decoding, or when tuning preload behaviour for cued playouts.
`VideoTrackInfo`	`Dictionary<string, object>`	`get`	Metadata about the video track in the loaded file (read-only). A dictionary with technical details about the video — codec, resolution, frame rate, bit rate, duration, and so on. Available once the file has finished loading.
`AudioTrackInfo`	`Dictionary<string, object>`	`get`	Metadata about the audio track in the loaded file (read-only). A dictionary with technical details about the audio — codec, sample rate, channel count, bit rate, and so on. Available once the file has finished loading.

Inherits from: AbstractInput, AbstractAudioProcessing, AbstractAudioMetering.

See also: Video File Input in Inputs — user-facing introduction, screenshots, and section summaries.