0
# Data Structures and Enums
1
2
Complete type definitions, enumerations, and data structures used throughout the Python-VLC API. These structures provide the foundation for all VLC operations and state management.
3
4
## Capabilities
5
6
### Player State Enumeration
7
8
Core player state definitions for tracking playback status.
9
10
```python { .api }
11
class State:
12
"""Media player state enumeration."""
13
NothingSpecial = 0 # No media loaded
14
Opening = 1 # Media is opening
15
Buffering = 2 # Media is buffering
16
Playing = 3 # Media is playing
17
Paused = 4 # Media is paused
18
Stopped = 5 # Media is stopped
19
Ended = 6 # Media playback ended
20
Error = 7 # Error occurred
21
```
22
23
### Media Type Classification
24
25
Enumeration for different types of media sources.
26
27
```python { .api }
28
class MediaType:
29
"""Media type enumeration."""
30
Unknown = 0 # Unknown media type
31
File = 1 # File-based media
32
Directory = 2 # Directory (playlist)
33
Disc = 3 # Physical disc (DVD, CD, etc.)
34
Stream = 4 # Network stream
35
Playlist = 5 # Playlist file
36
```
37
38
### Metadata Type Definitions
39
40
Enumeration for media metadata types.
41
42
```python { .api }
43
class Meta:
44
"""Media metadata type enumeration."""
45
Title = 0 # Media title
46
Artist = 1 # Artist name
47
Genre = 2 # Genre
48
Copyright = 3 # Copyright information
49
Album = 4 # Album name
50
TrackNumber = 5 # Track number
51
Description = 6 # Description
52
Rating = 7 # Rating
53
Date = 8 # Release date
54
Setting = 9 # Setting
55
URL = 10 # URL
56
Language = 11 # Language
57
NowPlaying = 12 # Now playing
58
Publisher = 13 # Publisher
59
EncodedBy = 14 # Encoded by
60
ArtworkURL = 15 # Artwork URL
61
TrackID = 16 # Track ID
62
TrackTotal = 17 # Total tracks
63
Director = 18 # Director
64
Season = 19 # Season number
65
Episode = 20 # Episode number
66
ShowName = 21 # Show name
67
Actors = 22 # Actors
68
AlbumArtist = 23 # Album artist
69
DiscNumber = 24 # Disc number
70
DiscTotal = 25 # Total discs
71
```
72
73
### Audio Output Configuration
74
75
Enumerations for audio output settings and device types.
76
77
```python { .api }
78
class AudioOutputChannel:
79
"""Audio output channel configuration."""
80
Error = -1 # Error state
81
Stereo = 1 # Stereo output
82
RStereo = 2 # Reverse stereo
83
Left = 3 # Left channel only
84
Right = 4 # Right channel only
85
Dolby = 5 # Dolby surround
86
87
class AudioOutputDeviceType:
88
"""Audio output device types."""
89
Error = -1 # Error state
90
Mono = 1 # Mono output
91
Stereo = 2 # Stereo output
92
_2F2R = 4 # 2 front, 2 rear
93
_3F2R = 5 # 3 front, 2 rear
94
_5_1 = 6 # 5.1 surround
95
_6_1 = 7 # 6.1 surround
96
_7_1 = 8 # 7.1 surround
97
SPDIF = 10 # S/PDIF output
98
```
99
100
### Video Adjustment Parameters
101
102
Enumerations for video filter and adjustment options.
103
104
```python { .api }
105
class VideoAdjustOption:
106
"""Video adjustment options for filters."""
107
Enable = 0 # Enable adjustment
108
Contrast = 1 # Contrast level
109
Brightness = 2 # Brightness level
110
Hue = 3 # Hue adjustment
111
Saturation = 4 # Saturation level
112
Gamma = 5 # Gamma correction
113
114
class VideoLogoOption:
115
"""Video logo overlay options."""
116
Enable = 0 # Enable logo
117
File = 1 # Logo file path
118
X = 2 # X position
119
Y = 3 # Y position
120
Delay = 4 # Display delay
121
Repeat = 5 # Repeat count
122
Opacity = 6 # Opacity level
123
Position = 7 # Position mode
124
Size = 8 # Logo size
125
126
class VideoMarqueeOption:
127
"""Video marquee text overlay options."""
128
Enable = 0 # Enable marquee
129
Text = 1 # Text content
130
Color = 2 # Text color
131
Opacity = 3 # Text opacity
132
Position = 4 # Text position
133
Refresh = 5 # Refresh rate
134
Size = 6 # Text size
135
Timeout = 7 # Display timeout
136
X = 8 # X position
137
Y = 9 # Y position
138
```
139
140
### Track Type Classification
141
142
Enumeration for different types of media tracks.
143
144
```python { .api }
145
class TrackType:
146
"""Media track type enumeration."""
147
Unknown = -1 # Unknown track type
148
Audio = 0 # Audio track
149
Video = 1 # Video track
150
Text = 2 # Subtitle/text track
151
```
152
153
### Playback Mode Configuration
154
155
Enumeration for media list playback modes.
156
157
```python { .api }
158
class PlaybackMode:
159
"""Media list playback modes."""
160
Default = 0 # Play once through
161
Loop = 1 # Loop entire list
162
Repeat = 2 # Repeat current item
163
```
164
165
### Media Discovery Categories
166
167
Enumeration for media discovery service categories.
168
169
```python { .api }
170
class MediaDiscovererCategory:
171
"""Media discovery service categories."""
172
Devices = 0 # Local devices
173
Lan = 1 # LAN services
174
Podcasts = 2 # Podcast services
175
LocalDirs = 3 # Local directories
176
```
177
178
### Media Parsing Configuration
179
180
Enumerations for media parsing options and status.
181
182
```python { .api }
183
class MediaParseFlag:
184
"""Media parsing flags."""
185
ParseLocal = 0x00 # Parse local media only
186
ParseNetwork = 0x01 # Parse network media
187
FetchLocal = 0x02 # Fetch local metadata
188
FetchNetwork = 0x04 # Fetch network metadata
189
DoInteract = 0x08 # Allow user interaction
190
191
class MediaParsedStatus:
192
"""Media parsing status enumeration."""
193
Skipped = 1 # Parsing skipped
194
Failed = 2 # Parsing failed
195
Timeout = 3 # Parsing timed out
196
Done = 4 # Parsing completed successfully
197
```
198
199
### Event Type Definitions
200
201
Comprehensive event type enumeration for all VLC events.
202
203
```python { .api }
204
class EventType:
205
"""VLC event type enumeration."""
206
207
# Media Events (0x000 - 0x0FF)
208
MediaMetaChanged = 0x000
209
MediaSubItemAdded = 0x001
210
MediaDurationChanged = 0x002
211
MediaParsedChanged = 0x003
212
MediaFreed = 0x004
213
MediaStateChanged = 0x005
214
MediaSubItemTreeAdded = 0x006
215
MediaThumbnailGenerated = 0x007
216
MediaAttachedThumbnailsFound = 0x008
217
218
# Media Player Events (0x100 - 0x1FF)
219
MediaPlayerMediaChanged = 0x100
220
MediaPlayerNothingSpecial = 0x101
221
MediaPlayerOpening = 0x102
222
MediaPlayerBuffering = 0x103
223
MediaPlayerPlaying = 0x104
224
MediaPlayerPaused = 0x105
225
MediaPlayerStopped = 0x106
226
MediaPlayerForward = 0x107
227
MediaPlayerBackward = 0x108
228
MediaPlayerEndReached = 0x109
229
MediaPlayerEncounteredError = 0x10a
230
MediaPlayerTimeChanged = 0x10b
231
MediaPlayerPositionChanged = 0x10c
232
MediaPlayerSeekableChanged = 0x10d
233
MediaPlayerPausableChanged = 0x10e
234
MediaPlayerTitleChanged = 0x10f
235
MediaPlayerSnapshotTaken = 0x110
236
MediaPlayerLengthChanged = 0x111
237
MediaPlayerVout = 0x112
238
MediaPlayerScrambledChanged = 0x113
239
MediaPlayerESAdded = 0x114
240
MediaPlayerESDeleted = 0x115
241
MediaPlayerESSelected = 0x116
242
MediaPlayerCorked = 0x117
243
MediaPlayerUncorked = 0x118
244
MediaPlayerMuted = 0x119
245
MediaPlayerUnmuted = 0x11a
246
MediaPlayerAudioVolume = 0x11b
247
MediaPlayerAudioDevice = 0x11c
248
MediaPlayerChapterChanged = 0x11d
249
250
# Media List Events (0x200 - 0x2FF)
251
MediaListItemAdded = 0x200
252
MediaListWillAddItem = 0x201
253
MediaListItemDeleted = 0x202
254
MediaListWillDeleteItem = 0x203
255
MediaListEndReached = 0x204
256
257
# Media List Player Events (0x400 - 0x4FF)
258
MediaListPlayerPlayed = 0x400
259
MediaListPlayerNextItemSet = 0x401
260
MediaListPlayerStopped = 0x402
261
262
# Media Discoverer Events (0x500 - 0x5FF)
263
MediaDiscovererStarted = 0x500
264
MediaDiscovererEnded = 0x501
265
266
# VLM Events (0x600 - 0x6FF)
267
VlmMediaAdded = 0x600
268
VlmMediaRemoved = 0x601
269
VlmMediaChanged = 0x602
270
VlmMediaInstanceStarted = 0x603
271
VlmMediaInstanceStopped = 0x604
272
VlmMediaInstanceStatusInit = 0x605
273
VlmMediaInstanceStatusOpening = 0x606
274
VlmMediaInstanceStatusPlaying = 0x607
275
VlmMediaInstanceStatusPause = 0x608
276
VlmMediaInstanceStatusEnd = 0x609
277
VlmMediaInstanceStatusError = 0x60a
278
279
# Renderer Discoverer Events (0x700 - 0x7FF)
280
RendererDiscovererItemAdded = 0x700
281
RendererDiscovererItemDeleted = 0x701
282
```
283
284
### Logging Configuration
285
286
Enumeration for logging levels and log message types.
287
288
```python { .api }
289
class LogLevel:
290
"""Logging level enumeration."""
291
Debug = 0 # Debug messages
292
Notice = 1 # Notice messages
293
Warning = 2 # Warning messages
294
Error = 3 # Error messages
295
```
296
297
### Navigation and Control
298
299
Enumerations for navigation modes and teletext control.
300
301
```python { .api }
302
class NavigateMode:
303
"""Navigation mode for DVD/Blu-ray."""
304
Activate = 0 # Activate navigation
305
Up = 1 # Navigate up
306
Down = 2 # Navigate down
307
Left = 3 # Navigate left
308
Right = 4 # Navigate right
309
Popup = 5 # Show popup menu
310
311
class TeletextKey:
312
"""Teletext key definitions."""
313
Red = 0 # Red key
314
Green = 1 # Green key
315
Yellow = 2 # Yellow key
316
Blue = 3 # Blue key
317
Index = 4 # Index key
318
319
class Position:
320
"""Position constants."""
321
Disable = -1 # Disable positioning
322
Center = 0 # Center position
323
Left = 1 # Left position
324
Right = 2 # Right position
325
Top = 4 # Top position
326
TopLeft = 5 # Top-left position
327
TopRight = 6 # Top-right position
328
Bottom = 8 # Bottom position
329
BottomLeft = 9 # Bottom-left position
330
BottomRight = 10 # Bottom-right position
331
```
332
333
### Media Slave Configuration
334
335
Enumeration for media slave types (subtitles, audio tracks).
336
337
```python { .api }
338
class MediaSlaveType:
339
"""Media slave type enumeration."""
340
Subtitle = 0 # Subtitle slave
341
Audio = 1 # Audio slave
342
```
343
344
### Dialog System
345
346
Enumeration for dialog question types in user interactions.
347
348
```python { .api }
349
class DialogQuestionType:
350
"""Dialog question type enumeration."""
351
Normal = 0 # Normal question
352
Warning = 1 # Warning dialog
353
Critical = 2 # Critical dialog
354
```
355
356
### Media Player Role
357
358
Enumeration for media player roles in system integration.
359
360
```python { .api }
361
class MediaPlayerRole:
362
"""Media player role enumeration."""
363
None_ = 0 # No specific role
364
Music = 1 # Music player role
365
Video = 2 # Video player role
366
Communication = 3 # Communication role
367
Game = 4 # Game role
368
Notification = 5 # Notification role
369
Animation = 6 # Animation role
370
Production = 7 # Production role
371
Accessibility = 8 # Accessibility role
372
Test = 9 # Test role
373
```
374
375
### Data Structure Classes
376
377
Core data structure classes used for complex data handling.
378
379
```python { .api }
380
class Event:
381
"""Event data structure."""
382
def __init__(self):
383
self.type = 0 # Event type
384
self.obj = None # Event object
385
self.u = None # Union of event-specific data
386
387
class MediaStats:
388
"""Media statistics structure."""
389
def __init__(self):
390
self.read_bytes = 0 # Bytes read
391
self.input_bitrate = 0.0 # Input bitrate
392
self.demux_read_bytes = 0 # Demux bytes read
393
self.demux_bitrate = 0.0 # Demux bitrate
394
self.demux_corrupted = 0 # Corrupted packets
395
self.demux_discontinuity = 0 # Discontinuities
396
self.decoded_video = 0 # Decoded video frames
397
self.decoded_audio = 0 # Decoded audio frames
398
self.displayed_pictures = 0 # Displayed pictures
399
self.late_pictures = 0 # Late pictures
400
self.lost_pictures = 0 # Lost pictures
401
self.played_abuffers = 0 # Played audio buffers
402
self.lost_abuffers = 0 # Lost audio buffers
403
self.sent_packets = 0 # Sent packets
404
self.sent_bytes = 0 # Sent bytes
405
406
class MediaTrack:
407
"""Media track information structure."""
408
def __init__(self):
409
self.codec = 0 # Track codec
410
self.original_fourcc = 0 # Original fourcc
411
self.id = 0 # Track ID
412
self.type = TrackType.Unknown # Track type
413
self.profile = 0 # Codec profile
414
self.level = 0 # Codec level
415
self.bitrate = 0 # Bitrate
416
self.language = None # Language code
417
self.description = None # Track description
418
419
class AudioTrack:
420
"""Audio track information structure."""
421
def __init__(self):
422
self.channels = 0 # Channel count
423
self.rate = 0 # Sample rate
424
425
class VideoTrack:
426
"""Video track information structure."""
427
def __init__(self):
428
self.height = 0 # Video height
429
self.width = 0 # Video width
430
self.sar_num = 0 # Sample aspect ratio numerator
431
self.sar_den = 0 # Sample aspect ratio denominator
432
self.frame_rate_num = 0 # Frame rate numerator
433
self.frame_rate_den = 0 # Frame rate denominator
434
435
class SubtitleTrack:
436
"""Subtitle track information structure."""
437
def __init__(self):
438
self.encoding = None # Text encoding
439
```
440
441
### Exception Classes
442
443
Exception classes for error handling.
444
445
```python { .api }
446
class VLCException(Exception):
447
"""Main exception class for LibVLC errors."""
448
pass
449
```
450
451
### Utility Classes
452
453
Utility classes for internal operations and memory management.
454
455
```python { .api }
456
class ListPOINTER:
457
"""ctypes utility for handling lists of pointers."""
458
pass
459
460
class CallbackDecorators:
461
"""Utility class for callback function decorators."""
462
pass
463
464
class Log:
465
"""Log entry structure wrapper."""
466
def __init__(self):
467
self.severity = LogLevel.Debug # Log severity
468
self.type = None # Log type
469
self.name = None # Logger name
470
self.header = None # Log header
471
self.message = None # Log message
472
```
473
474
## Usage Examples
475
476
### State Checking and Handling
477
478
```python
479
import vlc
480
import time
481
482
player = vlc.MediaPlayer('/path/to/video.mp4')
483
player.play()
484
485
# Check player state
486
while True:
487
state = player.get_state()
488
489
if state == vlc.State.NothingSpecial:
490
print("No media loaded")
491
elif state == vlc.State.Opening:
492
print("Opening media...")
493
elif state == vlc.State.Buffering:
494
print("Buffering...")
495
elif state == vlc.State.Playing:
496
print("Playing")
497
break
498
elif state == vlc.State.Paused:
499
print("Paused")
500
elif state == vlc.State.Stopped:
501
print("Stopped")
502
elif state == vlc.State.Ended:
503
print("Playback ended")
504
break
505
elif state == vlc.State.Error:
506
print("Error occurred")
507
break
508
509
time.sleep(0.5)
510
511
# Handle different media types
512
media = player.get_media()
513
if media:
514
media_type = media.get_type()
515
516
if media_type == vlc.MediaType.File:
517
print("Playing a file")
518
elif media_type == vlc.MediaType.Stream:
519
print("Playing a stream")
520
elif media_type == vlc.MediaType.Disc:
521
print("Playing from disc")
522
elif media_type == vlc.MediaType.Directory:
523
print("Playing from directory")
524
elif media_type == vlc.MediaType.Playlist:
525
print("Playing a playlist")
526
```
527
528
### Metadata Extraction
529
530
```python
531
import vlc
532
533
# Create media and parse it
534
media = vlc.Media('/path/to/audio.mp3')
535
media.parse()
536
537
# Extract various metadata
538
metadata = {}
539
meta_types = [
540
(vlc.Meta.Title, "Title"),
541
(vlc.Meta.Artist, "Artist"),
542
(vlc.Meta.Album, "Album"),
543
(vlc.Meta.Genre, "Genre"),
544
(vlc.Meta.Date, "Date"),
545
(vlc.Meta.TrackNumber, "Track Number"),
546
(vlc.Meta.TrackTotal, "Total Tracks"),
547
(vlc.Meta.Publisher, "Publisher"),
548
(vlc.Meta.Copyright, "Copyright"),
549
(vlc.Meta.Language, "Language"),
550
(vlc.Meta.Description, "Description"),
551
(vlc.Meta.Rating, "Rating"),
552
(vlc.Meta.ArtworkURL, "Artwork URL"),
553
]
554
555
print("Media Metadata:")
556
for meta_type, name in meta_types:
557
value = media.get_meta(meta_type)
558
if value:
559
metadata[name] = value
560
print(f" {name}: {value}")
561
562
# Get duration and other properties
563
duration = media.get_duration()
564
if duration > 0:
565
minutes = duration // 60000
566
seconds = (duration % 60000) // 1000
567
print(f" Duration: {minutes:02d}:{seconds:02d}")
568
```
569
570
### Audio Configuration
571
572
```python
573
import vlc
574
575
player = vlc.MediaPlayer('/path/to/audio.mp3')
576
player.play()
577
578
# Check and set audio channel configuration
579
channel = player.audio_get_channel()
580
print(f"Current audio channel: {channel}")
581
582
# Set different channel configurations
583
if channel == vlc.AudioOutputChannel.Stereo:
584
print("Audio is in stereo mode")
585
elif channel == vlc.AudioOutputChannel.Left:
586
print("Audio is left channel only")
587
elif channel == vlc.AudioOutputChannel.Right:
588
print("Audio is right channel only")
589
elif channel == vlc.AudioOutputChannel.Dolby:
590
print("Audio is in Dolby mode")
591
592
# Change to mono (left channel only)
593
player.audio_set_channel(vlc.AudioOutputChannel.Left)
594
print(f"Changed to: {player.audio_get_channel()}")
595
596
# Get audio output device information
597
instance = player.get_instance()
598
devices = instance.audio_output_enumerate_devices()
599
print("\nAvailable audio devices:")
600
for device_id, device_name in devices:
601
print(f" {device_id}: {device_name}")
602
```
603
604
### Video Adjustment and Effects
605
606
```python
607
import vlc
608
609
player = vlc.MediaPlayer('/path/to/video.mp4')
610
player.play()
611
612
# Wait for video to start
613
import time
614
time.sleep(2)
615
616
# Enable video adjustments
617
player.video_set_adjust_int(vlc.VideoAdjustOption.Enable, 1)
618
619
# Adjust video properties
620
adjustments = [
621
(vlc.VideoAdjustOption.Brightness, 1.2),
622
(vlc.VideoAdjustOption.Contrast, 1.3),
623
(vlc.VideoAdjustOption.Saturation, 1.1),
624
(vlc.VideoAdjustOption.Gamma, 1.0),
625
(vlc.VideoAdjustOption.Hue, 0)
626
]
627
628
print("Applying video adjustments:")
629
for option, value in adjustments:
630
player.video_set_adjust_float(option, value)
631
current = player.video_get_adjust_float(option)
632
print(f" {option}: {current}")
633
634
# Add logo overlay
635
print("\nAdding logo overlay:")
636
player.video_set_logo_int(vlc.VideoLogoOption.Enable, 1)
637
player.video_set_logo_string(vlc.VideoLogoOption.File, '/path/to/logo.png')
638
player.video_set_logo_int(vlc.VideoLogoOption.X, 10)
639
player.video_set_logo_int(vlc.VideoLogoOption.Y, 10)
640
player.video_set_logo_int(vlc.VideoLogoOption.Opacity, 128) # 50% opacity
641
642
# Add text marquee
643
print("Adding text marquee:")
644
player.video_set_marquee_int(vlc.VideoMarqueeOption.Enable, 1)
645
player.video_set_marquee_string(vlc.VideoMarqueeOption.Text, "Python-VLC Demo")
646
player.video_set_marquee_int(vlc.VideoMarqueeOption.X, 100)
647
player.video_set_marquee_int(vlc.VideoMarqueeOption.Y, 50)
648
player.video_set_marquee_int(vlc.VideoMarqueeOption.Size, 24)
649
player.video_set_marquee_int(vlc.VideoMarqueeOption.Color, 0xFFFFFF) # White
650
player.video_set_marquee_int(vlc.VideoMarqueeOption.Opacity, 255) # Fully opaque
651
```
652
653
### Track Information Analysis
654
655
```python
656
import vlc
657
658
media = vlc.Media('/path/to/video.mkv')
659
media.parse()
660
661
# Get track information
662
tracks = media.tracks_get()
663
if tracks:
664
print(f"Media has {len(tracks)} tracks:")
665
666
for i, track in enumerate(tracks):
667
print(f"\nTrack {i}:")
668
print(f" ID: {track.id}")
669
print(f" Type: {track.type}")
670
print(f" Codec: {track.codec}")
671
print(f" Language: {track.language}")
672
print(f" Description: {track.description}")
673
674
if track.type == vlc.TrackType.Audio:
675
print(f" Channels: {track.channels}")
676
print(f" Sample Rate: {track.rate} Hz")
677
elif track.type == vlc.TrackType.Video:
678
print(f" Resolution: {track.width}x{track.height}")
679
if track.frame_rate_den > 0:
680
fps = track.frame_rate_num / track.frame_rate_den
681
print(f" Frame Rate: {fps:.2f} fps")
682
elif track.type == vlc.TrackType.Text:
683
print(f" Encoding: {track.encoding}")
684
685
# Alternative: Get track info as dictionaries
686
track_info = media.get_tracks_info()
687
print(f"\nTrack info (dict format): {len(track_info)} tracks")
688
for i, info in enumerate(track_info):
689
print(f"Track {i}: {info}")
690
```
691
692
### Playlist Mode Configuration
693
694
```python
695
import vlc
696
697
# Create media list and player
698
instance = vlc.Instance()
699
media_list = instance.media_list_new()
700
list_player = instance.media_list_player_new()
701
702
# Add media to list
703
songs = ['/path/to/song1.mp3', '/path/to/song2.mp3', '/path/to/song3.mp3']
704
for song in songs:
705
media = instance.media_new(song)
706
media_list.add_media(media)
707
708
list_player.set_media_list(media_list)
709
710
# Set different playback modes
711
print("Testing playback modes:")
712
713
# Default mode - play once through
714
list_player.set_playback_mode(vlc.PlaybackMode.Default)
715
print("Mode: Default (play once)")
716
717
# Loop mode - repeat entire list
718
list_player.set_playback_mode(vlc.PlaybackMode.Loop)
719
print("Mode: Loop (repeat list)")
720
721
# Repeat mode - repeat current item
722
list_player.set_playback_mode(vlc.PlaybackMode.Repeat)
723
print("Mode: Repeat (repeat current)")
724
725
# Start playback
726
list_player.play()
727
```