Cav file input

Introduction

The Cav file input plays a Composer-native .cav file as a video and audio source. CAV (Composer Animated Video) is RealSprint's own container, designed for frame-accurate, scrub-friendly playback with cue points and an alpha channel — the things conventional H.264 / HEVC don't do well.

If you need looping background plates, animated overlays, motion-graphics interstitials with transparent areas, or any clip where you'll be jumping to specific frames or named cue points from a script, CAV is the format. For straight pre-recorded video without alpha, the Video File Input playing an MP4 is the simpler choice.

What is a .cav file?

CAV is an all-keyframe container — each frame is encoded independently of every other frame (typically as JPEG, optionally with alpha), wrapped in Composer's own header that carries audio, an embedded cue-point table, and per-frame timing. The all-keyframe design is what gives CAV its useful properties:

• Frame-accurate seek and scrub — jump directly to any frame number with no decode-buffer dependency on neighbouring frames. Stepping a frame at a time, jumping to a named cue, or looping a sub-range all happen instantly.
• Per-frame alpha channel — CAV is the right (and currently only) format Composer ships for animated overlays with transparency. Lower-thirds, animated logos, branded transitions, frame-perfect mattes — anything where you'd otherwise have to fall back to a frame-sequence on disk. Use the alpha parameter when transcoding to retain the source's alpha channel.
• Embedded cue points — named markers stored inside the file. Read out via CuePointJson, jumped-to via JumpToCuePointByName / JumpToCuePointByIndex, or addressed by index from a script. Handy for synchronising graphics to specific moments without hard-coding frame numbers.
• Predictable per-frame cost — every frame decodes in roughly the same time. Useful when a project's frame budget is tight and you can't afford the variable cost of a long GOP.

The trade-off is size and decode CPU load. Because every frame is a keyframe, a CAV file is several times larger than the equivalent H.264 MP4, and software JPEG decode for a 1080p file at 60 fps eats more CPU than NVDEC-accelerated H.264. Reach for CAV when you need its capabilities — frame-accurate cueing, alpha — and use Video File Input with H.264 for the cases where you don't.

For the conversion workflow — turning a source MP4 / MOV / image sequence into a .cav file with optional cue points — see the Creating a .cav file section at the bottom of this page.

What you can control on the input

• Media source — path or URL to the .cav file. Locked while playback is running; stop the input before changing it.
• Playback commands — Play, Pause, Stop, Rewind, Step Frame Backward / Forward, Skip 10 Frames, Jump To Cue Point By Index / By Name, Previous / Next Cue Point.
• Cue-point readout — CuePointJson exposes the embedded cue-point table to scripts; FrameIsCuePoint reports whether the current frame is itself a cue point; PassedCuePoint fires as each cue point is passed in playback.
• End-of-file behaviour — stop, loop, hold last frame, or fire a script callback. Same options as the Video File Input.
• Position read-outs — current frame number, current time-code, time remaining; updated every render tick.

For per-property reference and the full command set, see the auto-generated table below.

Cav file input - Settings

Configuration

Configuration — end-of-file behaviour and load-time auto-play.

Cue points

Cue points — jump to named or numbered anchor points in the file, and react when the playhead crosses one.

Performance and properties

Performance and properties — file dimensions, metadata, and runtime stats.

Inherits from: AbstractInput, AbstractAudioProcessing, AbstractAudioMetering.

See also: Cav 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.

Creating a .cav file

Composer ships a CLI converter, ComposerCAVCommandLineTool, that transcodes any FFmpeg-readable source into a CAV file. It lives at Utilities/ComposerCAVCommandLineTool/ in the source tree and is built and shipped alongside the Runtime / Desktop binaries.

Basic conversion

ComposerCAVCommandLineTool --source input.mov --target output.cav

Defaults: JPEG-compressed video at quality 80, audio passed through if the container has it, no cue points.

Quality control

ComposerCAVCommandLineTool --source input.mov --target output.cav --quality 90

Higher quality means proportionally larger files — a 1080p clip at quality 95 can be 2–3× the size of the same clip at 80. Pick based on the content: photographic / live-action footage tolerates lower numbers cleanly; line-art graphics, screenshots, and mattes need higher.

Adding cue points

Cue points are supplied via an external JSON file at conversion time:

ComposerCAVCommandLineTool --source input.mov --target output.cav --cuepointfile cues.json

cues.json is a list of { frame, name } objects following the standard Vindral cue-point format. Once embedded, scripts and the Cav file input's command set can address cue points by name or index without parsing the source separately.

Source format requirements

Any container FFmpeg can demux works as input — MP4, MOV, MKV, MXF, image sequences, ProRes, etc. To preserve a per-frame alpha channel, the source must already carry one (e.g. ProRes 4444 in MOV, PNG sequences, alpha-bearing MKV); the CLI then transcodes each frame as JPEG with alpha so the output .cav retains the channel.

If the source is a frame sequence on disk (e.g. frames-%04d.png), point --source at the FFmpeg-style sequence path. FFmpeg's image-sequence demuxer handles the rest.