music-importer/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Build
go build -o importer .

# Build with version baked in
go build -ldflags="-X main.version=v1.0.0" -o importer .

# Run locally (requires IMPORT_DIR and LIBRARY_DIR env vars)
IMPORT_DIR=/path/to/import LIBRARY_DIR=/path/to/library ./importer

# Build Docker image
docker build -t music-importer .

# Build Docker image with version
docker build --build-arg VERSION=v1.0.0 -t music-importer .

There are no tests in this codebase.

Architecture

This is a single-package Go web app (package main) that runs as a web server on port 8080. Users trigger an import via the web UI, which runs the import pipeline in a background goroutine.

Pipeline flow (importer.go: RunImporter):

1. Cluster — loose audio files at the top of IMPORT_DIR are grouped into subdirectories by album tag (files.go: cluster)
2. For each album directory:
   • Clean tags — removes COMMENT/DESCRIPTION tags via metaflac (audio.go)
   • Tag metadata — tries beets first; falls back to reading existing file tags, then MusicBrainz API (metadata.go: getAlbumMetadata)
   • Lyrics — fetches synced LRC lyrics from LRClib API; falls back to plain lyrics formatted as LRC (lrc.go)
   • ReplayGain — runs rsgain easy on the directory (audio.go)
   • Cover art — looks for existing image files, downloads from Cover Art Archive via MusicBrainz if missing, then embeds into tracks (media.go)
   • Move — moves tracks, .lrc files, and cover image into LIBRARY_DIR/{Artist}/[{Date}] {Album} [{Quality}]/ (files.go: moveToLibrary)

Key types (importer.go):

• AlbumResult — tracks per-step success/failure/skip for one album
• ImportSession — holds all AlbumResults for one run; stored in lastSession global
• MusicMetadata — artist/album/title/date/quality used throughout the pipeline

Web layer (main.go):

• GET / — renders index.html.tmpl with the last session's results
• POST /run — starts RunImporter() in a goroutine; prevents concurrent runs via importerMu mutex

External tool dependencies (must be present in PATH at runtime):

• ffprobe — reads audio tags and stream info
• beet — metadata tagging via MusicBrainz (primary metadata source)
• rsgain — ReplayGain calculation
• metaflac — FLAC tag manipulation and cover embedding
• curl — MusicBrainz API fallback queries

Environment variables:

• IMPORT_DIR — source directory scanned for albums
• LIBRARY_DIR — destination library root
• COPYMODE=true — copies files instead of moving (still destructive on the destination)
• SLSKD_URL — base URL of the slskd instance (e.g. http://localhost:5030)
• SLSKD_API_KEY — slskd API key (sent as X-API-Key header)

Releases: Docker image gabehf/music-importer is built and pushed to Docker Hub via GitHub Actions on v* tags.