flac-detective 0.9.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

Option 1: Install via pip (Recommended)

pip install flac-detective

Option 2: Run with Docker

# Pull from GitHub Container Registry
docker pull ghcr.io/guillainm/flac-detective:latest

# Analyze files
docker run --rm -v /path/to/audio:/data ghcr.io/guillainm/flac-detective:latest /data

📦 See Docker Guide for complete Docker usage documentation.

Basic Usage

Command Line

# 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

Docker

# Analyze a directory
docker run --rm -v /path/to/audio:/data ghcr.io/guillainm/flac-detective:latest /data

# With repair enabled
docker run --rm -v /path/to/audio:/data ghcr.io/guillainm/flac-detective:latest /data --repair

# Generate JSON report
docker run --rm -v /path/to/audio:/data ghcr.io/guillainm/flac-detective:latest /data --format json > report.json

---

📖 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 import FLACAnalyzer
from pathlib import Path

# Create analyzer
analyzer = FLACAnalyzer(sample_duration=30.0)

# Analyze a file
result = analyzer.analyze_file(Path('song.flac'))

print(f"Verdict: {result['verdict']}")
print(f"Score: {result['score']}/100")
print(f"Reason: {result['reason']}")

📚 Full API documentation available at flac-detective.readthedocs.io

---

📦 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

Version Management & Releases

FLAC Detective uses Commitizen for automated changelog generation and version management.

# Install pre-commit hooks (includes commit message validation)
pre-commit install --hook-type commit-msg

# Create a conventional commit interactively
cz commit

# Bump version and update CHANGELOG automatically
cz bump --changelog

# Or use the helper script
python scripts/bump_version.py --dry-run  # Preview changes
python scripts/bump_version.py --push     # Bump and push to trigger release

All commits must follow the Conventional Commits format:

• feat: - New features (bumps MINOR version)
• fix: - Bug fixes (bumps PATCH version)
• docs: - Documentation changes
• refactor: - Code refactoring
• perf: - Performance improvements

See docs/ci-cd/CHANGELOG_AUTOMATION.md for detailed documentation.

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

📖 Official Documentation

Read the full documentation on Read the Docs

The complete documentation includes:

• User Guide: Getting started, usage examples, troubleshooting
• API Reference: Complete Python API documentation with examples
• Technical Documentation: Architecture, algorithms, scoring rules
• Development Guide: Contributing, testing, code quality

📄 Additional Resources

Complete documentation available in the docs/ directory:

• Documentation Index - Complete documentation structure
• Getting Started - Quick start guide for new users
• Troubleshooting - Common issues and solutions
• Docker Guide - Complete Docker installation and usage
• API Reference - Python API documentation
• Technical Documentation - Architecture and algorithms
• Contributing Guide - Development guidelines
• Changelog - Version history and release notes

---

🎯 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! Please read our CONTRIBUTING.md for detailed guidelines and CODE_OF_CONDUCT.md for community standards.

📋 Issue Templates

We provide templates for different types of contributions:

1. 🐛 Bug Report: Report bugs or unexpected behavior
2. ✨ Feature Request: Suggest new features or enhancements
3. ⚡ Performance Issue: Report slow performance or resource issues
4. 📝 Documentation Issue: Report documentation problems
5. ❓ Question: Ask questions about usage

View Issue Templates Guide for detailed information.

How to Contribute

1. Report Issues: Use the appropriate issue template
2. Suggest Features: Submit a feature request
3. Start Discussions: Join GitHub Discussions
4. Submit PRs: Read CONTRIBUTING.md first, then fork the repo, create a feature branch, and submit a pull request
5. Improve Docs: Documentation improvements are always appreciated

Community Guidelines

Please follow our Code of Conduct to maintain a welcoming and inclusive environment for all contributors.

Development Workflow

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

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

# Set up pre-commit hooks for code quality
python scripts/setup_precommit.py
# Or manually: pre-commit install

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

# Make changes and run tests
pytest tests/unit/ -v                    # Unit tests
pytest tests/integration/ -v             # Integration tests
pytest --cov=flac_detective              # With coverage

# Code quality checks (runs automatically on commit via pre-commit hooks)
pre-commit run --all-files               # Run all checks manually
black src tests                          # Format code
isort src tests                          # Sort imports
flake8 src tests                         # Lint code
mypy src                                 # Type check

# Commit and push (pre-commit hooks run automatically)
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Open Pull Request on GitHub

Python Version Requirements:

• Supported: Python 3.8 - 3.12
• Testing: Use Python 3.8-3.12 for running tests (scipy/numpy compatibility)

Running Tests:

# Run all unit tests
pytest tests/unit/ -v

# Run integration tests
pytest tests/integration/ -v

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

# See tests/TESTING_STATUS.md for detailed testing guide

---

🔒 Security

Security is a priority for FLAC Detective. We use multiple automated tools to ensure code and dependency security.

Security Features

• 🛡️ Dependabot: Automated dependency updates for security patches
• 🔍 CodeQL: Static code analysis for vulnerability detection
• 🚨 Bandit: Python security linter
• 📦 Safety & Pip-audit: Dependency vulnerability scanners
• 📋 Security Policy: Responsible disclosure process

Reporting Vulnerabilities

Please do NOT report security vulnerabilities through public GitHub issues.

Email security issues to: [e-mail]

See SECURITY.md for:

• Supported versions
• Reporting guidelines
• Security best practices
• Vulnerability disclosure process

Security Documentation

• SECURITY.md - Official security policy
• Security Guide - Comprehensive security documentation

---

📝 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.9.0 - Maintaining authentic lossless audio collections