discover-music

# Discover Music Skill Find new music for Horus based on taste profile and external discovery services. ## Quick Start ```bash cd .pi/skills/discover-music # Find similar artists ./run.sh similar "Chelsea Wolfe" # Get trending artists ./run.sh trending --range week # Search by genre/style tag ./run.sh search-tag "doom metal" # Search by bridge attribute ./run.sh bridge Corruption # Get fresh releases ./run.sh fresh # Check API connectivity ./run.sh check ``` ## Discovery Services | Service | API | Use For | |---------|-----|---------| | **MusicBrainz** | Free (User-Agent only) | Artist search, metadata, genre tags, relationships | | **ListenBrainz** | Free (token optional) | Similar artists, trending, user stats, recommendations | No API keys required for basic functionality. ListenBrainz token enables personalized recommendations. ## Commands ### Similar Artists ```bash ./run.sh similar "<artist>" [--limit 10] [--json] ``` Find artists similar to a given artist via ListenBrainz + MusicBrainz tags fallback. ### Trending Artists ```bash ./run.sh trending [--range week|month|year|all_time] [--limit 10] [--json] ``` Get site-wide trending artists from ListenBrainz. ### Search by Tag ```bash ./run.sh search-tag "<tag>" [--limit 10] [--json] ``` Search MusicBrainz for artists by genre/style tag (e.g., "doom metal", "dark folk"). ### Search by Bridge ```bash ./run.sh bridge <attribute> [--limit 10] [--json] ``` Search for music matching an HMT bridge attribute: | Bridge | MusicBrainz Tags | |--------|------------------| | Precision | progressive metal, math rock, technical death metal, djent | | Resilience | epic metal, power metal, post-rock, cinematic, symphonic metal | | Fragility | dark folk, acoustic, slowcore, sadcore, singer-songwriter | | Corruption | industrial, doom metal, sludge metal, dark ambient, noise | | Loyalty | neofolk, neoclassical, world, ritual ambient, medieval | | Stealth | drone, dark ambient, ambient, minimalist, atmospheric | ### Fresh Releases ```bash ./run.sh fresh [--limit 10] [--json] ``` Get fresh/new releases from ListenBrainz explore API. ### User Top Artists ```bash ./run.sh user-top <username> [--range all_time] [--limit 10] [--json] ``` Get a ListenBrainz user's top artists. ### Check APIs ```bash ./run.sh check ``` Test connectivity to MusicBrainz and ListenBrainz APIs. ## Integration with /dogpile This skill can be invoked via `/dogpile music`: ```bash # Via dogpile /dogpile music "dark atmospheric metal similar to Chelsea Wolfe" # Equivalent to ./run.sh similar "Chelsea Wolfe" ./run.sh search-tag "dark atmospheric metal" ``` ## Configuration Environment variables (optional, in `.env`): ```bash LISTENBRAINZ_TOKEN=xxx # Optional: enables personalized recommendations LISTENBRAINZ_USERNAME=xxx # Optional: for user-specific queries ``` MusicBrainz requires no API key - only a User-Agent string (preconfigured as `HorusAgent/1.0`). ## Crucial Dependencies | Library | API/Method | Sanity Script | Status | |---------|------------|---------------|--------| | musicbrainzngs | MusicBrainz API | `sanity/musicbrainz.py` | [x] PASS | | pylistenbrainz | ListenBrainz API | `sanity/listenbrainz.py` | [x] PASS | | requests | HTTP client | N/A (well-known) | - | ## Rate Limits | Service | Limit | Implementation | |---------|-------|----------------| | MusicBrainz | 1 req/sec | Enforced in client | | ListenBrainz | ~2 req/sec | 0.5s minimum interval | ## Example Horus Queries ```bash # "What's similar to Chelsea Wolfe?" ./run.sh similar "Chelsea Wolfe" --limit 10 # "Find doom metal artists" ./run.sh search-tag "doom metal" # "Music for a battle scene" (Resilience bridge) ./run.sh bridge Resilience # "Dark ambient for corruption scene" ./run.sh bridge Corruption # "What's trending this week?" ./run.sh trending --range week # "New releases for discovery" ./run.sh fresh --json ``` ## Common Mistakes ### WRONG: Hammering MusicBrainz API without respecting rate limits ```python for artist in artists: search(artist) # 1 req/sec limit, will get blocked ``` ### RIGHT: Rate limits are enforced in the client (1 req/sec MusicBrainz, 0.5s ListenBrainz) ```bash # The skill handles rate limiting internally — just use the CLI ./run.sh similar "Chelsea Wolfe" ``` ### WRONG: Searching by bridge attribute without understanding the mapping ```bash ./run.sh bridge "dark metal" # not a valid bridge name ``` ### RIGHT: Use one of the 6 bridge attributes ```bash ./run.sh bridge Corruption # maps to: industrial, doom metal, dark ambient ./run.sh bridge Fragility # maps to: dark folk, acoustic, slowcore ``` ### WRONG: Not using --json for agent consumption ```bash ./run.sh similar "Chelsea Wolfe" # human-readable but hard to parse ``` ### RIGHT: Use --json for structured output ```bash ./run.sh similar "Chelsea Wolfe" --json # parseable JSON array ``` ## Output Formats All commands support `--json` for agent-parseable output: ```json [ {"name": "Emma Ruth Rundle", "mbid": "abc123...", "similarity": 0.85}, {"name": "Lingua Ignota", "mbid": "def456...", "similarity": 0.78} ] ```