🎵 FLAC Detective

Advanced FLAC Authenticity Analyzer for Detecting MP3-to-FLAC Transcodes

FLAC Detective is a professional-grade command-line tool that analyzes FLAC audio files to detect MP3-to-FLAC transcodes with high precision. Using spectral analysis, an 11-rule scoring system and an optional CNN classifier, it helps you keep your lossless music collection genuinely lossless.

🔍 How it works

Transcode an MP3 back to FLAC and the file is lossless as a container — but the audio already went through a lossy codec, and that leaves fingerprints. The clearest is a spectral cliff: MP3 discards everything above a bitrate-dependent frequency (~16 kHz at 128 kbps, ~20 kHz at 320), so the spectrum falls off a wall where a real recording keeps going.

FLAC Detective scores each file with 11 heuristic rules built around that idea — cutoff frequency vs. sample rate, MP3-bitrate signatures, compression artefacts (pre-echo, aliasing), bitrate sanity — plus protection rules so genuine vinyl rips, cassette transfers and naturally quiet recordings aren't flagged. An optional 12th rule is a small CNN (pip install "flac-detective[ml]") that sharpens borderline verdicts — measured, it raises confidence on already-suspect files far more than it catches fakes the heuristics miss outright. The rules sum to a 0–150 score and a 4-level verdict:

Verdict	Score	What to do
✅ AUTHENTIC	≤ 30	keep it
❓ WARNING	31–54	borderline — check manually
⚠️ SUSPICIOUS	55–85	likely a transcode
❌ FAKE_CERTAIN	≥ 86	multiple indicators — definitely transcoded

Higher score = stronger evidence of transcoding. The 0–150 range comes from summing the rules (some add points for fake signatures, protection rules subtract them); the four bands above turn that raw number into an action. The same thresholds drive the console, the reports and the API — there's no second opinion hiding anywhere.

The guiding principle throughout is "protect authentic files first": a false alarm on real music is worse than missing a borderline fake.

→ Every rule explained: Technical Details.

🤖 The ML side is a case study worth reading

Rule 12's model went through a real R&D saga, written up as a learning resource: a false-positive audit over 11 234 real FLACs, four dead-ends that didn't work (each instructive), a debunked "AUC 0.99" false discovery caught by cross-validation, and a twist where a "fundamental limit" turned out to be an artifact of listening in mono — fixed by going stereo.

📖 Read the ML detective story → — worth a look even if you never enable the ML extra.

🆕 Latest release — v1.0 (first stable release)

1.0 — stable public API. The CLI and its flags, the top-level exports (FLACAnalyzer, ProgressTracker, find_flac_files, LOGO, __version__) and the analyze_file() result-dict keys now follow semantic versioning. Internals under analysis/ may still change between minor versions.
Field-validated on a real ~72k-file library (v0.16.1): this surfaced and fixed an ALAC routing bug (cover-art .m4a files were wrongly rejected) that synthetic tests had missed — see ml/field_validation.py.
Analyses ALAC (.m4a) and APE (.ape) too (v0.16.0), decoded via ffmpeg — detection is codec-agnostic, so it's the same spectral pipeline. A lossy AAC .m4a is still correctly rejected (the real codec is probed, never trusted by extension).
Analyses WAV files too, not just FLAC — same spectral pipeline (v0.15.0).
Sharper WARNING/SUSPICIOUS boundary (v0.15.1): a score-distribution study found real transcodes cluster around a score of ~58, so the SUSPICIOUS floor moved 61 → 55, reclaiming ~+5 pp of transcodes as actionable while authentic false positives stay ~1 %.
One source of truth for verdicts (v0.15.2–v0.15.3): the console, the text/JSON reports and the Python API now all derive the verdict from the same thresholds.

