# oyvindln/vhs-decode architecture

> Architecture diagram of the GitHub repository oyvindln/vhs-decode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oyvindln/vhs-decode
- Repository: https://github.com/oyvindln/vhs-decode
- Video tour (about a minute): https://gitdiagram.com/oyvindln/vhs-decode/video

## Overview

##### Project type and purpose
- This is an open-source, cross-platform media-decoding tool suite rather than a web or multi-tier business app.
- Its primary goal: take raw FM RF captures from videotape formats (e.g., VHS, SVHS, U-Matic, Betamax, CVBS), demodulate and time-base-correct them into archival “.tbc” files, then export to standard video/audio formats.
- Key use cases: RF capture → lossless FLAC archive → vhs-decode & cvbs-decode CLI → .tbc output → post-processing (ld-analyse, ld-process-vbi/vits) → video export.

##### High-level analysis of the file structure
- Top level
- .github/workflows: CI for Linux/Mac/Windows builds, PyPI packaging.
- CMakeLists.txt & cmake_modules/: drive C++ toolchain builds (ld-tools, GUI apps).
- Cargo.toml & src/: Rust library routines (performance-critical decode/filter code).
- Python packaging files (setup.py, pyproject.toml, requirements.txt)
- README_*.md: per-area docs (pypi, CVBS, TBC export, etc.).
- docs/, notebooks/: documentation and experiments.
- tools/: dozens of CMake-managed C++ command-line utilities for specialized tasks (efm decoding, disc stacking, VBI, etc.).
- Python packages:
– cvbsdecode/: composite video decoder
– vhsdecode/: main RF decode code, plus plugin-style “format_defs” for tape types and Python-Cython wrappers
– filter_tune/: filter-tuning scripts
- Key config & automation
- .github CI for building: Python wheels via pipx, C++ binaries via CMake, AppImage, Docker
- scripts/: utility/batch scripts for building, packaging, testing, and sample workflows

##### Insights from the README
- Fragmented workflows:
- RF hardware capture (Dome­sday Duplicator, CXADC/CX Card, RTL-SDR) → raw .u8/.u16 or .lds/.ldf
- Lossless archive via FLAC
- Post-processing: ld-analyse (GUI for TBC previews), ld-process-vbi/vits (subtitle/timecode extraction), tbc-video-export
- Emphasis on multiple tape formats (NTSC, PAL, PAL-M, NTSC-J, SECAM/MESECAM) and “cvbs ntsc decoder” priority.

