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#

CredentialLocationRequiredPurposeAudD API key~/.config/audd/api_keyYesSong identificationSpotify OAuth tokens~/.config/spotify/tokens.jsonNo (optional)Queue to SpotifySpotify app credentials~/.config/spotify/credentials.jsonNo (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#

ScriptPurposeDependenciesscripts/identify.sh <audio_file>POST audio to AudD, return JSONcurl, jqscripts/spotify-auth.py [--url]One-time Spotify OAuth flowpython3scripts/spotify-queue.sh queue <uri>Queue track to active Spotifycurl, jqscripts/spotify-queue.sh statusCheck current Spotify playbackcurl, 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.