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

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

1. Run the auth flow: python3 scripts/spotify-auth.py
2. Open the printed URL in a browser, authorize, tokens save automatically
3. 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

1. Parse the JSON result and respond.
2. If Spotify is configured and active, queue the track.
3. 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

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.