The Rule 12 classifier reads the stereo mid + side channels instead of mono (v0.14), fixing its weak spot on band-limited music (baroque, jazz, old recordings). (Mid/side is a way to encode stereo as mid = L+R average and side = L−R difference; MP3 quantises the side channel aggressively, so its fingerprints survive even when the high-frequency cliff is faint.) Real-world specificity on a library of 11 234 authentic FLACs climbed from 80 % to 95 %:

	v0.12 (mono)	v0.14 (stereo + gate)
Specificity (authentic kept)	80 %	95 %
Transcode recall	87 %	94 %

Full version-by-version history → CHANGELOG.

✨ Key Features

🎯 High Precision Detection: 11-rule scoring system with intelligent protection mechanisms
📊 4-Level Verdict System: Clear confidence ratings from AUTHENTIC to FAKE_CERTAIN
⚡ Performance Optimized: 80% faster than baseline through smart caching and parallel processing
🔍 Advanced Analysis: Spectral analysis, compression artifact detection, and multi-segment validation
🛡️ Protection Layers: Prevents false positives for vinyl rips, cassette transfers, and high-quality MP3s
📝 Flexible Output: Console reports with Rich formatting, JSON export, and detailed logging
🔧 Robust Error Handling: Automatic retries, partial file reading, and comprehensive diagnostic tracking
🔨 Automatic Repair: Undecodable FLAC files are losslessly rebuilt (reference flac tool, exact PCM, metadata preserved, .bak backup kept) so they can still be analysed — healthy files are never touched (how & why)
🤖 CNN classifier (optional): A small ML model bundled with the package adds a 12th scoring rule on borderline cases. pip install "flac-detective[ml]" to enable.

🚀 Quick Start

Installation

# Install via pip (Recommended)
pip install flac-detective

# OR with the optional CNN classifier (Rule 12)
pip install "flac-detective[ml]"

# OR run with Docker (multi-arch: linux/amd64 + linux/arm64)
docker pull ghcr.io/guillain-rdcde/flac_detective:latest

Upgrading to the latest version

pip install flac-detective does not upgrade an existing install — if you already have an older version, pip prints Requirement already satisfied and exits without doing anything. To get the latest release, add the --upgrade flag (short form -U):

# Upgrade to the latest version on PyPI
pip install --upgrade flac-detective

# Same thing with the optional ML extra
pip install --upgrade "flac-detective[ml]"

# Verify the new version
flac-detective --version

# Docker: pull again to refresh the image
docker pull ghcr.io/guillain-rdcde/flac_detective:latest

📦 See Getting Started for complete installation instructions.

Basic Usage

# Analyze current directory
flac-detective .

# Analyze specific directory
flac-detective /path/to/music

# Interactive mode (prompts for paths, accepts drag-and-drop in Windows cmd)
flac-detective

Common Options

# Show version and help
flac-detective --version
flac-detective --help

# Verbose log + JSON output to a custom path
flac-detective -v --format json --output report.json /music

# Triage a whole library: CSV ranked most-suspicious-first (opens in any spreadsheet)
flac-detective /music --format csv --output triage.csv

# Quick scan (15 s sample instead of default 30 s)
flac-detective --sample-duration 15 /music

Triaging a large collection? --format csv writes one row per file, already sorted by score (most suspicious at the top) — sort/filter it in any spreadsheet to work through your library from the riskiest files down. The console summary also prints the top suspects so you see what to check first without opening anything.

📖 See User Guide for detailed usage examples and command line options.

Try it Now (No Installation Required)

Option 1: Docker with Sample File

# Download a sample FLAC file (public domain)
curl -O https://archive.org/download/test_flac/sample.flac

# Run analysis with Docker (mount current directory)
docker run --rm -v "$(pwd)":/data ghcr.io/guillain-rdcde/flac_detective:latest /data/sample.flac

Option 2: Quick Python Test

# Using Python (if you have pip installed)
pip install flac-detective
flac-detective --version
flac-detective --help

Option 3: Interactive Demo Script ⭐ (Best for Quick Test)

# Clone and run demo with synthetic test files
git clone https://github.com/Guillain-RDCDE/FLAC_Detective.git
cd FLAC_Detective
pip install -e .
python examples/quick_test.py

