# 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