music-identify

# Music Identify Identify songs from audio using AudD, return song info with Spotify link, and optionally queue to the user's active Spotify session. ## Runtime Dependencies Required on `$PATH`: - `curl` — HTTP requests to AudD and Spotify APIs - `jq` — JSON parsing for all API responses - `python3` — Spotify OAuth flow only (`scripts/spotify-auth.py`) ## Credentials | Credential | Location | Required | Purpose | |---|---|---|---| | AudD API key | `~/.config/audd/api_key` | Yes | Song identification | | Spotify OAuth tokens | `~/.config/spotify/tokens.json` | No (optional) | Queue to Spotify | | Spotify app credentials | `~/.config/spotify/credentials.json` | No (optional) | Token refresh | **Security notes:** - All credential files should be restricted: `chmod 600`. - This skill does not read, store, or access any platform tokens (Telegram, Discord, etc.). Audio file download from messaging platforms is handled by the host agent, not by this skill. ## Trigger - User sends `/songsearch` then follows with a voice message or audio file - User asks to identify a song from audio ("what song is this", "identify this song", "shazam this") - User asks to recall previously identified songs ("what was that song", "what did I shazam") ## Setup ### AudD API Key (required) 1. Sign up at <https://audd.io> (free tier: 300 requests, no credit card) 2. Save key: ```bash mkdir -p ~/.config/audd echo "YOUR_KEY" > ~/.config/audd/api_key chmod 600 ~/.config/audd/api_key ``` ### Spotify Integration (optional) 1. Create a Spotify Developer app at <https://developer.spotify.com/dashboard> 2. Set redirect URI to your callback URL 3. Save credentials: ```bash mkdir -p ~/.config/spotify cat > ~/.config/spotify/credentials.json << 'EOF' {"client_id": "...", "client_secret": "...", "redirect_uri": "https://your-host/callback"} EOF chmod 600 ~/.config/spotify/credentials.json ``` 4. Run the auth flow: `python3 scripts/spotify-auth.py` 5. Open the printed URL in a browser, authorize, tokens save automatically 6. `chmod 600 ~/.config/spotify/tokens.json` ## Workflow — Song Identification When a song identification is triggered: 1. Prompt user for a voice clip if not already provided. 2. Save the audio file to a temp location (e.g., `/tmp/music-identify-<timestamp>.ogg`). The host agent handles downloading audio from the messaging platform (Telegram, Discord, etc.) — this skill only needs the local file path. 3. Run identification: ```bash scripts/identify.sh /path/to/audio-file.ogg ``` 4. Parse the JSON result and respond. 5. If Spotify is configured and active, queue the track. 6. Log the identification to `memory/music-log.json`. **Supported formats:** OGG/Opus, MP3, WAV, FLAC, M4A. No transcoding needed — AudD accepts all common audio formats. ## Workflow — Spotify Queue After a successful identification, if Spotify tokens exist at `~/.config/spotify/tokens.json`: ```bash # Check if anything is playing scripts/spotify-queue.sh status # Queue the identified track scripts/spotify-queue.sh queue "spotify:track:<track_id>" ``` If no active Spotify session is found, fall back to returning the Spotify link only. Token refresh is handled automatically by `spotify-queue.sh` on 401 responses. ## Response Format - **Found**: `🎵 {title} by {artist}` + Spotify link on next line. If Spotify active, note it was queued. - **Found, no Spotify match**: `🎵 {title} by {artist}` (no link) - **Not found**: "Couldn't identify that one. Try a longer clip with more of the melody (5+ seconds works best)." - **Error**: "Something went wrong with the identification. Try again." - **Missing AudD key**: "AudD API key not configured. Get one at https://audd.io and save to ~/.config/audd/api_key" ## Memory Logging Append identified songs to `memory/music-log.json` (one JSON object per line): ```json {"date":"2026-03-22","time":"14:30","title":"Viva La Vida","artist":"Coldplay","album":"Viva la Vida","spotify":"https://open.spotify.com/track/..."} ``` Create the file if it doesn't exist. For recall queries, read and present this log. ## Scripts | Script | Purpose | Dependencies | |---|---|---| | `scripts/identify.sh <audio_file>` | POST audio to AudD, return JSON | curl, jq | | `scripts/spotify-auth.py [--url]` | One-time Spotify OAuth flow | python3 | | `scripts/spotify-queue.sh queue <uri>` | Queue track to active Spotify | curl, jq | | `scripts/spotify-queue.sh status` | Check current Spotify playback | curl, jq | Exit codes for `identify.sh`: 0=found, 1=not found, 2=error. ## API Reference See `references/audd-api.md` for AudD endpoint details, parameters, and response format.