VapourSynth Plugin APIΒΆ

The low-level VapourSynth plugin is registered under the analog namespace. It can be called directly from VapourSynth scripts without the Python wrapper.

analog.decode_4fsc_videoΒΆ

core.analog.decode_4fsc_video(composite_or_luma_source     [, chroma_or_pb_source]     [, pr_source]     [, decoder]     [, reverse_fields=0]     [, chroma_gain=1.0]     [, chroma_phase=0.0]     [, chroma_nr=0.0]     [, luma_nr=0.0]     [, phase_compensation=0]     [, padding_multiple=8]     [, dropout_correct=0]     [, dropout_overcorrect=0]     [, dropout_intra=0]     [, dropout_composite_or_luma_extra_sources]     [, dropout_chroma_extra_sources]     [, fpsnum]     [, fpsden=1])ΒΆ

Decodes 4𝑓𝑠𝑐 (four times subcarrier frequency) sampled analog video signals to a digital video clip. The signal data must be orthogonal video system lines with well-formed blanking and syncing structure at a stable time base, such as those produced by ld-decode and vhs-decode. These files normally have a .tbc extension indicating they are time-base-corrected and must have a metadata sidecar file in JSON or SQLite format.

For color decodes, returns a clip in YUV444PS format (32-bit float). For monochrome decodes, the clip is in GRAYS format.

Parameters:

  • composite_or_luma_source (str) – Path to the composite or luma-only .tbc file.

  • chroma_or_pb_source (str) – Path to a separate chroma .tbc file, for Y/C-separated sources such as S-Video or VHS color-under.

  • pr_source (str) – Path to the Pr component .tbc file (component video, not yet supported).

  • decoder (str) – Chroma decoder to use. See Decoder Options below. When not specified, the decoder is chosen automatically based on the video system in TBC metadata. When chroma_or_pb_source is supplied, this decoder applies to the chroma TBC only; the luma TBC is read with the mono decoder so it isn’t run through Y/C separation a second time.

  • reverse_fields (int) – Set to 1 to swap field order.

  • chroma_gain (float) – Chroma gain multiplier for saturation adjustment. Default 1.0.

  • chroma_phase (float) – Chroma phase adjustment in degrees. Default 0.0.

  • chroma_nr (float) – Chroma noise-reduction level. Only applies to NTSC decoders. Default 0.0.

  • luma_nr (float) – Luma noise-reduction level. Default 0.0.

  • phase_compensation (int) – Set to 1 to enable NTSC phase compensation. Default 0.

  • padding_multiple (int) – Round output dimensions to a multiple of this value. Set to 0 to disable. Default 8.

  • dropout_correct (int) – Set to 1 to enable dropout correction using metadata-identified dropouts. See Dropout Correction below. Default 0.

  • dropout_overcorrect (int) – Set to 1 to extend dropout boundaries by +/-24 samples. For heavily damaged sources. Default 0.

  • dropout_intra (int) – Set to 1 to force intra-field-only correction, avoiding inter-field borrowing artifacts on high-motion content. Default 0.

  • dropout_composite_or_luma_extra_sources (str[]) – Additional composite or luma .tbc files for multi-source dropout correction.

  • dropout_chroma_extra_sources (str[]) – Additional chroma .tbc files for multi-source dropout correction (for color-under formats).

  • fpsnum (int) – Override frame rate numerator. When not specified, frame rate is auto-detected from metadata.

  • fpsden (int) – Override frame rate denominator (used with fpsnum). Default 1.

UsageΒΆ

import vapoursynth as vs
from vapoursynth import core

# Basic composite decode:
clip = core.analog.decode_4fsc_video("/path/to/capture.tbc")

# Y/C-separated decode:
clip = core.analog.decode_4fsc_video("luma.tbc", "chroma.tbc")

Decoder OptionsΒΆ

The decoder parameter accepts the following values:

Decoder

Video System

Description

ntsc1d

NTSC

1D comb filter

ntsc2d

NTSC

2D comb filter (default for NTSC)

ntsc3d

NTSC

3D adaptive comb filter

ntsc3dnoadapt

NTSC

3D comb filter without adaptation

pal2d

PAL

2D PALcolour filter (default for PAL)

transform2d

PAL

2D Transform PAL frequency-domain filter

transform3d

PAL

3D Transform PAL frequency-domain filter

mono

Any

Luma-only decode (no chroma)

If not specified, the decoder is auto-selected based on the video system in the TBC metadata.

Dropout CorrectionΒΆ

Setting dropout_correct=1 replaces signal dropout regions identified in the TBC metadata with data from nearby clean lines, based on the algorithm from ld-decode-tools’ ld-dropout-correct. Luma and chroma are sourced independently using FIR frequency separation to find the closest match for each.

For multi-source correction, pass additional TBC captures of the same content via dropout_composite_or_luma_extra_sources (and dropout_chroma_extra_sources for Y/C-separated formats). Sources are aligned using VBI frame numbers when available (laserdisc CAV/CLV), falling back to sequential frame alignment for sources without VBI data (e.g. VHS-decode output).

When dropout correction is enabled, the following frame properties are set on each output frame:

Property

Type

Description

AnalogDropoutsCorrected

int

Dropout regions successfully replaced

AnalogDropoutsFailed

int

Dropout regions where no replacement was found

AnalogDropoutsTotalDistance

int

Sum of line distances for all replacements

Metadata SidecarsΒΆ

Each source signal file must have a corresponding metadata sidecar file with the same base name and a .db or .json extension. If the metadata is in JSON format, a .db file will automatically be created in the same directory.