0
# Mobile Sync Management
1

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

4
## Capabilities
5

6
### SyncItem Management
7

8
Individual sync items representing media content prepared for offline access.
9

10
```python { .api }
11
class SyncItem:
12
    """Individual sync item for offline media access."""
13
    
14
    def __init__(self, server, data, initpath=None):
15
        """
16
        Create sync item object.
17
        
18
        Args:
19
            server (PlexServer): Associated Plex server
20
            data (dict): Sync item data from server
21
            initpath (str, optional): API path used to create object
22
        """
23
    
24
    @classmethod
25
    def create(cls, server, media, client, **kwargs):
26
        """
27
        Create new sync item for media content.
28
        
29
        Args:
30
            server (PlexServer): Plex server instance
31
            media: Media object to sync (Movie, Episode, Album, etc.)
32
            client (PlexClient or str): Target sync client
33
            **kwargs: Sync configuration
34
                - title (str): Custom sync title
35
                - quality (str): Sync quality ('mobile', 'sd', 'hd')
36
                - videoBitrate (int): Video bitrate for transcoding
37
                - audioBitrate (int): Audio bitrate for transcoding
38
                - subtitle (str): Subtitle language code
39
                - unwatched (bool): Sync only unwatched items
40
                - limit (int): Limit number of items for shows/albums
41
                
42
        Returns:
43
            SyncItem: Created sync item object
44
        """
45
    
46
    @property
47
    def title(self):
48
        """str: Sync item title."""
49
        
50
    @property
51
    def status(self):
52
        """str: Current sync status ('created', 'processing', 'ready', 'error')."""
53
        
54
    @property
55
    def itemsCount(self):
56
        """int: Number of items in sync (for multi-item syncs)."""
57
        
58
    @property
59
    def totalSize(self):
60
        """int: Total size of sync in bytes."""
61
        
62
    @property
63
    def policy(self):
64
        """SyncPolicy: Sync policy configuration."""
65
        
66
    def delete(self):
67
        """Remove sync item and delete synced content."""
68
```
69

70
### SyncList Management
71

72
Collections of sync items for batch operations and management.
73

74
```python { .api }
75
class SyncList:
76
    """Collection of sync items for batch management."""
77
    
78
    def __init__(self, server, items=None):
79
        """
80
        Create sync list for batch operations.
81
        
82
        Args:
83
            server (PlexServer): Associated Plex server
84
            items (list, optional): Initial sync items
85
        """
86
    
87
    def sync(self, **kwargs):
88
        """
89
        Execute sync for all items in list.
90
        
91
        Args:
92
            **kwargs: Global sync options
93
                - quality (str): Default quality for all items
94
                - client (str): Default target client
95
        """
96
        
97
    def unsync(self, **kwargs):
98
        """
99
        Remove sync for all items in list.
100
        
101
        Args:
102
            **kwargs: Unsync options
103
        """
104
        
105
    def add(self, syncitem):
106
        """
107
        Add sync item to list.
108
        
109
        Args:
110
            syncitem (SyncItem): Sync item to add
111
        """
112
        
113
    def remove(self, syncitem):
114
        """
115
        Remove sync item from list.
116
        
117
        Args:
118
            syncitem (SyncItem): Sync item to remove
119
        """
120
```
121

122
### Sync Policy Configuration
123

124
Transcoding and quality settings for sync operations.
125

126
```python { .api }
127
class SyncPolicy:
128
    """Sync transcoding and quality policy."""
129
    
130
    @property
131
    def scope(self):
132
        """str: Policy scope ('all', 'mobile', 'cellular')."""
133
        
134
    @property
135
    def unwatched(self):
136
        """bool: Sync only unwatched content."""
137
        
138
    @property
139
    def quality(self):
140
        """str: Quality setting ('mobile', 'sd', 'hd', 'original')."""
141
        
142
    @property
143
    def videoBitrate(self):
144
        """int: Video bitrate in kbps."""
145
        
146
    @property
147
    def audioBitrate(self):
148
        """int: Audio bitrate in kbps."""
149
        
150
    @property
151
    def photoResolution(self):
152
        """str: Photo resolution for photo syncs."""
153
```
154

155
### Server Sync Methods
156

157
Server-level sync management and client interaction.
158

