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 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).