Discogs MP3 Tagger

Core library for automatic MP3 tagging using the Discogs API.
This package contains all the business logic required to analyze MP3 files, match them against Discogs releases, compute tag updates, and apply those updates to the files.

It is designed to be UI-agnostic and can be reused in:

• CLI tools
• Electron desktop applications
• Web or server-side applications

No CLI parsing or UI code is included in this package.

Features

• Scan files and directories to collect MP3 files
• Read existing ID3 tags and audio metadata (duration, embedded artwork)
• Search Discogs using an heuristic, multi-step strategy:
  • Prefer master releases
  • Automatic fallback to single release search when no master exists
• Resolve the most suitable release and track using:
  • Duration matching (preferred)
  • Title similarity (fallback)
• Compute a snapshot containing all proposed tag and artwork changes
• Let consumers review, modify, or override proposed changes before applying
• Apply tags and cover artwork to MP3 files
• Progress reporting via a reusable reporter callback API

Requirements

• Node.js >= 18
• A Discogs API token
  (create one at https://www.discogs.com/settings/developers)

Installation

npm install @salvobee/discogs-tagger