0
# Media Lists and Playlists
1

2
Media list management for creating and controlling playlists with sequential or custom playback modes. These classes enable building media applications with playlist functionality and batch media operations.
3

4
## Capabilities
5

6
### Media List Management
7

8
The MediaList class provides comprehensive media collection management with adding, removing, and accessing media items.
9

10
```python { .api }
11
class MediaList:
12
    def __init__(self, instance=None):
13
        """Create a new media list.
14
        
15
        Args:
16
            instance (Instance, optional): VLC instance to use
17
        """
18
        ...
19
    
20
    def get_instance(self):
21
        """Get the instance associated with this media list.
22
        
23
        Returns:
24
            Instance: The LibVLC instance
25
        """
26
        ...
27
    
28
    def add_media(self, media):
29
        """Add a media item to the list.
30
        
31
        Args:
32
            media (Media): Media object to add
33
            
34
        Returns:
35
            int: 0 on success, -1 on error
36
        """
37
        ...
38
    
39
    def insert_media(self, media, index):
40
        """Insert a media item at a specific position.
41
        
42
        Args:
43
            media (Media): Media object to insert
44
            index (int): Position to insert at
45
            
46
        Returns:
47
            int: 0 on success, -1 on error
48
        """
49
        ...
50
    
51
    def remove_index(self, index):
52
        """Remove a media item at a specific position.
53
        
54
        Args:
55
            index (int): Position of item to remove
56
            
57
        Returns:
58
            int: 0 on success, -1 on error
59
        """
60
        ...
61
    
62
    def count(self):
63
        """Get the number of items in the media list.
64
        
65
        Returns:
66
            int: Number of media items
67
        """
68
        ...
69
    
70
    def item_at_index(self, index):
71
        """Get the media item at a specific position.
72
        
73
        Args:
74
            index (int): Position of item to retrieve
75
            
76
        Returns:
77
            Media: Media object at position, or None if invalid index
78
        """
79
        ...
80
    
81
    def index_of_item(self, media):
82
        """Get the index of a specific media item.
83
        
84
        Args:
85
            media (Media): Media object to find
86
            
87
        Returns:
88
            int: Index of media item, or -1 if not found
89
        """
90
        ...
91
    
92
    def is_readonly(self):
93
        """Check if the media list is read-only.
94
        
95
        Returns:
96
            bool: True if read-only, False otherwise
97
        """
98
        ...
99
    
100
    def lock(self):
101
        """Lock the media list for thread-safe access."""
102
        ...
103
    
104
    def unlock(self):
105
        """Unlock the media list."""
106
        ...
107
    
108
    def event_manager(self):
109
        """Get the event manager for this media list.
110
        
111
        Returns:
112
            EventManager: Event manager for this media list
113
        """
114
        ...
115
    
116
    def release(self):
117
        """Release the media list."""
118
        ...
119
```
120

121
### Media List Player Control
122

123
The MediaListPlayer class provides playlist playback control with navigation and playback mode management.
124

125
```python { .api }
126
class MediaListPlayer:
127
    def __init__(self, instance=None):
128
        """Create a new media list player.
129
        
130
        Args:
131
            instance (Instance, optional): VLC instance to use
132
        """
133
        ...
134
    
135
    def get_instance(self):
136
        """Get the instance associated with this media list player.
137
        
138
        Returns:
139
            Instance: The LibVLC instance
140
        """
141
        ...
142
    
143
    def release(self):
144
        """Release the media list player."""
145
        ...
146
    
147
    def event_manager(self):
148
        """Get the event manager for this media list player.
149
        
150
        Returns:
151
            EventManager: Event manager for this media list player
152
        """
153
        ...
154
    
155
    def set_media_player(self, media_player):
156
        """Set the media player to use for playback.
157
        
158
        Args:
159
            media_player (MediaPlayer): Media player instance
160
        """
161
        ...
162
    
163
    def get_media_player(self):
164
        """Get the current media player.
165
        
166
        Returns:
167
            MediaPlayer: Current media player or None
168
        """
169
        ...
170
    
171
    def set_media_list(self, media_list):
172
        """Set the media list to play.
173
        
174
        Args:
175
            media_list (MediaList): Media list to play
176
        """
177
        ...
178
    
179
    def play(self):
180
        """Start or resume playback of the media list.
181
        
182
        Returns:
183
            int: 0 on success, -1 on error
184
        """
185
        ...
186
    
187
    def pause(self):
188
        """Pause playback of the media list."""
189
        ...
190
    
191
    def stop(self):
192
        """Stop playback of the media list."""
193
        ...
194
    
195
    def next(self):
196
        """Play the next item in the media list.
197
        
198
        Returns:
199
            int: 0 on success, -1 on error
200
        """
201
        ...
202
    
203
    def previous(self):
204
        """Play the previous item in the media list.
205
        
206
        Returns:
207
            int: 0 on success, -1 on error
208
        """
209
        ...
210
    
211
    def set_playback_mode(self, mode):
212
        """Set the playback mode.
213
        
214
        Args:
215
            mode (PlaybackMode): Playback mode to set
216
        """
217
        ...
218
    
219
    def get_state(self):
220
        """Get the current player state.
221
        
222
        Returns:
223
            State: Current player state
224
        """
225
        ...
226
    
227
    def play_item_at_index(self, index):
228
        """Play a specific item in the media list.
229
        
230
        Args:
231
            index (int): Index of item to play
232
            
233
        Returns:
234
            int: 0 on success, -1 on error
235
        """
236
        ...
237
    
238
    def play_item(self, media):
239
        """Play a specific media item in the media list.
240
        
241
        Args:
242
            media (Media): Media item to play
243
            
244
        Returns:
245
            int: 0 on success, -1 on error
246
        """
247
        ...
248
    
249
    def get_media_player(self):
250
        """Get the media player used by this list player.
251
        
252
        Returns:
253
            MediaPlayer: The media player instance
254
        """
255
        ...
256
```
257