a. Main components
- RF Capture Hardware (Dome­sday Duplicator, CX Card, RTL-SDR)
- Raw Data Storage (uncompressed .u8/.u16, Dome­sday .lds/.ldf)
- FLAC Compression module (ld-compress, flac CLI)
- CLI Decode Layer
– vhs-decode (Python CLI → vhsdecode package → Cython/Rust/C++ libs)
– cvbs-decode (Python CLI → cvbsdecode package)
– hifi-decode (Python/C++ Qt GUI for audio)
- Post-Processing Tools (ld-analyse GUI, ld-process-vbi/vits, filter_tune)
- Video Exporter (tbc-video-export → FFmpeg profiles)
- Notebooks & Scripts (experimentation layer)
b. Relationships & data flow
1. Tape player + RF tap → ADC hardware → raw files
2. Raw files → FLAC compressor → compressed archives
3. Compressed or raw → decode CLI → .tbc + .json + .log
4. .tbc → analysis tools (ld-analyse/ld-process-*) → enriched metadata
5. .tbc + audio tracks → tbc-video-export → final video containers
6. Jupyter notebooks/scripts can inject/extract at any stage for tuning or inspection
c. Architectural patterns/design principles
- Modular “plugin” pattern: each tape format or decoder lives in its own module (format_defs, tools/)
- Separation of concerns:
- Low-level DSP in Rust/C++
- Orchestration & I/O in Python
- GUI layer decoupled (Qt/C++ for ld-analyse, Qt/Python for hifi)
- Build-time integration: CMake + Cargo + Python pipx
d. Key technologies/frameworks
- Python 3.8+, numpy, scipy, cython, numba
- Rust (cargo, rust-utils.py bridge)
- C++17 via CMake (Qt5/6, Qwt, FFTW, FFmpeg libs)
- FFmpeg for previews & video export
- GitHub Actions for multi-OS CI
- Docker & AppImage for distribution

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Capture Layer
  subgraph "Capture"
    direction TB
    RF["RF Capture Hardware"]:::hardware
    ADC["ADC Hardware"]:::hardware
    RawFiles["Raw Files (.u8/.u16, .lds/.ldf)"]:::storage
  end

  %% Compression Layer
  subgraph "Compression"
    direction TB
    FLAC["FLAC Compression Module"]:::python
  end

  %% Decode Layer
  subgraph "Decode"
    direction TB
    VHSCLI["vhs-decode CLI (Python)"]:::python
    CVBSCLI["cvbs-decode CLI (Python)"]:::python
    HiFiGUI["hifi-decode GUI (Python/C++)"]:::python
    VHSLib["vhsdecode Library"]:::python
    CVBSLib["cvbsdecode Library"]:::python
  end

  %% TBC Output
  TBC["Timebase-Corrected (.tbc + .json + .log)"]:::storage

  %% Post-Processing Layer
  subgraph "Post-Processing"
    direction TB
    Analyse["ld-analyse GUI"]:::cpp
    VBI["ld-process-vbi"]:::cpp
    VITS["ld-process-vits"]:::cpp
    FilterTune["filter_tune Scripts"]:::python
  end

  %% Export Layer
  subgraph "Export"
    direction TB
    VideoExp["tbc-video-export (FFmpeg)"]:::python
  end

  %% Experimentation Layer
  subgraph "Experimentation"
    direction TB
    Notebooks["Jupyter Notebooks"]:::python
  end

  %% Build & CI Layer
  subgraph "Build & CI"
    direction TB
    CMake["CMake Toolchain"]:::cpp
    Cargo["Rust DSP Library"]:::rust
    PyPkg["Python Packaging"]:::python
    CI["GitHub Actions CI"]:::ci
  end

  %% Data Flow
  RF --> ADC
  ADC --> RawFiles
  RawFiles --> FLAC
  RawFiles --> HiFiGUI
  FLAC --> VHSCLI
  FLAC --> CVBSCLI
  VHSCLI --> VHSLib
  CVBSCLI --> CVBSLib
  VHSLib --> TBC
  CVBSLib --> TBC
  HiFiGUI --> TBC
  TBC --> Analyse
  TBC --> VBI
  TBC --> VITS
  TBC --> VideoExp
  TBC --> FilterTune
  RawFiles --> Notebooks
  FLAC --> Notebooks
  TBC --> Notebooks

  %% Build/CI Flow
  CMake --> VHSCLI
  Cargo --> VHSLib
  PyPkg --> VHSCLI
  CI --> CMake
  CI --> Cargo
  CI --> PyPkg

  %% Click Events
  click FLAC "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/scripts/ld-compress"
  click CVBSCLI "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/cvbs-decode/"
  click CVBSLib "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/cvbsdecode/main.py"
  click CVBSLib "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/cvbsdecode/process.py"
  click VHSCLI "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/vhs-decode/"
  click VHSLib "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/vhsdecode/main.py"
  click VHSLib "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/vhsdecode/demod.py"
  click VHSLib "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/vhsdecode/format_defs/"
  click HiFiGUI "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/vhsdecode/hifi/main.py"
  click HiFiGUI "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/vhsdecode/hifi/HiFiDecode.py"
  click HiFiGUI "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/vhsdecode/hifi/HifiUi.py"
  click Analyse "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/tools/ld-analyse"
  click VBI "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/tools/ld-process-vbi"
  click VITS "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/tools/ld-process-vits"
  click FilterTune "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/filter_tune/filter_tune.py"
  click FilterTune "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/filter-tune/"
  click CMake "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/CMakeLists.txt"
  click CMake "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/cmake_modules/"
  click Cargo "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/Cargo.toml"
  click Cargo "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/src/"
  click PyPkg "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/setup.py"
  click PyPkg "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/pyproject.toml"
  click PyPkg "https://github.com/oyvindln/vhs-decode/blob/vhs_decode/requirements.txt"
  click CI "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/.github/workflows/"
  click Notebooks "https://github.com/oyvindln/vhs-decode/tree/vhs_decode/notebooks/"

  %% Styles
  classDef python fill:#D0E8FF,stroke:#005B96,stroke-width:1px
  classDef cpp fill:#DFF2D8,stroke:#3A7E2E,stroke-width:1px
  classDef rust fill:#FFE5B4,stroke:#E07A00,stroke-width:1px
  classDef hardware fill:#F0F0F0,stroke:#909090,stroke-width:1px
  classDef storage fill:#E8F6FF,stroke:#31708E,stroke-width:1px
  classDef ci fill:#F3E5F5,stroke:#8E44AD,stroke-width:1px
```
