0
# Playlist and Media Loading
1

2
Comprehensive playlist management, file loading with options, and track selection for audio, video, and subtitle tracks. Supports local files, URLs, streaming sources, and advanced track management.
3

4
## Capabilities
5

6
### File Loading
7

8
Load individual media files with various modes and options.
9

10
```python { .api }
11
def loadfile(self, filename: str, mode: str = 'replace', index: int = None, **options):
12
    """
13
    Load a media file into the player.
14

15
    Parameters:
16
    - filename: Path to file or URL to load
17
    - mode: Loading mode ('replace', 'append', 'append-play')
18
    - index: Playlist position for insertion (for append modes)
19
    - options: Additional options as key-value pairs
20

21
    Loading modes:
22
    - 'replace': Replace current playlist with this file
23
    - 'append': Add to end of playlist
24
    - 'append-play': Add to playlist and play immediately
25
    """
26

27
def loadlist(self, playlist: str, mode: str = 'replace'):
28
    """
29
    Load a playlist file.
30

31
    Parameters:
32
    - playlist: Path to playlist file (.m3u, .pls, etc.)
33
    - mode: Loading mode ('replace', 'append', 'append-play')
34
    """
35
```
36

37
### Playlist Management
38

39
Complete playlist control including navigation, modification, and organization.
40

41
```python { .api }
42
def playlist_append(self, filename: str, **options):
43
    """
44
    Append a file to the current playlist.
45

46
    Parameters:
47
    - filename: File path or URL to append
48
    - options: File-specific options
49
    """
50

51
def playlist_next(self, mode: str = 'weak'):
52
    """
53
    Move to next playlist entry.
54

55
    Parameters:
56
    - mode: Transition mode ('weak', 'force')
57
           'weak': Only if current file is not playing
58
           'force': Always move to next entry
59
    """
60

61
def playlist_prev(self, mode: str = 'weak'):
62
    """
63
    Move to previous playlist entry.
64

65
    Parameters:
66
    - mode: Transition mode ('weak', 'force')
67
    """
68

69
def playlist_play_index(self, idx: int):
70
    """
71
    Play playlist entry at specific index.
72

73
    Parameters:
74
    - idx: Playlist index (0-based)
75
    """
76

77
def playlist_clear(self):
78
    """Clear the entire playlist."""
79

80
def playlist_remove(self, index: str = 'current'):
81
    """
82
    Remove entry from playlist.
83

84
    Parameters:
85
    - index: Index to remove ('current' or numeric index)
86
    """
87

88
def playlist_move(self, index1: int, index2: int):
89
    """
90
    Move playlist entry from one position to another.
91

92
    Parameters:
93
    - index1: Source index
94
    - index2: Destination index
95
    """
96

97
def playlist_shuffle(self):
98
    """Shuffle the playlist randomly."""
99

100
def playlist_unshuffle(self):
101
    """Restore original playlist order."""
102

103
@property
104
def playlist_filenames(self) -> list:
105
    """List of filenames in the current playlist."""
106
```
107

108
### Audio Track Management
109

110
Add, remove, and control audio tracks during playback.
111

112
```python { .api }
113
def audio_add(self, url: str, flags: str = 'select', title: str = None, lang: str = None):
114
    """
115
    Add an audio track.
116

117
    Parameters:
118
    - url: Path or URL to audio file
119
    - flags: Selection flags ('select', 'auto', 'cached')
120
    - title: Custom track title
121
    - lang: Language code for the track
122
    """
123

124
def audio_remove(self, audio_id: int = None):
125
    """
126
    Remove an audio track.
127

128
    Parameters:
129
    - audio_id: Track ID to remove (None for current)
130
    """
131

132
def audio_reload(self, audio_id: int = None):
133
    """
134
    Reload an audio track.
135

136
    Parameters:
137
    - audio_id: Track ID to reload (None for current)
138
    """
139
```
140

141
### Video Track Management
142

143
Add, remove, and control video tracks including album art.
144

