How oyvindln/vhs-decode works
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 (Domesday 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 (Domesday Duplicator, CX Card, RTL-SDR)
• Raw Data Storage (uncompressed .u8/.u16, Domesday .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