vinyl-check Version 1.0.1

Every click counted.Every grade explained.

vinyl-check records a side of a record bit-exact, finds clicks, pops and crackle, and suggests a condition grade on the Goldmine scale with the criteria behind it. It shows what a cleaning really achieved and how well your turntable is aligned. On your own hardware, without a cloud.

  • macOS · Windows · Linux · Raspberry Pi
  • Free for non-commercial use
  • English · Deutsch

analysed

5:00

Test Artist – Test Album · Side A · uncleaned · 33⅓

0 clipped · 0 dropouts

Grade (suggestion)
VG+ · 888.8 clicks/min in the music
Pops/min
2.6
Noise
−62.0 dBFS
Detections
43
4 tracks

Time axis of side A, 5:00: 43 detections (12 pops, 31 clicks), four tracks with pauses. Grade suggestion VG+, score 88.

Real output, not a mock-up: a synthetic five-minute side with built-in clicks, recorded and graded by vinyl-check 1.0.1. Time is shown 50× faster.

01The problem

Condition is judged by eye. Cleaning by ear. Alignment with a protractor.

  1. Grading

    A scuff that never plays, a click that never shows: looking at the vinyl misses both. vinyl-check grades what happens while the music plays.

    90 / 10clicks / pops in the grade

  2. Cleaning

    Two recordings of the same side never match exactly. vinyl-check measures that scatter, so only a real improvement counts as one.

    ±4 msmatching window between two recordings

  3. Alignment

    Anti-skating, azimuth and arm height show their effect in distortion and crosstalk, values no gauge can show.

    16bands of the AAPT 1 test record, recognised by their signal

  4. Test pressings

    Is a click on the vinyl or in the master? On one loudly mastered rock record, most detected pops in the music came from the music itself.

    77 %of the pops explained by the master

02The principle

One recording. Everything else is derived.

vinyl-check records a side as a WAV file, exactly as the stylus picks it up, and runs an analysis on that file. The grade, the cleaning comparison, the alignment findings and the master comparison all come from such recordings.

  1. Record33⅓ or 45
  2. Turntablestylus, arm, phono stage
  3. Audio interface16 · 24 · 32 bit, no resampling
  4. WAV of the sideSHA-256 checked before every re-analysis
  5. Analysisdetector, grading, comparison, alignment
  6. Findingsvalue · target · verdict · explanation

What the recording is of decides what you learn

The WAV is kept for a configurable number of days, the measurements for good: listen to any spot, re-analyse with another sensitivity, compare later.

03Capabilities

Four questions, measured.

Condition grade

Music is predictable over a few milliseconds. A click is not.

For every block of 2048 samples (about 43 ms at 48 kHz) vinyl-check fits an autoregressive model of order 32 and predicts each sample from the ones before it. What it cannot predict is the residual. In music it stays small and nearly white; a click stands out of it like a spike.

A sample becomes a candidate above 8 σ, with σ estimated robustly from the residual itself, so the threshold does not depend on level or loudness. A stripe check then removes drum hits: a click is a thin vertical line, at most 5 ms wide and 12 dB above its surroundings above 6 kHz.

  • Pop loud enough to be heard through the music
  • Click a single audible click
  • Crackle barely audible alone, the crackle of a pause
Signal, left channel
A real detection from the demo side: 116 σ at 3:37.8, peak −26.8 dBFS. Noise median 1.2 σ.

The grade counts what you hear while the music plays.

Clicks per minute of music decide 90 % of the grade, pops 10 %: in loud music, most detected pops are instrument transients. Noise and clicks in pauses are reported, but they do not enter the grade. F is only given when the stylus skips. Mint is never given, because it needs a visual inspection.

Clicks per minute in the music

Score0.9 × 88.2 + 0.1 × 87.1 = 88.1VG+ · 88

Limits are starting values; calibrate them for your chain.

Cleaning, before and after

Did the cleaning help, or did the stylus just land differently?

Record the side before and after cleaning. vinyl-check aligns both recordings to the sample, including the speed difference between two plays, and matches every event within ±4 ms. Each click is labelled removed (dirt), persistent (damage) or new.

Two uncleaned recordings of the same side show how repeatable the measurement is. Only a change beyond that scatter counts as an improvement.

Clicks/min in the music

11.2 3.6

Grade

VG+ · 83NM · 96

  • 23 removed
  • 8 persistent
  • 2 new
Found automatically: 0.2 % speed difference, 1.3 s offset. A synthetic side with dust, scratches and two new clicks, recorded twice and compared by vinyl-check 1.0.1.

Turntable alignment

A number is not a finding.

Play both sides of a test record. vinyl-check finds the bands by their signal, because band lengths are printed on no sleeve, and measures anti-skating and tracking reserve, balance, crosstalk and azimuth, arm/cartridge resonance, speed and wow & flutter, intermodulation for the arm height, frequency response and rumble.

Every result comes as value, target, verdict and explanation, and says what to adjust first.

Anti-skating: which channel breaks up first?

On the 315 Hz ramp from 0 to +12 dB, vinyl-check follows the distortion of the harmonics in each channel. Left first means too much anti-skating, right first too little; both together means the bias is right and tracking force is the next suspect.

0.3 %1 %3 %10 %30 %3 % limitLRL breaks up at +7.6 dBR clean to +11.4 dB

THD, harmonics 2–9Level above the start of the ramp

L breaks up at +7.6 dB; R clean to +11.4 dB; 3 % limit.

Anti-skating: which channel breaks up first?

What vinyl-check says

Left distorts first (from +7.6 dB), right clean up to +11.4 dB: anti-skating too strong, the stylus leans against the outer groove wall. Reduce the bias slightly (Rega arms: towards mark 0) and repeat the ramp.

FindingValueTargetVerdict
Anti-skating (bias)too strongboth channels clean up to +12 dB, or breaking up togethernote
Left distorts first (from +7.6 dB), right clean up to +11.4 dB: anti-skating too strong, the stylus leans against the outer groove wall. Reduce the bias slightly (Rega arms: towards mark 0) and repeat the ramp.
Tracking headroom7.6 dB≥ 11 dBnote
Distortion (harmonics) at the end of the ramp: left 17.55 %, right 1.91 % (threshold 3.0 %); THD+N including hum and noise: 17.60 / 1.91 %.
Input level−18.0 dBFS−24 to −16 dBFSok
Channel balance0.0 dB±1 dBok
Crosstalk left → right−27.0 dB≤ −25 dBok
Azimuth−0.8 dB±3 dBok
Speed+0.12 %±0.5 %ok
Wow & flutter (weighted, 2σ)0.04 %≤ 0.1 %ok
Arm/cartridge resonance10.6 Hz8 to 12 Hzok
Rumble / noise (silent groove)−60.1 dB≤ −55 dBok

Ramp and findings from simulated test-record runs (AAPT 1 band layout), measured by vinyl-check 1.0.1. Live meter: distortion per channel, five times per second, while you turn the anti-skating dial.

Master comparison and test pressing approval

On the vinyl, or in the music?

In engineer mode, upload the digital master of each side. vinyl-check aligns the pressing to it and, around every detection, subtracts the master: what remains is on the vinyl.

Across several copies, the approval separates stamper defects common to all copies from single faults, with checkpoints and a recommendation, and writes a PDF report with charts, spectrograms and excerpts for the pressing plant or the client.

  • Speed of the cut
  • Eccentricity
  • Polarity and channel swap
  • Wrong side
  • Frequency response across the side
  • Level per track
  • Pre- and post-echo
  • Clicks only on the vinyl

What the master explained

Pop77 % 83 / 108
Click14 % 16 / 113
Crackle35 % 198 / 568

explained by the masteron the vinyl

1,158 detections on two sides of a loudly mastered rock record (real recordings).

And around it

  • Discogs collection

    Search your collection, take over release, tracklist and cover, and write the measured grade back as media condition once you confirm it.

  • Learning from your judgements

    Mark detections as click, false alarm or unsure. Validated per recording: on ten recordings with a master, the clicks estimate was within ±4 %.

  • Listening and analyzer

    Listen to the turntable in the browser, rewind during a recording, play back only the detected clicks. A 31-band analyzer shows the spectrum.

  • PDF reports

    A report per recording and an approval report per record, with charts, spectrograms and excerpts. In English or German.

04Inside the station

Signal processing you can read.

A small web application in Python with numpy and scipy. Every threshold has a default and a reason, documented in How vinyl-check measures.

  1. 01

    Capture

    Bit-exact from the audio device: ALSA hw: on Linux, Core Audio, WASAPI exclusive or ASIO on macOS and Windows. No sound server, no resampling. Stops by itself in the run-out groove.

    16 · 24 · 32 bitSHA-256 per WAV

  2. 02

    Detection

    Autoregressive model of order 32 per 2048-sample block, Levinson-Durbin. Candidates above 8 σ; stripe check; events closer than 1.5 ms merged.

    AR(32)8 σ≥ 12 dB · ≤ 5 ms

  3. 03

    Segmentation

    A level curve in 50 ms steps finds lead-in, music, pauses and run-out. Track borders come from the Discogs tracklist and snap to the nearest pause.

    50 ms±8 s

  4. 04

    Grading

    Clicks and pops per minute of music, weighted 90 / 10, mapped to the Goldmine scale. A skip means F; the record grade is the mean of its sides.

    NM … F90 / 10

  5. 05

    Comparison

    Cross-correlation of the level curves, then speed and offset from 0.3 s windows; the second recording is resampled and anchored sample-accurately.

    ±4 msspeed-corrected

  6. 06

    Alignment

    Bands recognised by their signal, measured with 4-term Blackman-Harris spectra, THD and THD+N, sweeps and a resonance model.

    −92 dB side lobesIEC 60386

One station · docs/architecture.md
Browser / desktop window  ──HTTP/WebSocket──► FastAPI (web.py)
├── capture.py  arecord (ALSA hw:) or PortAudio (Core Audio, WASAPI, ASIO)
│     └── measure.LiveMeter  fundamental, THD+N L/R five times per second
├── jobs.py  one worker: analysis, alignment, comparison, master check
│     └── heavy.py  child process with low priority
│           ├── analysis.py  detect.py, grading.py, skips.py, second_opinion.py
│           ├── alignment.py  measure.py
│           ├── compare.py, master.py
│           └── spectro.py, technical.py
├── learning.py  model from judgements and master comparisons
├── discogs.py  collection, release data, condition write-back
├── report_pdf.py  PDF reports
└── db.py  SQLite (WAL): records, recordings, analyses, profiles, runs
  • One worker, heavy work in a child process

    An LP side needs 1–2 GB of RAM. The interface and a running recording keep priority, and an out-of-memory crash does not take the station down.

  • Database and audio in separate places

    Small, valuable measurements survive the loss of the drive that holds the large WAV files.

  • No external JavaScript libraries

    The interface works without internet access: no CDNs, no web fonts.

05Run it

From install to a station in minutes.

Desktop apps for macOS and Windows, a Python package for Linux and the Raspberry Pi, and a demo mode that needs no turntable at all.

Terminal: 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 ".[ml]" for the second-opinion network (PyTorch)
VINYLCHECK_CONFIG=config.toml vinyl-check     # then open http://localhost:8080

The source code goes public on GitHub with the first public release.

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)
Terminal: on your computer, then on the Pi
# Key login and password-less sudo on the Pi; installs packages, the sandboxed
# systemd unit, runs the tests on the Pi and restarts once nothing is recording
VC_TARGET=user@raspberrypi.local ./deploy.sh

systemctl status vinyl-check
journalctl -u vinyl-check -f
Terminal: without a turntable
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
Terminal: against a station on your network
# Is the station up, and which version runs?
curl http://raspberrypi.local:8080/api/health
# {"ok":true,"version":"1.0.1"}

# Recording or analysing right now? (check before an update)
curl http://raspberrypi.local:8080/api/status

# The PDF report of recording 16
curl -o report-16.pdf http://raspberrypi.local:8080/api/recordings/16/report.pdf

The REST API of a running station is documented at /docs on that station.

06Setups

Your turntable is part of the measurement.

vinyl-check works with an inexpensive USB turntable as well as a high-end chain. A properly aligned budget deck gives repeatable results, a badly aligned expensive one does not.

  1. Entry level

    USB turntablecomputer

    Good for cleaning comparisons and rough grades. The turntable profile records the chain's own reference level and click floor, so results stay comparable.

  2. Recommended

    Turntablephono preampaudio interface

    24 bit / 48 kHz, adjustable levels, lower noise. The reference setup for grading.

  3. High end

    Aligned turntablelow-noise phono stagestudio interface

    Lowest noise floor, reliable alignment measurements, test pressing approval against the master.

Every setup needs the same basics: tracking force, anti-skating, VTA, azimuth and overhang, a level calibration and a clean stylus. For clicks and pops, 16 bit / 44.1 kHz is always enough. Setup guide

Runs on

macOS
App for Apple Silicon, macOS 11 or newer. Core Audio.
Windows
Installer for Windows 10 and 11, 64-bit. WASAPI and ASIO.
Raspberry Pi and Linux
Python package, ALSA. Raspberry Pi 5 with 8 GB as a headless station.
From source
Python 3.11 or newer, 3.13 is the reference.

07Local by design

Next to the turntable. Not in a cloud.

  • No account and no cloud service. Recordings, database and configuration stay on your machine.

  • The interface works offline: no CDNs, no web fonts, no external scripts.

  • Access from phones and tablets is off by default; turned on, they join with a QR code and an access code.

  • Each recording carries its SHA-256, checked before every re-analysis and comparison.

Roadmap

Vinyl-Mind: stations that learn together, without sharing audio.

Each turntable profile trains its model locally, with the measured profile as the zero point so that setups become comparable. Only model weights and counts leave a station. A separate hub combines them and hands back a global model, which each station checks on its own data before using it. Taking part will be optional, and off until you turn it on.

  • Only knowledge travels, never audio.
  • The station calls, never the other way round.
  • A new model is checked before it is used.

08License

Free for non‑commercial use.

vinyl-check is licensed under the PolyForm Noncommercial License 1.0.0: free at home, for hobby and research, in schools and charitable organisations. You may change it and share it for these purposes, as long as the license and the copyright notice travel with it.

Source-available, not open source in the OSI sense: the license excludes commercial use.

Free

  • At home and as a hobby
  • Research and teaching
  • Schools and charitable organisations

Commercial license

  • Mastering studios and pressing plants
  • Record shops and grading services
  • Offering it as a service, selling it
Ask for a commercial license

09Getting started

Put a record on.

  1. 1

    Install

    The app for macOS or Windows, or the Python package on Linux and the Raspberry Pi.

    Download
  2. 2

    Set up the chain

    Tracking force, anti-skating, VTA, azimuth, overhang and the level. The setup guide has a checklist for every session.

    Setup guide
  3. 3

    Record a side

    Calibrate with the stylus up, add a record, record side A with the lead-in groove. The grade follows the run-out groove.

    User guide

Download vinyl-checkRead the documentation