Music Identify

Identify songs from audio clips using AudD API and optionally queue them to Spotify. Triggers on /songsearch command, voice messages with song identification intent, or when user asks "what song is this." Also handles recall queries like "what did I shazam" or "what was that song" by reading the music log. Works with any audio file (OGG, MP3, WAV, etc.).

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:

   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:

   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:

   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:

# 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):

{"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.