Intelligent Music File Organizer
Automatically identify, tag, and organize your music library using audio fingerprinting and online metadata services.
- Audio Fingerprinting: Identifies songs via AcoustID/Chromaprint -- even with missing or wrong tags
- Multi-Source Metadata: Pulls from MusicBrainz, Discogs, Internet Archive, and Cover Art Archive
- Internet Archive Integration: Primary source for known collections (e.g. DJ Screw "Diary of the Originator") with text-search fallback for other tracks
- DJ Screw / Compilation Detection: Automatically detects DJ mixes, compilations, and the 363-chapter "Diary of the Originator" series with specialized matching
- Confidence Scoring: Auto-applies high-confidence matches, flags uncertain ones for review
- Smart Organization: Sorts files into
Artist/Album (Year)/01 - Title.extstructure - Fuzzy Matching: Corrects misspelled tags using fuzzy string matching
- Parallel Fingerprinting: Configurable thread pool (default: half your CPU cores) for fast batch fingerprinting
- API Response Caching: Caches AcoustID, MusicBrainz, and Discogs responses in SQLite to avoid redundant API calls across runs
- Dry-Run Mode: Preview exactly what would change before committing any modifications
- Pause / Resume / Cancel: Full control over long-running batch operations, with clean shutdown on app close
- Resume on Restart: Tracks already processed are skipped when you re-run the same batch
- Safe Operations: Backs up originals before any changes, with full rollback support
- Modern Desktop UI: PyQt6 interface with drag-and-drop, progress tracking, manual search, and review queue
Your music files are important. Fingerprint Flow is designed to never lose your data.
- Backups first: Original files are backed up before tags are modified -- the backup always has your unmodified file
- Dry-run mode: Preview every change (tag edits, file moves) before anything happens
- Full rollback: Every file move is recorded in a database -- undo individual files or entire batches
- No overwrites: Duplicate files are detected and skipped, never silently replaced
- Integrity checks: Cross-drive moves verify file size after copying before deleting the source
- Source protection: The app never deletes directories outside your configured library path
- System path blocking: System directories (
C:\Windows,/usr, etc.) are blocked as library paths
See SECURITY.md for the full data safety policy.
MP3, FLAC, M4A/AAC, OGG Vorbis, OGG Opus, WMA, AIFF, WAV, APE, WavPack
The fpcalc binary is required for audio fingerprinting. Without it, the app falls back to tag-based fuzzy matching (less accurate but still functional).
Windows:
Download from https://acoustid.org/chromaprint
Extract and place fpcalc.exe in the project directory or add it to your PATH.
macOS:
brew install chromaprintLinux (Debian/Ubuntu):
sudo apt install libchromaprint-tools# Clone the repository
git clone https://github.com/uhaop/Fingerprint-flow.git
cd fingerprint-flow
# Create a virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS/Linux
# Install the package (includes all dependencies)
pip install -e .
# Or install from requirements.txt
pip install -r requirements.txt-
Copy the example config:
cp config/config.example.yaml config/config.yaml
-
Get your free API keys and add them to
config/config.yaml:- AcoustID: Register at https://acoustid.org/new-application
- Discogs (optional): Generate a token at https://www.discogs.com/settings/developers
You can also set keys via environment variables in a
.envfile (loaded automatically via python-dotenv).
# Launch the GUI
python -m src.main
# Or use the installed command
fingerprint-flow- Import: Drop a folder or select files to scan
- Fingerprint: Files are fingerprinted in parallel via Chromaprint (configurable worker count)
- Identify: Fingerprints are matched against AcoustID, then metadata is fetched from MusicBrainz and Discogs
- DJ Screw fast path: Known DJ Screw chapters are matched directly against Internet Archive (skips MusicBrainz/Discogs)
- Fallback: Tracks without fingerprint matches are searched by existing tags/filename via fuzzy matching. Internet Archive is used as a fallback when MusicBrainz/Discogs return nothing.
- Score: A confidence score is calculated from multiple factors (fingerprint match, title/artist similarity, duration, album consistency)
- Organize: High-confidence matches (>90%) are auto-applied; uncertain matches go to a review queue with manual search
- Output: Files are renamed and moved into a clean
Artist/Album (Year)/Trackstructure
fingerprint-flow/
src/
main.py # Entry point, config loading
core/ # Core processing engine
batch_processor.py # Orchestrator (scan -> fingerprint -> match -> organize)
scanner.py # Audio file discovery
fingerprinter.py # Chromaprint / AcoustID (parallel batch + lookup)
metadata_fetcher.py # MusicBrainz / Discogs API client
archive_org_fetcher.py # Internet Archive metadata source
confidence_scorer.py # Weighted match scoring algorithm
fuzzy_matcher.py # String similarity matching (rapidfuzz)
tag_editor.py # Read/write audio metadata tags (mutagen)
file_organizer.py # File moves with backup and rollback
dj_screw_handler.py # DJ Screw chapter detection and matching
compilation_detector.py # Compilation / mixtape / DJ mix detection
report_writer.py # Unmatched report generation (JSON + text)
models/ # Data models (Track, MatchResult, ProcessingState, AppConfig)
db/ # SQLite database layer (state, history, API cache)
gui/ # PyQt6 desktop interface
app.py # Main window with sidebar navigation
worker.py # Background threads (processing, review apply, manual search)
views/ # Import, Progress, Preview, Review, Library, Settings
widgets/ # Reusable components (ConfidenceBadge, MatchSelector, etc.)
styles/ # Theme module (Catppuccin Mocha/Latte)
utils/ # Constants, file helpers, logging, rate limiter
config/ # Configuration files (config.yaml, config.example.yaml)
tests/ # Test suite (pytest)
Docs/ # Architecture Decision Records, API reference links
The app works without Chromaprint but with reduced accuracy (tag-based matching only). To fix:
- Download the pre-built binary (not source) from https://acoustid.org/chromaprint
- Extract
fpcalc.exe(Windows) orfpcalc(macOS/Linux) - Place it in the project directory, or add the folder containing
fpcalcto your systemPATH - Restart Fingerprint Flow
- Register a free application at https://acoustid.org/new-application
- Set
acoustid_api_keyinconfig/config.yaml(or via Settings in the GUI)
- Ensure Chromaprint is installed for best results
- Try lowering
auto_apply_thresholdinconfig/config.yaml(default: 90) - Check
fingerprint_flow.logfor details on why a match was rejected - Files with very short duration (<10s) or corrupted audio may not fingerprint -- you'll see
fpcalc exited with status 3in the logs. This is normal for intros, skits, interludes, and instrumentals. These tracks fall back to tag/filename-based matching instead. fpcalc exited with status 2means the file couldn't be decoded (possibly corrupted or unusual codec). The track still gets matched via tags/filename.
If the GUI becomes unresponsive during fingerprinting of large libraries, this is due to progress update frequency. The app throttles updates to prevent this, but very large batches (10,000+ files) may still cause brief pauses.
Contributions are welcome! Please read the Contributing Guide before submitting a PR.
See SECURITY.md for our data safety policy -- all PRs that touch file operations require extra review.