flac-detective 0.8.0

Advanced FLAC authenticity analyzer - Detects MP3-to-FLAC transcodes with high precision

🎵 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 advanced spectral analysis and an 11-rule scoring system, it helps you maintain an authentic lossless music collection.

---

✨ 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: Corrupted FLAC files are automatically repaired with full metadata preservation

---

🚀 Quick Start

Installation

pip install flac-detective

Basic Usage

# Analyze current directory
flac-detective .

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

# Generate JSON report
flac-detective /path/to/music --format json

# Verbose output with detailed analysis
flac-detective /path/to/music --verbose

---

📖 How It Works

Detection Rules

FLAC Detective uses 11 independent rules with additive scoring (0-150 points):

Rule	Description	Points
Rule 1	MP3 Spectral Signature (CBR patterns)	+50
Rule 2	Cutoff Frequency Analysis	+50
Rule 3	Bitrate Inflation Detection	+50
Rule 4	Suspicious 24-bit Detection	+30
Rule 5	High Variance Protection (VBR)	-40
Rule 6	High Quality Protection	-30
Rule 7	Vinyl & Silence Analysis	-100
Rule 8	Nyquist Exception	-50
Rule 9	Compression Artifacts	+30
Rule 10	Multi-Segment Consistency	Variable
Rule 11	Cassette Detection	-60

Verdict System

Based on the total score, FLAC Detective assigns one of four verdicts:

Score ≤ 30   → ✅ AUTHENTIC      (High confidence - genuine lossless)
Score 31-60  → ⚡ WARNING        (Manual review recommended)
Score 61-85  → ⚠️  SUSPICIOUS    (Likely transcode)
Score ≥ 86   → ❌ FAKE_CERTAIN   (Definite transcode)

Protection Mechanisms

The tool implements a multi-layer protection system to prevent false positives:

1. Absolute Protection (Rule 8): Protects files with cutoff near Nyquist frequency
2. MP3 320k Protection (Rule 1): Exception for high-quality MP3 320 kbps
3. Analog Source Protection (Rules 7, 11): Detects vinyl rips and cassette transfers
4. Dynamic Protection (Rule 10): Validates consistency across file segments

---

🆕 What's New in v0.8.0

Automatic FLAC Repair with Metadata Preservation

• Smart Corruption Detection: Automatically identifies corrupted FLAC files during analysis
• Decode-Through-Errors: Recovers maximum audio data from corrupted files using flac --decode-through-errors
• Complete Metadata Preservation: Extracts and restores all tags (TITLE, ARTIST, ALBUM, etc.) and album art
• Automatic Source Replacement: Replaces corrupted files with repaired versions (creates .corrupted.bak backups)
• Integrity Verification: All repaired files validated with flac --test before replacement
• 6-Step Repair Process:
  1. Extract metadata (tags + pictures)
  2. Decode with error recovery
  3. Re-encode to clean FLAC
  4. Restore all metadata
  5. Verify integrity
  6. Replace source with backup

Enhanced Diagnostics

• Detailed repair logging with step-by-step progress
• Diagnostic tracking for all repair operations
• Clear success/failure indicators
• Reduces false "CORRUPTED" verdicts

Energy-Based Cutoff Detection

• Critical Fix: Bass-heavy music no longer misidentified as MP3
• Added 15 kHz minimum threshold to distinguish bass from MP3 artifacts
• Impact: 77% reduction in false positives

Quality Improvements

• False positives: 198 → 46 (-77%)
• Authentic detection: 59 → 244 (+314%)
• Overall quality score: 20.2% → 83.6%

---

💻 Usage Examples

Command Line

# Basic analysis
flac-detective /path/to/music

# Save report to file
flac-detective /path/to/music --output report.txt

# JSON output for automation
flac-detective /path/to/music --format json > results.json

# Verbose mode with detailed rule execution
flac-detective /path/to/music --verbose

Python API

from flac_detective.analysis.new_scoring import new_calculate_score
from pathlib import Path

# Analyze a FLAC file
filepath = Path("/path/to/file.flac")
score, verdict, confidence, reasons = new_calculate_score(
    cutoff_freq=20500,
    metadata={"sample_rate": 44100, "bit_depth": 16, "channels": 2},
    duration_check={"duration": 180.5},
    filepath=filepath
)

print(f"Verdict: {verdict}")
print(f"Score: {score}/150")
print(f"Confidence: {confidence}")
print(f"Detection Reasons: {reasons}")

---

📦 Requirements

Python Dependencies

• Python 3.8 or higher
• numpy >= 1.20.0
• scipy >= 1.7.0
• mutagen >= 1.45.0
• soundfile >= 0.10.0
• rich >= 13.0.0

Optional System Dependencies

The flac command-line tool is recommended for advanced features:

Linux (Debian/Ubuntu):

sudo apt-get install flac

macOS:

brew install flac

Windows: Download from Xiph.org FLAC

---

🏗️ Development

Installation from Source

# Clone the repository
git clone https://github.com/GuillainM/FLAC_Detective.git
cd FLAC_Detective

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Linux/macOS:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=flac_detective --cov-report=html

# Run specific test file
pytest tests/test_new_scoring_rules.py -v

Project Structure

src/flac_detective/
├── analysis/
│   ├── new_scoring/          # 11-rule scoring system
│   │   ├── rules/            # Individual rule implementations
│   │   ├── calculator.py     # Score orchestration
│   │   └── verdict.py        # Score interpretation
│   ├── spectrum.py           # Spectral analysis
│   └── audio_cache.py        # Optimized file reading
├── reporting/                # Report generation
└── main.py                   # CLI entry point

---

📚 Documentation

• Getting Started - Quick start guide for new users
• Diagnostic & Troubleshooting - Error handling and troubleshooting
• Changelog - Version history and release notes
• Project Structure - Codebase organization

---

🎯 Use Cases

✅ Ideal For

• 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

⚠️ Limitations

• Only analyzes FLAC files (other lossless formats not supported)
• Designed for batch analysis, not real-time processing
• Detects transcodes, not subjective audio quality
• May require manual review for edge cases (WARNING verdicts)

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report Issues: Found a bug? Open an issue
2. Suggest Features: Have an idea? Start a discussion
3. Submit PRs: Fork the repo, create a feature branch, and submit a pull request
4. Improve Docs: Documentation improvements are always appreciated

Development Workflow

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/FLAC_Detective.git
cd FLAC_Detective

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
pytest

# Format code
black src tests
isort src tests

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Open Pull Request on GitHub

---

📝 License

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

---

🙏 Acknowledgments

• Audio analysis community for MP3 compression research
• Contributors to NumPy, SciPy, and Soundfile libraries
• Beta testers and community feedback

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Project Wiki

---

FLAC Detective v0.7.0 - Maintaining authentic lossless audio collections