This creates test files and shows FLAC Detective in action in 30 seconds!

Option 4: GitHub Codespaces (Fully Interactive Online)

Click the "Code" button → "Codespaces" → "Create codespace"
Wait for environment setup (~30 seconds)
Run: pip install -e . && python examples/quick_test.py

No sample files? The tool works with any FLAC file from your music collection!

🎬 Demo

Live Demo

Watch FLAC Detective analyze files with real-time progress bars and colored output!

Example Output

======================================================================
  FLAC AUTHENTICITY ANALYZER
  Detection of MP3s transcoded to FLAC
======================================================================

⠋ Analyzing audio files... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  15% 0:02:34

======================================================================
  ANALYSIS COMPLETE
======================================================================
  FLAC files analyzed: 245
  Authentic files: 215 (87.8%)
  Fake/Suspicious files: 12 (4.9%)
  Text report: flac_report_20251220_143022.txt
======================================================================

⚡ Performance

FLAC Detective is optimized for both speed and accuracy:

Speed: 2-5 seconds per file (30s sample, default)
Throughput: 700-1,800 files/hour on modern hardware
Memory: ~150-300 MB peak usage
Optimization: 80% faster than baseline through intelligent caching and parallel processing
Scalability: Handles libraries with 10,000+ files efficiently

Customizable Performance:

# Faster analysis (15s per file) - good for quick scans
flac-detective /music --sample-duration 15

# Balanced (30s per file) - default, recommended
flac-detective /music

# More thorough (60s per file) - maximum accuracy
flac-detective /music --sample-duration 60

❓ Frequently Asked Questions

Does it work on Windows/Mac/Linux?

Yes! FLAC Detective is cross-platform and works on:

✅ Windows (7, 10, 11)
✅ macOS (10.14+)
✅ Linux (all major distributions)

How accurate is the detection?

FLAC Detective uses an 11-rule scoring system with protection layers:

High confidence: >95% accuracy for AUTHENTIC and FAKE_CERTAIN verdicts
Protection mechanisms: Prevents false positives for vinyl rips, cassette transfers, and high-quality sources
4-level system: AUTHENTIC, WARNING, SUSPICIOUS, FAKE_CERTAIN for nuanced results
Known blind spot (be honest): high-bitrate AAC and VBR transcodes, and transcodes of already band-limited recordings (baroque, historical, acoustic), are hard for any spectral tool to detect. On such material, treat AUTHENTIC as "no evidence of transcoding" rather than a guarantee.

Will it damage or modify my files?

Analysis is read-only. It only reads your files, never rewrites them — safe to run across your whole collection. There is exactly one exception, and it's hi-fi-safe by design: if a FLAC is so corrupted it can't be decoded at all (even after retries), the tool rebuilds a valid FLAC from it so the analysis can proceed. That rebuild is lossless — it uses Xiph's reference flac tool to recover the exact PCM samples and re-encode them bit-for-bit; no resampling, normalisation or "enhancement" ever touches the audio. It keeps a .corrupted.bak backup, restores all tags/artwork, and verifies the result before replacing anything. Healthy files are never rewritten.

→ Full, step-by-step explanation: Repair — lossless reconstruction. A standalone duration-fixer is also available: python -m flac_detective.repair /path/to/files.

Can I trust the results?

Yes, with common sense. Each score band and what to do about it is in the verdict table near the top of this README. For critical decisions, confirm with a complementary tool (e.g. Spek for visual spectral analysis).

What file formats are supported?

Currently:

