🎵 Music Auto Tagger | Automated Music Library Organizer

English | 简体中文

Music Auto Tagger is an automated music library organizer based on audio fingerprinting and duration sequence fingerprinting. Designed for NAS and server environments, it monitors your download folder, identifies music files, fetches comprehensive metadata (including lyrics), and organizes them into a clean structure.

Core Value: Say goodbye to messy music folders. Automatically tag, cover, and organize your music library to perfection.

📊 Web Monitoring Dashboard

The built-in real-time monitoring dashboard provides:

• 📊 Real-time statistics and processing progress
• 📝 Recently processed files with detailed metadata
• 📋 Live system logs with auto-scroll
• ⚙️ System configuration and status overview
• ✅ Pending review queue and manual re-identification pages, sharing one design system

🆕 What's New in 1.4.0

• 🖥️ Redesigned Web UI: A shared design system across the dashboard, review, and recovery pages — two-column dashboard layout, cover-art wall for recent albums, unified dialogs/toasts, collapsible navigation on narrow screens, and a fully localized (CN/EN) interface.
• ✅ Manual Review Queue (review.enabled): When tracks are recognized but the album cannot be determined, the folder is queued instead of being archived by guesswork. Original files keep their tags, names, and locations until you confirm a release, archive it as “not in MusicBrainz”, or reject it.
• 🛠️ Re-identification & Recovery: A dedicated page for the partial_files / failed_files quarantine folders. Retry jobs run in an atomic workspace (rollback on failure, cross-filesystem safe), and a recycle bin with a retention policy keeps the quarantined copies restorable.
• 🌐 Online-assisted Identification: Optional web search to build album candidates for hard cases, with two backends — native model web search or Tavily (llm.webSearch.provider). Candidates require at least one HIGH or two independent MEDIUM sources, and they always end up in the review queue for human confirmation, never auto-archived.
• 🤖 New LLM Configuration Model: Providers are first-class (name / URL / key / explicit OpenAI or Claude protocol / multiple models), stored in data/llm-providers.json. Pull models from a provider to fill a dropdown and self-test connectivity in one click. Old comma-separated settings are migrated automatically on first start. Server-side SSRF guards only allow public HTTPS endpoints unless llm.allowPrivateEndpoints is enabled.
• 🧠 LLM Album Judging: Optional LLM arbitration for ambiguous album matches, with an auto-apply confidence threshold.
• 🎨 Anime-edition Cover Preference (cover.preferAnimeEdition): For Japanese OP/ED singles that ship both an anime jacket and a regular artist jacket, candidate releases are scored by keyword so the anime cover wins, with fallback to the default cover.
• 🏷️ Release-type Tags for Plex: Writes EP / Single / Album release types and MusicBrainz IDs so Plex and similar players can distinguish them properly.
• 🕘 Historical Cover Backfill: A maintenance tool (Settings → Advanced) that backfills release_group_id for already-processed records album-by-album and warms the cover cache. Resumable, never touches audio files, and only accepts exact title matches with score ≥ 80.
• ⚡ Matching & Performance Fixes: Cache priority reordered (manual > duration sequence > quick scan > voting), multi-disc track counting fixed, release-group–level margin comparison, cached tag scanning, and album-artist resolution from artist credits (no more single-artist albums landing in Various Artists).
• 🔒 Security Hardening: audio.normalize.ffmpegPath is read-only via the API (command-execution vector), secrets are returned masked from GET /api/config, write APIs validate CSRF, and filenames are sanitized for length, reserved device names, and traversal-unsafe components.

Upgrading from an earlier version? Read UPGRADE_NOTES.md first.

✨ Key Features

• 🎧 Audio Fingerprinting: Uses Chromaprint (AcoustID) to accurately identify files even with garbled filenames (e.g., track01.mp3).
• 📝 Authoritative Metadata: Sources data from MusicBrainz to automatically complete Title, Artist, Album, Year, Composer, Lyricist, and more.
• 📜 Synced Lyrics: 🆕 Integrates with LrcLib to automatically download and embed synced lyrics (.lrc), perfect for modern players.
• 🖼️ HD Cover Art: Automatically downloads and embeds high-quality album art from the Cover Art Archive.
• 📁 Automated Organization: Automatically renames and sorts files into a Artist/Album/Title structure.
• 🤖 Unattended Operation: Works seamlessly with qBittorrent/Transmission to process downloads automatically upon completion.
• ⚡ Smart Scan Optimization: 🆕 Two-tier identification + folder-level caching
  • Tier 1: Quick Scan - Tag & duration sequence matching, passes at 90% accuracy
  • Tier 2: Fingerprint - Only triggered when quick scan fails, ensures high recognition rate
  • Folder-level Caching - Subsequent files in the same album use cached results, skip all scans
  • Performance Boost: Processing a 16-track album requires only 1 full scan + 15 cache lookups
• 💾 Dual Persistence Modes:
  • File Mode (Default): Uses a CSV file to track processed files. Zero config, ready out of the box for personal use.
  • MySQL Mode: Supports external database connection for massive libraries and high concurrency.
