flac-detective 0.6.0__tar.gz

flac_detective-0.6.0/PKG-INFO

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: flac-detective
+Version: 0.6.0
+Summary: Advanced FLAC authenticity analyzer - Detects MP3-to-FLAC transcodes with high precision
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Keywords: flac,audio,analysis,transcode,detection,mp3,quality,authenticity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: mutagen>=1.45.0
+Requires-Dist: openpyxl>=3.0.0
+Requires-Dist: soundfile>=0.10.0
+Requires-Dist: matplotlib>=3.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pylint>=2.17.0; extra == "dev"
+
+# 🎵 FLAC Detective
+
+**Advanced FLAC Authenticity Analyzer - Production Ready v0.5.0**
+
+> "Every FLAC file tells a story... I find the truth."
+
+FLAC Detective is a professional-grade tool for detecting MP3-to-FLAC transcodes with exceptional precision. Using advanced spectral analysis and multi-rule scoring, it achieves 79.2% authentic detection rate with less than 0.5% false positives.
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-beta-yellow)](https://github.com/GuillainM/FLAC_Detective)
+
+## ✨ Features
+
+### 🎯 Advanced 12-Rule Detection System
+
+- **Rule 1**: MP3 Spectral Signature Detection (CBR patterns)
+- **Rule 2**: Cutoff Frequency Analysis vs Nyquist
+- **Rule 3**: Source vs Container Bitrate Comparison
+- **Rule 4**: Suspicious 24-bit File Detection
+- **Rule 5**: High Variance Protection (VBR)
+- **Rule 6**: High Quality Protection
+- **Rule 7**: Silence & Vinyl Analysis (3 phases)
+  - Phase 1: Dither detection
+  - Phase 2: Vinyl surface noise
+  - Phase 3: Clicks & pops
+- **Rule 8**: Nyquist Exception (95% & 90% thresholds)
+- **Rule 9**: Compression Artifacts Detection
+  - Test A: Pre-echo (MDCT ghosting)
+  - Test B: High-frequency aliasing
+  - Test C: MP3 quantization noise
+- **Rule 10**: Multi-Segment Consistency Analysis
+
+### 📊 4-Level Verdict System
+
+```
+Score ≥ 86  → FAKE_CERTAIN ❌ (100% confidence)
+Score 61-85 → SUSPICIOUS ⚠️  (High confidence)
+Score 31-60 → WARNING ⚡ (Manual review recommended)
+Score ≤ 30  → AUTHENTIC ✅ (99.5% confidence)
+```
+
+### ⚡ Performance Optimizations
+
+- **80% faster** than baseline (10 hours → 1h45 for 759 files)
+- Smart short-circuits for obvious cases
+- Parallel execution of expensive rules
+- File read caching
+- Progressive analysis (2→5 segments when needed)
+
+### 🎯 Production Metrics
+
+| Metric | Result | Status |
+|--------|--------|--------|
+| **Authentic Rate** | 79.2% | ✅ Excellent |
+| **Fake Detection** | 2.2% | ✅ Precise |
+| **False Positives** | < 0.5% | ✅ Minimal |
+| **Performance** | +80% | ✅ Optimized |
+
+## 🛠️ Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install flac-detective
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/GuillainM/FLAC_Detective.git
+cd FLAC_Detective
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install in development mode
+pip install -e .
+
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+## 🚀 Usage
+
+### Command Line
+
+```bash
+# 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
+flac-detective /path/to/music --verbose
+
+# Custom output file
+flac-detective /path/to/music --output report.txt
+```
+
+### Python API
+
+```python
+from flac_detective.analysis.new_scoring import new_calculate_score
+from pathlib import Path
+
+# Analyze a 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} (Score: {score}/150)")
+print(f"Confidence: {confidence}")
+print(f"Reasons: {reasons}")
+```
+
+## 📖 Documentation
+
+- [**Release Notes**](RELEASE_NOTES_v0.5.0.md) - What's new in v0.5.0
+- [**Changelog**](CHANGELOG.md) - Complete version history
+- [**Technical Documentation**](docs/TECHNICAL_DOCUMENTATION.md) - Architecture and algorithms
+- [**Rule Specifications**](docs/RULE_SPECIFICATIONS.md) - Detailed rule documentation
+- [**Performance Guide**](docs/PERFORMANCE_OPTIMIZATIONS.md) - Optimization strategies
+
+## 🏗️ Architecture
+
+```
+src/flac_detective/
+├── analysis/
+│   ├── new_scoring/          # Advanced scoring system (v0.5.0)
+│   │   ├── rules.py          # All 12 detection rules
+│   │   ├── calculator.py     # Orchestration & optimization
+│   │   ├── bitrate.py        # Bitrate calculations
+│   │   ├── silence.py        # Silence & vinyl analysis
+│   │   ├── artifacts.py      # Compression artifacts
+│   │   └── verdict.py        # Score interpretation
+│   ├── spectrum.py           # Spectral analysis
+│   └── audio_cache.py        # File read optimization
+├── reporting/                # Report generation
+└── main.py                   # CLI entry point
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=flac_detective --cov-report=html
+
+# Run specific test
+pytest tests/test_new_scoring_rules.py -v
+```
+
+**Test Coverage**: ~85% overall, 100% for critical rules
+
+## 📊 How It Works
+
+### Detection Process
+
+1. **Spectral Analysis**: Extract frequency spectrum and detect cutoff
+2. **Rule 8 (First)**: Apply Nyquist protection before other rules
+3. **Fast Rules (R1-R6)**: Quick checks for obvious cases
+4. **Short-Circuit**: Skip expensive rules if verdict is certain
+5. **Expensive Rules (R7, R9)**: Deep analysis when needed
+6. **Multi-Segment (R10)**: Validate consistency across file
+7. **Verdict**: Interpret final score with confidence level
+
+### Protection Hierarchy
+
+```
+LEVEL 1: Absolute Protection
+└─ R8 (95-98% Nyquist): -30 to -50 pts
+
+LEVEL 2: Targeted MP3 320k Protection  
+└─ R1 Exception (90% Nyquist): Skip 320k detection
+
+LEVEL 3: High Quality Protection
+├─ R5 (High Variance): -40 pts
+├─ R6 (High Quality): -30 pts
+└─ R7 (Vinyl/Silence): -50 to -100 pts
+
+LEVEL 4: Dynamic Protection
+└─ R10 (Segment Inconsistency): -20 to -30 pts
+```
+
+## 🎯 Use Cases
+
+### ✅ Recommended For
+
+- **Collection Cleaning**: Remove transcoded files from your library
+- **Quality Verification**: Validate FLAC authenticity before archiving
+- **Batch Processing**: Analyze large music libraries efficiently
+- **Vinyl Rip Validation**: Confirm authentic vinyl sources
+
+### ❌ Not Recommended For
+
+- **Lossy Format Analysis**: Only works with FLAC files
+- **Real-time Processing**: Designed for batch analysis
+- **Subjective Quality**: Detects transcodes, not audio quality
+
+## 🔮 Roadmap
+
+### v0.6 (Planned)
+
+- [ ] GUI interface for easier usage
+- [ ] Configurable sensitivity presets (Strict/Normal/Aggressive)
+- [ ] Per-rule enable/disable options
+- [ ] Custom threshold configuration
+- [ ] HTML reports with spectrograms
+- [ ] Automatic file organization
+
+### Future Considerations
+
+- Support for other lossless formats (ALAC, WAV)
+- Machine learning integration
+- Cloud-based analysis API
+- Music player integration
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Audio analysis community for research on MP3 compression
+- Contributors to NumPy, SciPy, and Soundfile libraries
+- Beta testers who provided valuable feedback
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/GuillainM/FLAC_Detective/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/GuillainM/FLAC_Detective/discussions)
+- **Documentation**: [Wiki](https://github.com/GuillainM/FLAC_Detective/wiki)
+
+## 📈 Project Stats
+
+- **Version**: 0.5.0 (Production Ready)
+- **Status**: Beta
+- **Python**: 3.8+
+- **License**: MIT
+- **Tested**: 759 files, 79.2% authentic rate
+
+---
+
+**Made with ❤️ for audio enthusiasts**
+
+**FLAC Detective v0.5.0** - *Because your music deserves authenticity*

flac_detective-0.6.0/README.md

@@ -0,0 +1,269 @@
+# 🎵 FLAC Detective
+
+**Advanced FLAC Authenticity Analyzer - Production Ready v0.5.0**
+
+> "Every FLAC file tells a story... I find the truth."
+
+FLAC Detective is a professional-grade tool for detecting MP3-to-FLAC transcodes with exceptional precision. Using advanced spectral analysis and multi-rule scoring, it achieves 79.2% authentic detection rate with less than 0.5% false positives.
+
+[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Status](https://img.shields.io/badge/status-beta-yellow)](https://github.com/GuillainM/FLAC_Detective)
+
+## ✨ Features
+
+### 🎯 Advanced 12-Rule Detection System
+
+- **Rule 1**: MP3 Spectral Signature Detection (CBR patterns)
+- **Rule 2**: Cutoff Frequency Analysis vs Nyquist
+- **Rule 3**: Source vs Container Bitrate Comparison
+- **Rule 4**: Suspicious 24-bit File Detection
+- **Rule 5**: High Variance Protection (VBR)
+- **Rule 6**: High Quality Protection
+- **Rule 7**: Silence & Vinyl Analysis (3 phases)
+  - Phase 1: Dither detection
+  - Phase 2: Vinyl surface noise
+  - Phase 3: Clicks & pops
+- **Rule 8**: Nyquist Exception (95% & 90% thresholds)
+- **Rule 9**: Compression Artifacts Detection
+  - Test A: Pre-echo (MDCT ghosting)
+  - Test B: High-frequency aliasing
+  - Test C: MP3 quantization noise
+- **Rule 10**: Multi-Segment Consistency Analysis
+
+### 📊 4-Level Verdict System
+
+```
+Score ≥ 86  → FAKE_CERTAIN ❌ (100% confidence)
+Score 61-85 → SUSPICIOUS ⚠️  (High confidence)
+Score 31-60 → WARNING ⚡ (Manual review recommended)
+Score ≤ 30  → AUTHENTIC ✅ (99.5% confidence)
+```
+
+### ⚡ Performance Optimizations
+
+- **80% faster** than baseline (10 hours → 1h45 for 759 files)
+- Smart short-circuits for obvious cases
+- Parallel execution of expensive rules
+- File read caching
+- Progressive analysis (2→5 segments when needed)
+
+### 🎯 Production Metrics
+
+| Metric | Result | Status |
+|--------|--------|--------|
+| **Authentic Rate** | 79.2% | ✅ Excellent |
+| **Fake Detection** | 2.2% | ✅ Precise |
+| **False Positives** | < 0.5% | ✅ Minimal |
+| **Performance** | +80% | ✅ Optimized |
+
+## 🛠️ Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install flac-detective
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/GuillainM/FLAC_Detective.git
+cd FLAC_Detective
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install in development mode
+pip install -e .
+
+# Install development dependencies
+pip install -e ".[dev]"
+```
+
+## 🚀 Usage
+
+### Command Line
+
+```bash
+# 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
+flac-detective /path/to/music --verbose
+
+# Custom output file
+flac-detective /path/to/music --output report.txt
+```
+
+### Python API
+
+```python
+from flac_detective.analysis.new_scoring import new_calculate_score
+from pathlib import Path
+
+# Analyze a 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} (Score: {score}/150)")
+print(f"Confidence: {confidence}")
+print(f"Reasons: {reasons}")
+```
+
+## 📖 Documentation
+
+- [**Release Notes**](RELEASE_NOTES_v0.5.0.md) - What's new in v0.5.0
+- [**Changelog**](CHANGELOG.md) - Complete version history
+- [**Technical Documentation**](docs/TECHNICAL_DOCUMENTATION.md) - Architecture and algorithms
+- [**Rule Specifications**](docs/RULE_SPECIFICATIONS.md) - Detailed rule documentation
+- [**Performance Guide**](docs/PERFORMANCE_OPTIMIZATIONS.md) - Optimization strategies
+
+## 🏗️ Architecture
+
+```
+src/flac_detective/
+├── analysis/
+│   ├── new_scoring/          # Advanced scoring system (v0.5.0)
+│   │   ├── rules.py          # All 12 detection rules
+│   │   ├── calculator.py     # Orchestration & optimization
+│   │   ├── bitrate.py        # Bitrate calculations
+│   │   ├── silence.py        # Silence & vinyl analysis
+│   │   ├── artifacts.py      # Compression artifacts
+│   │   └── verdict.py        # Score interpretation
+│   ├── spectrum.py           # Spectral analysis
+│   └── audio_cache.py        # File read optimization
+├── reporting/                # Report generation
+└── main.py                   # CLI entry point
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=flac_detective --cov-report=html
+
+# Run specific test
+pytest tests/test_new_scoring_rules.py -v
+```
+
+**Test Coverage**: ~85% overall, 100% for critical rules
+
+## 📊 How It Works
+
+### Detection Process
+
+1. **Spectral Analysis**: Extract frequency spectrum and detect cutoff
+2. **Rule 8 (First)**: Apply Nyquist protection before other rules
+3. **Fast Rules (R1-R6)**: Quick checks for obvious cases
+4. **Short-Circuit**: Skip expensive rules if verdict is certain
+5. **Expensive Rules (R7, R9)**: Deep analysis when needed
+6. **Multi-Segment (R10)**: Validate consistency across file
+7. **Verdict**: Interpret final score with confidence level
+
+### Protection Hierarchy
+
+```
+LEVEL 1: Absolute Protection
+└─ R8 (95-98% Nyquist): -30 to -50 pts
+
+LEVEL 2: Targeted MP3 320k Protection  
+└─ R1 Exception (90% Nyquist): Skip 320k detection
+
+LEVEL 3: High Quality Protection
+├─ R5 (High Variance): -40 pts
+├─ R6 (High Quality): -30 pts
+└─ R7 (Vinyl/Silence): -50 to -100 pts
+
+LEVEL 4: Dynamic Protection
+└─ R10 (Segment Inconsistency): -20 to -30 pts
+```
+
+## 🎯 Use Cases
+
+### ✅ Recommended For
+
+- **Collection Cleaning**: Remove transcoded files from your library
+- **Quality Verification**: Validate FLAC authenticity before archiving
+- **Batch Processing**: Analyze large music libraries efficiently
+- **Vinyl Rip Validation**: Confirm authentic vinyl sources
+
+### ❌ Not Recommended For
+
+- **Lossy Format Analysis**: Only works with FLAC files
+- **Real-time Processing**: Designed for batch analysis
+- **Subjective Quality**: Detects transcodes, not audio quality
+
+## 🔮 Roadmap
+
+### v0.6 (Planned)
+
+- [ ] GUI interface for easier usage
+- [ ] Configurable sensitivity presets (Strict/Normal/Aggressive)
+- [ ] Per-rule enable/disable options
+- [ ] Custom threshold configuration
+- [ ] HTML reports with spectrograms
+- [ ] Automatic file organization
+
+### Future Considerations
+
+- Support for other lossless formats (ALAC, WAV)
+- Machine learning integration
+- Cloud-based analysis API
+- Music player integration
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Audio analysis community for research on MP3 compression
+- Contributors to NumPy, SciPy, and Soundfile libraries
+- Beta testers who provided valuable feedback
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/GuillainM/FLAC_Detective/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/GuillainM/FLAC_Detective/discussions)
+- **Documentation**: [Wiki](https://github.com/GuillainM/FLAC_Detective/wiki)
+
+## 📈 Project Stats
+
+- **Version**: 0.5.0 (Production Ready)
+- **Status**: Beta
+- **Python**: 3.8+
+- **License**: MIT
+- **Tested**: 759 files, 79.2% authentic rate
+
+---
+
+**Made with ❤️ for audio enthusiasts**
+
+**FLAC Detective v0.5.0** - *Because your music deserves authenticity*