Repository navigation
MacOS Build
Previous Page Installation | Home
Next Page Windows Build | Linux Build
TBC Tools (
ld-analyse) — the GUI analysis & export hub of the tbc-tools suite.
These instructions cover installing and building tbc-tools only — the post-decode TBC processing toolchain. It consumes .tbc files produced by the RF decode projects; the decoders themselves are separate repositories and are not covered here.
- VHS Decode (Python)
- Tape Decode (Real-Time Rust Version)
A self-contained universal .dmg (Apple Silicon + Intel merged via lipo) is the recommended way to run tbc-tools on macOS:
The .app bundle is ad-hoc codesigned (not notarized), so first launch requires allowing non-signed apps. The official CI builds on macOS 15 (Sequoia); older macOS versions are not regularly tested.
The bundle includes FFmpeg/FFprobe, numpy, the self-contained tbc-video-export, and the Auto Audio Align + vhs-teletext vendor payloads.
Open a Terminal (or Warp Terminal).
-
Disable Gatekeeper:
sudo spctl --master-disableYou will be prompted for your password. This unlocks the "allow any" option for apps.
-
Open System Settings → Privacy & Security. At the bottom under Security there will be a prompt to allow applications from anywhere to run.
-
Click Allow when prompted after the first launch of
tbc-tools.app.
Note
After launching once you can re-enable Gatekeeper (sudo spctl --master-enable) and the app will continue to run.
Move tbc-tools.app to your Applications directory, then open a terminal.
Run the GUI (ld-analyse):
open /Applications/tbc-tools.app
or call the binary directly:
/Applications/tbc-tools.app/Contents/MacOS/ld-analyse
The CLI tools are bundled inside the app and can be called directly, for example:
/Applications/tbc-tools.app/Contents/MacOS/ld-chroma-decoder --help
/Applications/tbc-tools.app/Contents/MacOS/tbc-video-export input.tbc output
Note
The Auto Audio Align (AAA) feature uses a vendored .NET assembly (VhsDecodeAutoAudioAlign.exe + Binah.dll) run through host Mono. Install Mono (brew install mono) to use AAA on macOS.
macOS x86_64 (Intel) and arm64 (Apple Silicon) are both supported, built with Nix and merged into a universal .app/.dmg. This mirrors the official macOS CI (.github/workflows/build_macos_tools.yml).
Note
Nix with flakes enabled is required. Ensure experimental-features = nix-command flakes is set in your Nix config.
Install Nix (the multi-user installer or the Determinate installer both work), then enable flakes.
git clone https://github.com/harrypm/tbc-tools.git
cd tbc-tools
git submodule update --init --recursive
nix build .#
The built tools land under ./result/bin/. Run the GUI:
./result/bin/ld-analyse
Run any other tool by replacing the name (e.g. ./result/bin/ld-chroma-decoder).
Install into your Nix profile instead:
nix profile install .#
nix develop
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
ninja -C build
Artifacts will be under build/. The flake sets -DEZPWD_DIR, -DAPP_BRANCH, and -DAPP_COMMIT automatically for nix build/nix profile install; inside nix develop the EZPWD_DIR env var is exported so manual cmake/ninja picks it up.
The official release pipeline builds a per-arch .app, bundles Qt plugins + a qt.conf, rewrites all Nix /nix/store dylib references to @rpath frameworks inside the bundle, bundles FFmpeg/FFprobe and the PyInstaller-built tbc-video-export, then merges the arm64 + x86_64 bundles with lipo into a universal .app and packages it as a .dmg via create-dmg, ad-hoc codesigned.
Reproducing the full bundling pipeline by hand is involved; see .github/workflows/build_macos_tools.yml for the exact steps. For production use, prefer the universal .dmg from the releases page.
Previous Page Installation | Home
TBC Tools Wiki - © 2026 Harry Munday