CVBS File Format Specification¶

Introduction¶

This document defines the CVBS File Format for use with the ld-decode, vhs-decode and related projects. CVBS (Colour, Video, Blank, and Sync) describes the full class of analogue video signal — both composite (luma and chroma combined into a single signal) and component YC representations carry the same Colour, Video, Blank, and Sync elements and are therefore both CVBS signals.

The format is organised around three independent preset systems, each of which captures a distinct dimension of the signal:

Video Standard Presets: define the timing and structural parameters of the video signal — line counts, field rates, horizontal sample structure, colour field sequence, and the normative sample level tables for standards-compliant signals.
Sample Encoding Presets: define the bit depth, word format, and amplitude mapping used when the sample data was recorded.
Signal State Presets: define the processing state of the signal at the time of storage — whether a standard 4×fsc sample rate was used, whether time-base correction (TBC) was applied, and whether the decoder was phase-locked to the colour burst.

Every CVBS file is described by one preset from each system. Together they specify how to interpret sample amplitudes, when normative field sizing rules apply, and how reliable phase and level measurements are expected to be.

The format accommodates non-standard cases (e.g., LaserDisc PAL pilot bursts and variations such as NTSC-J) through metadata flags rather than structural changes.

File Naming Convention¶

Each file type uses a distinct extension:

Composite CVBS: <basename>.composite
Dual-File YC CVBS (Luma): <basename>.y
Dual-File YC CVBS (Chroma): <basename>.c

Video Data Format¶

Sample Encoding¶

The physical encoding and amplitude mapping of samples are defined by the Sample Encoding Preset declared for the file. The main properties governed by the sample encoding preset are:

Word format: the integer width, signedness, and byte order of each stored sample word.
Amplitude mapping: the relationship between the stored integer value and the analogue signal amplitude — specifically, where sync tip, blanking, black, white, and peak levels fall within the integer range.
Headroom: whether negative or positive values beyond the nominal 0–1023 range are meaningful.

The standard encoding preset (CVBS_10BIT) represents the normative production output of ld-decode, vhs-decode, and similar tools. The raw capture presets represent unscaled ADC output from hardware capturers such as the DomesdayDuplicator. See sample-encoding-presets for the full definitions.

This specification supports two CVBS (Colour, Video, Blank, and Sync) storage representations, which differ only in how colour information is carried:

Composite CVBS: Single file containing luma and chroma combined into one signal.
Dual-File YC CVBS: Separate files for luma (Y) and chroma (C), keeping the colour components separated.

The specific sample range — sync tip, blanking, black, white, and peak levels together with any reserved protected values — is defined by the declared Sample Encoding Preset.

File Layout¶

Video data is stored as a sequence of frames, where each frame contains two sequential fields. A frame in this context is the smallest navigatable unit in the file and consists of a pair of field samples; this should not be confused with the visual rendering of interlaced video (a single interlaced video frame displayed to the user). No additional framing or headers are included:

[Frame 1 Video Data: 2 × Field Data = M bytes]
[Frame 2 Video Data: 2 × Field Data = M bytes]
...

Frame Ordering and Sequencing¶

Frames are stored sequentially in the file with no embedded markers identifying the colour field sequence position or validating correct sequential ordering. In this specification, ordering has two independent dimensions: (1) ordering of frames relative to other frames, and (2) ordering of the two fields inside each frame. No guarantee exists that either dimension is correct. A frame may contain the expected pair of fields but with intra-frame field order reversed. Due to the nature of RF capture and physical media characteristics — including disc jumps, scratches, media pauses, physical defects, and frame dropouts — the producer may have no reliable way to verify that captured frame and field ordering maintain proper sequential continuity.

If frame-level reordering, field-level analysis, phase verification, or dropout detection is required, those concerns are the responsibility of the consumer application. The file format itself operates at the frame level as the smallest unit of storage and navigation; field-level manipulation and validation are outside the scope of the format specification.

Video Standard Presets¶

Preset System¶

A Video Standard Preset is a named configuration that fully defines all timing and structural parameters for a video standard: sampling rate, line counts, field structure, sample level tables, colour field sequence length, and references to the external standards on which the preset is based. These presets do not define the physical sample word format or the processing state of the signal — those are covered by the Sample Encoding Preset and Signal State Preset respectively.

The preset field in the cvbs_file metadata table (see the cvbs_file table) identifies which Video Standard Preset applies to a given CVBS file. Consumers must implement a preset in full; an unrecognised preset name must not be silently interpreted — the consumer must refuse to process the file or report an error.

