python-plexapi/plexapi/video.py

944 lines
46 KiB
Python
Raw Normal View History

# -*- coding: utf-8 -*-
2020-05-28 01:53:04 +00:00
import os
from urllib.parse import quote_plus, urlencode
from plexapi import library, media, settings, utils
from plexapi.base import Playable, PlexPartialObject
2020-05-28 01:53:04 +00:00
from plexapi.exceptions import BadRequest, NotFound
2021-02-15 06:41:17 +00:00
from plexapi.mixins import ArtUrlMixin, ArtMixin, BannerMixin, PosterUrlMixin, PosterMixin
from plexapi.mixins import SplitMergeMixin, UnmatchMatchMixin
2021-02-07 18:54:03 +00:00
from plexapi.mixins import CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin
2014-12-29 03:21:58 +00:00
class Video(PlexPartialObject):
""" Base class for all video objects including :class:`~plexapi.video.Movie`,
:class:`~plexapi.video.Show`, :class:`~plexapi.video.Season`,
2020-12-24 06:24:46 +00:00
:class:`~plexapi.video.Episode`, and :class:`~plexapi.video.Clip`.
Attributes:
2020-12-23 23:53:42 +00:00
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.
2020-12-23 23:53:42 +00:00
fields (List<:class:`~plexapi.media.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>).
2020-12-23 23:53:42 +00:00
lastViewedAt (datetime): Datetime the item was last played.
librarySectionID (int): :class:`~plexapi.library.LibrarySection` ID.
2020-12-23 23:53:42 +00:00
librarySectionKey (str): :class:`~plexapi.library.LibrarySection` key.
librarySectionTitle (str): :class:`~plexapi.library.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.
2020-12-23 23:53:42 +00:00
title (str): Name of the movie, show, season, episode, or clip.
titleSort (str): Title to use when sorting (defaults to title).
2020-12-23 23:53:42 +00:00
type (str): 'movie', 'show', 'season', 'episode', or 'clip'.
updatedAt (datatime): Datetime the item was updated.
viewCount (int): Count of times the item was played.
"""
2014-12-29 03:21:58 +00:00
def _loadData(self, data):
2017-02-13 19:38:40 +00:00
""" Load attribute values from Plex XML response. """
self._data = data
2017-02-04 17:43:50 +00:00
self.addedAt = utils.toDatetime(data.attrib.get('addedAt'))
self.art = data.attrib.get('art')
self.artBlurHash = data.attrib.get('artBlurHash')
2020-12-24 04:39:15 +00:00
self.fields = self.findItems(data, media.Field)
2020-12-23 23:53:42 +00:00
self.guid = data.attrib.get('guid')
self.key = data.attrib.get('key', '')
2017-02-04 17:43:50 +00:00
self.lastViewedAt = utils.toDatetime(data.attrib.get('lastViewedAt'))
self.librarySectionID = data.attrib.get('librarySectionID')
2020-12-23 23:53:42 +00:00
self.librarySectionKey = data.attrib.get('librarySectionKey')
self.librarySectionTitle = data.attrib.get('librarySectionTitle')
self.listType = 'video'
2017-02-04 17:43:50 +00:00
self.ratingKey = utils.cast(int, data.attrib.get('ratingKey'))
self.summary = data.attrib.get('summary')
self.thumb = data.attrib.get('thumb')
self.thumbBlurHash = data.attrib.get('thumbBlurHash')
2017-02-04 17:43:50 +00:00
self.title = data.attrib.get('title')
self.titleSort = data.attrib.get('titleSort', self.title)
2017-02-04 17:43:50 +00:00
self.type = data.attrib.get('type')
self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt'))
self.viewCount = utils.cast(int, data.attrib.get('viewCount', 0))
2014-12-29 03:21:58 +00:00
2017-02-13 19:38:40 +00:00
@property
def isWatched(self):
""" Returns True if this video is watched. """
2017-09-29 16:10:55 +00:00
return bool(self.viewCount > 0) if self.viewCount else False
2017-09-29 16:11:14 +00:00
def url(self, part):
""" Returns the full url for something. Typically used for getting a specific image. """
return self._server.url(part, includeToken=True) if part else None
2014-12-29 03:21:58 +00:00
def markWatched(self):
""" Mark video as watched. """
key = '/:/scrobble?key=%s&identifier=com.plexapp.plugins.library' % self.ratingKey
self._server.query(key)
2014-12-29 03:21:58 +00:00
self.reload()
def markUnwatched(self):
""" Mark video unwatched. """
key = '/:/unscrobble?key=%s&identifier=com.plexapp.plugins.library' % self.ratingKey
self._server.query(key)
2014-12-29 03:21:58 +00:00
self.reload()
2019-08-06 19:53:31 +00:00
def rate(self, rate):
""" Rate video. """
key = '/:/rate?key=%s&identifier=com.plexapp.plugins.library&rating=%s' % (self.ratingKey, rate)
self._server.query(key)
self.reload()
2018-09-08 15:25:16 +00:00
def _defaultSyncTitle(self):
""" Returns str, default title for a new syncItem. """
return self.title
def subtitleStreams(self):
""" Returns a list of :class:`~plexapi.media.SubtitleStream` objects for all MediaParts. """
streams = []
parts = self.iterParts()
for part in parts:
streams += part.subtitleStreams()
return streams
def uploadSubtitles(self, filepath):
""" Upload Subtitle file for video. """
url = '%s/subtitles' % self.key
filename = os.path.basename(filepath)
subFormat = os.path.splitext(filepath)[1][1:]
with open(filepath, 'rb') as subfile:
params = {'title': filename,
'format': subFormat
}
headers = {'Accept': 'text/plain, */*'}
self._server.query(url, self._server._session.post, data=subfile, params=params, headers=headers)
def removeSubtitles(self, 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.
"""
for stream in self.subtitleStreams():
if streamID == stream.id or streamTitle == stream.title:
self._server.query(stream.key, self._server._session.delete)
2020-01-30 15:55:29 +00:00
def optimize(self, title=None, target="", targetTagID=None, locationID=-1, policyScope='all',
policyValue="", policyUnwatched=0, videoQuality=None, deviceProfile=None):
""" Optimize item
locationID (int): -1 in folder with original items
2 library path id
library path id is found in library.locations[i].id
2020-01-30 15:55:29 +00:00
target (str): custom quality name.
if none provided use "Custom: {deviceProfile}"
targetTagID (int): Default quality settings
1 Mobile
2 TV
3 Original Quality
deviceProfile (str): Android, IOS, Universal TV, Universal Mobile, Windows Phone,
Windows, Xbox One
Example:
Optimize for Mobile
item.optimize(targetTagID="Mobile") or item.optimize(targetTagID=1")
Optimize for Android 10 MBPS 1080p
item.optimize(deviceProfile="Android", videoQuality=10)
Optimize for IOS Original Quality
item.optimize(deviceProfile="IOS", videoQuality=-1)
* see sync.py VIDEO_QUALITIES for additional information for using videoQuality
"""
2020-01-30 16:25:45 +00:00
tagValues = [1, 2, 3]
2020-01-30 15:55:29 +00:00
tagKeys = ["Mobile", "TV", "Original Quality"]
tagIDs = tagKeys + tagValues
if targetTagID not in tagIDs and (deviceProfile is None or videoQuality is None):
2020-01-30 15:55:29 +00:00
raise BadRequest('Unexpected or missing quality profile.')
libraryLocationIDs = [location.id for location in self.section()._locations()]
libraryLocationIDs.append(-1)
if locationID not in libraryLocationIDs:
raise BadRequest('Unexpected library path ID. %s not in %s' %
(locationID, libraryLocationIDs))
2020-01-30 15:55:29 +00:00
if isinstance(targetTagID, str):
tagIndex = tagKeys.index(targetTagID)
targetTagID = tagValues[tagIndex]
if title is None:
title = self.title
2020-01-30 15:55:29 +00:00
2020-02-17 22:17:36 +00:00
backgroundProcessing = self.fetchItem('/playlists?type=42')
key = '%s/items?' % backgroundProcessing.key
params = {
'Item[type]': 42,
'Item[target]': target,
'Item[targetTagID]': targetTagID if targetTagID else '',
'Item[locationID]': locationID,
'Item[Policy][scope]': policyScope,
'Item[Policy][value]': policyValue,
'Item[Policy][unwatched]': policyUnwatched
}
2020-01-30 15:55:29 +00:00
if deviceProfile:
params['Item[Device][profile]'] = deviceProfile
2020-01-30 15:55:29 +00:00
if videoQuality:
from plexapi.sync import MediaSettings
2020-01-30 15:55:29 +00:00
mediaSettings = MediaSettings.createVideo(videoQuality)
params['Item[MediaSettings][videoQuality]'] = mediaSettings.videoQuality
params['Item[MediaSettings][videoResolution]'] = mediaSettings.videoResolution
params['Item[MediaSettings][maxVideoBitrate]'] = mediaSettings.maxVideoBitrate
params['Item[MediaSettings][audioBoost]'] = ''
params['Item[MediaSettings][subtitleSize]'] = ''
params['Item[MediaSettings][musicBitrate]'] = ''
params['Item[MediaSettings][photoQuality]'] = ''
titleParam = {'Item[title]': title}
section = self._server.library.sectionByID(self.librarySectionID)
params['Item[Location][uri]'] = 'library://' + section.uuid + '/item/' + \
quote_plus(self.key + '?includeExternalMedia=1')
2020-01-30 15:55:29 +00:00
data = key + urlencode(params) + '&' + urlencode(titleParam)
2020-01-30 16:28:33 +00:00
return self._server.query(data, method=self._server._session.put)
2020-01-30 15:55:29 +00:00
2018-09-08 15:25:16 +00:00
def sync(self, 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.
2020-11-23 03:06:30 +00:00
See :func:`~plexapi.myplex.MyPlexAccount.sync` for possible exceptions.
2018-09-08 15:25:16 +00:00
Parameters:
videoQuality (int): idx of quality of the video, one of VIDEO_QUALITY_* values defined in
2020-11-23 03:06:30 +00:00
:mod:`~plexapi.sync` module.
client (:class:`~plexapi.myplex.MyPlexDevice`): sync destination, see
:func:`~plexapi.myplex.MyPlexAccount.sync`.
clientId (str): sync destination, see :func:`~plexapi.myplex.MyPlexAccount.sync`.
2018-09-08 15:25:16 +00:00
limit (int): maximum count of items to sync, unlimited if `None`.
unwatched (bool): if `True` watched videos wouldn't be synced.
2020-11-23 03:06:30 +00:00
title (str): descriptive title for the new :class:`~plexapi.sync.SyncItem`, if empty the value would be
2018-09-08 15:25:16 +00:00
generated from metadata of current media.
Returns:
2020-11-23 03:06:30 +00:00
:class:`~plexapi.sync.SyncItem`: an instance of created syncItem.
2018-09-08 15:25:16 +00:00
"""
from plexapi.sync import SyncItem, Policy, MediaSettings
myplex = self._server.myPlexAccount()
sync_item = SyncItem(self._server, None)
sync_item.title = title if title else self._defaultSyncTitle()
sync_item.rootTitle = self.title
sync_item.contentType = self.listType
sync_item.metadataType = self.METADATA_TYPE
sync_item.machineIdentifier = self._server.machineIdentifier
section = self._server.library.sectionByID(self.librarySectionID)
sync_item.location = 'library://%s/item/%s' % (section.uuid, quote_plus(self.key))
sync_item.policy = Policy.create(limit, unwatched)
sync_item.mediaSettings = MediaSettings.createVideo(videoQuality)
return myplex.sync(sync_item, client=client, clientId=clientId)
@utils.registerPlexObject
class Movie(Video, Playable, ArtMixin, PosterMixin, SplitMergeMixin, UnmatchMatchMixin,
2021-02-07 18:54:03 +00:00
CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin):
""" Represents a single Movie.
Attributes:
2018-03-02 17:43:31 +00:00
TAG (str): 'Video'
2017-02-13 19:38:40 +00:00
TYPE (str): 'movie'
audienceRating (float): Audience rating (usually from Rotten Tomatoes).
2020-12-23 23:53:42 +00:00
audienceRatingImage (str): Key to audience rating image (rottentomatoes://image.rating.spilled).
chapters (List<:class:`~plexapi.media.Chapter`>): List of Chapter objects.
chapterSource (str): Chapter source (agent; media; mixed).
2020-12-23 23:53:42 +00:00
collections (List<:class:`~plexapi.media.Collection`>): List of collection objects.
contentRating (str) Content rating (PG-13; NR; TV-G).
2017-02-13 19:38:40 +00:00
countries (List<:class:`~plexapi.media.Country`>): List of countries objects.
directors (List<:class:`~plexapi.media.Director`>): List of director objects.
2020-12-23 23:53:42 +00:00
duration (int): Duration of the movie in milliseconds.
2017-02-13 19:38:40 +00:00
genres (List<:class:`~plexapi.media.Genre`>): List of genre objects.
guids (List<:class:`~plexapi.media.Guid`>): List of guid objects.
2020-12-23 23:53:42 +00:00
labels (List<:class:`~plexapi.media.Label`>): List of label objects.
languageOverride (str): Setting that indicates if a languge is used to override metadata
(eg. en-CA, None = Library default).
2017-02-13 19:38:40 +00:00
media (List<:class:`~plexapi.media.Media`>): List of media objects.
2020-12-23 23:53:42 +00:00
originallyAvailableAt (datetime): Datetime the movie was released.
originalTitle (str): Original title, often the foreign title (転々; 엽기적인 그녀).
primaryExtraKey (str) Primary extra key (/library/metadata/66351).
2017-02-13 19:38:40 +00:00
producers (List<:class:`~plexapi.media.Producer`>): List of producers objects.
2020-12-23 23:53:42 +00:00
rating (float): Movie critic rating (7.9; 9.8; 8.1).
ratingImage (str): Key to critic rating image (rottentomatoes://image.rating.rotten).
2017-02-13 19:38:40 +00:00
roles (List<:class:`~plexapi.media.Role`>): List of role objects.
2018-03-02 17:43:31 +00:00
similar (List<:class:`~plexapi.media.Similar`>): List of Similar objects.
2020-12-23 23:53:42 +00:00
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?).
useOriginalTitle (int): Setting that indicates if the original title is used for the movie
(-1 = Library default, 0 = No, 1 = Yes).
2020-12-23 23:53:42 +00:00
userRating (float): User rating (2.0; 8.0).
viewOffset (int): View offset in milliseconds.
writers (List<:class:`~plexapi.media.Writer`>): List of writers objects.
year (int): Year movie was released.
"""
TAG = 'Video'
2014-12-29 03:21:58 +00:00
TYPE = 'movie'
2018-09-08 15:25:16 +00:00
METADATA_TYPE = 'movie'
2014-12-29 03:21:58 +00:00
def _loadData(self, data):
2017-02-13 19:38:40 +00:00
""" Load attribute values from Plex XML response. """
Video._loadData(self, data)
Playable._loadData(self, data)
self.audienceRating = utils.cast(float, data.attrib.get('audienceRating'))
2017-02-04 17:43:50 +00:00
self.audienceRatingImage = data.attrib.get('audienceRatingImage')
2020-12-23 23:53:42 +00:00
self.chapters = self.findItems(data, media.Chapter)
2017-02-04 17:43:50 +00:00
self.chapterSource = data.attrib.get('chapterSource')
2020-12-23 23:53:42 +00:00
self.collections = self.findItems(data, media.Collection)
2017-02-04 17:43:50 +00:00
self.contentRating = data.attrib.get('contentRating')
2020-12-23 23:53:42 +00:00
self.countries = self.findItems(data, media.Country)
self.directors = self.findItems(data, media.Director)
2017-02-04 17:43:50 +00:00
self.duration = utils.cast(int, data.attrib.get('duration'))
2020-12-23 23:53:42 +00:00
self.genres = self.findItems(data, media.Genre)
self.guids = self.findItems(data, media.Guid)
2020-12-23 23:53:42 +00:00
self.labels = self.findItems(data, media.Label)
self.languageOverride = data.attrib.get('languageOverride')
2020-12-23 23:53:42 +00:00
self.media = self.findItems(data, media.Media)
self.originallyAvailableAt = utils.toDatetime(data.attrib.get('originallyAvailableAt'), '%Y-%m-%d')
2017-02-04 17:43:50 +00:00
self.originalTitle = data.attrib.get('originalTitle')
self.primaryExtraKey = data.attrib.get('primaryExtraKey')
2020-12-23 23:53:42 +00:00
self.producers = self.findItems(data, media.Producer)
self.rating = utils.cast(float, data.attrib.get('rating'))
2017-02-04 17:43:50 +00:00
self.ratingImage = data.attrib.get('ratingImage')
2020-12-23 23:53:42 +00:00
self.roles = self.findItems(data, media.Role)
self.similar = self.findItems(data, media.Similar)
2017-02-04 17:43:50 +00:00
self.studio = data.attrib.get('studio')
self.tagline = data.attrib.get('tagline')
self.useOriginalTitle = utils.cast(int, data.attrib.get('useOriginalTitle', '-1'))
2017-02-04 17:43:50 +00:00
self.userRating = utils.cast(float, data.attrib.get('userRating'))
self.viewOffset = utils.cast(int, data.attrib.get('viewOffset', 0))
self.writers = self.findItems(data, media.Writer)
2020-12-23 23:53:42 +00:00
self.year = utils.cast(int, data.attrib.get('year'))
2016-12-16 23:38:08 +00:00
@property
def actors(self):
2017-02-13 19:38:40 +00:00
""" Alias to self.roles. """
return self.roles
2016-12-16 23:38:08 +00:00
2017-01-09 14:21:54 +00:00
@property
def locations(self):
2017-01-09 14:21:54 +00:00
""" This does not exist in plex xml response but is added to have a common
2020-12-23 23:53:42 +00:00
interface to get the locations of the movie.
Retruns:
List<str> of file paths where the movie is found on disk.
2017-01-09 14:21:54 +00:00
"""
return [part.file for part in self.iterParts() if part]
def _prettyfilename(self):
# This is just for compat.
return self.title
def hubs(self):
""" Returns a list of :class:`~plexapi.library.Hub` objects. """
data = self._server.query(self._details_key)
video = data.find('Video')
if video:
related = video.find('Related')
if related:
return self.findItems(related, library.Hub)
2019-01-07 13:04:53 +00:00
def download(self, savepath=None, keep_original_name=False, **kwargs):
2017-02-13 19:38:40 +00:00
""" Download video files to specified directory.
2017-02-13 19:38:40 +00:00
Parameters:
savepath (str): Defaults to current working dir.
2019-01-07 13:04:53 +00:00
keep_original_name (bool): True to keep the original file name otherwise
2017-02-13 19:38:40 +00:00
a friendlier is generated.
2020-11-23 03:06:30 +00:00
**kwargs: Additional options passed into :func:`~plexapi.base.PlexObject.getStreamURL`.
2017-02-13 19:38:40 +00:00
"""
filepaths = []
locations = [i for i in self.iterParts() if i]
for location in locations:
name = location.file
2019-01-07 13:04:53 +00:00
if not keep_original_name:
title = self.title.replace(' ', '.')
name = '%s.%s' % (title, location.container)
if kwargs is not None:
url = self.getStreamURL(**kwargs)
2017-01-09 14:21:54 +00:00
else:
self._server.url('%s?download=1' % location.key)
filepath = utils.download(url, self._server._token, filename=name,
2020-03-14 14:52:54 +00:00
savepath=savepath, session=self._server._session)
2017-08-18 19:44:40 +00:00
if filepath:
filepaths.append(filepath)
return filepaths
2017-01-09 14:21:54 +00:00
2014-12-29 03:21:58 +00:00
@utils.registerPlexObject
2021-02-15 00:11:50 +00:00
class Show(Video, ArtMixin, BannerMixin, PosterMixin, SplitMergeMixin, UnmatchMatchMixin,
CollectionMixin, GenreMixin, LabelMixin):
2017-02-13 19:38:40 +00:00
""" Represents a single Show (including all seasons and episodes).
Attributes:
2018-03-02 17:43:31 +00:00
TAG (str): 'Directory'
2017-02-13 19:38:40 +00:00
TYPE (str): 'show'
audienceRating (float): Audience rating (TMDB or TVDB).
audienceRatingImage (str): Key to audience rating image (tmdb://image.rating).
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).
2020-12-23 23:53:42 +00:00
banner (str): Key to banner artwork (/library/metadata/<ratingkey>/banner/<bannerid>).
childCount (int): Number of seasons in the show.
collections (List<:class:`~plexapi.media.Collection`>): List of collection objects.
2017-02-13 19:38:40 +00:00
contentRating (str) Content rating (PG-13; NR; TV-G).
2020-12-23 23:53:42 +00:00
duration (int): Typical duration of the show episodes in milliseconds.
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).
2017-02-13 19:38:40 +00:00
genres (List<:class:`~plexapi.media.Genre`>): List of genre objects.
guids (List<:class:`~plexapi.media.Guid`>): List of guid objects.
2020-12-23 23:53:42 +00:00
index (int): Plex index number for the show.
key (str): API URL (/library/metadata/<ratingkey>).
labels (List<:class:`~plexapi.media.Label`>): List of label objects.
languageOverride (str): Setting that indicates if a languge is used to override metadata
(eg. en-CA, None = Library default).
2020-12-23 23:53:42 +00:00
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.
2020-12-23 23:53:42 +00:00
originallyAvailableAt (datetime): Datetime the show was released.
2021-02-11 05:05:21 +00:00
originalTitle (str): The original title of the show.
2020-12-23 23:53:42 +00:00
rating (float): Show rating (7.9; 9.8; 8.1).
2017-02-13 19:38:40 +00:00
roles (List<:class:`~plexapi.media.Role`>): List of role objects.
showOrdering (str): Setting that indicates the episode ordering for the show
(None = Library default).
2018-03-02 17:43:31 +00:00
similar (List<:class:`~plexapi.media.Similar`>): List of Similar objects.
2020-12-23 23:53:42 +00:00
studio (str): Studio that created show (Di Bonaventura Pictures; 21 Laps Entertainment).
2021-02-27 07:01:00 +00:00
tagline (str): Show tag line.
2020-12-23 23:53:42 +00:00
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).
userRating (float): User rating (2.0; 8.0).
2020-12-23 23:53:42 +00:00
viewedLeafCount (int): Number of items marked as played in the show view.
year (int): Year the show was released.
2017-02-13 19:38:40 +00:00
"""
TAG = 'Directory'
2014-12-29 03:21:58 +00:00
TYPE = 'show'
2018-09-08 15:25:16 +00:00
METADATA_TYPE = 'episode'
2015-02-24 03:42:29 +00:00
2014-12-29 03:21:58 +00:00
def _loadData(self, data):
2017-02-13 19:38:40 +00:00
""" Load attribute values from Plex XML response. """
Video._loadData(self, data)
self.audienceRating = utils.cast(float, data.attrib.get('audienceRating'))
self.audienceRatingImage = data.attrib.get('audienceRatingImage')
self.autoDeletionItemPolicyUnwatchedLibrary = utils.cast(
int, data.attrib.get('autoDeletionItemPolicyUnwatchedLibrary', '0'))
self.autoDeletionItemPolicyWatchedLibrary = utils.cast(
int, data.attrib.get('autoDeletionItemPolicyWatchedLibrary', '0'))
2017-02-04 17:43:50 +00:00
self.banner = data.attrib.get('banner')
self.childCount = utils.cast(int, data.attrib.get('childCount'))
self.collections = self.findItems(data, media.Collection)
2020-12-23 23:53:42 +00:00
self.contentRating = data.attrib.get('contentRating')
2017-02-04 17:43:50 +00:00
self.duration = utils.cast(int, data.attrib.get('duration'))
self.episodeSort = utils.cast(int, data.attrib.get('episodeSort', '-1'))
self.flattenSeasons = utils.cast(int, data.attrib.get('flattenSeasons', '-1'))
2020-12-23 23:53:42 +00:00
self.genres = self.findItems(data, media.Genre)
self.guids = self.findItems(data, media.Guid)
2020-12-23 23:53:42 +00:00
self.index = utils.cast(int, data.attrib.get('index'))
self.key = self.key.replace('/children', '') # FIX_BUG_50
self.labels = self.findItems(data, media.Label)
self.languageOverride = data.attrib.get('languageOverride')
2017-02-04 17:43:50 +00:00
self.leafCount = utils.cast(int, data.attrib.get('leafCount'))
2017-02-13 03:15:47 +00:00
self.locations = self.listAttrs(data, 'path', etag='Location')
self.network = data.attrib.get('network')
2020-12-23 23:53:42 +00:00
self.originallyAvailableAt = utils.toDatetime(data.attrib.get('originallyAvailableAt'), '%Y-%m-%d')
2021-02-11 05:05:21 +00:00
self.originalTitle = data.attrib.get('originalTitle')
2017-02-04 17:43:50 +00:00
self.rating = utils.cast(float, data.attrib.get('rating'))
2020-12-23 23:53:42 +00:00
self.roles = self.findItems(data, media.Role)
self.showOrdering = data.attrib.get('showOrdering')
2020-12-23 23:53:42 +00:00
self.similar = self.findItems(data, media.Similar)
2017-02-04 17:43:50 +00:00
self.studio = data.attrib.get('studio')
2021-02-27 07:01:00 +00:00
self.tagline = data.attrib.get('tagline')
2017-02-04 17:43:50 +00:00
self.theme = data.attrib.get('theme')
self.useOriginalTitle = utils.cast(int, data.attrib.get('useOriginalTitle', '-1'))
self.userRating = utils.cast(float, data.attrib.get('userRating'))
self.viewedLeafCount = utils.cast(int, data.attrib.get('viewedLeafCount'))
2017-02-04 17:43:50 +00:00
self.year = utils.cast(int, data.attrib.get('year'))
2020-12-23 23:53:42 +00:00
def __iter__(self):
for season in self.seasons():
yield season
@property
def actors(self):
2017-02-13 19:38:40 +00:00
""" Alias to self.roles. """
return self.roles
2016-12-16 23:38:08 +00:00
@property
def isWatched(self):
2020-12-23 23:53:42 +00:00
""" Returns True if the show is fully watched. """
return bool(self.viewedLeafCount == self.leafCount)
2014-12-29 03:21:58 +00:00
2020-05-24 03:07:44 +00:00
def preferences(self):
""" Returns a list of :class:`~plexapi.settings.Preferences` objects. """
items = []
2020-11-21 20:08:27 +00:00
data = self._server.query(self._details_key)
2020-05-24 03:07:44 +00:00
for item in data.iter('Preferences'):
for elem in item:
setting = settings.Preferences(data=elem, server=self._server)
setting._initpath = self.key
items.append(setting)
2020-05-24 03:07:44 +00:00
return items
def editAdvanced(self, **kwargs):
2020-06-05 18:20:39 +00:00
""" Edit a show's advanced settings. """
data = {}
key = '%s/prefs?' % self.key
preferences = {pref.id: list(pref.enumValues.keys()) for pref in self.preferences()}
for settingID, value in kwargs.items():
enumValues = preferences.get(settingID)
if value in enumValues:
data[settingID] = value
else:
raise NotFound('%s not found in %s' % (value, enumValues))
url = key + urlencode(data)
self._server.query(url, method=self._server._session.put)
def defaultAdvanced(self):
2020-06-05 18:20:39 +00:00
""" Edit all of show's advanced settings to default. """
data = {}
key = '%s/prefs?' % self.key
for preference in self.preferences():
data[preference.id] = preference.default
url = key + urlencode(data)
self._server.query(url, method=self._server._session.put)
2020-05-24 03:20:22 +00:00
def hubs(self):
""" Returns a list of :class:`~plexapi.library.Hub` objects. """
2020-11-21 20:08:27 +00:00
data = self._server.query(self._details_key)
directory = data.find('Directory')
if directory:
related = directory.find('Related')
if related:
return self.findItems(related, library.Hub)
2020-05-24 03:20:22 +00:00
2020-05-24 03:30:44 +00:00
def onDeck(self):
""" Returns show's On Deck :class:`~plexapi.video.Video` object or `None`.
2020-05-25 02:24:32 +00:00
If show is unwatched, return will likely be the first episode.
"""
2020-11-21 20:08:27 +00:00
data = self._server.query(self._details_key)
episode = next(data.iter('OnDeck'), None)
if episode:
return self.findItems(episode)[0]
return None
2020-05-24 03:20:22 +00:00
def season(self, title=None, season=None):
""" Returns the season with the specified title or number.
2017-01-02 21:06:40 +00:00
Parameters:
title (str): Title of the season to return.
season (int): Season number (default: None; required if title not specified).
Raises:
:exc:`~plexapi.exceptions.BadRequest`: If title or season parameter is missing.
2017-01-02 21:06:40 +00:00
"""
key = '/library/metadata/%s/children' % self.ratingKey
2020-12-30 23:35:57 +00:00
if title is not None and not isinstance(title, int):
return self.fetchItem(key, Season, title__iexact=title)
2020-12-30 23:35:57 +00:00
elif season is not None or isinstance(title, int):
2020-12-30 23:49:26 +00:00
if isinstance(title, int):
index = title
else:
index = season
return self.fetchItem(key, Season, index=index)
2020-12-24 06:00:00 +00:00
raise BadRequest('Missing argument: title or season is required')
2014-12-29 03:21:58 +00:00
def seasons(self, **kwargs):
""" Returns a list of :class:`~plexapi.video.Season` objects in the show. """
key = '/library/metadata/%s/children?excludeAllLeaves=1' % self.ratingKey
return self.fetchItems(key, Season, **kwargs)
2014-12-29 03:21:58 +00:00
2017-01-04 20:38:04 +00:00
def episode(self, title=None, season=None, episode=None):
2017-02-13 19:38:40 +00:00
""" Find a episode using a title or season and episode.
2020-11-23 04:43:59 +00:00
Parameters:
2017-02-13 19:38:40 +00:00
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).
2020-11-23 04:43:59 +00:00
Raises:
:exc:`~plexapi.exceptions.BadRequest`: If title or season and episode parameters are missing.
"""
key = '/library/metadata/%s/allLeaves' % self.ratingKey
2020-12-30 23:49:26 +00:00
if title is not None:
return self.fetchItem(key, Episode, title__iexact=title)
elif season is not None and episode is not None:
return self.fetchItem(key, Episode, parentIndex=season, index=episode)
raise BadRequest('Missing argument: title or season and episode are required')
2014-12-29 03:21:58 +00:00
def episodes(self, **kwargs):
""" Returns a list of :class:`~plexapi.video.Episode` objects in the show. """
key = '/library/metadata/%s/allLeaves' % self.ratingKey
return self.fetchItems(key, Episode, **kwargs)
def get(self, title=None, season=None, episode=None):
""" Alias to :func:`~plexapi.video.Show.episode`. """
return self.episode(title, season, episode)
def watched(self):
2017-02-13 19:38:40 +00:00
""" Returns list of watched :class:`~plexapi.video.Episode` objects. """
return self.episodes(viewCount__gt=0)
def unwatched(self):
2017-02-13 19:38:40 +00:00
""" Returns list of unwatched :class:`~plexapi.video.Episode` objects. """
return self.episodes(viewCount=0)
2019-01-07 13:04:53 +00:00
def download(self, savepath=None, keep_original_name=False, **kwargs):
2017-02-13 19:38:40 +00:00
""" Download video files to specified directory.
2017-02-13 19:38:40 +00:00
Parameters:
savepath (str): Defaults to current working dir.
2019-01-07 13:04:53 +00:00
keep_original_name (bool): True to keep the original file name otherwise
2017-02-13 19:38:40 +00:00
a friendlier is generated.
2020-11-23 03:06:30 +00:00
**kwargs: Additional options passed into :func:`~plexapi.base.PlexObject.getStreamURL`.
2017-02-13 19:38:40 +00:00
"""
filepaths = []
for episode in self.episodes():
2019-01-07 13:04:53 +00:00
filepaths += episode.download(savepath, keep_original_name, **kwargs)
return filepaths
2014-12-29 03:21:58 +00:00
@utils.registerPlexObject
2021-02-07 04:19:11 +00:00
class Season(Video, ArtMixin, PosterMixin):
2017-02-13 19:38:40 +00:00
""" Represents a single Show Season (including all episodes).
Attributes:
2018-03-02 17:43:31 +00:00
TAG (str): 'Directory'
2017-02-13 19:38:40 +00:00
TYPE (str): 'season'
guids (List<:class:`~plexapi.media.Guid`>): List of guid objects.
2017-02-13 19:38:40 +00:00
index (int): Season number.
2020-12-23 23:53:42 +00:00
key (str): API URL (/library/metadata/<ratingkey>).
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.
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.
viewedLeafCount (int): Number of items marked as played in the season view.
2017-02-13 19:38:40 +00:00
"""
TAG = 'Directory'
2014-12-29 03:21:58 +00:00
TYPE = 'season'
2018-09-08 15:25:16 +00:00
METADATA_TYPE = 'episode'
2014-12-29 03:21:58 +00:00
def _loadData(self, data):
2017-02-13 19:38:40 +00:00
""" Load attribute values from Plex XML response. """
Video._loadData(self, data)
self.guids = self.findItems(data, media.Guid)
2017-02-04 17:43:50 +00:00
self.index = utils.cast(int, data.attrib.get('index'))
2020-12-23 23:53:42 +00:00
self.key = self.key.replace('/children', '') # FIX_BUG_50
self.leafCount = utils.cast(int, data.attrib.get('leafCount'))
self.parentGuid = data.attrib.get('parentGuid')
self.parentIndex = data.attrib.get('parentIndex')
2017-02-04 17:43:50 +00:00
self.parentKey = data.attrib.get('parentKey')
self.parentRatingKey = utils.cast(int, data.attrib.get('parentRatingKey'))
2020-12-23 23:53:42 +00:00
self.parentTheme = data.attrib.get('parentTheme')
self.parentThumb = data.attrib.get('parentThumb')
2017-02-04 17:43:50 +00:00
self.parentTitle = data.attrib.get('parentTitle')
self.viewedLeafCount = utils.cast(int, data.attrib.get('viewedLeafCount'))
2016-12-16 23:38:08 +00:00
2020-12-23 23:53:42 +00:00
def __iter__(self):
for episode in self.episodes():
yield episode
def __repr__(self):
return '<%s>' % ':'.join([p for p in [
self.__class__.__name__,
self.key.replace('/library/metadata/', '').replace('/children', ''),
2017-02-20 05:37:00 +00:00
'%s-s%s' % (self.parentTitle.replace(' ', '-')[:20], self.seasonNumber),
] if p])
@property
def isWatched(self):
2020-12-23 23:53:42 +00:00
""" Returns True if the season is fully watched. """
return bool(self.viewedLeafCount == self.leafCount)
2014-12-29 03:21:58 +00:00
@property
def seasonNumber(self):
2017-02-13 19:38:40 +00:00
""" Returns season number. """
return self.index
2017-02-09 04:08:25 +00:00
def episodes(self, **kwargs):
2020-12-23 23:53:42 +00:00
""" Returns a list of :class:`~plexapi.video.Episode` objects in the season. """
key = '/library/metadata/%s/children' % self.ratingKey
return self.fetchItems(key, Episode, **kwargs)
2014-12-29 03:21:58 +00:00
2017-02-13 19:38:40 +00:00
def episode(self, title=None, episode=None):
""" Returns the episode with the given title or number.
2017-01-02 21:06:40 +00:00
Parameters:
title (str): Title of the episode to return.
episode (int): Episode number (default: None; required if title not specified).
Raises:
:exc:`~plexapi.exceptions.BadRequest`: If title or episode parameter is missing.
2016-12-16 23:38:08 +00:00
"""
key = '/library/metadata/%s/children' % self.ratingKey
2020-12-30 23:49:26 +00:00
if title is not None:
return self.fetchItem(key, Episode, title__iexact=title)
2020-12-30 23:49:26 +00:00
elif episode is not None:
return self.fetchItem(key, Episode, parentIndex=self.index, index=episode)
raise BadRequest('Missing argument: title or episode is required')
2017-01-04 20:38:04 +00:00
2017-02-13 19:38:40 +00:00
def get(self, title=None, episode=None):
2020-11-23 03:06:30 +00:00
""" Alias to :func:`~plexapi.video.Season.episode`. """
2017-02-13 19:38:40 +00:00
return self.episode(title, episode)
2014-12-29 03:21:58 +00:00
def onDeck(self):
""" Returns season's On Deck :class:`~plexapi.video.Video` object or `None`.
Will only return a match if the show's On Deck episode is in this season.
"""
data = self._server.query(self._details_key)
episode = next(data.iter('OnDeck'), None)
if episode:
return self.findItems(episode)[0]
return None
2014-12-29 03:21:58 +00:00
def show(self):
2020-12-23 23:53:42 +00:00
""" Return the season's :class:`~plexapi.video.Show`. """
return self.fetchItem(self.parentRatingKey)
2014-12-29 03:21:58 +00:00
def watched(self):
2017-02-13 19:38:40 +00:00
""" Returns list of watched :class:`~plexapi.video.Episode` objects. """
2021-03-02 01:54:19 +00:00
return self.episodes(viewCount__gt=0)
def unwatched(self):
2017-02-13 19:38:40 +00:00
""" Returns list of unwatched :class:`~plexapi.video.Episode` objects. """
2021-03-02 01:54:19 +00:00
return self.episodes(viewCount=0)
2019-01-07 13:04:53 +00:00
def download(self, savepath=None, keep_original_name=False, **kwargs):
2017-02-13 19:38:40 +00:00
""" Download video files to specified directory.
2017-02-13 19:38:40 +00:00
Parameters:
savepath (str): Defaults to current working dir.
2019-01-07 13:04:53 +00:00
keep_original_name (bool): True to keep the original file name otherwise
2017-02-13 19:38:40 +00:00
a friendlier is generated.
2020-11-23 03:06:30 +00:00
**kwargs: Additional options passed into :func:`~plexapi.base.PlexObject.getStreamURL`.
2017-02-13 19:38:40 +00:00
"""
filepaths = []
for episode in self.episodes():
2019-01-07 13:04:53 +00:00
filepaths += episode.download(savepath, keep_original_name, **kwargs)
return filepaths
2018-09-08 15:25:16 +00:00
def _defaultSyncTitle(self):
""" Returns str, default title for a new syncItem. """
return '%s - %s' % (self.parentTitle, self.title)
2014-12-29 03:21:58 +00:00
@utils.registerPlexObject
class Episode(Video, Playable, ArtMixin, PosterMixin,
2021-02-07 18:54:03 +00:00
DirectorMixin, WriterMixin):
2017-02-13 19:38:40 +00:00
""" Represents a single Shows Episode.
2017-02-13 19:38:40 +00:00
Attributes:
2018-03-02 17:43:31 +00:00
TAG (str): 'Video'
2017-02-13 19:38:40 +00:00
TYPE (str): 'episode'
audienceRating (float): Audience rating (TMDB or TVDB).
audienceRatingImage (str): Key to audience rating image (tmdb://image.rating).
2020-12-23 23:53:42 +00:00
chapters (List<:class:`~plexapi.media.Chapter`>): List of Chapter objects.
chapterSource (str): Chapter source (agent; media; mixed).
2017-02-13 19:38:40 +00:00
contentRating (str) Content rating (PG-13; NR; TV-G).
directors (List<:class:`~plexapi.media.Director`>): List of director objects.
2020-12-23 23:53:42 +00:00
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<:class:`~plexapi.media.Guid`>): List of guid objects.
2020-12-23 23:53:42 +00:00
index (int): Episode number.
markers (List<:class:`~plexapi.media.Marker`>): List of marker objects.
2017-02-13 19:38:40 +00:00
media (List<:class:`~plexapi.media.Media`>): List of media objects.
2020-12-23 23:53:42 +00:00
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.
rating (float): Episode rating (7.9; 9.8; 8.1).
skipParent (bool): True if the show's seasons are set to hidden.
userRating (float): User rating (2.0; 8.0).
2020-12-23 23:53:42 +00:00
viewOffset (int): View offset in milliseconds.
2017-02-13 19:38:40 +00:00
writers (List<:class:`~plexapi.media.Writer`>): List of writers objects.
2020-12-23 23:53:42 +00:00
year (int): Year episode was released.
2017-02-13 19:38:40 +00:00
"""
TAG = 'Video'
2014-12-29 03:21:58 +00:00
TYPE = 'episode'
2018-09-08 15:25:16 +00:00
METADATA_TYPE = 'episode'
2014-12-29 03:21:58 +00:00
def _loadData(self, data):
2017-02-13 19:38:40 +00:00
""" Load attribute values from Plex XML response. """
Video._loadData(self, data)
Playable._loadData(self, data)
self._seasonNumber = None # cached season number
self.audienceRating = utils.cast(float, data.attrib.get('audienceRating'))
self.audienceRatingImage = data.attrib.get('audienceRatingImage')
2020-12-23 23:53:42 +00:00
self.chapters = self.findItems(data, media.Chapter)
2017-02-04 17:43:50 +00:00
self.chapterSource = data.attrib.get('chapterSource')
self.contentRating = data.attrib.get('contentRating')
2020-12-23 23:53:42 +00:00
self.directors = self.findItems(data, media.Director)
2017-02-04 17:43:50 +00:00
self.duration = utils.cast(int, data.attrib.get('duration'))
self.grandparentArt = data.attrib.get('grandparentArt')
2020-12-23 23:53:42 +00:00
self.grandparentGuid = data.attrib.get('grandparentGuid')
2017-02-04 17:43:50 +00:00
self.grandparentKey = data.attrib.get('grandparentKey')
self.grandparentRatingKey = utils.cast(int, data.attrib.get('grandparentRatingKey'))
self.grandparentTheme = data.attrib.get('grandparentTheme')
self.grandparentThumb = data.attrib.get('grandparentThumb')
self.grandparentTitle = data.attrib.get('grandparentTitle')
self.guids = self.findItems(data, media.Guid)
2017-02-04 17:43:50 +00:00
self.index = utils.cast(int, data.attrib.get('index'))
2020-12-23 23:53:42 +00:00
self.markers = self.findItems(data, media.Marker)
self.media = self.findItems(data, media.Media)
2017-02-04 17:43:50 +00:00
self.originallyAvailableAt = utils.toDatetime(data.attrib.get('originallyAvailableAt'), '%Y-%m-%d')
2020-12-23 23:53:42 +00:00
self.parentGuid = data.attrib.get('parentGuid')
self.parentIndex = utils.cast(int, data.attrib.get('parentIndex'))
2017-02-04 17:43:50 +00:00
self.parentKey = data.attrib.get('parentKey')
self.parentRatingKey = utils.cast(int, data.attrib.get('parentRatingKey'))
self.parentThumb = data.attrib.get('parentThumb')
self.parentTitle = data.attrib.get('parentTitle')
2017-02-04 17:43:50 +00:00
self.rating = utils.cast(float, data.attrib.get('rating'))
self.skipParent = utils.cast(bool, data.attrib.get('skipParent', '0'))
self.userRating = utils.cast(float, data.attrib.get('userRating'))
self.viewOffset = utils.cast(int, data.attrib.get('viewOffset', 0))
self.writers = self.findItems(data, media.Writer)
2020-12-23 23:53:42 +00:00
self.year = utils.cast(int, data.attrib.get('year'))
# If seasons are hidden, parentKey and parentRatingKey are missing from the XML response.
# https://forums.plex.tv/t/parentratingkey-not-in-episode-xml-when-seasons-are-hidden/300553
if self.skipParent and not self.parentRatingKey:
# Parse the parentRatingKey from the parentThumb
if self.parentThumb.startswith('/library/metadata/'):
self.parentRatingKey = utils.cast(int, self.parentThumb.split('/')[3])
# Get the parentRatingKey from the season's ratingKey
if not self.parentRatingKey and self.grandparentRatingKey:
self.parentRatingKey = self.show().season(season=self.parentIndex).ratingKey
if self.parentRatingKey:
self.parentKey = '/library/metadata/%s' % self.parentRatingKey
def __repr__(self):
return '<%s>' % ':'.join([p for p in [
self.__class__.__name__,
self.key.replace('/library/metadata/', '').replace('/children', ''),
'%s-%s' % (self.grandparentTitle.replace(' ', '-')[:20], self.seasonEpisode),
] if p])
2017-02-13 19:38:40 +00:00
def _prettyfilename(self):
""" Returns a human friendly filename. """
return '%s.%s' % (self.grandparentTitle.replace(' ', '.'), self.seasonEpisode)
2017-02-13 19:38:40 +00:00
@property
2017-02-13 19:38:40 +00:00
def locations(self):
""" This does not exist in plex xml response but is added to have a common
2020-12-23 23:53:42 +00:00
interface to get the locations of the episode.
Retruns:
List<str> of file paths where the episode is found on disk.
2017-02-13 19:38:40 +00:00
"""
return [part.file for part in self.iterParts() if part]
2014-12-29 03:21:58 +00:00
@property
def seasonNumber(self):
2020-12-23 23:53:42 +00:00
""" Returns the episodes season number. """
if self._seasonNumber is None:
self._seasonNumber = self.parentIndex if self.parentIndex else self.season().seasonNumber
2017-01-04 20:38:04 +00:00
return utils.cast(int, self._seasonNumber)
@property
def seasonEpisode(self):
""" Returns the s00e00 string containing the season and episode. """
return 's%se%s' % (str(self.seasonNumber).zfill(2), str(self.index).zfill(2))
@property
def hasIntroMarker(self):
2020-12-23 23:53:42 +00:00
""" Returns True if the episode has an intro marker in the xml. """
if not self.isFullObject():
self.reload()
2020-05-27 16:26:54 +00:00
return any(marker.type == 'intro' for marker in self.markers)
2014-12-29 03:21:58 +00:00
def season(self):
2020-12-23 23:53:42 +00:00
"""" Return the episode's :class:`~plexapi.video.Season`. """
return self.fetchItem(self.parentKey)
2014-12-29 03:21:58 +00:00
def show(self):
2020-12-23 23:53:42 +00:00
"""" Return the episode's :class:`~plexapi.video.Show`. """
return self.fetchItem(self.grandparentRatingKey)
2018-09-08 15:25:16 +00:00
def _defaultSyncTitle(self):
""" Returns str, default title for a new syncItem. """
return '%s - %s - (%s) %s' % (self.grandparentTitle, self.parentTitle, self.seasonEpisode, self.title)
2019-12-05 18:02:50 +00:00
@utils.registerPlexObject
2021-02-15 03:38:09 +00:00
class Clip(Video, Playable, ArtUrlMixin, PosterUrlMixin):
2021-02-15 04:06:49 +00:00
""" Represents a single Clip.
2020-12-23 23:53:42 +00:00
Attributes:
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<:class:`~plexapi.media.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.
"""
2019-12-05 18:02:50 +00:00
TAG = 'Video'
TYPE = 'clip'
METADATA_TYPE = 'clip'
def _loadData(self, data):
2021-02-15 04:06:49 +00:00
""" Load attribute values from Plex XML response. """
Video._loadData(self, data)
Playable._loadData(self, data)
2020-12-23 23:53:42 +00:00
self._data = data
self.duration = utils.cast(int, data.attrib.get('duration'))
self.extraType = utils.cast(int, data.attrib.get('extraType'))
self.index = utils.cast(int, data.attrib.get('index'))
2020-12-23 23:53:42 +00:00
self.media = self.findItems(data, media.Media)
2019-12-05 18:02:50 +00:00
self.originallyAvailableAt = data.attrib.get('originallyAvailableAt')
2020-12-23 23:53:42 +00:00
self.skipDetails = utils.cast(int, data.attrib.get('skipDetails'))
2019-12-05 18:02:50 +00:00
self.subtype = data.attrib.get('subtype')
2020-12-23 23:53:42 +00:00
self.thumbAspectRatio = data.attrib.get('thumbAspectRatio')
self.viewOffset = utils.cast(int, data.attrib.get('viewOffset', 0))
2020-12-23 23:53:42 +00:00
self.year = utils.cast(int, data.attrib.get('year'))
2020-12-23 23:53:42 +00:00
@property
def locations(self):
""" This does not exist in plex xml response but is added to have a common
interface to get the locations of the clip.
Retruns:
List<str> of file paths where the clip is found on disk.
2020-12-23 23:53:42 +00:00
"""
return [part.file for part in self.iterParts() if part]