145
```python { .api }
146
def video_add(self, url: str, flags: str = 'select', title: str = None, lang: str = None, albumart: bool = None):
147
    """
148
    Add a video track.
149

150
    Parameters:
151
    - url: Path or URL to video file
152
    - flags: Selection flags ('select', 'auto', 'cached')
153
    - title: Custom track title
154
    - lang: Language code for the track
155
    - albumart: Whether track is album art
156
    """
157

158
def video_remove(self, video_id: int = None):
159
    """
160
    Remove a video track.
161

162
    Parameters:
163
    - video_id: Track ID to remove (None for current)
164
    """
165

166
def video_reload(self, video_id: int = None):
167
    """
168
    Reload a video track.
169

170
    Parameters:
171
    - video_id: Track ID to reload (None for current)
172
    """
173
```
174

175
### Subtitle Management
176

177
Comprehensive subtitle track control including timing and positioning.
178

179
```python { .api }
180
def sub_add(self, url: str, flags: str = 'select', title: str = None, lang: str = None):
181
    """
182
    Add a subtitle track.
183

184
    Parameters:
185
    - url: Path or URL to subtitle file
186
    - flags: Selection flags ('select', 'auto', 'cached')
187
    - title: Custom track title
188
    - lang: Language code for the track
189
    """
190

191
def sub_remove(self, sub_id: int = None):
192
    """
193
    Remove a subtitle track.
194

195
    Parameters:
196
    - sub_id: Track ID to remove (None for current)
197
    """
198

199
def sub_reload(self, sub_id: int = None):
200
    """
201
    Reload a subtitle track.
202

203
    Parameters:
204
    - sub_id: Track ID to reload (None for current)
205
    """
206

207
def sub_step(self, skip: int):
208
    """
209
    Step through subtitle entries.
210

211
    Parameters:
212
    - skip: Number of subtitle entries to skip (positive or negative)
213
    """
214

215
def sub_seek(self, skip: int):
216
    """
217
    Seek to next/previous subtitle.
218

219
    Parameters:
220
    - skip: Direction and count (1 for next, -1 for previous)
221
    """
222
```
223

224
## Playlist Properties
225

226
```python { .api }
227
# Playlist information
228
playlist_count: int          # Number of entries in playlist
229
playlist_pos: int           # Current playlist position (0-based)
230
playlist_pos_1: int         # Current playlist position (1-based)
231

232
# Playlist behavior
233
loop_playlist: str          # Playlist looping ('no', 'inf', 'force')
234
shuffle: bool              # Playlist shuffle state
235

236
# Track information
237
track_list: list           # List of all available tracks
238
audio_id: int             # Current audio track ID
239
video_id: int             # Current video track ID
240
sub_id: int               # Current subtitle track ID
241
```
242

243
## Usage Examples
244

245
### Basic Playlist Operations
246

247
```python
248
import mpv
249

250
player = mpv.MPV()
251

252
# Load single file
253
player.loadfile('/path/to/video1.mp4')
254

255
# Append files to playlist
256
player.playlist_append('/path/to/video2.mp4')
257
player.playlist_append('/path/to/video3.mp4')
258

259
# Load entire playlist file
260
player.loadlist('/path/to/playlist.m3u')
261

262
# Navigate playlist
263
player.playlist_next()      # Next video
264
player.playlist_prev()      # Previous video
265
player.playlist_play_index(0)  # Jump to first video
266

267
# Playlist information
268
print(f"Playlist has {player.playlist_count} entries")
269
print(f"Currently playing: {player.playlist_pos}")
270
print(f"Files: {player.playlist_filenames}")
271
```
272

273
### Advanced File Loading
274

275
```python
276
# Load with specific options
277
player.loadfile('/path/to/video.mp4', 
278
                start=30,           # Start at 30 seconds
279
                end=120,            # Stop at 2 minutes
280
                volume=75,          # Set volume
281
                loop_file='inf')    # Loop this file
282

283
# Load and append with play
284
player.loadfile('/path/to/first.mp4', mode='replace')
285
player.loadfile('/path/to/second.mp4', mode='append-play')
286

287
# Insert at specific position
288
player.loadfile('/path/to/insert.mp4', mode='append', index=1)
289
```
290

291
### Track Management
292

293
```python
294
# Add external audio track
295
player.audio_add('/path/to/commentary.mp3', 
296
                 title='Director Commentary',
297
                 lang='en')
298

299
# Add subtitle file
300
player.sub_add('/path/to/subtitles.srt',
301
               title='English Subtitles',
302
               lang='en')
303

304
# Add video track (for videos with multiple angles)
305
player.video_add('/path/to/angle2.mp4',
306
                 title='Camera Angle 2')
307

308
# Get track information
309
tracks = player.track_list
310
for track in tracks:
311
    print(f"Track {track['id']}: {track['type']} - {track.get('title', 'Untitled')}")
312

313
# Switch tracks
314
player.audio_id = 2  # Switch to audio track 2
315
player.sub_id = 1    # Switch to subtitle track 1
316
```
317