159
```python { .api }
160
# Via PlexServer
161
class PlexServer:
162
    def syncItems(self, client=None):
163
        """
164
        Get all sync items on server.
165
        
166
        Args:
167
            client (str, optional): Filter by client name
168
            
169
        Returns:
170
            list: List of SyncItem objects
171
        """
172
        
173
    def sync(self, media, client, **kwargs):
174
        """
175
        Create sync item for media content.
176
        
177
        Args:
178
            media: Media object to sync
179
            client (PlexClient or str): Target sync client
180
            **kwargs: Sync configuration options
181
            
182
        Returns:
183
            SyncItem: Created sync item
184
        """
185

186
# Via MyPlexAccount  
187
class MyPlexAccount:
188
    def syncItems(self, client=None, clientId=None):
189
        """
190
        Get sync items for account across all servers.
191
        
192
        Args:
193
            client (str, optional): Filter by client name
194
            clientId (str, optional): Filter by client ID
195
            
196
        Returns:
197
            list: List of SyncItem objects
198
        """
199
```
200

201
## Usage Examples
202

203
### Basic Sync Operations
204

205
```python
206
from plexapi.server import PlexServer
207
from plexapi.sync import SyncItem
208

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

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

214
# Create sync item for mobile device
215
sync_item = SyncItem.create(
216
    server=plex,
217
    media=movie,
218
    client='iPhone',
219
    title='Matrix for Travel',
220
    quality='mobile',
221
    subtitle='en'
222
)
223

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

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

235
if sync_item.status == 'ready':
236
    print("Sync completed successfully!")
237
```
238

239
### TV Show Sync with Episodes
240

241
```python
242
# Sync TV show with specific criteria
243
show = plex.library.section('TV Shows').get('The Office')
244

245
# Sync unwatched episodes only
246
show_sync = SyncItem.create(
247
    server=plex,
248
    media=show,
249
    client='iPad',
250
    title='The Office - Unwatched',
251
    quality='sd',
252
    unwatched=True,
253
    limit=10  # Only sync next 10 episodes
254
)
255

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

258
# Sync specific season
259
season_2 = show.season(2)
260
season_sync = SyncItem.create(
261
    server=plex,
262
    media=season_2,
263
    client='iPad',
264
    title='The Office Season 2',
265
    quality='hd'
266
)
267
```
268

269
### Music Sync
270

271
```python
272
# Sync entire album
273
album = plex.library.section('Music').get('The Beatles').album('Abbey Road')
274

275
album_sync = SyncItem.create(
276
    server=plex,
277
    media=album,
278
    client='iPhone',
279
    title='Abbey Road - Mobile',
280
    quality='mobile',
281
    audioBitrate=128
282
)
283

284
# Sync playlist
285
playlist = plex.playlist('Road Trip Mix')
286
playlist_sync = SyncItem.create(
287
    server=plex,
288
    media=playlist,
289
    client='iPhone',
290
    title='Road Trip Offline',
291
    audioBitrate=192
292
)
293
```
294

295
### Batch Sync Management
296

297
```python
298
from plexapi.sync import SyncList
299

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

303
# Add multiple movies
304
movies_to_sync = [
305
    plex.library.section('Movies').get('Inception'),
306
    plex.library.section('Movies').get('Interstellar'),
307
    plex.library.section('Movies').get('The Dark Knight')
308
]
309

310
for movie in movies_to_sync:
311
    sync_item = SyncItem.create(
312
        server=plex,
313
        media=movie,
314
        client='iPad',
315
        quality='hd',
316
        videoBitrate=4000
317
    )
318
    sync_list.add(sync_item)
319

320
# Execute all syncs
321
sync_list.sync()
322

323
print(f"Started sync for {len(sync_list)} items")
324
```
325

326
### Sync Quality Management
327

328
```python
329
# High quality sync for home WiFi
330
hq_sync = SyncItem.create(
331
    server=plex,
332
    media=movie,
333
    client='AppleTV',
334
    quality='hd',
335
    videoBitrate=8000,
336
    audioBitrate=320
337
)
338

339
# Mobile quality for cellular usage
340
mobile_sync = SyncItem.create(
341
    server=plex,
342
    media=movie,  
343
    client='iPhone',
344
    quality='mobile',
345
    videoBitrate=1500,
346
    audioBitrate=128
347
)
348

349
# Original quality (no transcoding)
350
original_sync = SyncItem.create(
351
    server=plex,
352
    media=movie,
353
    client='Laptop',
354
    quality='original'
355
)
356
```
357

358
### Sync Status Monitoring
359

360
```python
361
# Get all sync items
362
all_syncs = plex.syncItems()
363

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

366
# Monitor sync status
367
for sync_item in all_syncs:
368
    print(f"\nSync: {sync_item.title}")
369
    print(f"  Status: {sync_item.status}")
370
    print(f"  Items: {sync_item.itemsCount}")
371
    print(f"  Size: {sync_item.totalSize / 1024 / 1024:.1f} MB")
372
    
373
    if sync_item.status == 'error':
374
        print(f"  Error: Check sync configuration")
375
    elif sync_item.status == 'processing':
376
        print(f"  Processing: Transcoding in progress")
377

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

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

386
print(f"Processing: {len(processing_syncs)}, Ready: {len(ready_syncs)}")
387
```
388

