Create and manage playlists and collections, organize media content, and control playback queues for seamless media experiences.
Create, manage, and share playlists for organizing media content.
class Playlist:
"""User-created or smart playlist for organizing media."""
@property
def title(self):
"""str: Playlist title."""
@property
def smart(self):
"""bool: Whether this is a smart playlist."""
@property
def playlistType(self):
"""str: Playlist type ('audio', 'video', 'photo')."""
def items(self):
"""
Get playlist items.
Returns:
list: List of media objects in playlist
"""
def addItems(self, items):
"""
Add items to playlist.
Args:
items (list or single item): Media items to add
"""
def removeItems(self, items):
"""
Remove items from playlist.
Args:
items (list or single item): Media items to remove
"""
def copyToUser(self, user):
"""
Share playlist with user.
Args:
user (str or MyPlexUser): User to share with
"""
def edit(self, **kwargs):
"""
Edit playlist metadata.
Args:
**kwargs: Playlist properties to update
- title (str): New playlist title
- summary (str): Playlist description
"""
def delete(self):
"""Delete this playlist."""
def play(self, client=None):
"""
Play playlist on client.
Args:
client (PlexClient, optional): Client to play on
"""
def moveItem(self, item, after):
"""
Reorder playlist by moving item to new position.
Args:
item: Playlist item to move
after: Item to place the moved item after (None for beginning)
"""
def updateFilters(self, **kwargs):
"""
Update smart playlist filters and criteria.
Args:
**kwargs: Filter parameters for smart playlist
- sort (str): Sort field and direction
- filters (dict): Filter criteria
- limit (int): Maximum number of items
"""
def sync(self, client, **kwargs):
"""
Add playlist to mobile sync queue.
Args:
client (PlexClient or str): Target sync client
**kwargs: Sync options
- quality (str): Sync quality setting
- videoQuality (int): Video quality level
- audioQuality (int): Audio quality level
"""Create and manage collections for grouping related media.
class Collection:
"""Media collection for grouping related content."""
@property
def title(self):
"""str: Collection title."""
@property
def smart(self):
"""bool: Whether this is a smart collection."""
@property
def collectionSort(self):
"""int: Collection sort order."""
def items(self):
"""
Get collection items.
Returns:
list: List of media objects in collection
"""
def addItems(self, items):
"""
Add items to collection.
Args:
items (list or single item): Media items to add
"""
def removeItems(self, items):
"""
Remove items from collection.
Args:
items (list or single item): Media items to remove
"""
def edit(self, **kwargs):
"""
Edit collection metadata.
Args:
**kwargs: Collection properties to update
- title (str): New collection title
- summary (str): Collection description
- contentRating (str): Content rating
"""
def delete(self):
"""Delete this collection."""
def moveItem(self, item, after):
"""
Reorder collection by moving item to new position.
Args:
item: Collection item to move
after: Item to place the moved item after (None for beginning)
"""
def updateFilters(self, **kwargs):
"""
Update smart collection filters and criteria.
Args:
**kwargs: Filter parameters for smart collection
- sort (str): Sort field and direction
- filters (dict): Filter criteria
"""
def mode(self, mode):
"""
Set collection display mode.
Args:
mode (str): Collection display mode ('default', 'hide', 'hideItems', 'showItems')
"""
def sort(self, field, **params):
"""
Set collection sort order.
Args:
field (str): Sort field ('titleSort', 'year', 'rating', etc.)
**params: Additional sort parameters
- descending (bool): Sort in descending order
"""Control dynamic playback queues for seamless media playback.
class PlayQueue:
"""Dynamic playback queue for controlling playback order."""
@property
def playQueueID(self):
"""int: Unique play queue identifier."""
@property
def selectedItem(self):
"""Media object: Currently selected item."""
def items(self):
"""
Get queue items.
Returns:
list: List of media objects in queue
"""
def addItem(self, item, playNext=False):
"""
Add item to queue.
Args:
item: Media item to add
playNext (bool): Add as next item vs end of queue
"""
def removeItem(self, item):
"""
Remove item from queue.
Args:
item: Media item to remove
"""
def clear(self):
"""Clear entire queue."""Create playlists and collections at the server level.
# Via PlexServer
class PlexServer:
def createPlaylist(self, title, section=None, items=None, smart=False, **kwargs):
"""
Create server playlist.
Args:
title (str): Playlist title
section (LibrarySection, optional): Section for smart playlists
items (list, optional): Initial items for regular playlists
smart (bool): Create smart playlist vs regular playlist
**kwargs: Additional playlist properties
- summary (str): Playlist description
- playlistType (str): Media type ('audio', 'video', 'photo')
Returns:
Playlist: Created playlist object
"""
def createCollection(self, title, section, items=None, smart=False, **kwargs):
"""
Create server collection.
Args:
title (str): Collection title
section (LibrarySection): Target library section
items (list, optional): Initial collection items
smart (bool): Create smart collection vs regular collection
**kwargs: Additional collection properties
- summary (str): Collection description
- contentRating (str): Content rating
Returns:
Collection: Created collection object
"""
def createPlayQueue(self, item, **kwargs):
"""
Create playback queue.
Args:
item: Media item to start queue with
**kwargs: Additional queue parameters
- shuffle (bool): Shuffle queue
- repeat (int): Repeat mode
- includeChapters (bool): Include chapter markers
Returns:
PlayQueue: Created play queue object
"""from plexapi.server import PlexServer
plex = PlexServer('http://localhost:32400', token='your-token')
# Get existing playlists
playlists = plex.playlists()
for playlist in playlists:
print(f"Playlist: {playlist.title} ({len(playlist.items())} items)")
# Get specific playlist
my_playlist = next(p for p in playlists if p.title == 'My Favorites')
# View playlist items
items = my_playlist.items()
for item in items:
print(f"- {item.title}")# Create regular playlist with specific items
movies = plex.library.section('Movies')
action_movies = [
movies.get('Die Hard'),
movies.get('The Matrix'),
movies.get('John Wick')
]
action_playlist = plex.createPlaylist(
title='Action Favorites',
items=action_movies,
summary='My favorite action movies'
)
# Create music playlist
music = plex.library.section('Music')
rock_tracks = music.search(genre='Rock', libtype='track')[:20]
rock_playlist = plex.createPlaylist(
title='Rock Hits',
items=rock_tracks,
playlistType='audio'
)# Create smart movie playlist
movie_section = plex.library.section('Movies')
# Smart playlist for highly rated recent movies
recent_hits = plex.createPlaylist(
title='Recent Hits',
section=movie_section,
smart=True,
summary='Movies from 2020+ with rating > 8.0'
# Note: Smart playlist criteria set through web interface
)
# Create smart music playlist
music_section = plex.library.section('Music')
top_rock = plex.createPlaylist(
title='Top Rock',
section=music_section,
smart=True,
playlistType='audio'
)# Add items to existing playlist
new_movies = [
movies.get('Avengers: Endgame'),
movies.get('Spider-Man: No Way Home')
]
action_playlist.addItems(new_movies)
# Remove items from playlist
action_playlist.removeItems([movies.get('Die Hard')])
# Edit playlist metadata
action_playlist.edit(
title='Ultimate Action Collection',
summary='The best action movies ever made'
)
# Share playlist with user
action_playlist.copyToUser('friend@example.com')# Get existing collections
movie_section = plex.library.section('Movies')
collections = movie_section.collections()
for collection in collections:
print(f"Collection: {collection.title} ({len(collection.items())} movies)")
# Create new collection
marvel_movies = [
movies.get('Iron Man'),
movies.get('Captain America: The First Avenger'),
movies.get('Thor'),
movies.get('The Avengers')
]
marvel_collection = plex.createCollection(
title='Marvel Cinematic Universe',
section=movie_section,
items=marvel_movies,
summary='Marvel superhero movies'
)
# Add more movies to collection
phase_2_movies = [
movies.get('Iron Man 3'),
movies.get('Thor: The Dark World'),
movies.get('Captain America: The Winter Soldier')
]
marvel_collection.addItems(phase_2_movies)# Create smart collection for a director
movie_section = plex.library.section('Movies')
nolan_collection = plex.createCollection(
title='Christopher Nolan Films',
section=movie_section,
smart=True,
summary='All movies directed by Christopher Nolan'
# Smart collection criteria configured through web interface
)
# Create smart collection for decade
eighties_collection = plex.createCollection(
title='80s Movies',
section=movie_section,
smart=True,
summary='Movies from the 1980s'
)# Create play queue from album
music = plex.library.section('Music')
album = music.get('Abbey Road')
queue = plex.createPlayQueue(
album,
shuffle=False,
repeat=0
)
print(f"Queue has {len(queue.items())} tracks")
# Add more items to queue
another_album = music.get('Dark Side of the Moon')
queue.addItem(another_album, playNext=True)
# Play queue on client
client = plex.client('Living Room')
client.playMedia(queue.selectedItem)# Create playlist from search results
recent_movies = plex.search('', libtype='movie', year__gte=2022)
recent_playlist = plex.createPlaylist(
title='Recent Releases',
items=recent_movies[:50], # Limit to 50 items
summary=f'Recently released movies ({len(recent_movies)} total)'
)
# Create themed playlists
# Holiday movies
holiday_movies = movie_section.search(title='Christmas') + \
movie_section.search(title='Holiday')
holiday_playlist = plex.createPlaylist(
title='Holiday Movies',
items=holiday_movies
)
# Workout music
upbeat_tracks = music.search(genre=['Pop', 'Rock', 'Electronic'], libtype='track')
workout_playlist = plex.createPlaylist(
title='Workout Mix',
items=upbeat_tracks[:100],
playlistType='audio'
)# Create genre-based collections
genres = ['Action', 'Comedy', 'Drama', 'Horror', 'Sci-Fi']
for genre in genres:
genre_movies = movie_section.search(genre=genre)
if genre_movies:
collection = plex.createCollection(
title=f'{genre} Movies',
section=movie_section,
items=genre_movies[:25], # Limit to 25 per collection
summary=f'Best {genre.lower()} movies in the library'
)
print(f"Created {genre} collection with {len(genre_movies)} movies")
# Create decade collections
decades = [(1980, 1989, '80s'), (1990, 1999, '90s'), (2000, 2009, '2000s')]
for start_year, end_year, decade_name in decades:
decade_movies = []
for year in range(start_year, end_year + 1):
year_movies = movie_section.search(year=year)
decade_movies.extend(year_movies)
if decade_movies:
collection = plex.createCollection(
title=f'{decade_name} Movies',
section=movie_section,
items=decade_movies,
summary=f'Movies from the {decade_name}'
)# Play entire playlist
playlist = plex.playlists()[0] # Get first playlist
client = plex.client('Living Room TV')
# Play playlist from beginning
playlist.play(client)
# Create queue from playlist and control playback
items = playlist.items()
queue = plex.createPlayQueue(items[0])
for item in items[1:]:
queue.addItem(item)
# Play queue with custom settings
client.playMedia(
queue.selectedItem,
shuffle=True,
repeat=2 # Repeat all
)# Clean up empty playlists
playlists = plex.playlists()
for playlist in playlists:
if len(playlist.items()) == 0:
print(f"Deleting empty playlist: {playlist.title}")
playlist.delete()
# Remove duplicate items from playlist
playlist = plex.playlists()[0]
items = playlist.items()
seen_keys = set()
duplicates = []
for item in items:
if item.ratingKey in seen_keys:
duplicates.append(item)
else:
seen_keys.add(item.ratingKey)
if duplicates:
print(f"Removing {len(duplicates)} duplicate items")
playlist.removeItems(duplicates)
# Update collection with new matching items
collection = plex.library.section('Movies').collections()[0]
current_items = set(item.ratingKey for item in collection.items())
# Find new items that match collection criteria
# (This example assumes manual criteria - smart collections update automatically)
all_action = movie_section.search(genre='Action')
new_items = [item for item in all_action if item.ratingKey not in current_items]
if new_items:
print(f"Adding {len(new_items)} new items to collection")
collection.addItems(new_items)