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

Mobile Sync Management

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

Manage mobile sync items, transcoding settings, and device synchronization for offline media access across mobile devices and clients.

Capabilities

SyncItem Management

Individual sync items representing media content prepared for offline access.

class SyncItem:
    """Individual sync item for offline media access."""
    
    def __init__(self, server, data, initpath=None):
        """
        Create sync item object.
        
        Args:
            server (PlexServer): Associated Plex server
            data (dict): Sync item data from server
            initpath (str, optional): API path used to create object
        """
    
    @classmethod
    def create(cls, server, media, client, **kwargs):
        """
        Create new sync item for media content.
        
        Args:
            server (PlexServer): Plex server instance
            media: Media object to sync (Movie, Episode, Album, etc.)
            client (PlexClient or str): Target sync client
            **kwargs: Sync configuration
                - title (str): Custom sync title
                - quality (str): Sync quality ('mobile', 'sd', 'hd')
                - videoBitrate (int): Video bitrate for transcoding
                - audioBitrate (int): Audio bitrate for transcoding
                - subtitle (str): Subtitle language code
                - unwatched (bool): Sync only unwatched items
                - limit (int): Limit number of items for shows/albums
                
        Returns:
            SyncItem: Created sync item object
        """
    
    @property
    def title(self):
        """str: Sync item title."""
        
    @property
    def status(self):
        """str: Current sync status ('created', 'processing', 'ready', 'error')."""
        
    @property
    def itemsCount(self):
        """int: Number of items in sync (for multi-item syncs)."""
        
    @property
    def totalSize(self):
        """int: Total size of sync in bytes."""
        
    @property
    def policy(self):
        """SyncPolicy: Sync policy configuration."""
        
    def delete(self):
        """Remove sync item and delete synced content."""

SyncList Management

Collections of sync items for batch operations and management.

class SyncList:
    """Collection of sync items for batch management."""
    
    def __init__(self, server, items=None):
        """
        Create sync list for batch operations.
        
        Args:
            server (PlexServer): Associated Plex server
            items (list, optional): Initial sync items
        """
    
    def sync(self, **kwargs):
        """
        Execute sync for all items in list.
        
        Args:
            **kwargs: Global sync options
                - quality (str): Default quality for all items
                - client (str): Default target client
        """
        
    def unsync(self, **kwargs):
        """
        Remove sync for all items in list.
        
        Args:
            **kwargs: Unsync options
        """
        
    def add(self, syncitem):
        """
        Add sync item to list.
        
        Args:
            syncitem (SyncItem): Sync item to add
        """
        
    def remove(self, syncitem):
        """
        Remove sync item from list.
        
        Args:
            syncitem (SyncItem): Sync item to remove
        """

Sync Policy Configuration

Transcoding and quality settings for sync operations.

class SyncPolicy:
    """Sync transcoding and quality policy."""
    
    @property
    def scope(self):
        """str: Policy scope ('all', 'mobile', 'cellular')."""
        
    @property
    def unwatched(self):
        """bool: Sync only unwatched content."""
        
    @property
    def quality(self):
        """str: Quality setting ('mobile', 'sd', 'hd', 'original')."""
        
    @property
    def videoBitrate(self):
        """int: Video bitrate in kbps."""
        
    @property
    def audioBitrate(self):
        """int: Audio bitrate in kbps."""
        
    @property
    def photoResolution(self):
        """str: Photo resolution for photo syncs."""

Server Sync Methods

Server-level sync management and client interaction.

# Via PlexServer
class PlexServer:
    def syncItems(self, client=None):
        """
        Get all sync items on server.
        
        Args:
            client (str, optional): Filter by client name
            
        Returns:
            list: List of SyncItem objects
        """
        
    def sync(self, media, client, **kwargs):
        """
        Create sync item for media content.
        
        Args:
            media: Media object to sync
            client (PlexClient or str): Target sync client
            **kwargs: Sync configuration options
            
        Returns:
            SyncItem: Created sync item
        """

# Via MyPlexAccount  
class MyPlexAccount:
    def syncItems(self, client=None, clientId=None):
        """
        Get sync items for account across all servers.
        
        Args:
            client (str, optional): Filter by client name
            clientId (str, optional): Filter by client ID
            
        Returns:
            list: List of SyncItem objects
        """

Usage Examples

Basic Sync Operations

