get_audio_features
Retrieve audio analysis data for Spotify tracks including tempo, key, energy, danceability, and other musical characteristics. Analyze up to 100 tracks in a single API call to understand their sonic properties.
Instructions
Get audio features for one or more tracks (tempo, key, energy, danceability, etc).
Args:
track_ids: Single track ID or list of track IDs (up to 100)
Returns:
Dict with 'features' list containing audio features for each track.
Features include: tempo, key, mode, time_signature, danceability, energy,
valence, loudness, speechiness, acousticness, instrumentalness, liveness.
Note: Batch lookup is efficient - 100 tracks = 1 API call.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| track_ids | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- The handler function for the 'get_audio_features' tool. Registered via @mcp.tool() decorator. Normalizes input track IDs, calls Spotify API's audio_features endpoint, parses results using AudioFeatures Pydantic model, and returns structured features data.
@mcp.tool() @log_tool_execution def get_audio_features(track_ids: str | list[str]) -> dict[str, Any]: """Get audio features for one or more tracks (tempo, key, energy, danceability, etc). Args: track_ids: Single track ID or list of track IDs (up to 100) Returns: Dict with 'features' list containing audio features for each track. Features include: tempo, key, mode, time_signature, danceability, energy, valence, loudness, speechiness, acousticness, instrumentalness, liveness. Note: Batch lookup is efficient - 100 tracks = 1 API call. """ try: # Normalize to list ids = [track_ids] if isinstance(track_ids, str) else track_ids if len(ids) > 100: raise ValueError("Maximum 100 track IDs per request (Spotify API limit)") logger.info(f"🎼 Getting audio features for {len(ids)} track(s)") result = spotify_client.audio_features(ids) features_list = [] for features in result: if features: audio = AudioFeatures( id=features["id"], tempo=features.get("tempo"), key=features.get("key"), mode=features.get("mode"), time_signature=features.get("time_signature"), danceability=features.get("danceability"), energy=features.get("energy"), valence=features.get("valence"), loudness=features.get("loudness"), speechiness=features.get("speechiness"), acousticness=features.get("acousticness"), instrumentalness=features.get("instrumentalness"), liveness=features.get("liveness"), ) features_list.append(audio.model_dump()) return {"features": features_list} except SpotifyException as e: raise convert_spotify_error(e) from e - Pydantic BaseModel defining the schema for audio features data returned by the tool. Used to structure and validate the output from Spotify's audio_features API.
class AudioFeatures(BaseModel): """Audio features for a track.""" id: str tempo: float | None = None key: int | None = None mode: int | None = None time_signature: int | None = None danceability: float | None = None energy: float | None = None valence: float | None = None loudness: float | None = None speechiness: float | None = None acousticness: float | None = None instrumentalness: float | None = None liveness: float | None = None - src/spotify_mcp/fastmcp_server.py:790-790 (registration)The @mcp.tool() decorator registers the get_audio_features function as an MCP tool, using the function name as the tool name.
@mcp.tool()