Preset Definitions¶

Full definitions — including naming convention, sampling rates, sample level tables, horizontal and vertical structure, and normative field sizes — are in video-standard-presets.

Non-Standard Value Signaling¶

Certain captures may contain sample values that fall outside the nominal standard-protected ranges. See video-standard-presets for details.

Field Ordering and Phase Verification¶

Because frames consist of sequential field pairs and frame ordering is not guaranteed, consumers performing field-level analysis must validate field sequence position, field order, and phase continuity against the declared preset. They may optionally reorder fields and/or frames to establish continuity.

Note: The choice to perform these validations and reorderings is entirely optional and application-dependent. The file format itself makes no assertions about frame ordering correctness.

Preset-specific progression rules and ld-decode/vhs-decode field-ordering conventions are defined in video-standard-presets.

Metadata Schema¶

The metadata file is optional. A CVBS file is self-contained as raw sample data and can be processed without a metadata file provided the consumer obtains the necessary parameters (such as video standard, frame count, and colour sequence position) by other means — for example, from user-supplied command-line arguments or application settings.

When present, metadata is stored in a separate .meta file alongside the video data files.

Metadata: <basename>.meta

The metadata file is a SQLite database containing the core metadata table defined below.

SQLite Metadata Schema¶

PRAGMA user_version = 6;

CREATE TABLE cvbs_file (
    cvbs_file_id                INTEGER PRIMARY KEY,
    preset                      TEXT    NOT NULL
        CHECK (preset IN ('NTSC', 'PAL', 'PAL_M')),
    sample_encoding_preset      TEXT    NOT NULL
        CHECK (sample_encoding_preset IN ('CVBS_10BIT', 'RAW_S16_28MSPS', 'RAW_S16_40MSPS', 'SWTPG21_10BIT')),
    signal_state_preset         TEXT    NOT NULL
        CHECK (signal_state_preset IN (
            'STANDARD_TBC_LOCKED',
            'STANDARD_TBC_UNLOCKED',
            'STANDARD_RAW',
            'NONSTANDARD_TBC_LOCKED',
            'NONSTANDARD_TBC_UNLOCKED',
            'NONSTANDARD_RAW'
        )),
    signal_type                 TEXT    NOT NULL
        CHECK (signal_type IN ('composite', 'yc')),
    decoder                     TEXT    NOT NULL,
    git_branch                  TEXT,
    git_commit                  TEXT,
    number_of_sequential_frames INTEGER
        CHECK (number_of_sequential_frames IS NULL OR number_of_sequential_frames >= 1),
    black_level                 INTEGER,
    has_nonstandard_values      BOOLEAN,
    capture_notes               TEXT
);

`cvbs_file` Table¶

The cvbs_file table records file-level metadata. There is one row per CVBS file.

`cvbs_file_id`¶

Type: INTEGER, PRIMARY KEY
Nullable: No
Description: Unique identifier for the CVBS file record within this metadata database.

`preset`¶

Type: TEXT
Nullable: No
Range: Any Video Standard Preset name defined in video-standard-presets
Description: Identifies the Video Standard Preset that applies to this CVBS file. The preset name uniquely determines all timing and structural parameters — sampling rate, line counts, field structure, sample level tables, and colour field sequence length. Consumers must implement the named preset in full; an unrecognised preset name must not be silently interpreted.

`sample_encoding_preset`¶

Type: TEXT
Nullable: No
Range: Any Sample Encoding Preset name defined in sample-encoding-presets
Description: Identifies the Sample Encoding Preset that defines the physical word format and amplitude mapping of the sample data.

`signal_state_preset`¶

Type: TEXT
Nullable: No
Range: Any Signal State Preset name defined in signal-state-presets
Description: Identifies the Signal State Preset that describes the processing state of the signal at the time of storage — whether the sample rate is standard 4×fsc, whether TBC was applied, and whether burst locking was applied.

`signal_type`¶

Type: TEXT
Nullable: No
Range: 'composite', 'yc'
Description: Declares whether the accompanying CVBS data file is a composite signal ('composite', paired with a .composite file) or one file of a dual-file YC pair ('yc', paired with a .y or .c file). This allows consumers to determine the project type explicitly without relying on file presence detection.

`decoder`¶

