Skip to content

Installing

Jump to bottom
André Borchert edited this page Sep 16, 2026 · 2 revisions

Installing

Requirements

  • macOS 15 or newer on Apple Silicon
  • ffmpeg (provides ffmpeg and ffprobe) and ImageMagick (magick)
  • macOS system awk and sed (already present)
brew install ffmpeg imagemagick

Then confirm everything converter needs is actually usable:

./converter -doctor

-doctor goes further than checking the binaries exist — it verifies the ffmpeg filters (loudnorm, astats, volumedetect, setparams, bass) and encoders (alac, plus the video ladders) that the pipeline depends on, checks directory permissions, and reports free space.

Getting the binary

A prebuilt Apple Silicon binary named converter ships at the repository root, so cloning is enough to start. The current version is 1.1 — see VERSION.

The same binary is attached to every GitHub release together with converter.sha256. Verify a download before running it:

shasum -a 256 -c converter.sha256

The binary is Apple Silicon (arm64) only, ad-hoc signed and not notarized, so macOS quarantines it. Once the checksum verifies, clear the flag with xattr -dr com.apple.quarantine ./converter.

To build it yourself you need Swift tools 6.4 or newer (Xcode 27):

swift build --package-path Sources -c release
# Swift 6.4 moved the products, so ask SwiftPM where they are instead of hardcoding the path.
cp "$(swift build --package-path Sources -c release --show-bin-path)/converter" ./converter
chmod +x ./converter

The Swift package lives in Sources/, so every SwiftPM command needs --package-path Sources.

The release build is deliberately CPU-generic so one binary runs on every Apple Silicon generation. Targeting a specific chip measured no faster and would restrict which Macs can run it.

Optional: dependency auto-install

Converter does not install anything by default. A missing tool produces an error telling you exactly what to brew install.

If you would rather it handle setup itself:

CONVERTER_AUTO_INSTALL_DEPS=1 ./converter -full

That opts you into two behaviours:

  • brew install is run for each missing formula
  • if Homebrew itself is absent, converter downloads and executes the official Homebrew install script (curl … | bash), which runs remote code on your machine

Leave the variable unset on any machine where that is not acceptable.

Where files live

Path Purpose
Output/ Input and output directory. Non-recursive; clear it between runs
config.txt Quality, render and loudness settings — see Configuration
album.txt Track order for -wavtoalbum and -mp3toalbum
converter The binary

Environment variables

Variable Effect
SRC_DIR, OUT_DIR, OUTPUT_DIR Override input/output directories (same as --src-dir, --out-dir, --output-dir)
CONFIG_FILE Use a different settings file
CONVERTER_AUTO_INSTALL_DEPS Set to 1 to opt into dependency auto-install
DEBUG Set to 1 for verbose logging (same as --debug)
CONVERTER_ROOT, CONVERTER_NAME Override the resolved project root and program name

Any config.txt key can also be set as an environment variable and takes precedence over the file.

Clone this wiki locally