• 🐳 Docker Ready: Provides lightweight Docker images compatible with Synology, QNAP, Unraid, and other NAS systems.
• 🔄 Smart Retry: Automatically handles network failures with retry logic and isolates failed files for later inspection.
• 📊 Web Monitoring Dashboard: 🆕 Built-in real-time monitoring dashboard to visualize processing progress, system status, and runtime logs.
• 🌐 Multi-language Support: 🆕 Supports both Chinese and English interfaces, easily switchable via configuration file, providing localized experience for global users.
• 🤖 LLM Artist Matching: Optional LLM-assisted matching for partial recognition scenarios. When files have tags and covers but fingerprint recognition fails, uses LLM to fuzzy match artist names (supports romanization, aliases, translations, etc.) and automatically archives to the correct artist folder. Supports multiple providers/models with automatic failover.
• ✅ Human-in-the-loop: 🆕 Ambiguous albums go to a review queue instead of being archived incorrectly; quarantined files can be retried, confirmed with online evidence, or restored from the recycle bin.

⚠️ Best Practice: How to Get the Most Accurate Results

Since music releases are extremely complex (Singles, EPs, Albums, Compilations, Deluxe Editions, etc.), to ensure the tool accurately categorizes your music into the correct albums, it is highly recommended to follow this practice:

Please place audio files from the same album (or single) into a separate folder before processing them with this tool.

❌ Not Recommended: Dumping hundreds of songs from different artists and albums into a single directory. ✅ Recommended:

• /Downloads/Jay_Chou_Fantasy/ (Contains songs from the Fantasy album)
• /Downloads/Adele_21/ (Contains songs from the 21 album)

Reason: When files are isolated in separate folders, the program can better determine that they belong to the same album based on context, avoiding misidentification of album tracks as "Best Of" compilations or "Single" versions.

Quick Start (Docker Compose)

The easiest way to run the application. Configuration is done in the web UI after login.

1. Create docker-compose.yml

   version: '3.8'
   services:
     music-tagger:
       image: ghcr.io/lux032/musicautotagger:latest
       container_name: music-tagger
       ports:
         - "8080:8080"  # Web dashboard
       environment:
         - PUID=1000
         - PGID=1000
         - UMASK=022
       volumes:
         - /path/to/downloads:/music
         - /path/to/music_library:/app/tagged_music
         # admin account, review queue, LLM providers, recovery trash
         - ./data:/app/data
         # quarantine dirs used by the recovery page (otherwise lost on recreate)
         - ./partial_files:/app/partial_files
         - ./failed_files:/app/failed_files
         - ./config.properties:/app/config.properties
       restart: unless-stopped

   Set PUID/PGID to match the NAS user/group that owns your mounted folders. UMASK controls default permissions.

2. Start Service

   docker-compose up -d

3. Access Web Monitoring Dashboard

   Open http://localhost:8080 in your browser.

   • First visit will prompt you to create an admin account (stored in data/admin.json).
   • If config.properties is missing, the app auto-generates it on startup.
   • All settings (API keys, database, proxy, paths, language) are managed in the web UI.

💻 Local Installation

If you prefer to run it locally for development or testing:

Prerequisites

• JDK 17+
• Maven 3.6+
• Chromaprint (fpcalc) (Must be added to system PATH)
• FFmpeg (Must be added to system PATH)

Build & Run

# 1. Build
mvn clean package

# 2. Run
java -jar target/MusicDemo-1.0-SNAPSHOT.jar

# 3. Access Web Dashboard
# Open http://localhost:8080 in your browser

Configuration is created automatically on first run. All settings (API keys, database, proxy, paths, language) are managed in the web UI after login.

📚 Documentation

• QNAP NAS Users: See QNAP Deployment Guide (Chinese)
• Database Setup: Default is file-based. For MySQL setup, see Database Setup
• Windows Guide: Windows Build & Test
• Upgrade Notes: UPGRADE_NOTES.md (behaviour changes and operational caveats)
• Album Matching: ALBUM_MATCHING_FIXES.md, FOLDER_ALBUM_CACHE.md
• All Settings: see config.properties.example; every documented key is also editable in the web settings panel (except the read-only audio.normalize.ffmpegPath).

🤝 Contribution

Issues and Pull Requests are welcome!

If this project helps you, please consider giving it a ⭐ Star!

📄 License

This project is licensed under the MIT License.

License Summary

The MIT License is a permissive open source license that allows you to:

• ✅ Commercial use
• ✅ Modification
• ✅ Distribution
• ✅ Private use

The only requirement is to include the copyright notice and license notice in all copies or substantial portions of the software.

Third-Party Services

This tool relies on the following third-party services. Please respect their respective Terms of Service:

• MusicBrainz - Music metadata service
• AcoustID - Audio fingerprinting service
• LrcLib - Lyrics service
• Cover Art Archive - Album art service
• FFmpeg - Audio processing toolkit

---

Disclaimer: This tool relies on third-party services (MusicBrainz, AcoustID, LrcLib). Please respect their Terms of Service.