bitrater 0.1.1__tar.gz

bitrater-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bitrater
+    permissions:
+      id-token: write  # Required for OIDC trusted publishing
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bitrater-0.1.1/.gitignore

@@ -0,0 +1,68 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.coverage
+htmlcov/
+.pytest_cache/
+.tox/
+
+# Misc
+.DS_Store
+
+# AI dev tools
+.claude/
+.serena/
+.worktrees/
+.mcp.json
+CLAUDE.md
+
+# Development docs and research papers
+docs/
+documents/
+images/
+
+# Training data (large files, user-provided)
+training_data/lossless/
+training_data/encoded/
+training_data/cache/
+training_data/analysis_results/
+training_data/logs/
+
+# Log files
+encoding_log_*.txt
+*.log
+
+# VS Code workspace
+*.code-workspace

bitrater-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 yamsnjams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bitrater-0.1.1/MODEL_CARD.md

@@ -0,0 +1,155 @@
+# Model Card: Bitrater Deep Learning Classifier
+
+## Model Details
+
+- **Architecture**: Two-stage CNN + BiLSTM with multi-head attention
+- **Task**: 7-class audio bitrate classification
+- **Version**: 1.0
+- **Files**: `bitrater/models/stage1_cnn.onnx` (1.7 MB), `bitrater/models/stage2_seq.onnx` (3.1 MB)
+- **Inference**: ONNX Runtime (no PyTorch required)
+- **Training**: PyTorch (optional `[training]` extra)
+- **License**: MIT (same as project)
+
+## Architecture
+
+### Stage 1: CNN Feature Extractor (~430K parameters)
+
+Extracts a 128-dimensional feature vector from each 2-second spectrogram window.
+
+| Layer | Output Shape | Notes |
+|-------|-------------|-------|
+| Conv2d(1, 32) + BN + ReLU + MaxPool2d(2) | (32, 64, T/2) | |
+| Conv2d(32, 64) + BN + ReLU + MaxPool2d(2) | (64, 32, T/4) | |
+| Conv2d(64, 128) + BN + ReLU + MaxPool2d(2) | (128, 16, T/8) | |
+| Conv2d(128, 256) + BN + ReLU + MaxPool2d(2) | (256, 8, T/16) | |
+| AdaptiveAvgPool2d(1) + Linear(256, 128) | (128,) | Feature vector |
+
+Dropout (p=0.2) after each conv block.
+
+### Stage 2: Sequence Classifier (~700K parameters)
+
+Processes sequences of 48 CNN feature vectors with auxiliary features.
+
+- **BiLSTM**: 2-layer, hidden_dim=128, bidirectional (output: 256-dim per timestep)
+- **Multi-head attention pooling**: 4 heads over LSTM outputs
+- **Auxiliary input**: 211-dim vector (181 SVM spectral features + 30 global modulation DCT features)
+- **Classifier head**: Linear(256+211, 256) -> ReLU -> Linear(256, 7)
+- **VBR auxiliary head**: Linear(256, 32) -> ReLU -> Linear(32, 1)
+
+### Input Representation
+
+**Dual-band spectrogram** (128 frequency bins x T time frames):
+- Bins 0-63: Mel-scale filterbank, 0-16 kHz (captures overall spectral content)
+- Bins 64-127: Linear-scale, 16-22 kHz with ~94 Hz resolution (captures MP3 compression cutoffs)
+
+This gives 3x better frequency resolution in the critical 16-22 kHz region compared to a standard 128-bin mel spectrogram, enabling precise detection of:
+- CBR 192 cutoff at ~18.6 kHz
+- CBR 320 cutoff at ~20.5 kHz
+- VBR's variable cutoff behavior vs CBR's fixed cutoff
+
+### Inference Pipeline
+
+For each file:
+1. Load audio at 44.1 kHz mono
+2. Compute shared STFT (n_fft=2048, hop=512)
+3. Extract dual-band spectrograms for 2-second windows (1-second hop)
+4. CNN forward pass on all needed windows -> 128-dim feature vectors
+5. Extract global modulation features (2D DCT over log-mel, 30 coefficients)
+6. Extract SVM spectral features (181-dim PSD/cutoff/temporal/artifact vector)
+7. Sliding window over sequences of 48 CNN features + auxiliary features
+8. Average softmax probabilities across all sequences -> final prediction
+
+Typical inference time: 2-5 seconds per file on CPU.
+
+## Training
+
+### Dataset
+
+Training data was generated by transcoding a collection of ~2,400 lossless FLAC files (85 GB) to MP3 at each target bitrate using LAME:
+
+| Class | Encoding | Files | Description |
+|-------|----------|-------|-------------|
+| 128 | `lame -b 128` | ~2,400 | CBR 128 kbps |
+| V2 | `lame -V 2` | ~2,400 | VBR preset 2 (~170-210 kbps) |
+| 192 | `lame -b 192` | ~2,400 | CBR 192 kbps |
+| V0 | `lame -V 0` | ~2,400 | VBR preset 0 (~220-260 kbps) |
+| 256 | `lame -b 256` | ~2,400 | CBR 256 kbps |
+| 320 | `lame -b 320` | ~2,400 | CBR 320 kbps |
+| LOSSLESS | (original) | ~2,400 | Source FLAC files |
+
+Total: ~16,800 files across 7 classes. Split: 80% train, 10% validation, 10% test.
+
+Source material spans diverse genres and recording conditions.
+
+### Training Procedure
+
+**Stage 1 (CNN warmup):**
+- Train `WindowClassifier` on individual 2-second spectrogram windows
+- 25 epochs, OneCycleLR (max_lr=1e-3), batch size 64
+- Focal loss (gamma=2.0) with class weighting [1.0, 2.0, 2.0, 1.5, 1.0, 1.0, 1.0]
+- Label smoothing (0.05)
+- Max 10 random windows sampled per file per epoch
+
+**Stage 2 (sequence training):**
+- Freeze CNN, train `SequenceClassifier` on sequences of 48 CNN feature vectors
+- 60 epochs, OneCycleLR (max_lr=3e-4), batch size 32
+- Same focal loss and class weighting as Stage 1
+- 4 random sequences sampled per file per epoch
+- Early stopping with patience 15 on validation accuracy
+
+**Hardware**: Trained on NVIDIA GTX 1660 Super (6 GB VRAM), FP32 only (no Tensor Cores).
+
+### Key Design Decisions
+
+- **Dual-band filterbank**: Standard mel spectrograms lose resolution above 16 kHz. The linear high-frequency band provides precise cutoff detection.
+- **Two-stage training**: Separates representation learning (CNN on windows) from temporal reasoning (BiLSTM on sequences).
+- **Focal loss with class weighting**: V2 and 192 kbps are inherently hard to separate (overlapping bitrate ranges), so they receive 2x class weight.
+- **SVM features as auxiliary input**: The hand-crafted SVM features (PSD bands, cutoff detection, temporal statistics) provide complementary information to the learned CNN features.
+- **Global modulation features**: 2D DCT over the full-file spectrogram captures long-range spectral patterns that distinguish VBR's gradually varying lowpass filter from CBR's fixed cutoff.
+- **Variance features disabled**: Ablation study showed temporal variance/range features did not improve accuracy when SVM+global modulation features are present.
+
+## Performance
+
+**Overall accuracy: 98.42%** (file-level evaluation on held-out test set, 1,391 files)
+
+### Per-Class Metrics
+
+| Class | Precision | Recall | F1 Score | Support |
+|-------|-----------|--------|----------|---------|
+| 128 | 98.5% | 100.0% | 99.2% | 195 |
+| V2 | 98.4% | 97.3% | 97.8% | 184 |
+| 192 | 97.7% | 98.2% | 97.9% | 219 |
+| V0 | 98.1% | 97.7% | 97.9% | 217 |
+| 256 | 99.4% | 99.4% | 99.4% | 170 |
+| 320 | 97.7% | 98.6% | 98.1% | 213 |
+| LOSSLESS | 99.5% | 97.9% | 98.7% | 193 |
+
+### Confusion Matrix
+
+Rows are true labels, columns are predictions.
+
+| | 128 | V2 | 192 | V0 | 256 | 320 | LOSSLESS |
+|----------|----:|---:|----:|---:|----:|----:|---------:|
+| **128** | 195 | 0 | 0 | 0 | 0 | 0 | 0 |
+| **V2** | 1 | 179 | 3 | 1 | 0 | 0 | 0 |
+| **192** | 1 | 3 | 215 | 0 | 0 | 0 | 0 |
+| **V0** | 0 | 0 | 0 | 212 | 0 | 4 | 1 |
+| **256** | 0 | 0 | 1 | 0 | 169 | 0 | 0 |
+| **320** | 1 | 0 | 0 | 1 | 1 | 210 | 0 |
+| **LOSSLESS** | 0 | 0 | 1 | 2 | 0 | 1 | 189 |
+
+Total errors: 22/1,391 (1.58%). V2/192 cross-confusion: 6 files.
+
+### Known Limitations
+
+- **V2/192 confusion**: These two classes have the most overlap — V2 VBR averages 170-210 kbps with a variable lowpass filter, while CBR 192 has a fixed ~18.6 kHz cutoff. The model achieves ~97.8% F1 on both, but some edge cases remain.
+- **LAME encoder only**: Training data was generated with LAME. Other MP3 encoders (FhG, Fraunhofer) may produce different spectral signatures.
+- **44.1 kHz sample rate**: Files must be 44.1 kHz for accurate analysis. Other sample rates will be resampled by librosa.
+- **Minimum file length**: Files shorter than ~50 seconds may have fewer sequences for aggregation, potentially reducing confidence.
+
+## Research Foundation
+
+- **SVM baseline**: D'Alessandro & Shi (2009), "MP3 Bit Rate Quality Detection through Frequency Spectrum Analysis"
+- **CNN approach**: Informed by Hennequin et al. (2017, Deezer/ICASSP) and Seichter et al. (2016, Fraunhofer)
+- **Global modulation**: Inspired by "Generalized Spoofing Detection Inspired from Audio Generation Artifacts" (2021)
+- **VBR vs CBR discrimination at similar bitrates**: Novel contribution — no published work addresses this specific problem

