Audio plexapi.audio

class plexapi.audio.Audio(server, data, initpath=None, parent=None)

Bases: PlexPartialObject, PlayedUnplayedMixin

Base class for all audio objects including Artist, Album, and Track.

Variables:

• 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<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).

• key (str) – API URL (/library/metadata/<ratingkey>).

• lastRatedAt (datetime) – Datetime the item was last rated.

• lastViewedAt (datetime) – Datetime the item was last played.

• librarySectionID (int) – LibrarySection ID.

• librarySectionKey (str) – LibrarySection key.

• librarySectionTitle (str) – LibrarySection title.

• listType (str) – Hardcoded as ‘audio’ (useful for search filters).

• moods (List<Mood>) – List of mood objects.

• musicAnalysisVersion (int) – The Plex music analysis version for the item.

• ratingKey (int) – Unique key identifying the item.

• summary (str) – Summary of the artist, album, or track.

• thumb (str) – URL to thumbnail image (/library/metadata/<ratingKey>/thumb/<thumbid>).

• thumbBlurHash (str) – BlurHash string for thumbnail image.

• title (str) – Name of the artist, album, or track (Jason Mraz, We Sing, Lucky, etc.).

• titleSort (str) – Title to use when sorting (defaults to title).

• type (str) – ‘artist’, ‘album’, or ‘track’.

• updatedAt (datetime) – Datetime the item was updated.

• userRating (float) – Rating of the item (0.0 - 10.0) equaling (0 stars - 5 stars).

• viewCount (int) – Count of times the item was played.

url(part)

Returns the full URL for the audio item. Typically used for getting a specific track.

property hasSonicAnalysis

Returns True if the audio has been sonically analyzed.

sync(bitrate, client=None, clientId=None, limit=None, title=None)

Add current audio (artist, album or track) as sync item for specified device. See sync() for possible exceptions.

Parameters:

• bitrate (int) – maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the module sync.

• client (MyPlexDevice) – sync destination, see sync().

• clientId (str) – sync destination, see sync().

• limit (int) – maximum count of items to sync, unlimited if None.

• title (str) – descriptive title for the new SyncItem, if empty the value would be generated from metadata of current media.

Returns:

an instance of created syncItem.

Return type:

SyncItem

