0
# Core Media Playback
1
2
Essential media playback functionality including media players, media objects, and basic playback control. These classes form the foundation for any media application using Python-VLC.
3
4
## Capabilities
5
6
### Instance Management
7
8
The VLC Instance serves as the main entry point for all LibVLC functionality. It manages the LibVLC environment and creates media players and media objects.
9
10
```python { .api }
11
class Instance:
12
def __init__(self, *args):
13
"""Create a new LibVLC instance.
14
15
Args:
16
*args: Command line arguments (strings) to pass to LibVLC.
17
Common options: '--no-audio', '--quiet', '--intf', 'dummy'
18
"""
19
...
20
21
def media_player_new(self, uri=None):
22
"""Create a new media player from this instance.
23
24
Args:
25
uri (str, optional): Media URI to load immediately
26
27
Returns:
28
MediaPlayer: New media player instance
29
"""
30
...
31
32
def media_new(self, mrl):
33
"""Create a new media object from a media resource locator.
34
35
Args:
36
mrl (str): Media resource locator (URI, file path, etc.)
37
38
Returns:
39
Media: New media object
40
"""
41
...
42
43
def media_new_path(self, path):
44
"""Create a new media object from a file path.
45
46
Args:
47
path (str): File system path to media file
48
49
Returns:
50
Media: New media object
51
"""
52
...
53
54
def media_list_new(self, mrls=None):
55
"""Create a new media list.
56
57
Args:
58
mrls (list, optional): Initial list of media resource locators
59
60
Returns:
61
MediaList: New media list instance
62
"""
63
...
64
65
def media_list_player_new(self):
66
"""Create a new media list player from this instance.
67
68
Returns:
69
MediaListPlayer: New media list player instance
70
"""
71
...
72
73
def audio_output_enumerate_devices(self):
74
"""Enumerate available audio output devices.
75
76
Returns:
77
list: List of available audio output devices
78
"""
79
...
80
81
def media_new_callbacks(self, open_cb, read_cb, seek_cb, close_cb, opaque):
82
"""Create a media with custom I/O callbacks. (LibVLC 3.0.0+)
83
84
Args:
85
open_cb: Open callback function
86
read_cb: Read callback function
87
seek_cb: Seek callback function
88
close_cb: Close callback function
89
opaque: User data pointer
90
91
Returns:
92
Media: New media object with custom I/O
93
"""
94
...
95
96
def set_exit_handler(self, cb, opaque):
97
"""Register exit event callback. (LibVLC 3.0.0+)
98
99
Args:
100
cb: Callback function to register
101
opaque: User data pointer
102
103
Returns:
104
int: 0 on success, -1 on error
105
"""
106
...
107
108
def media_discoverer_new(self, psz_name):
109
"""Create media discoverer by name. (LibVLC 3.0.0+)
110
111
Args:
112
psz_name (str): Service name for discovery
113
114
Returns:
115
MediaDiscoverer: New media discoverer instance
116
"""
117
...
118
119
def renderer_discoverer_new(self, psz_name):
120
"""Create renderer discoverer. (LibVLC 3.0.0+)
121
122
Args:
123
psz_name (str): Service name for renderer discovery
124
125
Returns:
126
RendererDiscoverer: New renderer discoverer instance
127
"""
128
...
129
130
def release(self):
131
"""Decrement the reference count of a libvlc instance."""
132
...
133
```
134
135
### Media Player Control
136
137
The MediaPlayer class provides complete control over media playback, including play/pause/stop operations and playback state management.
138
139
```python { .api }
140
class MediaPlayer:
141
def __init__(self, *args):
142
"""Create a media player object.
143
144
Args:
145
*args: Can be Instance, URI string, or Instance and URI
146
"""
147
...
148
149
def get_instance(self):
150
"""Get the instance associated with this media player.
151
152
Returns:
153
Instance: The LibVLC instance
154
"""
155
...
156
157
def set_media(self, media):
158
"""Set the media that will be used by the media player.
159
160
Args:
161
media (Media): Media object to play
162
"""
163
...
164
165
def get_media(self):
166
"""Get the media used by the media player.
167
168
Returns:
169
Media: Current media object or None
170
"""
171
...
172
173
def play(self):
174
"""Play the current media.
175
176
Returns:
177
int: 0 if playback started, -1 on error
178
"""
179
...
180
181
def pause(self):
182
"""Toggle the pause state of the player.
183
184
If player is playing, this pauses it.
185
If player is paused, this resumes playback.
186
"""
187
...
188
189
def stop(self):
190
"""Stop the player."""
191
...
192
193
def set_pause(self, do_pause):
194
"""Pause or resume the player.
195
196
Args:
197
do_pause (bool): True to pause, False to resume
198
"""
199
...
200
201
def get_time(self):
202
"""Get the current playback time in milliseconds.
203
204
Returns:
205
int: Current time in milliseconds, or -1 on error
206
"""
207
...
208
209
def set_time(self, time):
210
"""Set the current playback time in milliseconds.
211
212
Args:
213
time (int): Time in milliseconds
214
"""
215
...
216
217
def get_position(self):
218
"""Get the current playback position as a float between 0.0 and 1.0.
219
220
Returns:
221
float: Position from 0.0 to 1.0, or -1.0 on error
222
"""
223
...
224
225
def set_position(self, position):
226
"""Set the current playback position.
227
228
Args:
229
position (float): Position from 0.0 to 1.0
230
"""
231
...
232
233
def get_length(self):
234
"""Get the total length of the media in milliseconds.
235
236
Returns:
237
int: Length in milliseconds, or -1 if unavailable
238
"""
239
...
240
241
def get_state(self):
242
"""Get the current player state.
243
244
Returns:
245
State: Current player state (NothingSpecial, Opening, Buffering,
246
Playing, Paused, Stopped, Ended, Error)
247
"""
248
...
249
250
def get_rate(self):
251
"""Get the playback rate (speed).
252
253
Returns:
254
float: Playback rate (1.0 = normal speed)
255
"""
256
...
257
258
def set_rate(self, rate):
259
"""Set the playback rate (speed).
260
261
Args:
262
rate (float): Playback rate (1.0 = normal, 2.0 = double speed, etc.)
263
264
Returns:
265
int: 0 on success, -1 on error
266
"""
267
...
268
269
def is_playing(self):
270
"""Check if the player is playing.
271
272
Returns:
273
bool: True if playing, False otherwise
274
"""
275
...
276
277
def will_play(self):
278
"""Check if the player will play.
279
280
Returns:
281
bool: True if the player will play, False otherwise
282
"""
283
...
284
285
def is_seekable(self):
286
"""Check if the current media is seekable.
287
288
Returns:
289
bool: True if seekable, False otherwise
290
"""
291
...
292
293
def can_pause(self):
294
"""Check if the current media can be paused.
295
296
Returns:
297
bool: True if can pause, False otherwise
298
"""
299
...
300
301
def add_slave(self, i_type, psz_uri, b_select):
302
"""Add external subtitle or audio track. (LibVLC 3.0.0+)
303
304
Args:
305
i_type (int): Slave type (subtitle=0, audio=1)
306
psz_uri (str): URI of the slave track
307
b_select (bool): Whether to select this track immediately
308
309
Returns:
310
int: 0 on success, -1 on error
311
"""
312
...
313
314
def set_renderer(self, p_renderer):
315
"""Set renderer for casting. (LibVLC 3.0.0+)
316
317
Args:
318
p_renderer (Renderer): Renderer object or None to unset
319
320
Returns:
321
int: 0 on success, -1 on error
322
"""
323
...
324
325
def get_role(self):
326
"""Get media player role. (LibVLC 3.0.0+)
327
328
Returns:
329
int: Current player role
330
"""
331
...
332
333
def set_role(self, role):
334
"""Set media player role. (LibVLC 3.0.0+)
335
336
Args:
337
role (int): Player role to set
338
339
Returns:
340
int: 0 on success, -1 on error
341
"""
342
...
343
```
344
345
### Media Object Management
346
347
The Media class represents individual media files or streams with metadata and parsing capabilities.
348
349
```python { .api }
350
class Media:
351
def __init__(self, *args):
352
"""Create a media object.
353
354
Args:
355
*args: Can be Instance and MRL, or just MRL string
356
"""
357
...
358
359
def get_instance(self):
360
"""Get the instance associated with this media.
361
362
Returns:
363
Instance: The LibVLC instance
364
"""
365
...
366
367
def get_mrl(self):
368
"""Get the media resource locator.
369
370
Returns:
371
str: MRL string of this media
372
"""
373
...
374
375
def parse(self):
376
"""Parse the media synchronously. [DEPRECATED]
377
378
This fetches metadata and track information.
379
Use parse_with_options() for LibVLC 3.0+.
380
"""
381
...
382
383
def parse_async(self):
384
"""Parse the media asynchronously. [DEPRECATED]
385
386
This fetches metadata and track information in the background.
387
Use parse_with_options() for LibVLC 3.0+.
388
"""
389
...
390
391
def parse_with_options(self, parse_flag, timeout):
392
"""Parse the media with specific options. (LibVLC 3.0.0+) [RECOMMENDED]
393
394
Args:
395
parse_flag (int): Combination of ParseFlag values
396
timeout (int): Timeout in milliseconds (-1 for no timeout)
397
398
Returns:
399
int: -1 on error, 0 otherwise
400
"""
401
...
402
403
def parse_stop(self):
404
"""Stop ongoing parsing operation. (LibVLC 3.0.0+)
405
406
Stops any running asynchronous parsing.
407
"""
408
...
409
410
def get_parsed_status(self):
411
"""Get the current parsed status. (LibVLC 3.0.0+)
412
413
Returns:
414
MediaParsedStatus: Current parsing status
415
"""
416
...
417
418
def get_meta(self, meta_type):
419
"""Get metadata for the specified type.
420
421
Args:
422
meta_type (Meta): Type of metadata to retrieve
423
424
Returns:
425
str: Metadata value or None if not available
426
"""
427
...
428
429
def set_meta(self, meta_type, meta_value):
430
"""Set metadata for the specified type.
431
432
Args:
433
meta_type (Meta): Type of metadata to set
434
meta_value (str): Value to set
435
"""
436
...
437
438
def save_meta(self):
439
"""Save the previously set metadata to the media file.
440
441
Returns:
442
bool: True on success, False on failure
443
"""
444
...
445
446
def get_duration(self):
447
"""Get the duration of the media in milliseconds.
448
449
Returns:
450
int: Duration in milliseconds, or -1 if unknown
451
"""
452
...
453
454
def get_type(self):
455
"""Get the media type.
456
457
Returns:
458
MediaType: Type of media (Unknown, File, Directory, Disc, Stream, Playlist)
459
"""
460
...
461
462
def get_tracks_info(self):
463
"""Get information about tracks in the media. [DEPRECATED]
464
465
Use tracks_get() for LibVLC 2.1.0+.
466
467
Returns:
468
list: List of track information dictionaries
469
"""
470
...
471
472
def tracks_get(self):
473
"""Get tracks information as MediaTrack objects. (LibVLC 2.1.0+) [RECOMMENDED]
474
475
Returns:
476
iterator: Iterator of MediaTrack objects or None
477
"""
478
...
479
480
def subitems(self):
481
"""Get the subitems media list.
482
483
Returns:
484
MediaList: List of subitems or None
485
"""
486
...
487
488
def event_manager(self):
489
"""Get the event manager for this media.
490
491
Returns:
492
EventManager: Event manager for this media
493
"""
494
...
495
496
def add_option(self, option):
497
"""Add an option to the media.
498
499
Args:
500
option (str): Option string in format 'key=value'
501
"""
502
...
503
504
def add_option_flag(self, option, flag):
505
"""Add an option to the media with specific flags.
506
507
Args:
508
option (str): Option string
509
flag (int): Option flags
510
"""
511
...
512
513
def slaves_add(self, i_type, i_priority, psz_uri):
514
"""Add external subtitle or audio track. (LibVLC 3.0.0+)
515
516
Args:
517
i_type (int): Subtitle (0) or audio (1)
518
i_priority (int): Priority (0-4)
519
psz_uri (str): URI of the slave track
520
521
Returns:
522
int: 0 on success, -1 on error
523
"""
524
...
525
526
def slaves_clear(self):
527
"""Clear all added slaves. (LibVLC 3.0.0+)
528
529
Removes all previously added slave tracks.
530
"""
531
...
532
533
def duplicate(self):
534
"""Duplicate the media object.
535
536
Returns:
537
Media: Duplicated media object
538
"""
539
...
540
541
def release(self):
542
"""Decrement the reference count of a media object."""
543
...
544
```
545
546
## Usage Examples
547
548
### Basic Media Player
549
550
```python
551
import vlc
552
553
# Simple player with a file
554
player = vlc.MediaPlayer('/path/to/video.mp4')
555
player.play()
556
557
# Control playback
558
player.pause()
559
player.stop()
560
561
# Check status
562
if player.is_playing():
563
print(f"Current time: {player.get_time()}ms")
564
print(f"Total length: {player.get_length()}ms")
565
```
566
567
### Using Instance for Advanced Control
568
569
```python
570
import vlc
571
572
# Create instance with options
573
instance = vlc.Instance('--no-audio', '--quiet')
574
575
# Create media and player
576
media = instance.media_new('file:///path/to/video.mp4')
577
player = instance.media_player_new()
578
player.set_media(media)
579
580
# Parse media for metadata (LibVLC 3.0+)
581
media.parse_with_options(vlc.MediaParseFlag.ParseLocal, -1)
582
# Wait for parsing to complete
583
while media.get_parsed_status() == vlc.MediaParsedStatus.Skipped:
584
pass
585
586
title = media.get_meta(vlc.Meta.Title)
587
duration = media.get_duration()
588
589
print(f"Title: {title}")
590
print(f"Duration: {duration}ms")
591
592
# Start playback
593
player.play()
594
```
595
596
### Media Parsing and Metadata
597
598
```python
599
import vlc
600
601
# Create media object
602
media = vlc.Media('/path/to/audio.mp3')
603
604
# Parse with modern method (LibVLC 3.0+)
605
media.parse_with_options(vlc.MediaParseFlag.ParseLocal, -1)
606
# For older versions, use:
607
# media.parse()
608
609
# Get various metadata
610
title = media.get_meta(vlc.Meta.Title)
611
artist = media.get_meta(vlc.Meta.Artist)
612
album = media.get_meta(vlc.Meta.Album)
613
duration = media.get_duration()
614
615
print(f"Title: {title}")
616
print(f"Artist: {artist}")
617
print(f"Album: {album}")
618
print(f"Duration: {duration}ms")
619
620
# Get track information (modern method)
621
tracks = media.tracks_get()
622
if tracks:
623
for track in tracks:
624
print(f"Track type: {track.type}")
625
print(f"Codec: {track.codec}")
626
```