Files

Thomas Hallock 7ff69449d6 Initial haunt-fm implementation

Full music recommendation pipeline: listening history capture via webhook,
Last.fm candidate discovery, iTunes preview download, CLAP audio embeddings
(512-dim), pgvector cosine similarity recommendations, playlist generation
with known/new track interleaving, and Music Assistant playback via HA.

Includes: FastAPI app, SQLAlchemy models, Alembic migrations, Docker Compose
with pgvector/pg17, status dashboard, and all API endpoints.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-22 08:36:36 -06:00

1.7 KiB

Raw Blame History

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_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

1.7 KiB Raw Blame History