bitrater-0.1.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: bitrater
+Version: 0.1.1
+Summary: Audio quality analysis and bitrate detection, with optional beets plugin
+Project-URL: Homepage, https://github.com/yamsnjams/bitrater
+Project-URL: Repository, https://github.com/yamsnjams/bitrater
+Project-URL: Bug Tracker, https://github.com/yamsnjams/bitrater/issues
+Author-email: yamsnjams <yamsnjams@protonmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: audio,beets,bitrate,mp3,spectral-analysis,transcoding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: <3.14,>=3.10
+Requires-Dist: joblib>=1.0.0
+Requires-Dist: librosa>=0.10.0
+Requires-Dist: mutagen>=1.45.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: onnxruntime>=1.16.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: tqdm>=4.60.0
+Provides-Extra: beets
+Requires-Dist: beets>=1.6.0; extra == 'beets'
+Provides-Extra: dev
+Requires-Dist: black>=22.0.0; extra == 'dev'
+Requires-Dist: flake8>=4.0.0; extra == 'dev'
+Requires-Dist: isort>=5.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: training
+Requires-Dist: torch>=2.0.0; extra == 'training'
+Requires-Dist: torchaudio>=2.0.0; extra == 'training'
+Description-Content-Type: text/markdown
+
+# bitrater
+
+Audio quality analysis and bitrate detection for audio files. Detects the true encoding quality of MP3, FLAC, WAV, AAC, and other formats using spectral analysis and deep learning. Identifies transcodes (e.g., a 128 kbps source re-encoded as 320 kbps MP3 or upsampled to FLAC) and verifies lossless files are genuinely lossless.
+
+Available as a **standalone CLI tool** or as a **[beets](https://beets.io/) plugin**.
+
+## Features
+
+- **7-class bitrate classification**: 128, 192, 256, 320 kbps CBR, V0/V2 VBR presets, and lossless (FLAC/WAV/AIFF)
+- **Lossless verification**: confirms whether lossless files are truly lossless or transcodes from lossy sources
+- **Transcode detection**: identifies files whose stated bitrate doesn't match their true encoding quality
+- **Pre-trained deep learning model**: ships with a CNN+BiLSTM model achieving 98.4% accuracy
+- **Confidence scoring**: every prediction includes a confidence score
+- **Feature caching**: thread-safe NPZ cache avoids redundant spectral analysis
+- **Parallel processing**: multi-threaded analysis via joblib
+
+## Installation
+
+Requires Python 3.10+ and [FFmpeg](https://ffmpeg.org/).
+
+### Standalone (no beets)
+
+```bash
+pip install bitrater
+```
+
+### With beets plugin
+
+```bash
+pip install "bitrater[beets]"
+```
+
+Then enable the plugin in your beets config (`~/.config/beets/config.yaml`):
+
+```yaml
+plugins: bitrater
+```
+
+### From source (with uv)
+
+```bash
+git clone https://github.com/yamsnjams/bitrater.git
+cd bitrater
+uv sync              # standalone
+uv sync --all-extras # with beets + training + dev dependencies
+```
+
+## Quick Start
+
+### Standalone CLI
+
+```bash
+# Analyze a single file
+bitrater analyze song.mp3
+
+# Analyze a directory
+bitrater analyze /path/to/music/
+
+# Verbose output (show warnings)
+bitrater -v analyze /path/to/music/
+```
+
+Example output:
+```
+[OK] song.mp3: MP3 320kbps (confidence: 95%)
+[TRANSCODE] another.mp3: MP3 128kbps (confidence: 88%)
+[OK] track.flac: LOSSLESS (confidence: 97%)
+[TRANSCODE] fake_lossless.flac: MP3 192kbps (confidence: 91%)
+```
+
+### Beets Plugin
+
+```bash
+# Analyze your library (or a subset via query)
+beet bitrater
+beet bitrater artist:radiohead
+
+# Verbose output
+beet bitrater -v
+```
+
+The plugin stores results in beets' database as custom fields:
+
+| Field | Description |
+|-------|-------------|
+| `original_bitrate` | Estimated true encoding bitrate |
+| `bitrate_confidence` | Confidence score (0.0-1.0) |
+| `is_transcoded` | Whether the file appears to be a transcode |
+| `spectral_quality` | Overall spectral quality score |
+| `format_warnings` | Warning messages from analysis |
+
+## Pre-trained Model
+
+Bitrater ships with a pre-trained deep learning model that works out of the box. No training is required. See [MODEL_CARD.md](MODEL_CARD.md) for full details on the model architecture, training data, and performance metrics.
+
+The bundled model achieves **98.4% accuracy** across all 7 classes on a held-out test set.
+
+## Beets Plugin Configuration
+
+All options and their defaults:
+
+```yaml
+bitrater:
+    auto: false              # Auto-analyze on import
+    min_confidence: 0.8      # Minimum confidence threshold
+    warn_transcodes: true    # Show transcode warnings
+    threads: null            # Analysis threads (null = auto)
+    on_transcode: ask        # Action for transcodes: ask, quarantine, keep, skip
+    quarantine_dir: null     # Quarantine folder (default: {library}/.quarantine/)
+```
+
+### Transcode Handling
+
+When a counterfeit/transcoded file is detected, `on_transcode` controls the behavior:
+
+| Value | Behavior |
+|-------|----------|
+| `ask` | Prompt the user: Keep, Quarantine, or Skip (default) |
+| `quarantine` | Automatically move to quarantine folder |
+| `keep` | Log a warning but take no action |
+| `skip` | Remove from library and delete the file |
+
+The quarantine folder defaults to `.quarantine/` inside your beets library directory.
+Set `quarantine_dir` to override with a custom path.
+
+## How It Works
+
+### Spectral Analysis
+
+Audio files are analyzed in the frequency domain. MP3 encoding introduces characteristic artifacts:
+
+- **Frequency cutoffs**: lower bitrates have lower high-frequency cutoffs (e.g., 128 kbps cuts off around 16 kHz)
+- **Spectral flatness**: lossy compression reduces spectral detail in high frequencies
+- **SFB21 band**: the highest scale factor band is a strong indicator of encoding quality
+
+### Deep Learning Classifier
+
+Two-stage CNN + BiLSTM architecture (~1.1M total parameters):
+
+- **Stage 1**: CNN feature extractor on dual-band spectrograms (64 mel + 64 linear HF bins, 2-second windows)
+- **Stage 2**: BiLSTM with multi-head attention over sequences of 48 CNN features, plus 211 auxiliary features (spectral + global modulation DCT)
+- Focal loss with class weighting, file-level aggregation across all sequences
+- **98.4% overall accuracy** with all classes above 96% F1
+
+See [MODEL_CARD.md](MODEL_CARD.md) for complete details.
+
+## Development
+
+```bash
+# Run tests
+uv run python -m pytest tests/
+
+# Run tests with coverage
+uv run python -m pytest tests/ --cov=bitrater --cov=beetsplug
+
+# Format and lint
+uv run black bitrater/ beetsplug/ tests/
+uv run ruff check --fix bitrater/ beetsplug/ tests/
+```
+
+## License
+
+[MIT](LICENSE)

bitrater-0.1.1/README.md

@@ -0,0 +1,163 @@
+# bitrater
+
+Audio quality analysis and bitrate detection for audio files. Detects the true encoding quality of MP3, FLAC, WAV, AAC, and other formats using spectral analysis and deep learning. Identifies transcodes (e.g., a 128 kbps source re-encoded as 320 kbps MP3 or upsampled to FLAC) and verifies lossless files are genuinely lossless.
+
+Available as a **standalone CLI tool** or as a **[beets](https://beets.io/) plugin**.
+
+## Features
+
+- **7-class bitrate classification**: 128, 192, 256, 320 kbps CBR, V0/V2 VBR presets, and lossless (FLAC/WAV/AIFF)
+- **Lossless verification**: confirms whether lossless files are truly lossless or transcodes from lossy sources
+- **Transcode detection**: identifies files whose stated bitrate doesn't match their true encoding quality
+- **Pre-trained deep learning model**: ships with a CNN+BiLSTM model achieving 98.4% accuracy
+- **Confidence scoring**: every prediction includes a confidence score
+- **Feature caching**: thread-safe NPZ cache avoids redundant spectral analysis
+- **Parallel processing**: multi-threaded analysis via joblib
+
+## Installation
+
+Requires Python 3.10+ and [FFmpeg](https://ffmpeg.org/).
+
+### Standalone (no beets)
+
+```bash
+pip install bitrater
+```
+
+### With beets plugin
+
+```bash
+pip install "bitrater[beets]"
+```
+
+Then enable the plugin in your beets config (`~/.config/beets/config.yaml`):
+
+```yaml
+plugins: bitrater
+```
+
+### From source (with uv)
+
+```bash
+git clone https://github.com/yamsnjams/bitrater.git
+cd bitrater
+uv sync              # standalone
+uv sync --all-extras # with beets + training + dev dependencies
+```
+
+## Quick Start
+
+### Standalone CLI
+
+```bash
+# Analyze a single file
+bitrater analyze song.mp3
+
+# Analyze a directory
+bitrater analyze /path/to/music/
+
+# Verbose output (show warnings)
+bitrater -v analyze /path/to/music/
+```
+
+Example output:
+```
+[OK] song.mp3: MP3 320kbps (confidence: 95%)
+[TRANSCODE] another.mp3: MP3 128kbps (confidence: 88%)
+[OK] track.flac: LOSSLESS (confidence: 97%)
+[TRANSCODE] fake_lossless.flac: MP3 192kbps (confidence: 91%)
+```
+
+### Beets Plugin
+
+```bash
+# Analyze your library (or a subset via query)
+beet bitrater
+beet bitrater artist:radiohead
+
+# Verbose output
+beet bitrater -v
+```
+
+The plugin stores results in beets' database as custom fields:
+
+| Field | Description |
+|-------|-------------|
+| `original_bitrate` | Estimated true encoding bitrate |
+| `bitrate_confidence` | Confidence score (0.0-1.0) |
+| `is_transcoded` | Whether the file appears to be a transcode |
+| `spectral_quality` | Overall spectral quality score |
+| `format_warnings` | Warning messages from analysis |
+
+## Pre-trained Model
+
+Bitrater ships with a pre-trained deep learning model that works out of the box. No training is required. See [MODEL_CARD.md](MODEL_CARD.md) for full details on the model architecture, training data, and performance metrics.
+
+The bundled model achieves **98.4% accuracy** across all 7 classes on a held-out test set.
+
+## Beets Plugin Configuration
+
+All options and their defaults:
+
+```yaml
+bitrater:
+    auto: false              # Auto-analyze on import
+    min_confidence: 0.8      # Minimum confidence threshold
+    warn_transcodes: true    # Show transcode warnings
+    threads: null            # Analysis threads (null = auto)
+    on_transcode: ask        # Action for transcodes: ask, quarantine, keep, skip
+    quarantine_dir: null     # Quarantine folder (default: {library}/.quarantine/)
+```
+
+### Transcode Handling
+
+When a counterfeit/transcoded file is detected, `on_transcode` controls the behavior:
+
+| Value | Behavior |
+|-------|----------|
+| `ask` | Prompt the user: Keep, Quarantine, or Skip (default) |
+| `quarantine` | Automatically move to quarantine folder |
+| `keep` | Log a warning but take no action |
+| `skip` | Remove from library and delete the file |
+
+The quarantine folder defaults to `.quarantine/` inside your beets library directory.
+Set `quarantine_dir` to override with a custom path.
+
+## How It Works
+
+### Spectral Analysis
+
+Audio files are analyzed in the frequency domain. MP3 encoding introduces characteristic artifacts:
+
+- **Frequency cutoffs**: lower bitrates have lower high-frequency cutoffs (e.g., 128 kbps cuts off around 16 kHz)
+- **Spectral flatness**: lossy compression reduces spectral detail in high frequencies
+- **SFB21 band**: the highest scale factor band is a strong indicator of encoding quality
+
+### Deep Learning Classifier
+
+Two-stage CNN + BiLSTM architecture (~1.1M total parameters):
+
+- **Stage 1**: CNN feature extractor on dual-band spectrograms (64 mel + 64 linear HF bins, 2-second windows)
+- **Stage 2**: BiLSTM with multi-head attention over sequences of 48 CNN features, plus 211 auxiliary features (spectral + global modulation DCT)
+- Focal loss with class weighting, file-level aggregation across all sequences
+- **98.4% overall accuracy** with all classes above 96% F1
+
+See [MODEL_CARD.md](MODEL_CARD.md) for complete details.
+
+## Development
+
+```bash
+# Run tests
+uv run python -m pytest tests/
+
+# Run tests with coverage
+uv run python -m pytest tests/ --cov=bitrater --cov=beetsplug
+
+# Format and lint
+uv run black bitrater/ beetsplug/ tests/
+uv run ruff check --fix bitrater/ beetsplug/ tests/
+```
+
+## License
+
+[MIT](LICENSE)

bitrater-0.1.1/beetsplug/bitrater/__init__.py

@@ -0,0 +1,9 @@
+"""Beets plugin for bitrater — wraps the standalone bitrater library."""
+
+from bitrater._threading import clamp_threads
+
+clamp_threads()
+
+from beetsplug.bitrater.plugin import BitraterPlugin  # noqa: E402
+
+__all__ = ["BitraterPlugin"]