sonicallySimilar(limit: int | None = None, maxDistance: float | None = 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 fetchItems().

Returns:

list of sonically similar audio items.

Return type:

List[Audio]

class plexapi.audio.Artist(server, data, initpath=None, parent=None)

Bases: Audio, AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin, ArtMixin, PosterMixin, ThemeMixin, ArtistEditMixins

Represents a single Artist.

Variables:

• TAG (str) – ‘Directory’

• TYPE (str) – ‘artist’

• albumSort (int) – Setting that indicates how albums are sorted for the artist (-1 = Library default, 0 = Newest first, 1 = Oldest first, 2 = By name).

• collections (List<Collection>) – List of collection objects.

• countries (List<Country>) – List country objects.

• genres (List<Genre>) – List of genre objects.

• guids (List<Guid>) – List of guid objects.

• key (str) – API URL (/library/metadata/<ratingkey>).

• labels (List<Label>) – List of label objects.

• locations (List<str>) – List of folder paths where the artist is found on disk.

• similar (List<Similar>) – List of similar objects.

• styles (List<Style>) – List of style objects.

• theme (str) – URL to theme resource (/library/metadata/<ratingkey>/theme/<themeid>).

album(title)

Returns the Album that matches the specified title.

Parameters:

title (str) – Title of the album to return.

albums(**kwargs)

Returns a list of Album objects by the artist.

track(title=None, album=None, track=None)

Returns the Track that matches the specified title.

Parameters:

• title (str) – Title of the track to return.

• album (str) – Album name (default: None; required if title not specified).

• track (int) – Track number (default: None; required if title not specified).

Raises:

BadRequest – If title or album and track parameters are missing.

tracks(**kwargs)

Returns a list of Track objects by the artist.

get(title=None, album=None, track=None)

Alias of track().

download(savepath=None, keep_original_name=False, subfolders=False, **kwargs)

Download all tracks from the artist. See download() for details.

Parameters:

• savepath (str) – Defaults to current working dir.

• keep_original_name (bool) – True to keep the original filename otherwise a friendlier filename is generated.

• subfolders (bool) – True to separate tracks in to album folders.

• **kwargs – Additional options passed into getStreamURL().

station()

Returns a Playlist artist radio station or None.

property metadataDirectory

Returns the Plex Media Server data directory where the metadata is stored.

class plexapi.audio.Album(server, data, initpath=None, parent=None)

Bases: Audio, UnmatchMatchMixin, RatingMixin, ArtMixin, PosterMixin, ThemeUrlMixin, AlbumEditMixins

Represents a single Album.

Variables:

• TAG (str) – ‘Directory’

• TYPE (str) – ‘album’

• collections (List<Collection>) – List of collection objects.

• formats (List<Format>) – List of format objects.

• genres (List<Genre>) – List of genre objects.

• guids (List<Guid>) – List of guid objects.

• key (str) – API URL (/library/metadata/<ratingkey>).

• labels (List<Label>) – List of label objects.

• leafCount (int) – Number of items in the album view.

• loudnessAnalysisVersion (int) – The Plex loudness analysis version level.

• originallyAvailableAt (datetime) – Datetime the album was released.

• parentGuid (str) – Plex GUID for the album artist (plex://artist/5d07bcb0403c64029053ac4c).

• parentKey (str) – API URL of the album artist (/library/metadata/<parentRatingKey>).

• parentRatingKey (int) – Unique key identifying the album artist.

• parentTheme (str) – URL to artist theme resource (/library/metadata/<parentRatingkey>/theme/<themeid>).

• parentThumb (str) – URL to album artist thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).

• parentTitle (str) – Name of the album artist.

• rating (float) – Album rating (7.9; 9.8; 8.1).

• studio (str) – Studio that released the album.

• styles (List<Style>) – List of style objects.

• subformats (List<Subformat>) – List of subformat objects.

• viewedLeafCount (int) – Number of items marked as played in the album view.

• year (int) – Year the album was released.

track(title=None, track=None)

Returns the Track that matches the specified title.

Parameters:

• title (str) – Title of the track to return.

• track (int) – Track number (default: None; required if title not specified).

Raises:

BadRequest – If title or track parameter is missing.

tracks(**kwargs)

Returns a list of Track objects in the album.

get(title=None, track=None)

Alias of track().

artist()

Return the album’s Artist.

download(savepath=None, keep_original_name=False, **kwargs)

Download all tracks from the album. See download() for details.

Parameters:

• savepath (str) – Defaults to current working dir.

• keep_original_name (bool) – True to keep the original filename otherwise a friendlier filename is generated.

• **kwargs – Additional options passed into getStreamURL().

property metadataDirectory

Returns the Plex Media Server data directory where the metadata is stored.

class plexapi.audio.Track(server, data, initpath=None, parent=None)

Bases: Audio, Playable, ExtrasMixin, RatingMixin, ArtUrlMixin, PosterUrlMixin, ThemeUrlMixin, TrackEditMixins

Represents a single Track.

Variables:

• TAG (str) – ‘Directory’

• TYPE (str) – ‘track’

• chapters (List<Chapter>) – List of Chapter objects.

• chapterSource (str) – Unknown

• collections (List<Collection>) – List of collection objects.

• duration (int) – Length of the track in milliseconds.

• grandparentArt (str) – URL to album artist artwork (/library/metadata/<grandparentRatingKey>/art/<artid>).

• grandparentGuid (str) – Plex GUID for the album artist (plex://artist/5d07bcb0403c64029053ac4c).

• grandparentKey (str) – API URL of the album artist (/library/metadata/<grandparentRatingKey>).

• grandparentRatingKey (int) – Unique key identifying the album artist.

• grandparentTheme (str) – URL to artist theme resource (/library/metadata/<grandparentRatingkey>/theme/<themeid>). (/library/metadata/<grandparentRatingkey>/theme/<themeid>).

• grandparentThumb (str) – URL to album artist thumbnail image (/library/metadata/<grandparentRatingKey>/thumb/<thumbid>).

• grandparentTitle (str) – Name of the album artist for the track.

• guids (List<Guid>) – List of guid objects.

• labels (List<Label>) – List of label objects.

• media (List<Media>) – List of media objects.

• originalTitle (str) – The artist for the track.

• parentGuid (str) – Plex GUID for the album (plex://album/5d07cd8e403c640290f180f9).

• parentIndex (int) – Disc number of the track.

• parentKey (str) – API URL of the album (/library/metadata/<parentRatingKey>).

• parentRatingKey (int) – Unique key identifying the album.

• parentThumb (str) – URL to album thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).

• parentTitle (str) – Name of the album for the track.

• primaryExtraKey (str) –

• ratingCount (int) – Number of listeners who have scrobbled this track, as reported by Last.fm.

• skipCount (int) – Number of times the track has been skipped.

• viewOffset (int) – View offset in milliseconds.

• year (int) – Year the track was released.

property locations

This does not exist in plex xml response but is added to have a common interface to get the locations of the track.

Returns:

List<str> of file paths where the track is found on disk.

property trackNumber

Returns the track number.

album()

Return the track’s Album.

artist()

Return the track’s Artist.

property metadataDirectory

Returns the Plex Media Server data directory where the metadata is stored.

class plexapi.audio.TrackSession(server, data, initpath=None, parent=None)

Bases: PlexSession, Track

Represents a single Track session loaded from sessions().

class plexapi.audio.TrackHistory(server, data, initpath=None, parent=None)

Bases: PlexHistory, Track

Represents a single Track history entry loaded from history().