from plexapi.server import PlexServer
from plexapi.sync import SyncItem

plex = PlexServer('http://localhost:32400', token='your-token')

# Get a movie to sync
movie = plex.library.section('Movies').get('The Matrix')

# Create sync item for mobile device
sync_item = SyncItem.create(
    server=plex,
    media=movie,
    client='iPhone',
    title='Matrix for Travel',
    quality='mobile',
    subtitle='en'
)

print(f"Created sync: {sync_item.title}")
print(f"Status: {sync_item.status}")
print(f"Size: {sync_item.totalSize / 1024 / 1024:.1f} MB")

# Monitor sync progress
import time
while sync_item.status in ['created', 'processing']:
    time.sleep(5)
    sync_item.reload()
    print(f"Sync status: {sync_item.status}")

if sync_item.status == 'ready':
    print("Sync completed successfully!")

TV Show Sync with Episodes

# Sync TV show with specific criteria
show = plex.library.section('TV Shows').get('The Office')

# Sync unwatched episodes only
show_sync = SyncItem.create(
    server=plex,
    media=show,
    client='iPad',
    title='The Office - Unwatched',
    quality='sd',
    unwatched=True,
    limit=10  # Only sync next 10 episodes
)

print(f"Syncing {show_sync.itemsCount} episodes")

# Sync specific season
season_2 = show.season(2)
season_sync = SyncItem.create(
    server=plex,
    media=season_2,
    client='iPad',
    title='The Office Season 2',
    quality='hd'
)

Music Sync

# Sync entire album
album = plex.library.section('Music').get('The Beatles').album('Abbey Road')

album_sync = SyncItem.create(
    server=plex,
    media=album,
    client='iPhone',
    title='Abbey Road - Mobile',
    quality='mobile',
    audioBitrate=128
)

# Sync playlist
playlist = plex.playlist('Road Trip Mix')
playlist_sync = SyncItem.create(
    server=plex,
    media=playlist,
    client='iPhone',
    title='Road Trip Offline',
    audioBitrate=192
)

Batch Sync Management

from plexapi.sync import SyncList

# Create sync list for multiple items
sync_list = SyncList(plex)

# Add multiple movies
movies_to_sync = [
    plex.library.section('Movies').get('Inception'),
    plex.library.section('Movies').get('Interstellar'),
    plex.library.section('Movies').get('The Dark Knight')
]

for movie in movies_to_sync:
    sync_item = SyncItem.create(
        server=plex,
        media=movie,
        client='iPad',
        quality='hd',
        videoBitrate=4000
    )
    sync_list.add(sync_item)

# Execute all syncs
sync_list.sync()

print(f"Started sync for {len(sync_list)} items")

Sync Quality Management

# High quality sync for home WiFi
hq_sync = SyncItem.create(
    server=plex,
    media=movie,
    client='AppleTV',
    quality='hd',
    videoBitrate=8000,
    audioBitrate=320
)

# Mobile quality for cellular usage
mobile_sync = SyncItem.create(
    server=plex,
    media=movie,  
    client='iPhone',
    quality='mobile',
    videoBitrate=1500,
    audioBitrate=128
)

# Original quality (no transcoding)
original_sync = SyncItem.create(
    server=plex,
    media=movie,
    client='Laptop',
    quality='original'
)

Sync Status Monitoring

# Get all sync items
all_syncs = plex.syncItems()

print(f"Total sync items: {len(all_syncs)}")

# Monitor sync status
for sync_item in all_syncs:
    print(f"\nSync: {sync_item.title}")
    print(f"  Status: {sync_item.status}")
    print(f"  Items: {sync_item.itemsCount}")
    print(f"  Size: {sync_item.totalSize / 1024 / 1024:.1f} MB")
    
    if sync_item.status == 'error':
        print(f"  Error: Check sync configuration")
    elif sync_item.status == 'processing':
        print(f"  Processing: Transcoding in progress")

# Filter by client  
iphone_syncs = plex.syncItems(client='iPhone')
print(f"\niPhone syncs: {len(iphone_syncs)}")

# Filter by status
processing_syncs = [s for s in all_syncs if s.status == 'processing']
ready_syncs = [s for s in all_syncs if s.status == 'ready']

print(f"Processing: {len(processing_syncs)}, Ready: {len(ready_syncs)}")

MyPlex Account Sync Management

