Quick Start¶

This walkthrough builds a complete PAL CAV laserdisc from nothing: a lead-in, a programme area and a lead-out, carrying IEC 60856-compliant biphase VBI metadata and a pair of insertion test signals on the laserdisc VITS lines. At the end you will have a .cvbs sample file that a laserdisc-aware decoder will read as a real disc capture.

You can follow it in the GUI, on the command line, or both — the project file is the same either way.

What you are going to build¶

Section	Type	Frames	Carries
`LeadIn`	`lead_in`	938	`lead_in` biphase code (`88FFFF`)
`Programme`	`programme_area`	250	Picture numbers 1–250, chapter 1, programme status, OSD burn-in
`LeadOut`	`lead_out`	1250	`lead_out` biphase code (`80EEEE`)

Project-wide: CAV addressing, the PAL 3.75 MHz pilot burst on every sync pulse, and the UK national ITS plus the ITS-2 chrominance reference on the laserdisc VITS lines.

The 938- and 1250-frame lead-in and lead-out durations are not arbitrary — IEC 60856 requires at least 1.5 mm of track before the programme and 2 mm after it, which at the 1.6 µm track pitch works out at those frame counts. On a CAV disc the validator warns about a shorter lead-in or lead-out.

Total output is 2438 frames — about 3.5 GB of samples, generated in a few seconds on a modern machine.

Part 1 — Create the project in the GUI¶

1. Start the application and create a project¶

Launch videosynth-gui. It opens on the welcome page — a project must be open before there is anything to edit. Click New Project….

The New Project dialog is the project settings editor, so everything project-wide is set here before the project exists.

In the Project group:

Name: PalCavQuickStart
Version: 1.0
Description: PAL CAV laserdisc with VITS and IEC 60856 biphase metadata

In the CVBS Presets group:

Video standard: PAL.
Sample encoding: CVBS_S16_4FSC. This is a signed preset, which matters here: the laserdisc pilot burst swings to −600 mV, below the −300 mV floor the unsigned CVBS_U10_4FSC preset can represent. With an unsigned preset the burst trough is clipped, and videosynth warns you about it.
Signal state: STANDARD_STABLE_LOCKED.

The video standard is fixed at creation time

You can change the standard freely in this dialog, but once the project is created the control is disabled. Too much of the signal geometry, VBI line allocation and code validity depends on it. If you pick the wrong one, create a new project.

In the Output group:

Video path: {output}/quickstart_pal_cav.cvbs. The {output} token means "wherever this run is told to put its media" — by default, the project's own directory.
Leave Signal type as composite.

In the VITS group:

Placement: Laserdisc (IEC 60856/60857). This tells the validator that VITS live on the laserdisc VBI lines (19, 20, 332, 333 for PAL) rather than on their broadcast lines, which on a disc are occupied by the address codes. Selecting it seeds the spec-required PAL set for you.
In the VITS list, confirm uk-national and vits20 are ticked. Under laserdisc placement their lines are set to 19/332 and 20/333.

Tick the LaserDisc group. Everything specific to LaserDisc is in it, and a project that is not a disc leaves it unticked:

Disc format: CAV.
Tick PAL pilot burst (IEC 60856 §9.1.2). It is only enabled for PAL projects. The NTSC VBI burst option below it is the NTSC equivalent and is enabled only for NTSC projects.
Leave Digital audio and LaserVision channel (pressing) unticked.

Leave Channel (pressing) and Chroma error (capture) unticked; this disc is ideal.

Click Create. You are asked where to save the project file. Choose a directory and save it — the project is written to disk as part of creation, so {project}-relative paths and the preview always have something to anchor to.

A new project starts with a single progressive section sourced from the bundled colour-bar still, so it previews immediately. To reopen this dialog later, use Project → Edit Project….

2. Build the disc structure¶

The Sections dock holds the section list, with Add, Remove, Duplicate, Up and Down buttons. Add appends a plain progressive section; you turn it into a disc section by ticking its LaserDisc group in the section editor and choosing a disc area.

Add two more sections so there are three, then arrange them as LeadIn, Programme, LeadOut using Up and Down.

Section order is validated

