Add sonicallySimilar method to Audio class

plexapi/audio.py

@@ -3,6 +3,8 @@
 from pathlib import Path
 from urllib.parse import quote_plus
 
+from typing import List, Optional, TypeVar
+
 from plexapi import media, utils
 from plexapi.base import Playable, PlexPartialObject, PlexHistory, PlexSession
 from plexapi.exceptions import BadRequest
@@ -14,6 +16,9 @@
 from plexapi.playlist import Playlist
 
 
+TAudio = TypeVar("TAudio", bound="Audio")
+
+
 class Audio(PlexPartialObject, PlayedUnplayedMixin):
     """ Base class for all audio objects including :class:`~plexapi.audio.Artist`,
         :class:`~plexapi.audio.Album`, and :class:`~plexapi.audio.Track`.
@@ -22,6 +27,7 @@ class Audio(PlexPartialObject, PlayedUnplayedMixin):
             addedAt (datetime): Datetime the item was added to the library.
             art (str): URL to artwork image (/library/metadata/<ratingKey>/art/<artid>).
             artBlurHash (str): BlurHash string for artwork image.
+            distance (float): Sonic Distance of the item from the seed item.
             fields (List<:class:`~plexapi.media.Field`>): List of field objects.
             guid (str): Plex GUID for the artist, album, or track (plex://artist/5d07bcb0403c64029053ac4c).
             index (int): Plex index number (often the track number).
@@ -65,6 +71,7 @@ def _loadData(self, data):
         self.listType = 'audio'
         self.moods = self.findItems(data, media.Mood)
         self.musicAnalysisVersion = utils.cast(int, data.attrib.get('musicAnalysisVersion'))
+        self.distance = utils.cast(float, data.attrib.get('distance'))
         self.ratingKey = utils.cast(int, data.attrib.get('ratingKey'))
         self.summary = data.attrib.get('summary')
         self.thumb = data.attrib.get('thumb')
@@ -125,6 +132,35 @@ def sync(self, bitrate, client=None, clientId=None, limit=None, title=None):
 
         return myplex.sync(sync_item, client=client, clientId=clientId)
 
+    def sonicallySimilar(
+        self: TAudio,
+        limit: Optional[int] = None,
+        maxDistance: Optional[float] = None,
+        **kwargs,
+    ) -> List[TAudio]:
+        """Returns a list of sonically similar audio items.
+
+        Parameters:
+            limit (int): Maximum count of items to return. Default 50 (server default)
+            maxDistance (float): Maximum distance between tracks, 0.0 - 1.0. Default 0.25 (server default).
+            **kwargs: Additional options passed into :func:`~plexapi.base.PlexObject.fetchItems`.
+
+        Returns:
+            List[:class:`~plexapi.audio.Audio`]: list of sonically similar audio items.
+        """
+
+        key = f"{self.key}/nearest"
+        params = {"maxDistance": maxDistance, "limit": limit}
+        key += utils.joinArgs(
+            {k: v for k, v in params.items() if v is not None}
+        )
+
+        return self.fetchItems(
+            key,
+            cls=self.__class__,
+            **kwargs,
+        )
+
 
 @utils.registerPlexObject
 class Artist(

tests/test_audio.py

@@ -439,6 +439,12 @@ def test_audio_Audio_section(artist, album, track):
     assert track.section().key == album.section().key == artist.section().key
 
 
+def test_audio_Audio_sonicallySimilar(artist):
+    similar_audio = artist.sonicallySimilar()
+    assert isinstance(similar_audio, list)
+    assert all(isinstance(i, type(artist)) for i in similar_audio)
+
+
 def test_audio_Artist_download(monkeydownload, tmpdir, artist):
     total = len(artist.tracks())
     filepaths = artist.download(savepath=str(tmpdir))