318
### Playlist Manipulation
319

320
```python
321
# Create and manage playlist
322
files = [
323
    '/path/to/episode1.mp4',
324
    '/path/to/episode2.mp4', 
325
    '/path/to/episode3.mp4'
326
]
327

328
# Add all files
329
for i, file in enumerate(files):
330
    if i == 0:
331
        player.loadfile(file, mode='replace')
332
    else:
333
        player.playlist_append(file)
334

335
# Shuffle and loop
336
player.shuffle = True
337
player.loop_playlist = 'inf'
338

339
# Remove specific entries
340
player.playlist_remove(1)  # Remove second entry
341
player.playlist_remove('current')  # Remove current entry
342

343
# Reorder playlist
344
player.playlist_move(0, 2)  # Move first to third position
345
```
346

347
### Streaming and URLs
348

349
```python
350
# Stream from URL
351
player.play('https://example.com/stream.m3u8')
352

353
# YouTube with youtube-dl integration (if available)
354
player.play('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
355

356
# Add external tracks for streams
357
player.sub_add('https://example.com/subtitles.vtt')
358
player.audio_add('https://example.com/alternate_audio.mp3')
359

360
# Radio streams
361
player.play('http://stream.example.com:8000/radio')
362
```
363

364
### Subtitle Control
365

366
```python
367
# Add and configure subtitles
368
player.sub_add('/path/to/subtitles.srt')
369

370
# Subtitle timing and appearance
371
player.sub_delay = 0.5      # Delay by 500ms
372
player.sub_scale = 1.2      # Increase size by 20%
373
player.sub_pos = 90         # Position at 90% from top
374

375
# Navigate through subtitles
376
player.sub_step(1)          # Next subtitle
377
player.sub_step(-1)         # Previous subtitle
378
player.sub_seek(1)          # Seek to next subtitle timing
379

380
# Toggle subtitle visibility
381
player.sub_visibility = False
382
```
383

384
### Playlist Events and Monitoring
385

386
```python
387
# Monitor playlist changes
388
@player.property_observer('playlist-pos')
389
def playlist_changed(name, value):
390
    if value is not None:
391
        current_file = player.playlist_filenames[value]
392
        print(f"Now playing: {current_file}")
393

394
@player.property_observer('playlist-count')
395
def playlist_size_changed(name, value):
396
    print(f"Playlist now has {value} entries")
397

398
# Handle end of playlist
399
@player.event_callback('end-file')
400
def handle_file_end(event):
401
    if player.playlist_pos == player.playlist_count - 1:
402
        print("Reached end of playlist")
403

404
# Auto-play next with custom logic
405
@player.event_callback('end-file')
406
def auto_advance(event):
407
    if event.data == mpv.MpvEventEndFile.EOF:
408
        if player.playlist_pos < player.playlist_count - 1:
409
            player.playlist_next('force')
410
        else:
411
            print("Playlist completed")
412
```
413

414
### Complex Playlist Scenarios
415

416
```python
417
# Multi-format playlist with options
418
playlist_items = [
419
    ('/path/to/intro.mp4', {'volume': 100}),
420
    ('/path/to/main.mkv', {'audio-delay': 0.2}),
421
    ('/path/to/credits.mp4', {'speed': 1.5})
422
]
423

424
# Load with per-file options
425
for i, (filename, options) in enumerate(playlist_items):
426
    if i == 0:
427
        player.loadfile(filename, **options)
428
    else:
429
        player.playlist_append(filename, **options)
430

431
# Dynamic playlist modification
432
def add_related_content():
433
    current_file = player.filename
434
    if 'episode' in current_file:
435
        # Add next episode automatically
436
        next_episode = current_file.replace('episode1', 'episode2')
437
        if os.path.exists(next_episode):
438
            player.playlist_append(next_episode)
439

440
# Monitor for automatic playlist expansion
441
@player.property_observer('playlist-pos')
442
def auto_expand_playlist(name, value):
443
    if value == player.playlist_count - 2:  # Near end of playlist
444
        add_related_content()
445
```