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 or WAV so they look lossless when the quality was already thrown away. It scores each file with an 11-rule spectral 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

All 11 rules + the optional ML Rule 12, the scoring, 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).