Audio plexapi.audio

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

Bases: plexapi.base.PlexPartialObject, plexapi.mixins.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)[source]

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

hasSonicAnalysis

Returns True if the audio has been sonically analyzed.

sync(bitrate, client=None, clientId=None, limit=None, title=None)[source]

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=None, maxDistance=None, **kwargs)[source]

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)[source]

Bases: plexapi.audio.Audio, plexapi.mixins.AdvancedSettingsMixin, plexapi.mixins.SplitMergeMixin, plexapi.mixins.UnmatchMatchMixin, plexapi.mixins.ExtrasMixin, plexapi.mixins.HubsMixin, plexapi.mixins.RatingMixin, plexapi.mixins.ArtMixin, plexapi.mixins.PosterMixin, plexapi.mixins.ThemeMixin, plexapi.mixins.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)[source]

Returns the Album that matches the specified title.

Parameters:title (str) – Title of the album to return.
albums(**kwargs)[source]

Returns a list of Album objects by the artist.

track(title=None, album=None, track=None)[source]

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)[source]

Returns a list of Track objects by the artist.

get(title=None, album=None, track=None)[source]

Alias of track().

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

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()[source]

Returns a Playlist artist radio station or None.

metadataDirectory

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

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

Bases: plexapi.audio.Audio, plexapi.mixins.SplitMergeMixin, plexapi.mixins.UnmatchMatchMixin, plexapi.mixins.RatingMixin, plexapi.mixins.ArtMixin, plexapi.mixins.PosterMixin, plexapi.mixins.ThemeUrlMixin, plexapi.mixins.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)[source]

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)[source]

Returns a list of Track objects in the album.

get(title=None, track=None)[source]

Alias of track().

artist()[source]

Return the album’s Artist.

download(savepath=None, keep_original_name=False, **kwargs)[source]

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().
metadataDirectory

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

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

Bases: plexapi.audio.Audio, plexapi.base.Playable, plexapi.mixins.ExtrasMixin, plexapi.mixins.RatingMixin, plexapi.mixins.ArtUrlMixin, plexapi.mixins.PosterUrlMixin, plexapi.mixins.ThemeUrlMixin, plexapi.mixins.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.
  • genres (List<Genre>) – List of genre objects.
  • 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.
  • sourceURI (str) – Remote server URI (server://<machineIdentifier>/com.plexapp.plugins.library) (remote playlist item only).
  • viewOffset (int) – View offset in milliseconds.
  • year (int) – Year the track was released.
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.
trackNumber

Returns the track number.

album()[source]

Return the track’s Album.

artist()[source]

Return the track’s Artist.

metadataDirectory

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

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

Bases: plexapi.base.PlexSession, plexapi.audio.Track

Represents a single Track session loaded from sessions().

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

Bases: plexapi.base.PlexHistory, plexapi.audio.Track

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