Python APIΒΆ

The vsanalog Python package provides a high-level, type-hinted interface to the vsanalog VapourSynth plugin. It handles plugin loading automatically and accepts Python-native types like Path and bool.

vsanalog.decode_4fsc_videoΒΆ

vsanalog.decode_4fsc_video(composite_or_luma_source, chroma_or_pb_source=None, pr_source=None, *, decoder=None, reverse_fields=False, chroma_gain=1.0, chroma_phase=0.0, chroma_nr=0.0, luma_nr=0.0, phase_compensation=False, padding_multiple=8, dropout_correct=False, dropout_overcorrect=False, dropout_intra=False, dropout_composite_or_luma_extra_sources=None, dropout_chroma_extra_sources=None, fpsnum=None, fpsden=1)ΒΆ

Decode 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) – Path to the composite or luma-only .tbc file.

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

  • pr_source (str | Path | None) – Path to the Pr component .tbc file (component video).

  • decoder (str | None) – Chroma decoder to use. One of "ntsc1d", "ntsc2d", "ntsc3d", "ntsc3dnoadapt", "pal2d", "transform2d", "transform3d", or "mono". When None, the decoder is chosen automatically based on the video system in the TBC metadata.

  • reverse_fields (bool) – Swap field order.

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

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

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

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

  • phase_compensation (bool) – Enable NTSC phase compensation.

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

  • dropout_correct (bool) – Enable dropout correction using metadata-identified dropouts.

  • dropout_overcorrect (bool) – Extend dropout boundaries by +/-24 samples (for heavily damaged sources).

  • dropout_intra (bool) – Force intra-field-only dropout correction, avoiding inter-field borrowing artifacts on high-motion content.

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

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

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

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

Return type:

VideoNode

Usage ExamplesΒΆ

Basic Composite DecodeΒΆ

from vsanalog import decode_4fsc_video

clip = decode_4fsc_video("/path/to/capture.tbc")

Y/C-Separated SourcesΒΆ

For S-Video or VHS color-under captures produced by vhs-decode:

clip = decode_4fsc_video("luma.tbc", "chroma.tbc")

Choosing a DecoderΒΆ

# Use the 3D adaptive comb filter for NTSC:
clip = decode_4fsc_video("capture.tbc", decoder="ntsc3d")

# Use the Transform PAL frequency-domain filter:
clip = decode_4fsc_video("capture.tbc", decoder="transform3d")

# Luma-only (monochrome) decode:
clip = decode_4fsc_video("capture.tbc", decoder="mono")

Dropout CorrectionΒΆ

# Basic dropout correction:
clip = decode_4fsc_video("capture.tbc", dropout_correct=True)

# Multi-source dropout correction with extra captures:
clip = decode_4fsc_video(
    "capture1.tbc",
    dropout_correct=True,
    dropout_composite_or_luma_extra_sources=[
        "capture2.tbc",
        "capture3.tbc",
    ],
)

Working with the OutputΒΆ

The resulting YUV444PS format retains maximum quality from the decode but is uncommon. You will often want to convert it for downstream filters:

import vapoursynth as vs

# R'G'B' for color/levels adjustment filters:
workable_clip = clip.resize.Point(format=vs.RGBS)

# For mvtools2 pipelines like QTGMC that require an integer format:
workable_clip = clip.resize.Point(format=vs.YUV444P16)

# Reducing chroma resolution closer to analog source aids some NR filters:
workable_clip = clip.resize.Spline36(format=vs.YUV422P16)

Utility: requires_pluginΒΆ