52 lines
4 KiB
Markdown
52 lines
4 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
**Musiksammlung** is a Python CLI tool that automates digitizing physical CD collections for use with Jellyfin. It orchestrates: CD ripping (via `abcde`), phone-based back cover photo upload, Vision-LLM analysis, OCR of cover/back images (via Tesseract), LLM-based tracklist extraction, file renaming/tagging, and M3U playlist generation.
|
||
|
|
|
||
|
|
## Build & Development Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pip install -e ".[dev]" # Install in editable mode with dev deps
|
||
|
|
pytest tests/ -v # Run all tests
|
||
|
|
pytest tests/test_models.py -v # Run a single test module
|
||
|
|
ruff check src/ tests/ # Lint
|
||
|
|
musiksammlung --help # CLI entry point
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
The pipeline flows: **Rip → (Vision-LLM parallel) → Organize → Tag → Playlist**
|
||
|
|
|
||
|
|
- `models.py` — Pydantic models (`Album`, `Disc`, `Track`) shared across all modules; `Album` includes optional `genre` field; the LLM JSON output validates directly into `Album`
|
||
|
|
- `cli.py` — Typer CLI with three commands: `scan` (OCR+LLM→JSON), `apply` (JSON→files), `process` (full pipeline); `rip` command accepts `--vision-model`, `--vision-url`, `--scanner-port`; `scan` supports five modes: `--barcode` (EAN→MB), `--from-photo` (photo→Vision-LLM→EAN→MB), `--from-text` (text→LLM), `--vision` (image→Vision-LLM), default (image→OCR→LLM)
|
||
|
|
- `ocr.py` — Tesseract wrapper with Pillow-based image preprocessing
|
||
|
|
- `llm_parser.py` — Sends OCR text to LLM (Ollama or OpenAI-compatible), enforces JSON output, retries on parse failure
|
||
|
|
- `organizer.py` — Builds source→target file mapping, handles single-disc and multi-disc layouts
|
||
|
|
- `tagger.py` — Sets audio tags via mutagen (format-agnostic), optional cover embedding for FLAC/MP3
|
||
|
|
- `playlist.py` — Generates M3U playlists with relative paths
|
||
|
|
- `cddb.py` — GnuDB/CDDB lookup via HTTP; returns `CddbResult` (tracks, artist, album, year from DYEAR, genre from DGENRE)
|
||
|
|
- `musicbrainz.py` — MusicBrainz lookup by EAN/barcode; returns `Album` model
|
||
|
|
- `ripper.py` — Drives `abcde` via subprocess; EAN-first interactive workflow (MusicBrainz auto-rip on hit, CDDB fallback on miss); scanner server starts at top of every album loop for EAN barcode photo and/or back cover upload; EAN can be typed or photographed (Vision-LLM reads the barcode); starts album Vision-LLM in background thread while ripping; extracts MBID from abcde temp dirs (`abcde.*/mbid.N`) for CAA cover download; outputs concrete copy-paste `apply` commands at the end
|
||
|
|
- `vision_llm.py` — Vision-LLM: `parse_image()` extracts album metadata from back cover photos; `extract_barcode_from_image()` reads EAN/barcode digits from CD sleeve photos
|
||
|
|
- `scanner_server.py` — Mini HTTP server (default port 8765) for phone-based photo upload; serves both EAN barcode scanning and back cover upload; mobile-friendly upload form; QR code displayed in terminal at start of every album; `ScannerServer` class + `print_qr()` helper
|
||
|
|
- `cover.py` — Resizes/converts cover images to JPEG for Jellyfin
|
||
|
|
|
||
|
|
## Vision-LLM Priority
|
||
|
|
|
||
|
|
Data sources are used with this priority (highest first):
|
||
|
|
|
||
|
|
1. **Vision-LLM** — result from analysing back cover photo (phone upload or CAA download)
|
||
|
|
2. **MusicBrainz** — structured metadata from EAN barcode lookup
|
||
|
|
3. **CDDB/GnuDB** — fallback from disc fingerprint lookup
|
||
|
|
|
||
|
|
## Conventions
|
||
|
|
|
||
|
|
- Python 3.11+, German variable names and comments are acceptable
|
||
|
|
- Pydantic for data models, Typer for CLI, mutagen for audio tagging
|
||
|
|
- External tools required at runtime: `tesseract`, `abcde`
|
||
|
|
- Firewall: port 8765 (TCP) must be open for phone scanner server (`sudo ufw allow 8765/tcp`)
|
||
|
|
- The two-step workflow (`rip` → review JSON → `apply`) is the recommended default over the one-shot `process` command
|
||
|
|
- `sanitize_filename` (organizer, used by ripper and apply): whitelist approach — spaces→`_`, keeps `\w` and hyphens, removes brackets and all other punctuation, collapses multiple underscores
|