Once any section is a lead-in or lead-out, the sequence must be [lead_in] programme_area… [lead_out]: at most one lead-in and it must come first, at most one lead-out and it must come last. Out-of-order sections would break monotonic picture-number generation, so this is an error rather than a warning.

3. Configure the programme section¶

Select the middle section in the sections list.

Section

Name: Programme.
Leave Source on Built-in asset and Still image (EXR), and choose 100_BARS.exr from the file dropdown. The raster (720x576) is derived from the project standard and is never a field you set. The Source Profile box reports whether the file passes the profile checks.
Set Duration to 250 frames. The editor shows the equivalent time beside it — 10 seconds at 25 fps.

LaserDisc

This group appears in the section editor because the project's LaserDisc group is ticked. Tick it, and set Disc area to programme_area. The disc area is what brings the code checklist to life: it now knows which code types IEC 60856 permits here, and pre-ticks the ones a CAV programme section normally carries.

Codes is a checklist, not an add/remove list: you tick the codes this section carries, and only codes the validator accepts for this disc format, disc area and standard are offered. Each has a one-line explanation of what it does at generation time. Tick:

picture_number, and set its start value to 1.
chapter_number, and set chapter to 1.
programme_status. Click the button beside it to open the Programme Status Code dialog, which composes the 24-bit word from readable fields — CX noise reduction, disc size, disc side, teletext presence, copy permission and audio/video mode — and computes the Hamming check digit. Leave the defaults, which produce 0x8DC000.

There is no line selection anywhere in this editor. Laserdisc VBI line placement is entirely determined by IEC 60856 from the code type, the disc format and which field opens the picture; videosynth works it out per frame.

On-screen display

Add an overlay so you can see the picture number burnt into the picture:

Tick the On-screen display group, which adds a first overlay row (Add overlay adds more).
Text: PN:{picture_number} {section_name}
x: 16, y: 32, Scale: 2
Fg luma: White, Bg luma: Black

The available tokens are listed beneath the text field. {picture_number} resolves to the CAV picture number the biphase encoder actually wrote into the VBI of this frame, so the burn-in and the VBI code cannot disagree.

4. Configure the lead-in and lead-out¶

Select the first section:

Name: LeadIn; tick LaserDisc and set Disc area to lead_in.
Duration: 938 frames — the IEC 60856 minimum (1.5 mm of track at the 1.6 µm pitch). A shorter lead-in produces a validation warning.
Source: PLUGE.exr, so the lead-in is visually distinct.
In the Codes checklist, tick the lead_in code. The only other code offered is users_code, which this disc does not need.

Then the last section:

Name: LeadOut; tick LaserDisc and set Disc area to lead_out. Duration: 1250 frames (2 mm of track).
Source: PLUGE.exr, code lead_out ticked.

5. Preview¶

The Preview dock on the right synthesises the selected section's frames on demand; the Line Scope dock beneath it shows one line of that frame as a waveform. If either is hidden, bring it back from View → Panels.

Switch to the Encoded tab to see the woven full-frame composite raster, including the VBI lines carrying the biphase codes.
Drag the crosshair to a VBI line — 17 or 18 for the picture number (field 1), 330 or 331 for the chapter (field 2), 16 for the programme status — and the Line Scope shows the actual waveform for that line, with sample position, time in microseconds and level in millivolts under the cursor.
Set the scope's vertical Range to Sub-sync to see the pilot burst excursions below sync.

6. Validate and generate¶

Validation runs continuously in the background; the Issues dock lists anything wrong and double-clicking an issue jumps to the section it relates to. Run it explicitly with Project → Validate.

When the project is clean, choose Generate → Generate (or Ctrl+G). The status bar shows the current pipeline stage and the progress bar counts frames. When it finishes, a summary dialog lists the artefacts and offers to open the containing folder.

Part 2 — The same project as a YAML file¶

Everything the GUI just did is stored in a plain YAML file that the CLI reads unchanged. Here it is in full — you can save it as quickstart.yaml and skip Part 1 entirely.

project:
  name: PalCavQuickStart
  version: "1.0"
  description: PAL CAV laserdisc with VITS and IEC 60856 biphase metadata

cvbs_presets:
  video_standard_preset: PAL
  sample_encoding_preset: CVBS_S16_4FSC
  signal_state_preset: STANDARD_STABLE_LOCKED

