0
# Playlists & Collections
1
2
Create and manage playlists and collections, organize media content, and control playback queues for seamless media experiences.
3
4
## Capabilities
5
6
### Playlist Management
7
8
Create, manage, and share playlists for organizing media content.
9
10
```python { .api }
11
class Playlist:
12
"""User-created or smart playlist for organizing media."""
13
14
@property
15
def title(self):
16
"""str: Playlist title."""
17
18
@property
19
def smart(self):
20
"""bool: Whether this is a smart playlist."""
21
22
@property
23
def playlistType(self):
24
"""str: Playlist type ('audio', 'video', 'photo')."""
25
26
def items(self):
27
"""
28
Get playlist items.
29
30
Returns:
31
list: List of media objects in playlist
32
"""
33
34
def addItems(self, items):
35
"""
36
Add items to playlist.
37
38
Args:
39
items (list or single item): Media items to add
40
"""
41
42
def removeItems(self, items):
43
"""
44
Remove items from playlist.
45
46
Args:
47
items (list or single item): Media items to remove
48
"""
49
50
def copyToUser(self, user):
51
"""
52
Share playlist with user.
53
54
Args:
55
user (str or MyPlexUser): User to share with
56
"""
57
58
def edit(self, **kwargs):
59
"""
60
Edit playlist metadata.
61
62
Args:
63
**kwargs: Playlist properties to update
64
- title (str): New playlist title
65
- summary (str): Playlist description
66
"""
67
68
def delete(self):
69
"""Delete this playlist."""
70
71
def play(self, client=None):
72
"""
73
Play playlist on client.
74
75
Args:
76
client (PlexClient, optional): Client to play on
77
"""
78
79
def moveItem(self, item, after):
80
"""
81
Reorder playlist by moving item to new position.
82
83
Args:
84
item: Playlist item to move
85
after: Item to place the moved item after (None for beginning)
86
"""
87
88
def updateFilters(self, **kwargs):
89
"""
90
Update smart playlist filters and criteria.
91
92
Args:
93
**kwargs: Filter parameters for smart playlist
94
- sort (str): Sort field and direction
95
- filters (dict): Filter criteria
96
- limit (int): Maximum number of items
97
"""
98
99
def sync(self, client, **kwargs):
100
"""
101
Add playlist to mobile sync queue.
102
103
Args:
104
client (PlexClient or str): Target sync client
105
**kwargs: Sync options
106
- quality (str): Sync quality setting
107
- videoQuality (int): Video quality level
108
- audioQuality (int): Audio quality level
109
"""
110
```
111
112
### Collection Management
113
114
Create and manage collections for grouping related media.
115
116
```python { .api }
117
class Collection:
118
"""Media collection for grouping related content."""
119
120
@property
121
def title(self):
122
"""str: Collection title."""
123
124
@property
125
def smart(self):
126
"""bool: Whether this is a smart collection."""
127
128
@property
129
def collectionSort(self):
130
"""int: Collection sort order."""
131
132
def items(self):
133
"""
134
Get collection items.
135
136
Returns:
137
list: List of media objects in collection
138
"""
139
140
def addItems(self, items):
141
"""
142
Add items to collection.
143
144
Args:
145
items (list or single item): Media items to add
146
"""
147
148
def removeItems(self, items):
149
"""
150
Remove items from collection.
151
152
Args:
153
items (list or single item): Media items to remove
154
"""
155
156
def edit(self, **kwargs):
157
"""
158
Edit collection metadata.
159
160
Args:
161
**kwargs: Collection properties to update
162
- title (str): New collection title
163
- summary (str): Collection description
164
- contentRating (str): Content rating
165
"""
166
167
def delete(self):
168
"""Delete this collection."""
169
170
def moveItem(self, item, after):
171
"""
172
Reorder collection by moving item to new position.
173
174
Args:
175
item: Collection item to move
176
after: Item to place the moved item after (None for beginning)
177
"""
178
179
def updateFilters(self, **kwargs):
180
"""
181
Update smart collection filters and criteria.
182
183
Args:
184
**kwargs: Filter parameters for smart collection
185
- sort (str): Sort field and direction
186
- filters (dict): Filter criteria
187
"""
188
189
def mode(self, mode):
190
"""
191
Set collection display mode.
192
193
Args:
194
mode (str): Collection display mode ('default', 'hide', 'hideItems', 'showItems')
195
"""
196
197
def sort(self, field, **params):
198
"""
199
Set collection sort order.
200
201
Args:
202
field (str): Sort field ('titleSort', 'year', 'rating', etc.)
203
**params: Additional sort parameters
204
- descending (bool): Sort in descending order
205
"""
206
```
207
208
### Play Queue Management
209
210
Control dynamic playback queues for seamless media playback.
211
212
```python { .api }
213
class PlayQueue:
214
"""Dynamic playback queue for controlling playback order."""
215
216
@property
217
def playQueueID(self):
218
"""int: Unique play queue identifier."""
219
220
@property
221
def selectedItem(self):
222
"""Media object: Currently selected item."""
223
224
def items(self):
225
"""
226
Get queue items.
227
228
Returns:
229
list: List of media objects in queue
230
"""
231
232
def addItem(self, item, playNext=False):
233
"""
234
Add item to queue.
235
236
Args:
237
item: Media item to add
238
playNext (bool): Add as next item vs end of queue
239
"""
240
241
def removeItem(self, item):
242
"""
243
Remove item from queue.
244
245
Args:
246
item: Media item to remove
247
"""
248
249
def clear(self):
250
"""Clear entire queue."""
251
```
252
253
### Server Playlist Creation
254
255
Create playlists and collections at the server level.
256
257
```python { .api }
258
# Via PlexServer
259
class PlexServer:
260
def createPlaylist(self, title, section=None, items=None, smart=False, **kwargs):
261
"""
262
Create server playlist.
263
264
Args:
265
title (str): Playlist title
266
section (LibrarySection, optional): Section for smart playlists
267
items (list, optional): Initial items for regular playlists
268
smart (bool): Create smart playlist vs regular playlist
269
**kwargs: Additional playlist properties
270
- summary (str): Playlist description
271
- playlistType (str): Media type ('audio', 'video', 'photo')
272
273
Returns:
274
Playlist: Created playlist object
275
"""
276
277
def createCollection(self, title, section, items=None, smart=False, **kwargs):
278
"""
279
Create server collection.
280
281
Args:
282
title (str): Collection title
283
section (LibrarySection): Target library section
284
items (list, optional): Initial collection items
285
smart (bool): Create smart collection vs regular collection
286
**kwargs: Additional collection properties
287
- summary (str): Collection description
288
- contentRating (str): Content rating
289
290
Returns:
291
Collection: Created collection object
292
"""
293
294
def createPlayQueue(self, item, **kwargs):
295
"""
296
Create playback queue.
297
298
Args:
299
item: Media item to start queue with
300
**kwargs: Additional queue parameters
301
- shuffle (bool): Shuffle queue
302
- repeat (int): Repeat mode
303
- includeChapters (bool): Include chapter markers
304
305
Returns:
306
PlayQueue: Created play queue object
307
"""
308
```
309
310
## Usage Examples
311
312
### Basic Playlist Operations
313
314
```python
315
from plexapi.server import PlexServer
316
317
plex = PlexServer('http://localhost:32400', token='your-token')
318
319
# Get existing playlists
320
playlists = plex.playlists()
321
for playlist in playlists:
322
print(f"Playlist: {playlist.title} ({len(playlist.items())} items)")
323
324
# Get specific playlist
325
my_playlist = next(p for p in playlists if p.title == 'My Favorites')
326
327
# View playlist items
328
items = my_playlist.items()
329
for item in items:
330
print(f"- {item.title}")
331
```
332
333
### Creating Playlists
334
335
```python
336
# Create regular playlist with specific items
337
movies = plex.library.section('Movies')
338
action_movies = [
339
movies.get('Die Hard'),
340
movies.get('The Matrix'),
341
movies.get('John Wick')
342
]
343
344
action_playlist = plex.createPlaylist(
345
title='Action Favorites',
346
items=action_movies,
347
summary='My favorite action movies'
348
)
349
350
# Create music playlist
351
music = plex.library.section('Music')
352
rock_tracks = music.search(genre='Rock', libtype='track')[:20]
353
354
rock_playlist = plex.createPlaylist(
355
title='Rock Hits',
356
items=rock_tracks,
357
playlistType='audio'
358
)
359
```
360
361
### Smart Playlists
362
363
```python
364
# Create smart movie playlist
365
movie_section = plex.library.section('Movies')
366
367
# Smart playlist for highly rated recent movies
368
recent_hits = plex.createPlaylist(
369
title='Recent Hits',
370
section=movie_section,
371
smart=True,
372
summary='Movies from 2020+ with rating > 8.0'
373
# Note: Smart playlist criteria set through web interface
374
)
375
376
# Create smart music playlist
377
music_section = plex.library.section('Music')
378
top_rock = plex.createPlaylist(
379
title='Top Rock',
380
section=music_section,
381
smart=True,
382
playlistType='audio'
383
)
384
```
385
386
### Playlist Management
387
388
```python
389
# Add items to existing playlist
390
new_movies = [
391
movies.get('Avengers: Endgame'),
392
movies.get('Spider-Man: No Way Home')
393
]
394
action_playlist.addItems(new_movies)
395
396
# Remove items from playlist
397
action_playlist.removeItems([movies.get('Die Hard')])
398
399
# Edit playlist metadata
400
action_playlist.edit(
401
title='Ultimate Action Collection',
402
summary='The best action movies ever made'
403
)
404
405
# Share playlist with user
406
action_playlist.copyToUser('friend@example.com')
407
```
408
409
### Collection Operations
410
411
```python
412
# Get existing collections
413
movie_section = plex.library.section('Movies')
414
collections = movie_section.collections()
415
416
for collection in collections:
417
print(f"Collection: {collection.title} ({len(collection.items())} movies)")
418
419
# Create new collection
420
marvel_movies = [
421
movies.get('Iron Man'),
422
movies.get('Captain America: The First Avenger'),
423
movies.get('Thor'),
424
movies.get('The Avengers')
425
]
426
427
marvel_collection = plex.createCollection(
428
title='Marvel Cinematic Universe',
429
section=movie_section,
430
items=marvel_movies,
431
summary='Marvel superhero movies'
432
)
433
434
# Add more movies to collection
435
phase_2_movies = [
436
movies.get('Iron Man 3'),
437
movies.get('Thor: The Dark World'),
438
movies.get('Captain America: The Winter Soldier')
439
]
440
marvel_collection.addItems(phase_2_movies)
441
```
442
443
### Smart Collections
444
445
```python
446
# Create smart collection for a director
447
movie_section = plex.library.section('Movies')
448
449
nolan_collection = plex.createCollection(
450
title='Christopher Nolan Films',
451
section=movie_section,
452
smart=True,
453
summary='All movies directed by Christopher Nolan'
454
# Smart collection criteria configured through web interface
455
)
456
457
# Create smart collection for decade
458
eighties_collection = plex.createCollection(
459
title='80s Movies',
460
section=movie_section,
461
smart=True,
462
summary='Movies from the 1980s'
463
)
464
```
465
466
### Play Queue Management
467
468
```python
469
# Create play queue from album
470
music = plex.library.section('Music')
471
album = music.get('Abbey Road')
472
473
queue = plex.createPlayQueue(
474
album,
475
shuffle=False,
476
repeat=0
477
)
478
479
print(f"Queue has {len(queue.items())} tracks")
480
481
# Add more items to queue
482
another_album = music.get('Dark Side of the Moon')
483
queue.addItem(another_album, playNext=True)
484
485
# Play queue on client
486
client = plex.client('Living Room')
487
client.playMedia(queue.selectedItem)
488
```
489
490
### Advanced Playlist Features
491
492
```python
493
# Create playlist from search results
494
recent_movies = plex.search('', libtype='movie', year__gte=2022)
495
recent_playlist = plex.createPlaylist(
496
title='Recent Releases',
497
items=recent_movies[:50], # Limit to 50 items
498
summary=f'Recently released movies ({len(recent_movies)} total)'
499
)
500
501
# Create themed playlists
502
# Holiday movies
503
holiday_movies = movie_section.search(title='Christmas') + \
504
movie_section.search(title='Holiday')
505
holiday_playlist = plex.createPlaylist(
506
title='Holiday Movies',
507
items=holiday_movies
508
)
509
510
# Workout music
511
upbeat_tracks = music.search(genre=['Pop', 'Rock', 'Electronic'], libtype='track')
512
workout_playlist = plex.createPlaylist(
513
title='Workout Mix',
514
items=upbeat_tracks[:100],
515
playlistType='audio'
516
)
517
```
518
519
### Collection Organization
520
521
```python
522
# Create genre-based collections
523
genres = ['Action', 'Comedy', 'Drama', 'Horror', 'Sci-Fi']
524
525
for genre in genres:
526
genre_movies = movie_section.search(genre=genre)
527
if genre_movies:
528
collection = plex.createCollection(
529
title=f'{genre} Movies',
530
section=movie_section,
531
items=genre_movies[:25], # Limit to 25 per collection
532
summary=f'Best {genre.lower()} movies in the library'
533
)
534
print(f"Created {genre} collection with {len(genre_movies)} movies")
535
536
# Create decade collections
537
decades = [(1980, 1989, '80s'), (1990, 1999, '90s'), (2000, 2009, '2000s')]
538
539
for start_year, end_year, decade_name in decades:
540
decade_movies = []
541
for year in range(start_year, end_year + 1):
542
year_movies = movie_section.search(year=year)
543
decade_movies.extend(year_movies)
544
545
if decade_movies:
546
collection = plex.createCollection(
547
title=f'{decade_name} Movies',
548
section=movie_section,
549
items=decade_movies,
550
summary=f'Movies from the {decade_name}'
551
)
552
```
553
554
### Playlist Playback Control
555
556
```python
557
# Play entire playlist
558
playlist = plex.playlists()[0] # Get first playlist
559
client = plex.client('Living Room TV')
560
561
# Play playlist from beginning
562
playlist.play(client)
563
564
# Create queue from playlist and control playback
565
items = playlist.items()
566
queue = plex.createPlayQueue(items[0])
567
for item in items[1:]:
568
queue.addItem(item)
569
570
# Play queue with custom settings
571
client.playMedia(
572
queue.selectedItem,
573
shuffle=True,
574
repeat=2 # Repeat all
575
)
576
```
577
578
### Maintenance Operations
579
580
```python
581
# Clean up empty playlists
582
playlists = plex.playlists()
583
for playlist in playlists:
584
if len(playlist.items()) == 0:
585
print(f"Deleting empty playlist: {playlist.title}")
586
playlist.delete()
587
588
# Remove duplicate items from playlist
589
playlist = plex.playlists()[0]
590
items = playlist.items()
591
seen_keys = set()
592
duplicates = []
593
594
for item in items:
595
if item.ratingKey in seen_keys:
596
duplicates.append(item)
597
else:
598
seen_keys.add(item.ratingKey)
599
600
if duplicates:
601
print(f"Removing {len(duplicates)} duplicate items")
602
playlist.removeItems(duplicates)
603
604
# Update collection with new matching items
605
collection = plex.library.section('Movies').collections()[0]
606
current_items = set(item.ratingKey for item in collection.items())
607
608
# Find new items that match collection criteria
609
# (This example assumes manual criteria - smart collections update automatically)
610
all_action = movie_section.search(genre='Action')
611
new_items = [item for item in all_action if item.ratingKey not in current_items]
612
613
if new_items:
614
print(f"Adding {len(new_items)} new items to collection")
615
collection.addItems(new_items)
616
```