mirror of
https://github.com/gabehf/music-importer.git
synced 2026-04-22 11:31:52 -07:00
63 lines
2.9 KiB
Markdown
63 lines
2.9 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# 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 `AlbumResult`s 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.
|