haunt-fm/CLAUDE.md

# haunt-fm

Personal music recommendation service. Captures listening history from Music Assistant, discovers similar tracks via Last.fm, embeds audio with CLAP, and generates playlists.

## Quick Start

```bash
# On NAS
cd /volume1/homes/antialias/projects/haunt-fm
docker compose up -d
docker compose exec haunt-fm alembic upgrade head
```

## Architecture

- **FastAPI** app with async SQLAlchemy + asyncpg
- **PostgreSQL + pgvector** for tracks, embeddings, and vector similarity search
- **CLAP model** (laion/larger_clap_music) for 512-dim audio embeddings
- **Last.fm API** for track similarity discovery
- **iTunes Search API** for 30-second audio previews
- **Music Assistant** (via Home Assistant REST API) for playback

## Key Commands

```bash
# Health check
curl http://192.168.86.51:8321/health

# Log a listen event
curl -X POST http://192.168.86.51:8321/api/history/webhook \
  -H "Content-Type: application/json" \
  -d '{"title":"Song","artist":"Artist"}'

# Run discovery
curl -X POST http://192.168.86.51:8321/api/admin/discover -H "Content-Type: application/json" -d '{}'

# Get recommendations
curl http://192.168.86.51:8321/api/recommendations?limit=20

# Generate and play a playlist
curl -X POST http://192.168.86.51:8321/api/playlists/generate \
  -H "Content-Type: application/json" \
  -d '{"total_tracks":20,"known_pct":30,"speaker_entity":"media_player.living_room_speaker_2","auto_play":true}'
```

## Environment Variables

All prefixed with `HAUNTFM_`. See `.env.example` for full list.

## Database

- Alembic migrations in `alembic/versions/`
- Run migrations: `alembic upgrade head`
- Schema: tracks, listen_events, track_embeddings, similarity_links, taste_profiles, playlists, playlist_tracks