Video plexapi.video

class plexapi.video.Video(server, data, initpath=None, parent=None)

Bases: PlexPartialObject, PlayedUnplayedMixin

Base class for all video objects including Movie, Show, Season, Episode, and Clip.

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.

• fields (List<Field>) – List of field objects.

• guid (str) – Plex GUID for the movie, show, season, episode, or clip (plex://movie/5d776b59ad5437001f79c6f8).

• 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 ‘video’ (useful for search filters).

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

• summary (str) – Summary of the movie, show, season, episode, or clip.

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

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

• title (str) – Name of the movie, show, season, episode, or clip.

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

• type (str) – ‘movie’, ‘show’, ‘season’, ‘episode’, or ‘clip’.

• 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 something. Typically used for getting a specific image.

augmentation()

Returns a list of Hub objects. Augmentation returns hub items relating to online media sources such as Tidal Music “Track from {item}” or “Soundtrack of {item}”. Plex Pass and linked Tidal account are required.

videoStreams()

Returns a list of videoStream objects for all MediaParts.

audioStreams()

Returns a list of AudioStream objects for all MediaParts.

subtitleStreams()

Returns a list of SubtitleStream objects for all MediaParts.

uploadSubtitles(filepath)

Upload Subtitle file for video.

removeSubtitles(streamID=None, streamTitle=None)

Remove Subtitle from movie’s subtitles listing.

Note: If subtitle file is located inside video directory it will bbe deleted. Files outside of video directory are not effected.

optimize(title='', target='', deviceProfile='', videoQuality=None, locationID=-1, limit=None, unwatched=False)

Create an optimized version of the video.

Parameters:

• title (str, optional) – Title of the optimized video.

• target (str, optional) – Target quality profile: “Optimized for Mobile” (“mobile”), “Optimized for TV” (“tv”), “Original Quality” (“original”), or custom quality profile name (default “Custom: {deviceProfile}”).

• deviceProfile (str, optional) – Custom quality device profile: “Android”, “iOS”, “Universal Mobile”, “Universal TV”, “Windows Phone”, “Windows”, “Xbox One”. Required if target is custom.

• videoQuality (int, optional) – Index of the quality profile, one of VIDEO_QUALITY_* values defined in the sync module. Only used if target is custom.

• locationID (int or Location, optional) – Default -1 for “In folder with original items”, otherwise a Location object or ID. See examples below.

• limit (int, optional) – Maximum count of items to optimize, unlimited if None.

• unwatched (bool, optional) – True to only optimized unwatched videos.

Raises:

• BadRequest – Unknown quality profile target or missing deviceProfile and videoQuality.

• BadRequest – Unknown location ID.

Example

# Optimize for mobile using defaults
video.optimize(target="mobile")

# Optimize for Android at 10 Mbps 1080p
from plexapi.sync import VIDEO_QUALITY_10_MBPS_1080p
video.optimize(deviceProfile="Android", videoQuality=sync.VIDEO_QUALITY_10_MBPS_1080p)

# Optimize for iOS at original quality in library location
from plexapi.sync import VIDEO_QUALITY_ORIGINAL
locations = plex.library.section("Movies")._locations()
video.optimize(deviceProfile="iOS", videoQuality=VIDEO_QUALITY_ORIGINAL, locationID=locations[0])

# Optimize for tv the next 5 unwatched episodes
show.optimize(target="tv", limit=5, unwatched=True)

sync(videoQuality, client=None, clientId=None, limit=None, unwatched=False, title=None)

Add current video (movie, tv-show, season or episode) as sync item for specified device. See sync() for possible exceptions.

Parameters:

• videoQuality (int) – idx of quality of the video, one of VIDEO_QUALITY_* values defined in sync module.

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

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

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

• unwatched (bool) – if True watched videos wouldn’t be synced.

• 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

class plexapi.video.Movie(server, data, initpath=None, parent=None)

Bases: Video, Playable, AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin, ArtMixin, PosterMixin, ThemeMixin, MovieEditMixins, WatchlistMixin

Represents a single Movie.

Variables:

• TAG (str) – ‘Video’

• TYPE (str) – ‘movie’

• audienceRating (float) – Audience rating (usually from Rotten Tomatoes).

• audienceRatingImage (str) – Key to audience rating image (rottentomatoes://image.rating.spilled).

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

• chapterSource (str) – Chapter source (agent; media; mixed).

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

• contentRating (str) Content rating (PG-13; NR; TV-G) –

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

• directors (List<Director>) – List of director objects.

• duration (int) – Duration of the movie in milliseconds.

• editionTitle (str) – The edition title of the movie (e.g. Director’s Cut, Extended Edition, etc.).

• enableCreditsMarkerGeneration (int) – Setting that indicates if credits markers detection is enabled. (-1 = Library default, 0 = Disabled)

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

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

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

• languageOverride (str) – Setting that indicates if a language is used to override metadata (eg. en-CA, None = Library default).

• markers (List<Marker>) – List of marker objects.

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

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

• originalTitle (str) – Original title, often the foreign title (転々; 엽기적인 그녀).

• primaryExtraKey (str) Primary extra key (/library/metadata/66351) –

• producers (List<Producer>) – List of producers objects.

• rating (float) – Movie critic rating (7.9; 9.8; 8.1).

• ratingImage (str) – Key to critic rating image (rottentomatoes://image.rating.rotten).

• ratings (List<Rating>) – List of rating objects.

• roles (List<Role>) – List of role objects.

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

• studio (str) – Studio that created movie (Di Bonaventura Pictures; 21 Laps Entertainment).

• tagline (str) – Movie tag line (Back 2 Work; Who says men can’t change?).

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

• useOriginalTitle (int) – Setting that indicates if the original title is used for the movie (-1 = Library default, 0 = No, 1 = Yes).

• viewOffset (int) – View offset in milliseconds.

• writers (List<Writer>) – List of writers objects.

• year (int) – Year movie was released.

property actors

Alias to self.roles.

property locations

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

Returns:

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

property hasCreditsMarker

Returns True if the movie has a credits marker.

property hasPreviewThumbnails

Returns True if any of the media parts has generated preview (BIF) thumbnails.

reviews()

Returns a list of Review objects.

editions()

Returns a list of Movie objects for other editions of the same movie.

removeFromContinueWatching()

Remove the movie from continue watching.

property metadataDirectory

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

class plexapi.video.Show(server, data, initpath=None, parent=None)

Bases: Video, AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin, ArtMixin, PosterMixin, ThemeMixin, ShowEditMixins, WatchlistMixin

Represents a single Show (including all seasons and episodes).

Variables:

• TAG (str) – ‘Directory’

• TYPE (str) – ‘show’

• audienceRating (float) – Audience rating (TMDB or TVDB).

• audienceRatingImage (str) – Key to audience rating image (tmdb://image.rating).

• audioLanguage (str) – Setting that indicates the preferred audio language.

• autoDeletionItemPolicyUnwatchedLibrary (int) – Setting that indicates the number of unplayed episodes to keep for the show (0 = All episodes, 5 = 5 latest episodes, 3 = 3 latest episodes, 1 = 1 latest episode, -3 = Episodes added in the past 3 days, -7 = Episodes added in the past 7 days, -30 = Episodes added in the past 30 days).

• autoDeletionItemPolicyWatchedLibrary (int) – Setting that indicates if episodes are deleted after being watched for the show (0 = Never, 1 = After a day, 7 = After a week, 100 = On next refresh).

• childCount (int) – Number of seasons (including Specials) in the show.

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

• contentRating (str) Content rating (PG-13; NR; TV-G) –

• duration (int) – Typical duration of the show episodes in milliseconds.

• enableCreditsMarkerGeneration (int) – Setting that indicates if credits markers detection is enabled. (-1 = Library default, 0 = Disabled).

• episodeSort (int) – Setting that indicates how episodes are sorted for the show (-1 = Library default, 0 = Oldest first, 1 = Newest first).

• flattenSeasons (int) – Setting that indicates if seasons are set to hidden for the show (-1 = Library default, 0 = Hide, 1 = Show).

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

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

• index (int) – Plex index number for the show.

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

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

• languageOverride (str) – Setting that indicates if a language is used to override metadata (eg. en-CA, None = Library default).

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

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

• network (str) – The network that distributed the show.

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

• originalTitle (str) – The original title of the show.

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

• ratings (List<Rating>) – List of rating objects.

• roles (List<Role>) – List of role objects.

• seasonCount (int) – Number of seasons (excluding Specials) in the show.

• showOrdering (str) – Setting that indicates the episode ordering for the show (None = Library default, tmdbAiring = The Movie Database (Aired), aired = TheTVDB (Aired), dvd = TheTVDB (DVD), absolute = TheTVDB (Absolute)).

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

• studio (str) – Studio that created show (Di Bonaventura Pictures; 21 Laps Entertainment).

• subtitleLanguage (str) – Setting that indicates the preferred subtitle language.

• subtitleMode (int) – Setting that indicates the auto-select subtitle mode. (-1 = Account default, 0 = Manually selected, 1 = Shown with foreign audio, 2 = Always enabled).

• tagline (str) – Show tag line.

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

• useOriginalTitle (int) – Setting that indicates if the original title is used for the show (-1 = Library default, 0 = No, 1 = Yes).

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

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

property actors

Alias to self.roles.

property isPlayed

Returns True if the show is fully played.

onDeck()

Returns show’s On Deck Video object or None. If show is unwatched, return will likely be the first episode.

season(title=None, season=None)

Returns the season with the specified title or number.

Parameters:

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

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

Raises:

BadRequest – If title or season parameter is missing.

seasons(**kwargs)

Returns a list of Season objects in the show.

episode(title=None, season=None, episode=None)

Find a episode using a title or season and episode.

Parameters:

• title (str) – Title of the episode to return

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

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

Raises:

BadRequest – If title or season and episode parameters are missing.

episodes(**kwargs)

Returns a list of Episode objects in the show.

get(title=None, season=None, episode=None)

Alias to episode().

watched()

Returns list of watched Episode objects.

unwatched()

Returns list of unwatched Episode objects.

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

Download all episodes from the show. 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 episodes in to season folders.

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

property metadataDirectory

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

class plexapi.video.Season(server, data, initpath=None, parent=None)

Bases: Video, AdvancedSettingsMixin, ExtrasMixin, RatingMixin, ArtMixin, PosterMixin, ThemeUrlMixin, SeasonEditMixins

Represents a single Show Season (including all episodes).

Variables:

• TAG (str) – ‘Directory’

• TYPE (str) – ‘season’

• audioLanguage (str) – Setting that indicates the preferred audio language.

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

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

• index (int) – Season number.

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

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

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

• parentGuid (str) – Plex GUID for the show (plex://show/5d9c086fe9d5a1001f4d9fe6).

• parentIndex (int) – Plex index number for the show.

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

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

• parentStudio (str) – Studio that created show.

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

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

• parentTitle (str) – Name of the show for the season.

• ratings (List<Rating>) – List of rating objects.

• subtitleLanguage (str) – Setting that indicates the preferred subtitle language.

• subtitleMode (int) – Setting that indicates the auto-select subtitle mode. (-1 = Series default, 0 = Manually selected, 1 = Shown with foreign audio, 2 = Always enabled).

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

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

property isPlayed

Returns True if the season is fully played.

property seasonNumber

Returns the season number.

onDeck()

Returns season’s On Deck Video object or None. Will only return a match if the show’s On Deck episode is in this season.

episode(title=None, episode=None)

Returns the episode with the given title or number.

Parameters:

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

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

Raises:

BadRequest – If title or episode parameter is missing.

episodes(**kwargs)

Returns a list of Episode objects in the season.

get(title=None, episode=None)

Alias to episode().

show()

Return the season’s Show.

watched()

Returns list of watched Episode objects.

unwatched()

Returns list of unwatched Episode objects.

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

Download all episodes from the season. 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.video.Episode(server, data, initpath=None, parent=None)

Bases: Video, Playable, ExtrasMixin, RatingMixin, ArtMixin, PosterMixin, ThemeUrlMixin, EpisodeEditMixins

Represents a single Shows Episode.

Variables:

• TAG (str) – ‘Video’

• TYPE (str) – ‘episode’

• audienceRating (float) – Audience rating (TMDB or TVDB).

• audienceRatingImage (str) – Key to audience rating image (tmdb://image.rating).

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

• chapterSource (str) – Chapter source (agent; media; mixed).

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

• contentRating (str) Content rating (PG-13; NR; TV-G) –

• directors (List<Director>) – List of director objects.

• duration (int) – Duration of the episode in milliseconds.

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

• grandparentGuid (str) – Plex GUID for the show (plex://show/5d9c086fe9d5a1001f4d9fe6).

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

• grandparentRatingKey (int) – Unique key identifying the show.

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

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

• grandparentTitle (str) – Name of the show for the episode.

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

• index (int) – Episode number.

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

• markers (List<Marker>) – List of marker objects.

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

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

• parentGuid (str) – Plex GUID for the season (plex://season/5d9c09e42df347001e3c2a72).

• parentIndex (int) – Season number of episode.

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

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

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

• parentTitle (str) – Name of the season for the episode.

• parentYear (int) – Year the season was released.

• producers (List<Producer>) – List of producers objects.

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

• ratings (List<Rating>) – List of rating objects.

• roles (List<Role>) – List of role objects.

• skipParent (bool) – True if the show’s seasons are set to hidden.

• viewOffset (int) – View offset in milliseconds.

• writers (List<Writer>) – List of writers objects.

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

property actors

Alias to self.roles.

property locations

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

Returns:

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

property episodeNumber

Returns the episode number.

property seasonNumber

Returns the episode’s season number.

property seasonEpisode

Returns the s00e00 string containing the season and episode numbers.

property hasCommercialMarker

Returns True if the episode has a commercial marker.

property hasIntroMarker

Returns True if the episode has an intro marker.

property hasCreditsMarker

Returns True if the episode has a credits marker.

property hasPreviewThumbnails

Returns True if any of the media parts has generated preview (BIF) thumbnails.

season()

” Return the episode’s Season.

show()

” Return the episode’s Show.

removeFromContinueWatching()

Remove the movie from continue watching.

property metadataDirectory

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

class plexapi.video.Clip(server, data, initpath=None, parent=None)

Bases: Video, Playable, ArtUrlMixin, PosterUrlMixin

Represents a single Clip.

Variables:

• TAG (str) – ‘Video’

• TYPE (str) – ‘clip’

• duration (int) – Duration of the clip in milliseconds.

• extraType (int) – Unknown.

• index (int) – Plex index number for the clip.

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

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

• skipDetails (int) – Unknown.

• subtype (str) – Type of clip (trailer, behindTheScenes, sceneOrSample, etc.).

• thumbAspectRatio (str) – Aspect ratio of the thumbnail image.

• viewOffset (int) – View offset in milliseconds.

• year (int) – Year clip 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 clip.

Returns:

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

property metadataDirectory

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

class plexapi.video.Extra(server, data, initpath=None, parent=None)

Bases: Clip

Represents a single Extra (trailer, behindTheScenes, etc).

class plexapi.video.MovieSession(server, data, initpath=None, parent=None)

Bases: PlexSession, Movie

Represents a single Movie session loaded from sessions().

class plexapi.video.EpisodeSession(server, data, initpath=None, parent=None)

Bases: PlexSession, Episode

Represents a single Episode session loaded from sessions().

class plexapi.video.ClipSession(server, data, initpath=None, parent=None)

Bases: PlexSession, Clip

Represents a single Clip session loaded from sessions().

class plexapi.video.MovieHistory(server, data, initpath=None, parent=None)

Bases: PlexHistory, Movie

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

class plexapi.video.EpisodeHistory(server, data, initpath=None, parent=None)

Bases: PlexHistory, Episode

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

class plexapi.video.ClipHistory(server, data, initpath=None, parent=None)

Bases: PlexHistory, Clip

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