258
### Playback Modes
259

260
Enumeration for media list playback modes.
261

262
```python { .api }
263
class PlaybackMode:
264
    """Media list playback modes."""
265
    Default = 0
266
    Loop = 1
267
    Repeat = 2
268
```
269

270
### Media List Events
271

272
Event types specific to media list operations.
273

274
```python { .api }
275
class MediaListEventType:
276
    """Media list event types."""
277
    MediaListItemAdded = 0x200
278
    MediaListWillAddItem = 0x201
279
    MediaListItemDeleted = 0x202
280
    MediaListWillDeleteItem = 0x203
281
    MediaListEndReached = 0x204
282
```
283

284
### Media List Player Events
285

286
Event types specific to media list player operations.
287

288
```python { .api }
289
class MediaListPlayerEventType:
290
    """Media list player event types."""
291
    MediaListPlayerPlayed = 0x400
292
    MediaListPlayerNextItemSet = 0x401
293
    MediaListPlayerStopped = 0x402
294
```
295

296
## Usage Examples
297

298
### Basic Playlist Creation
299

300
```python
301
import vlc
302

303
# Create instance and media list
304
instance = vlc.Instance()
305
media_list = instance.media_list_new()
306

307
# Add media files to the list
308
media1 = instance.media_new('/path/to/song1.mp3')
309
media2 = instance.media_new('/path/to/song2.mp3')
310
media3 = instance.media_new('/path/to/song3.mp3')
311

312
media_list.add_media(media1)
313
media_list.add_media(media2)  
314
media_list.add_media(media3)
315

316
print(f"Playlist has {media_list.count()} items")
317

318
# Get item at specific position
319
first_item = media_list.item_at_index(0)
320
if first_item:
321
    print(f"First item: {first_item.get_mrl()}")
322
```
323

324
### Media List Player with Navigation
325

326
```python
327
import vlc
328
import time
329

330
# Create media list and populate it
331
instance = vlc.Instance()
332
media_list = instance.media_list_new()
333

334
songs = ['/path/to/song1.mp3', '/path/to/song2.mp3', '/path/to/song3.mp3']
335
for song_path in songs:
336
    media = instance.media_new(song_path)
337
    media_list.add_media(media)
338

339
# Create media list player
340
list_player = instance.media_list_player_new()
341
list_player.set_media_list(media_list)
342

343
# Start playback
344
list_player.play()
345
print("Playing playlist...")
346

347
# Wait a bit, then navigate
348
time.sleep(5)
349

350
# Skip to next song
351
print("Skipping to next...")
352
list_player.next()
353

354
time.sleep(5)
355

356
# Go back to previous song
357
print("Going to previous...")
358
list_player.previous()
359

360
time.sleep(5)
361

362
# Play specific item by index
363
print("Playing item at index 2...")
364
list_player.play_item_at_index(2)
365
```
366

367
### Playlist Management Operations
368

