Installation and configuration

Quick start

Requirements

• Python 3.11 or newer; 3.13 is recommended and the reference version (tested up to 3.14).
• For recording: a USB turntable or a USB audio interface. On Linux vinyl-check records with ALSA (arecord from the alsa-utils package); on macOS (Core Audio) and Windows (WASAPI, ASIO) through PortAudio, which is installed with vinyl-check (recording on macOS and Windows).
• About 1–2 GB of free RAM while an LP side is analysed, and disk space for recordings (about 12 MB per minute at 16 bit / 48 kHz, 17 MB at 24 bit / 48 kHz).

Install from source

git clone https://github.com/michaelpietzsch/vinyl-check.git
cd vinyl-check
python3 -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
pip install .                     # or: pip install ".[ml]" to add the second-opinion network (PyTorch)

On Linux, pip install ".[portaudio]" adds PortAudio recording as an alternative to arecord; macOS and Windows get it by default.

Run

vinyl-check reads its configuration from the TOML file named in VINYLCHECK_CONFIG. For a local instance, a few lines are enough:

# config.toml
data_dir = "data"            # recordings (large)
state_dir = "state"          # database, caches (small)
host = "127.0.0.1"           # "0.0.0.0" to open the interface to other devices in your network
port = 8080
device = ""                  # empty = first USB capture device, or e.g. "hw:CARD=CODEC,DEV=0" (Linux),
                             # "Core Audio: USB Audio CODEC" (macOS), "Windows WASAPI: Line (USB Audio CODEC)"
sample_format = "S24_3LE"    # 24 bit if your interface supports it (Linux: arecord --dump-hw-params)

VINYLCHECK_CONFIG=config.toml vinyl-check       # same as: python -m vinylcheck

Then open http://localhost:8080. The interface walks you through the first steps: add your turntable, calibrate the chain, align it with a test record, then check your first record (user guide).

Try it without a turntable

The demo mode plays a WAV file instead of a turntable. vinyl-check can synthesize a test side with music, pauses, groove noise and logged clicks:

python -c "import soundfile as sf; from vinylcheck import synth; a, _ = synth.make_side(120); sf.write('demo-side.wav', a, 48000, subtype='PCM_16')"
VINYLCHECK_FAKE_SOURCE=demo-side.wav VINYLCHECK_FAKE_SPEED=10 \
VINYLCHECK_DATA_DIR=data VINYLCHECK_STATE_DIR=state vinyl-check

VINYLCHECK_FAKE_SPEED=10 plays the file ten times faster than real time. The examples use POSIX shell syntax. In PowerShell, set each variable first, for example $env:VINYLCHECK_FAKE_SOURCE = "demo-side.wav".

Raspberry Pi as a headless station

A Raspberry Pi 5 (8 GB recommended) next to the turntable makes a quiet, always-on measuring station. Phones, tablets and computers in the same network use it through the browser. deploy.sh sets it up from your computer over SSH (key login and password-less sudo on the Pi):

VC_TARGET=user@raspberrypi.local ./deploy.sh

The script installs the Debian packages, creates the service user vinylcheck, copies the code to /opt/vinyl-check, installs the sandboxed systemd unit (systemd/vinyl-check.service), runs the test suite on the Pi and restarts the service once no recording or analysis is running. The configuration in /etc/vinyl-check/config.toml is created from config.example.toml on the first run and never overwritten. --target=user@host passes the target as an option instead of VC_TARGET, --no-test skips the test run on the Pi, and --now restarts at once even while a recording or analysis is running (it is aborted); see the header of deploy.sh.

systemctl status vinyl-check
journalctl -u vinyl-check -f

Desktop apps

vinyl-check also runs as a desktop app with the same interface in its own window. Download it from the latest release:

System	File
macOS 11 or newer, Apple Silicon	vinyl-check-<version>-macos-arm64.dmg
Windows 10 or 11, 64-bit	vinyl-check-<version>-windows-x64-setup.exe

Install. On macOS, open the disk image and drag vinyl-check to Applications. On Windows, run the installer: it installs for your user without administrator rights (or for all users, if you choose so) and adds a Start menu entry. The window uses Microsoft Edge WebView2, which is part of Windows 11 and current Windows 10.

First start. The apps are not signed yet (code signing), so the system asks once:

• macOS: open vinyl-check and close the message that macOS cannot verify it. Then open System Settings → Privacy & Security and click Open Anyway next to the note about vinyl-check. Before the first recording, allow access to the microphone: macOS uses this name for every audio input, your audio interface included.
• Windows: if Microsoft Defender SmartScreen shows Windows protected your PC, click More info, then Run anyway.

