Add support for retrieving audio features (#354)

Author: joostlek

src/spotifyaio/models.py

@@ -4,7 +4,7 @@
 
 from dataclasses import dataclass, field
 from datetime import datetime  # noqa: TCH003
-from enum import StrEnum
+from enum import IntEnum, StrEnum
 from typing import Annotated, Any
 
 from mashumaro import field_options
@@ -533,3 +533,55 @@ class AlbumTracksResponse(DataClassORJSONMixin):
     """Album tracks response model."""
 
     items: list[SimplifiedTrack]
+
+
+class Key(IntEnum):
+    """Key of a track."""
+
+    C = 0
+    C_SHARP = 1
+    D = 2
+    D_SHARP = 3
+    E = 4
+    F = 5
+    F_SHARP = 6
+    G = 7
+    G_SHARP = 8
+    A = 9
+    A_SHARP = 10
+    B = 11
+
+
+class Mode(IntEnum):
+    """Mode of a track."""
+
+    MINOR = 0
+    MAJOR = 1
+
+
+class TimeSignature(IntEnum):
+    """Time signature of a track."""
+
+    THREE_FOUR = 3
+    FOUR_FOUR = 4
+    FIVE_FOUR = 5
+    SIX_FOUR = 6
+    SEVEN_FOUR = 7
+
+
+@dataclass
+class AudioFeatures(DataClassORJSONMixin):
+    """Audio features model."""
+
+    danceability: float
+    energy: float
+    key: Key | None
+    loudness: float
+    mode: Mode
+    speechiness: float
+    acousticness: float
+    instrumentalness: float
+    liveness: float
+    valence: float
+    tempo: float
+    time_signature: TimeSignature

src/spotifyaio/spotify.py

@@ -19,6 +19,7 @@
     AlbumTracksResponse,
     Artist,
     ArtistResponse,
+    AudioFeatures,
     BasePlaylist,
     BaseUserProfile,
     CategoriesResponse,
@@ -503,7 +504,11 @@ async def get_saved_tracks(self) -> list[SavedTrack]:
 
     # Get audio features for several tracks
 
-    # Get audio features for a track
+    async def get_audio_features(self, track_id: str) -> AudioFeatures:
+        """Get audio features."""
+        identifier = get_identifier(track_id)
+        response = await self._get(f"v1/audio-features/{identifier}")
+        return AudioFeatures.from_json(response)
 
     # Get audio analysis for a track
 

tests/__snapshots__/test_spotify.ambr

@@ -2487,6 +2487,22 @@
     }),
   ])
 # ---
+# name: test_get_audio_features
+  dict({
+    'acousticness': 0.011,
+    'danceability': 0.696,
+    'energy': 0.905,
+    'instrumentalness': 0.000905,
+    'key': <Key.D: 2>,
+    'liveness': 0.302,
+    'loudness': -2.743,
+    'mode': <Mode.MAJOR: 1>,
+    'speechiness': 0.103,
+    'tempo': 114.944,
+    'time_signature': <TimeSignature.FOUR_FOUR: 4>,
+    'valence': 0.625,
+  })
+# ---
 # name: test_get_categories
   list([
     dict({

tests/fixtures/audio_features.json

@@ -0,0 +1,20 @@
+{
+  "danceability": 0.696,
+  "energy": 0.905,
+  "key": 2,
+  "loudness": -2.743,
+  "mode": 1,
+  "speechiness": 0.103,
+  "acousticness": 0.011,
+  "instrumentalness": 0.000905,
+  "liveness": 0.302,
+  "valence": 0.625,
+  "tempo": 114.944,
+  "type": "audio_features",
+  "id": "11dFghVXANMlKmJXsNCbNl",
+  "uri": "spotify:track:11dFghVXANMlKmJXsNCbNl",
+  "track_href": "https://api.spotify.com/v1/tracks/11dFghVXANMlKmJXsNCbNl",
+  "analysis_url": "https://api.spotify.com/v1/audio-analysis/11dFghVXANMlKmJXsNCbNl",
+  "duration_ms": 207960,
+  "time_signature": 4
+}

tests/test_spotify.py

@@ -1297,3 +1297,25 @@ async def test_get_categories(
         params={"limit": 48},
         json=None,
     )
+
+
+async def test_get_audio_features(
+    responses: aioresponses,
+    snapshot: SnapshotAssertion,
+    authenticated_client: SpotifyClient,
+) -> None:
+    """Test retrieving audio features."""
+    responses.get(
+        f"{SPOTIFY_URL}/v1/audio-features/11dFghVXANMlKmJXsNCbNl",
+        status=200,
+        body=load_fixture("audio_features.json"),
+    )
+    response = await authenticated_client.get_audio_features("11dFghVXANMlKmJXsNCbNl")
+    assert response == snapshot
+    responses.assert_called_once_with(
+        f"{SPOTIFY_URL}/v1/audio-features/11dFghVXANMlKmJXsNCbNl",
+        METH_GET,
+        headers=HEADERS,
+        params=None,
+        json=None,
+    )