output:
  video_path: "{output}/quickstart_pal_cav.cvbs"

line_injections:
  placement: laserdisc
  vits:
    - vits_type: uk-national
      target_lines: [19, 332]
    - vits_type: vits20
      target_lines: [20, 333]

laserdisc:
  disc_type: CAV
  pilot_burst: true

sections:
  - name: LeadIn
    type: progressive
    source: "{bundled}/exr/720x576/PLUGE.exr"
    duration_frames: 938
    laserdisc:
      area: lead_in
      codes:
        - code_type: lead_in

  - name: Programme
    type: progressive
    source: "{bundled}/exr/720x576/100_BARS.exr"
    duration_frames: 250
    laserdisc:
      area: programme_area
      codes:
        - code_type: picture_number
          start_value: 1
        - code_type: chapter_number
          chapter: 1
        - code_type: programme_status
          programme_status: "0x8DC000"
    osd:
      overlays:
        - text: "PN:{picture_number}  {section_name}"
          x: 16
          y: 32
          scale: 2
          fg_luma: white
          bg_luma: black

  - name: LeadOut
    type: progressive
    source: "{bundled}/exr/720x576/PLUGE.exr"
    duration_frames: 1250
    laserdisc:
      area: lead_out
      codes:
        - code_type: lead_out

Reading the file¶

cvbs_presets fixes the signal for the whole project: one standard, one sample encoding, one signal state. There is no per-section override, because a capture file has one format.
line_injections is project-wide: the VITS set that every frame of every section carries. A disc's reference signals do not change between lead-in and programme, so they are declared once.
laserdisc at the top level holds everything LaserDisc-specific about the project: here the disc format and the pilot burst. A disc is entirely CAV or entirely CLV, so the format is declared once. A project that is not a disc has no laserdisc: block.
laserdisc inside a section is per-section: its disc area, which is what makes this a disc rather than a plain three-part video — it selects which code types are legal in each section and triggers the minimum-duration checks — and the biphase codes that legitimately differ between disc areas. Note that no section names a VBI line: there is no target_lines key on laserdisc codes.

Part 3 — Validate and generate from the command line¶

Validate first. This parses the file, checks every rule, probes the source files, and generates nothing:

videosynth --project quickstart.yaml --validate

[info] Starting pipeline: parse -> validate -> generate -> output
[info] Parsing project file: quickstart.yaml
[info] Validation successful.

Then generate, sending the media somewhere with room for it:

videosynth --project quickstart.yaml --output-root /path/to/scratch

[info] Pipeline progress: 2438/2438 frame(s) written.
[info] Wrote 2438 frame(s) to output files.
[info] Generation completed successfully.

--output-root is what {output} resolves to. Without it, {output} is the project file's own directory. This separation is deliberate: the project says what its artefacts are called, and the caller decides where this particular run puts them.

Part 4 — What you got¶

quickstart_pal_cav.cvbs     3.5 GB   composite samples, 2438 frames
quickstart_pal_cav.meta      12 KB   SQLite metadata sidecar

The .cvbs file is a flat stream of 4fsc composite samples — 1135 samples per line, 625 lines per frame for PAL. The .meta sidecar is a SQLite database describing the file as a whole: standard, sample encoding, signal state, frame count, black level and the build that produced it. Both are the input format that decode-orc and the ld-decode tool chain expect.

Because generation is deterministic, running the same project again — on a different machine, with a different thread count — produces byte-identical files.

Where to go next¶

Swap laserdisc.disc_type: CAV for CLV and replace picture_number with programme_time_code, clv_code and clv_picture_number — see Laserdisc discs.
Build the NTSC equivalent. A compliant NTSC disc also carries the 40-bit FM codes on lines 10/273 with the white flag on line 11, and the validator requires a virs VITS (conventionally on lines 19/282).
Add noise and dropouts to make the disc look like a real, imperfect capture.
Add audio — analogue channel pairs, or EFM digital audio (laserdisc.efm_audio) with a proper table of contents.
Model a real pressing and player with the LaserVision channel — FM beat, group delay, replay response, field-2 offset.
Read the Project File Reference for the exact meaning of every key.