Choose the audio interface. Open Settings → Audio interface. vinyl-check picks an audio interface automatically (never a microphone or a virtual device) and lists every device with its number of inputs and current rate. Choose the inputs the turntable or phono stage is connected to, the sample rate and the bit depth, press Test while a record plays and Save. On Windows, interfaces with an ASIO driver are recorded through ASIO and others through WASAPI (setup guide).

Your data. Recordings, database and configuration stay in your user profile: ~/Library/Application Support/vinyl-check on macOS and %LOCALAPPDATA%\vinyl-check on Windows. An optional config.toml there takes the same keys as on a station (configuration) for advanced settings; the log is in the logs folder. The apps contain everything except the PyTorch second opinion. While a recording runs, the computer does not go to sleep.

Use it from your phone or tablet. In Settings → Network access, turn on Allow access from other devices on the network (it is off by default). The settings then show the address, a QR code and an access code. Scan the QR code with the phone’s camera, or open the address in the phone’s browser and enter the code once; the phone stays signed in. Other devices always need the code, the computer itself never does, and New code signs all devices out. If the firewall asks whether vinyl-check may accept incoming connections, allow it for private networks.

Uninstall. On macOS, quit vinyl-check and move it from Applications to the Bin. On Windows, open Settings → Apps → Installed apps, choose vinyl-check and Uninstall. Your recordings and the database are kept; delete the data folder named above to remove them as well.

From source. pip install ".[desktop]" adds the command vinyl-check-desktop, which opens the same window (on Linux, pywebview needs GTK or Qt). vinyl-check-desktop --browser uses the default browser instead of a window. Building the apps yourself is described in CONTRIBUTING.md.

Configuration

All settings have defaults. config.example.toml lists the keys with comments. A service reads the file named in VINYLCHECK_CONFIG or /etc/vinyl-check/config.toml. Without either, vinyl-check uses the folders of the user who runs it: config.toml and the data in ~/Library/Application Support/vinyl-check on macOS and %LOCALAPPDATA%\vinyl-check on Windows, ~/.config/vinyl-check/config.toml and ~/.local/share/vinyl-check on Linux (XDG). The most important keys:

Key	Default	Meaning
data_dir, state_dir	/mnt/data/vinyl-check, /var/lib/vinyl-check	recordings and database (service; see above for the user folders)
language	"en"	interface language until a user picks one in the settings; "auto" follows the browser
access_code	""	other devices in the network must enter this code once; empty = open to the local network
device	""	capture device (ALSA hw: name, or PortAudio <audio system>: <name>), empty = chosen automatically
rate, channels, sample_format	48000, 2, "S16_LE"	capture format (S16_LE, S24_3LE, S32_LE)
capture_channels, input_channels	—	for interfaces that only record with all their channels open
audio_backend	"auto"	"alsa" (arecord), "portaudio" (Core Audio, WASAPI, ASIO); auto = arecord on Linux if installed
wasapi_exclusive, asio	true, "auto"	Windows: WASAPI exclusive mode; ASIO drivers where installed, false = WASAPI only (setup guide)
require_mount	""	refuse to record unless this mount point is present (protects an SD card)
retention_days	30	delete original audio after this many days; measurements are kept
discogs_token, discogs_username	—	Discogs access via personal token
discogs_consumer_key, discogs_consumer_secret	—	Discogs access via OAuth app (“Connect with Discogs” in the settings)

Device, sample rate, bit depth, the input pair and the Windows options can also be set in the interface under Settings → Audio interface: values saved there take precedence over the file, apply from the next recording without a restart, and Back to the configuration file removes them. Further sections of config.example.toml hold the detector, analysis, grading and alignment parameters. Many values can also be changed in the interface under Settings. Environment variables override the file: VINYLCHECK_DATA_DIR, VINYLCHECK_STATE_DIR, VINYLCHECK_PORT, VINYLCHECK_FAKE_SOURCE, VINYLCHECK_FAKE_SPEED, VINYLCHECK_REQUIRE_MOUNT, VINYLCHECK_RETENTION_DAYS, VINYLCHECK_DISCOGS_TOKEN, VINYLCHECK_DISCOGS_USERNAME, VINYLCHECK_DISCOGS_CONSUMER_KEY, VINYLCHECK_DISCOGS_CONSUMER_SECRET, VINYLCHECK_DISCOGS_SYNC_MINUTES, VINYLCHECK_AUDIO_BACKEND, VINYLCHECK_FONT_DIR (IBM Plex fonts for the PDF reports).

The REST API is documented at /docs on a running instance.

Languages

The interface, API messages and PDF reports are available in English and German. vinyl-check starts in English (or in the language set with language in the configuration; "auto" follows the browser), and each user can change it in the settings. Numbers and dates use the conventions of the chosen language. To add a language, see docs/translating.md.