from plexapi.myplex import MyPlexAccount

account = MyPlexAccount(token='your-token')

# Get sync items across all servers
all_account_syncs = account.syncItems()

print(f"Total syncs across all servers: {len(all_account_syncs)}")

# Filter by client
mobile_syncs = account.syncItems(client='iPhone')
tablet_syncs = account.syncItems(client='iPad')

print(f"Mobile syncs: {len(mobile_syncs)}")
print(f"Tablet syncs: {len(tablet_syncs)}")

# Get sync items by client ID (more precise)
device = account.device('iPhone')
if device:
    device_syncs = account.syncItems(clientId=device.clientIdentifier)
    print(f"Device-specific syncs: {len(device_syncs)}")

Sync Cleanup and Management

# Remove completed syncs older than 30 days
import datetime
from datetime import timedelta

cutoff_date = datetime.datetime.now() - timedelta(days=30)
old_syncs = []

for sync_item in plex.syncItems():
    if sync_item.status == 'ready' and hasattr(sync_item, 'updatedAt'):
        if sync_item.updatedAt < cutoff_date:
            old_syncs.append(sync_item)

print(f"Found {len(old_syncs)} old sync items to remove")

# Remove old syncs
for sync_item in old_syncs:
    print(f"Removing: {sync_item.title}")
    sync_item.delete()

# Remove failed syncs
failed_syncs = [s for s in plex.syncItems() if s.status == 'error']
for sync_item in failed_syncs:
    print(f"Removing failed sync: {sync_item.title}")
    sync_item.delete()

Advanced Sync Configuration

# Sync with custom transcoding settings
custom_sync = SyncItem.create(
    server=plex,
    media=movie,
    client='Android',
    title='Custom Quality Sync',
    quality='custom',
    
    # Video settings
    videoBitrate=3000,
    videoResolution='720p',
    videoCodec='h264',
    
    # Audio settings  
    audioBitrate=192,
    audioCodec='aac',
    audioChannels=2,
    
    # Subtitle settings
    subtitle='en',
    subtitleFormat='srt',
    
    # Content filtering
    unwatched=True,
    limit=5
)

# Sync with cellular optimization
cellular_sync = SyncItem.create(
    server=plex,
    media=show,
    client='iPhone',
    title='Cellular Optimized',
    quality='mobile',
    videoBitrate=800,  # Very low for cellular
    audioBitrate=64,   # Minimal audio bitrate  
    videoResolution='480p'
)

Sync Progress Tracking

def monitor_sync_progress(sync_item, interval=10):
    """Monitor sync progress with periodic updates."""
    import time
    
    print(f"Monitoring sync: {sync_item.title}")
    
    while sync_item.status in ['created', 'processing']:
        sync_item.reload()
        
        if hasattr(sync_item, 'progress'):
            progress = getattr(sync_item, 'progress', 0)
            print(f"Progress: {progress}% - Status: {sync_item.status}")
        else:
            print(f"Status: {sync_item.status}")
            
        time.sleep(interval)
    
    print(f"Final status: {sync_item.status}")
    
    if sync_item.status == 'ready':
        print(f"Sync completed! Size: {sync_item.totalSize / 1024 / 1024:.1f} MB")
    elif sync_item.status == 'error':
        print("Sync failed - check server logs for details")

# Usage
sync_item = SyncItem.create(plex, movie, 'iPhone', quality='hd')
monitor_sync_progress(sync_item, interval=5)

Playlist Sync Integration

# Sync playlists to mobile devices
music_playlist = plex.playlist('Workout Mix')
video_playlist = plex.playlist('Action Movies')

# Sync audio playlist
music_sync = music_playlist.sync(
    client='iPhone',
    quality='mobile',
    audioBitrate=192
)

# Sync video playlist with custom settings
video_sync = video_playlist.sync(
    client='iPad',
    quality='hd',
    videoBitrate=4000,
    limit=10  # Only sync first 10 movies
)

print(f"Music playlist sync: {music_sync.status}")
print(f"Video playlist sync: {video_sync.status}")

Sync Requirements

Mobile sync functionality requires:

Server Configuration: Sync must be enabled on the Plex Media Server
Client Support: Target client must support offline sync
Storage Space: Sufficient storage on both server and client devices
Processing Power: Server needs transcoding capability for quality conversion
Network Bandwidth: Adequate bandwidth for initial sync transfers