389
### MyPlex Account Sync Management
390

391
```python
392
from plexapi.myplex import MyPlexAccount
393

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

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

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

401
# Filter by client
402
mobile_syncs = account.syncItems(client='iPhone')
403
tablet_syncs = account.syncItems(client='iPad')
404

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

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

415
### Sync Cleanup and Management
416

417
```python
418
# Remove completed syncs older than 30 days
419
import datetime
420
from datetime import timedelta
421

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

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

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

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

437
# Remove failed syncs
438
failed_syncs = [s for s in plex.syncItems() if s.status == 'error']
439
for sync_item in failed_syncs:
440
    print(f"Removing failed sync: {sync_item.title}")
441
    sync_item.delete()
442
```
443

444
### Advanced Sync Configuration
445

446
```python
447
# Sync with custom transcoding settings
448
custom_sync = SyncItem.create(
449
    server=plex,
450
    media=movie,
451
    client='Android',
452
    title='Custom Quality Sync',
453
    quality='custom',
454
    
455
    # Video settings
456
    videoBitrate=3000,
457
    videoResolution='720p',
458
    videoCodec='h264',
459
    
460
    # Audio settings  
461
    audioBitrate=192,
462
    audioCodec='aac',
463
    audioChannels=2,
464
    
465
    # Subtitle settings
466
    subtitle='en',
467
    subtitleFormat='srt',
468
    
469
    # Content filtering
470
    unwatched=True,
471
    limit=5
472
)
473

474
# Sync with cellular optimization
475
cellular_sync = SyncItem.create(
476
    server=plex,
477
    media=show,
478
    client='iPhone',
479
    title='Cellular Optimized',
480
    quality='mobile',
481
    videoBitrate=800,  # Very low for cellular
482
    audioBitrate=64,   # Minimal audio bitrate  
483
    videoResolution='480p'
484
)
485
```
486

487
### Sync Progress Tracking
488

489
```python
490
def monitor_sync_progress(sync_item, interval=10):
491
    """Monitor sync progress with periodic updates."""
492
    import time
493
    
494
    print(f"Monitoring sync: {sync_item.title}")
495
    
496
    while sync_item.status in ['created', 'processing']:
497
        sync_item.reload()
498
        
499
        if hasattr(sync_item, 'progress'):
500
            progress = getattr(sync_item, 'progress', 0)
501
            print(f"Progress: {progress}% - Status: {sync_item.status}")
502
        else:
503
            print(f"Status: {sync_item.status}")
504
            
505
        time.sleep(interval)
506
    
507
    print(f"Final status: {sync_item.status}")
508
    
509
    if sync_item.status == 'ready':
510
        print(f"Sync completed! Size: {sync_item.totalSize / 1024 / 1024:.1f} MB")
511
    elif sync_item.status == 'error':
512
        print("Sync failed - check server logs for details")
513

514
# Usage
515
sync_item = SyncItem.create(plex, movie, 'iPhone', quality='hd')
516
monitor_sync_progress(sync_item, interval=5)
517
```
518

519
### Playlist Sync Integration
520

521
```python
522
# Sync playlists to mobile devices
523
music_playlist = plex.playlist('Workout Mix')
524
video_playlist = plex.playlist('Action Movies')
525

526
# Sync audio playlist
527
music_sync = music_playlist.sync(
528
    client='iPhone',
529
    quality='mobile',
530
    audioBitrate=192
531
)
532

533
# Sync video playlist with custom settings
534
video_sync = video_playlist.sync(
535
    client='iPad',
536
    quality='hd',
537
    videoBitrate=4000,
538
    limit=10  # Only sync first 10 movies
539
)
540

541
print(f"Music playlist sync: {music_sync.status}")
542
print(f"Video playlist sync: {video_sync.status}")
543
```
544

545
## Sync Requirements
546

547
Mobile sync functionality requires:
548

549
1. **Server Configuration**: Sync must be enabled on the Plex Media Server
550
2. **Client Support**: Target client must support offline sync  
551
3. **Storage Space**: Sufficient storage on both server and client devices
552
4. **Processing Power**: Server needs transcoding capability for quality conversion
553
5. **Network Bandwidth**: Adequate bandwidth for initial sync transfers
554

555
## Common Sync Use Cases
556

557
- **Travel Preparation**: Sync movies and shows before trips
558
- **Mobile Data Management**: Lower quality syncs for cellular usage
559
- **Offline Access**: Sync content for areas with poor connectivity
560
- **Device Optimization**: Different quality settings per device type
561
- **Content Curation**: Sync curated playlists and collections
562
- **Bandwidth Management**: Pre-sync during off-peak hours