Type: TEXT
Nullable: No
Range: 'ld-decode', 'vhs-decode', 'cvbs-encode', 'cvbs-decode', 'other'
Description: The tool that produced the CVBS file. Used to identify the software source and inform interpretation of any tool-specific behaviours.

`git_branch`¶

Type: TEXT
Nullable: Yes
Description: The Git branch name of the decoder tool at the time of capture. NULL if not recorded.

`git_commit`¶

Type: TEXT
Nullable: Yes
Description: The Git commit hash of the decoder tool at the time of capture. NULL if not recorded. Enables exact reproduction of the decoding conditions.

`number_of_sequential_frames`¶

Type: INTEGER
Nullable: Yes
Range: ≥ 1, or NULL
Description: The total number of frames stored in the accompanying CVBS data file(s), counted sequentially from the first to the last. NULL if the frame count is not known at the time of writing — for example, when the file is produced by a raw sampling device that does not segment or count frames during capture. Consumers encountering a NULL value must determine the frame count by parsing the file directly.

`black_level`¶

Type: INTEGER
Nullable: Yes
Range: NULL, or an INTEGER value interpreted according to the declared presets
Description: Optional override for non-standard black levels. NULL means no explicit override is provided and consumers should use the default black level behavior defined by the declared Video Standard Preset and Sample Encoding Preset (see video-standard-presets and sample-encoding-presets). A non-NULL value provides an explicit black-level override in the integer domain of the declared Sample Encoding Preset. For Sample Encoding Presets where black-level calibration is not defined or not meaningful (for example raw capture presets), this field should be NULL.

`has_nonstandard_values`¶

Type: BOOLEAN
Nullable: Yes
Description: Indicates that the producer observed or intentionally generated non-standard sample values relative to the declared Video Standard Preset and Sample Encoding Preset expectations (for example values outside the nominal legal 10-bit domain, including blanking-interval anomalies such as additional bursts). This flag declares presence only; it does not encode the exact signal type or location. Some sample encodings may preserve such values directly while others may clip or quantize them. NULL means not applicable or not known.

`capture_notes`¶

Type: TEXT
Nullable: Yes
Description: Free-form human-readable notes about the capture. May include source material description, known non-compliance (e.g., LaserDisc PAL pilot bursts), equipment details, or other contextual information. NULL if no notes are recorded.

Producer Extension Metadata¶

Per-frame, per-field, and per-sample annotations (for example: frame-level dropout flags, dropout maps, confidence scores, or producer-specific segmentation data) are intentionally not part of the core CVBS metadata schema.

When a producer needs to store such additional information, it must be written in a separate, explicitly defined extension format (for example a sidecar file or extension database with its own schema/versioning document).

The core standard in this document defines only the cvbs_file metadata table. Consumers must not assume that any producer-specific extension metadata exists unless that extension format is explicitly declared and available.

A standard frame-based dropout extension is defined in dropout-extension-format.

Sample Encoding Presets¶

A Sample Encoding Preset defines the physical word format and amplitude mapping applied to every sample in the file: the integer width, signedness, byte order, and the relationship between stored values and analogue signal levels (sync tip, blanking, black, white, peak). The preset name is stored in the sample_encoding_preset field of the cvbs_file metadata table (see the cvbs_file table).

Full definitions: sample-encoding-presets

Signal State Presets¶

A Signal State Preset defines the processing state of the signal at the time of storage along three independent axes: sample rate (standard 4×fsc vs. non-standard), TBC applied (yes vs. no), and burst locked (yes vs. no). The combination governs whether normative field sizes apply, whether signal level compliance is required, and whether phase continuity can be assumed. The preset name is stored in the signal_state_preset field of the cvbs_file metadata table (see the cvbs_file table).

Full definitions: signal-state-presets

Audio Data¶

Audio tracks are stored as separate 48 kHz Stereo PCM WAV files (no other formats, sample rates or encoding are permitted). Up to 16 audio tracks are supported, each as a separate file.

Each file must be a standard RIFF WAV file with the following properties:

Container: RIFF/WAVE with a standard RIFF header (RIFF chunk, WAVE format identifier, fmt sub-chunk, data sub-chunk)
Format tag: PCM (0x0001)
Channels: 2 (stereo)
Sample rate: 48000 Hz
Bit depth: 16-bit signed integer, little-endian

No compression, no extended fmt chunks, and no non-standard RIFF variants are permitted.

File naming: <basename>_audio_<track_number>.wav

Track number is zero-padded to two digits: 00, 01, 02, …, 15.