✅ FLAC files (.flac) — read natively
✅ WAV files (.wav) — read natively, since v0.15.0
✅ ALAC (Apple Lossless, .m4a) and APE (Monkey's Audio, .ape) — since v0.16.0, decoded via ffmpeg (a hard dependency for these formats only; FLAC/WAV never need it). An .m4a holding lossy AAC is correctly rejected, not analysed.

How long does analysis take?

About 2–5 s per file with the default 30 s sample — roughly 50–90 min for 1,000 files, a few hours for a 10,000-file library. The Performance section above covers throughput and how --sample-duration trades speed for thoroughness.

Can I use it in my own application?

Yes! FLAC Detective provides a Python API:

from flac_detective import FLACAnalyzer

analyzer = FLACAnalyzer()
result = analyzer.analyze_file("song.flac")
print(result['verdict'])  # AUTHENTIC, WARNING, SUSPICIOUS, or FAKE_CERTAIN

See examples/ directory for integration examples.

Is it free and open source?

Yes! MIT License:

✅ Free for personal and commercial use
✅ Open source on GitHub
✅ Contributions welcome

How can I contribute?

Bug reports, code, docs, and testing are all welcome — see CONTRIBUTING.md.

📚 Documentation

📖 Full documentation site: guillain-rdcde.github.io/FLAC_Detective (searchable, built from docs/ on every release).

The same content lives in the docs/ directory:

Documentation Index - Overview and navigation
Getting Started - Installation and first analysis
User Guide - Complete usage guide with examples
Technical Details - Deep dive into detection rules and algorithms
API Reference - Python API documentation
Contributing - Development guide

🎯 Use Cases

Library Maintenance: Clean your music collection of fake lossless files
Quality Verification: Validate FLAC authenticity before archiving
Batch Processing: Analyze large music libraries efficiently
Format Validation: Ensure genuine lossless quality for critical listening

💡 Quick Examples

See the examples/ directory for ready-to-run scripts:

basic_usage.py - Simple file and directory analysis
batch_processing.py - Process multiple directories with statistics
json_export.py - Export results to JSON for further processing
api_integration.py - Advanced API usage and integration patterns

🤝 Contributing

Contributions are welcome! Please read our CONTRIBUTING.md for detailed guidelines and CODE_OF_CONDUCT.md for community standards.

🔒 Security

For security policy and vulnerability reporting, please see SECURITY.md.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Security: see SECURITY.md

🙏 Acknowledgements

Thanks to the community members who took the time to report bugs and confirm fixes — first issues are special.

@GearKite — Filed #7 with a clean traceback that pinpointed the circular import in v0.9.6, and #6 spotting the underscore-vs-dash Docker image name.
@Aakiles — Diagnosed the circular import end-to-end and shipped a working patch via comment. The v0.9.7 fix is a refinement of his approach.
@AnotherMuggle and @tomelephant-git — Confirmed the fix across operating systems, including Windows 11 LTSC.
@AKHwyJunkie — Confirmed the v0.9.6 import crash, validating @GearKite's report.
@pblue3 — First reported the Docker image inaccessibility (#6).

⭐ Star History

FLAC Detective - Maintaining authentic lossless audio collections

Name		Name	Last commit message	Last commit date
Latest commit History 216 Commits
.claude		.claude
.github		.github
assets		assets
dev-tools		dev-tools
docker		docker
docs		docs
examples		examples
ml		ml
scripts		scripts
src/flac_detective		src/flac_detective
tests		tests
.bandit		.bandit
.flake8		.flake8
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.readthedocs.yml		.readthedocs.yml
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

🎵 FLAC Detective

🔍 How it works

🤖 The ML side is a case study worth reading

🆕 Latest release — v1.0 (first stable release)

✨ Key Features

🚀 Quick Start

Installation

Upgrading to the latest version

Basic Usage

Common Options

Try it Now (No Installation Required)

🎬 Demo

Live Demo

Example Output

⚡ Performance

❓ Frequently Asked Questions

Does it work on Windows/Mac/Linux?

How accurate is the detection?

Will it damage or modify my files?

Can I trust the results?

What file formats are supported?

How long does analysis take?

Can I use it in my own application?

Is it free and open source?

How can I contribute?

📚 Documentation

🎯 Use Cases

💡 Quick Examples

🤝 Contributing

🔒 Security

📝 License

📞 Support

🙏 Acknowledgements

⭐ Star History

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 22

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages