FLAC Detective Documentation

FLAC Detective is a command-line tool that detects fake lossless audio files — MP3s (and other lossy codecs) re-saved as FLAC, ALAC, APE, WAV or AIFF, or wrapped as lossless audio inside a video container, so they look lossless when the quality was already thrown away. It scores each file with a multi-rule engine (plus an optional 12th CNN rule) and gives a clear, four-level verdict, while protecting genuine vinyl rips, cassette transfers and quiet recordings from false alarms.

👉 Find your path

Pick the row that sounds like you — each leads straight to the right page.

If you are…

Start with

You’ll get

🟢 New to all this — just want to check your music

Start Here

A 5-minute, jargon-free walkthrough: what it does, install, scan, read results. No command-line experience needed.

🎧 A user ready to scan a real library

Getting Started → User Guide

Install options (ffmpeg, Docker, ML extra), every flag, real examples, --deep, CSV/HTML reports.

🐍 A developer integrating it in Python

API Reference

The public API, the result dict, and integration examples.

🔬 Curious how it works under the hood

Technical Details

Every rule, the three evidence families, the corroboration gate, the protection layers.

🧪 Here for the deep dives

ML case study · Formats roadmap

How Rule 12’s CNN was built (the false-positive audit, the dead-ends, the mono→stereo breakthrough), and why multi-format support is an input problem.

New here and not sure? Start with Start Here — it’s enough for day-to-day use, and it points onward when you want more.

The 30-second version

pip install flac-detective       # needs Python 3.10+
flac-detective /path/to/music    # scan a file or a whole folder

Every file comes back with one of four verdicts — read them like traffic lights:

Verdict

Score

Meaning

✅ AUTHENTIC

≤ 30

No evidence of transcoding — keep it

❓ WARNING

31–54

Borderline — give it a listen

⚠️ SUSPICIOUS

55–85

Likely a transcode

❌ FAKE_CERTAIN

≥ 86

Multiple strong indicators — replace it

The scan only reads your files — it never edits, moves or deletes anything. The same thresholds drive the console, the reports and the API.

(Plain pip install won’t upgrade an existing install — use pip install --upgrade flac-detective. See Getting Started → Upgrading.)

Why a fake is detectable

To save space, an MP3 throws away the highest frequencies — a real recording keeps them, so the shape of the spectrum gives a fake away (it “falls off a cliff” well below where a real file keeps going). FLAC Detective measures that cliff plus a dozen other clues. The full story is in Start Here (the gentle version) and Technical Details (every rule).