tessl/pypi-plex-api

Python bindings for the Plex Media Server API, enabling programmatic interaction with Plex servers and media libraries.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Playlists & Collections

Name: tessl/pypi-plex-api
Author: tessl

Create and manage playlists and collections, organize media content, and control playback queues for seamless media experiences.

Capabilities

Playlist Management

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
        """

Collection Management

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
        """

Play Queue Management

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."""

Server Playlist Creation

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
        """

Usage Examples

Basic Playlist Operations

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}")

Creating Playlists

# 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'
)

Smart Playlists

# 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'
)

Playlist Management

# 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')

Collection Operations

# 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)

Smart Collections

# 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'
)

Play Queue Management

# 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)

Advanced Playlist Features

# 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'
)

Collection Organization

# 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}'
        )

Playlist Playback Control

# 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
)

Maintenance Operations

# 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)

Install with Tessl CLI