Thomas Hallock
57b6d333e9
Full documentation covering architecture, deployment, API endpoints, speaker entity mapping, pipeline stages, and how recommendations improve over time. Fixed stale speaker entity reference. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1.7 KiB
1.7 KiB
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
# 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
# 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