369
```python
370
import vlc
371

372
instance = vlc.Instance()
373
media_list = instance.media_list_new()
374

375
# Add multiple media files
376
media_files = [
377
    '/path/to/video1.mp4',
378
    '/path/to/video2.mp4', 
379
    '/path/to/video3.mp4'
380
]
381

382
for file_path in media_files:
383
    media = instance.media_new(file_path)
384
    media_list.add_media(media)
385

386
print(f"Initial count: {media_list.count()}")
387

388
# Insert media at specific position
389
new_media = instance.media_new('/path/to/inserted_video.mp4')
390
media_list.insert_media(new_media, 1)  # Insert at position 1
391
print(f"After insert: {media_list.count()}")
392

393
# Remove media at specific position
394
media_list.remove_index(2)  # Remove item at position 2
395
print(f"After removal: {media_list.count()}")
396

397
# List all items in the playlist
398
print("Current playlist:")
399
for i in range(media_list.count()):
400
    item = media_list.item_at_index(i)
401
    if item:
402
        print(f"  {i}: {item.get_mrl()}")
403

404
# Find index of specific media
405
search_media = media_list.item_at_index(0)
406
if search_media:
407
    index = media_list.index_of_item(search_media)
408
    print(f"First item is at index: {index}")
409
```
410

411
### Playback Modes
412

413
```python
414
import vlc
415

416
instance = vlc.Instance()
417
media_list = instance.media_list_new()
418

419
# Add some media
420
for i in range(3):
421
    media = instance.media_new(f'/path/to/song{i+1}.mp3')
422
    media_list.add_media(media)
423

424
# Create list player
425
list_player = instance.media_list_player_new()
426
list_player.set_media_list(media_list)
427

428
# Set different playback modes
429
print("Setting loop mode...")
430
list_player.set_playback_mode(vlc.PlaybackMode.Loop)
431
list_player.play()
432

433
# The playlist will now loop continuously
434
# Change to repeat mode (repeat current item)
435
# list_player.set_playback_mode(vlc.PlaybackMode.Repeat)
436

437
# Change to default mode (play once through)
438
# list_player.set_playback_mode(vlc.PlaybackMode.Default)
439
```
440

441
### Media List Events
442

443
```python
444
import vlc
445
import time
446

447
def on_item_added(event):
448
    print(f"Item added to media list")
449

450
def on_item_deleted(event):
451
    print(f"Item deleted from media list")
452

453
def on_list_ended(event):
454
    print("Reached end of media list")
455

456
def on_next_item_set(event):
457
    print("Next item set in playlist")
458

459
def on_list_player_stopped(event):
460
    print("Media list player stopped")
461

462
# Create media list with event handling
463
instance = vlc.Instance()
464
media_list = instance.media_list_new()
465

466
# Attach media list events
467
list_em = media_list.event_manager()
468
list_em.event_attach(vlc.EventType.MediaListItemAdded, on_item_added)
469
list_em.event_attach(vlc.EventType.MediaListItemDeleted, on_item_deleted)
470
list_em.event_attach(vlc.EventType.MediaListEndReached, on_list_ended)
471

472
# Create list player with events
473
list_player = instance.media_list_player_new()
474
list_player.set_media_list(media_list)
475

476
# Attach list player events
477
player_em = list_player.event_manager()
478
player_em.event_attach(vlc.EventType.MediaListPlayerNextItemSet, on_next_item_set)
479
player_em.event_attach(vlc.EventType.MediaListPlayerStopped, on_list_player_stopped)
480

481
# Add media (triggers event)
482
media = instance.media_new('/path/to/song.mp3')
483
media_list.add_media(media)
484

485
# Start playback
486
list_player.play()
487
time.sleep(10)
488

489
# Remove media (triggers event)
490
media_list.remove_index(0)
491

492
# Stop playback (triggers event)
493
list_player.stop()
494
```
495

496
### Thread-Safe Media List Operations
497

498
```python
499
import vlc
500
import threading
501
import time
502

503
def worker_thread(media_list, instance):
504
    """Worker thread that modifies the media list"""
505
    for i in range(5):
506
        media_list.lock()  # Lock for thread safety
507
        try:
508
            media = instance.media_new(f'/path/to/file{i}.mp3')
509
            media_list.add_media(media)
510
            print(f"Added media {i}")
511
        finally:
512
            media_list.unlock()  # Always unlock
513
        time.sleep(1)
514

515
# Create media list
516
instance = vlc.Instance()
517
media_list = instance.media_list_new()
518

519
# Start worker thread
520
thread = threading.Thread(target=worker_thread, args=(media_list, instance))
521
thread.start()
522

523
# Main thread can safely read the list
524
while thread.is_alive():
525
    media_list.lock()
526
    try:
527
        count = media_list.count()
528
        print(f"Current count: {count}")
529
    finally:
530
        media_list.unlock()
531
    time.sleep(0.5)
532

533
thread.join()
534
print(f"Final count: {media_list.count()}")
535
```