0
# Event System
1

2
Comprehensive event handling system for responding to media state changes, playback events, and user interactions. The event system enables building responsive media applications that react to VLC's internal state changes.
3

4
## Capabilities
5

6
### Event Manager
7

8
The EventManager class provides the core event handling mechanism for attaching and detaching event callbacks.
9

10
```python { .api }
11
class EventManager:
12
    def event_attach(self, event_type, callback, user_data=None):
13
        """Attach an event callback.
14
        
15
        Args:
16
            event_type (EventType): Type of event to listen for
17
            callback (function): Function to call when event occurs
18
            user_data: Optional user data passed to callback
19
        """
20
        ...
21
    
22
    def event_detach(self, event_type):
23
        """Detach an event callback.
24
        
25
        Args:
26
            event_type (EventType): Type of event to stop listening for
27
        """
28
        ...
29
```
30

31
### Media Player Events
32

33
Event types related to media player state and playback changes.
34

35
```python { .api }
36
class EventType:
37
    # Media Player Events
38
    MediaPlayerMediaChanged = 0x100
39
    MediaPlayerNothingSpecial = 0x101
40
    MediaPlayerOpening = 0x102
41
    MediaPlayerBuffering = 0x103
42
    MediaPlayerPlaying = 0x104
43
    MediaPlayerPaused = 0x105
44
    MediaPlayerStopped = 0x106
45
    MediaPlayerForward = 0x107
46
    MediaPlayerBackward = 0x108
47
    MediaPlayerEndReached = 0x109
48
    MediaPlayerEncounteredError = 0x10a
49
    MediaPlayerTimeChanged = 0x10b
50
    MediaPlayerPositionChanged = 0x10c
51
    MediaPlayerSeekableChanged = 0x10d
52
    MediaPlayerPausableChanged = 0x10e
53
    MediaPlayerTitleChanged = 0x10f
54
    MediaPlayerSnapshotTaken = 0x110
55
    MediaPlayerLengthChanged = 0x111
56
    MediaPlayerVout = 0x112
57
    MediaPlayerScrambledChanged = 0x113
58
    MediaPlayerESAdded = 0x114
59
    MediaPlayerESDeleted = 0x115
60
    MediaPlayerESSelected = 0x116
61
    MediaPlayerCorked = 0x117
62
    MediaPlayerUncorked = 0x118
63
    MediaPlayerMuted = 0x119
64
    MediaPlayerUnmuted = 0x11a
65
    MediaPlayerAudioVolume = 0x11b
66
    MediaPlayerAudioDevice = 0x11c
67
    MediaPlayerChapterChanged = 0x11d
68
```
69

70
### Media Events
71

72
Event types related to media object changes and parsing.
73

74
```python { .api }
75
class EventType:
76
    # Media Events  
77
    MediaMetaChanged = 0x000
78
    MediaSubItemAdded = 0x001
79
    MediaDurationChanged = 0x002
80
    MediaParsedChanged = 0x003
81
    MediaFreed = 0x004
82
    MediaStateChanged = 0x005
83
    MediaSubItemTreeAdded = 0x006
84
    MediaThumbnailGenerated = 0x007
85
    MediaAttachedThumbnailsFound = 0x008
86
```
87

88
### Media List Events
89

90
Event types for media list operations and changes.
91

92
```python { .api }
93
class EventType:
94
    # Media List Events
95
    MediaListItemAdded = 0x200
96
    MediaListWillAddItem = 0x201
97
    MediaListItemDeleted = 0x202
98
    MediaListWillDeleteItem = 0x203
99
    MediaListEndReached = 0x204
100
```
101

102
### Media List Player Events
103

104
Event types for media list player operations.
105

106
```python { .api }
107
class EventType:
108
    # Media List Player Events
109
    MediaListPlayerPlayed = 0x400
110
    MediaListPlayerNextItemSet = 0x401
111
    MediaListPlayerStopped = 0x402
112
```
113

114
### Media Discoverer Events
115

116
Event types for media discovery operations.
117

118
```python { .api }
119
class EventType:
120
    # Media Discoverer Events
121
    MediaDiscovererStarted = 0x500
122
    MediaDiscovererEnded = 0x501
123
```
124

125
### VLC Instance Events
126

127
Event types for VLC instance-level operations.
128

129
```python { .api }
130
class EventType:
131
    # VLC Instance Events
132
    VlmMediaAdded = 0x600
133
    VlmMediaRemoved = 0x601
134
    VlmMediaChanged = 0x602
135
    VlmMediaInstanceStarted = 0x603
136
    VlmMediaInstanceStopped = 0x604
137
    VlmMediaInstanceStatusInit = 0x605
138
    VlmMediaInstanceStatusOpening = 0x606
139
    VlmMediaInstanceStatusPlaying = 0x607
140
    VlmMediaInstanceStatusPause = 0x608
141
    VlmMediaInstanceStatusEnd = 0x609
142
    VlmMediaInstanceStatusError = 0x60a
143
```
144

145
### Renderer Discoverer Events
146

147
Event types for renderer discovery operations.
148

149
```python { .api }
150
class EventType:
151
    # Renderer Discoverer Events
152
    RendererDiscovererItemAdded = 0x700
153
    RendererDiscovererItemDeleted = 0x701
154
```
155

156
### Event Data Structures
157

158
Data structures that provide event-specific information in callbacks.
159

160
```python { .api }
161
class Event:
162
    """Base event structure."""
163
    def __init__(self):
164
        self.type = None
165
        self.obj = None
166
        self.u = None  # Union of event-specific data
167

168
class MediaEvent:
169
    """Media-specific event data."""
170
    def __init__(self):
171
        self.meta_type = None
172
        self.new_child = None
173
        self.new_duration = None
174
        self.new_status = None
175
        self.new_state = None
176

177
class MediaPlayerEvent:
178
    """Media player-specific event data."""
179
    def __init__(self):
180
        self.new_media = None
181
        self.new_cache = None
182
        self.new_position = None
183
        self.new_time = None
184
        self.new_title = None
185
        self.new_seekable = None
186
        self.new_pausable = None
187
        self.new_scrambled = None
188
        self.new_count = None
189
        self.volume = None
190
        self.device = None
191
        self.new_chapter = None
192

193
class MediaListEvent:
194
    """Media list-specific event data.""" 
195
    def __init__(self):
196
        self.item = None
197
        self.index = None
198

199
class MediaDiscovererEvent:
200
    """Media discoverer-specific event data."""
201
    def __init__(self):
202
        self.media = None
203

204
class RendererDiscovererEvent:
205
    """Renderer discoverer-specific event data."""
206
    def __init__(self):
207
        self.item = None
208
```
209

210
## Usage Examples
211

212
### Basic Event Handling
213

214
```python
215
import vlc
216
import time
217

218
def on_media_state_changed(event):
219
    """Callback for media state changes."""
220
    print(f"Media state changed to: {event.u.new_state}")
221

222
def on_player_time_changed(event):
223
    """Callback for playback time changes."""
224
    print(f"Playback time: {event.u.new_time}ms")
225

226
def on_player_position_changed(event):
227
    """Callback for playback position changes."""
228
    print(f"Playback position: {event.u.new_position:.2%}")
229

230
# Create player and media
231
player = vlc.MediaPlayer('/path/to/video.mp4')
232
media = player.get_media()
233

234
# Attach media events
235
if media:
236
    media_em = media.event_manager()
237
    media_em.event_attach(vlc.EventType.MediaStateChanged, on_media_state_changed)
238

239
# Attach player events
240
player_em = player.event_manager()
241
player_em.event_attach(vlc.EventType.MediaPlayerTimeChanged, on_player_time_changed)
242
player_em.event_attach(vlc.EventType.MediaPlayerPositionChanged, on_player_position_changed)
243

244
# Start playback and let events fire
245
player.play()
246
time.sleep(10)
247
player.stop()
248
```
249

250
### Comprehensive Player Event Monitoring
251

252
```python
253
import vlc
254
import time
255

256
class PlayerEventHandler:
257
    def on_nothing_special(self, event):
258
        print("Player state: Nothing special")
259
    
260
    def on_opening(self, event):
261
        print("Player state: Opening media")
262
    
263
    def on_buffering(self, event):
264
        cache = event.u.new_cache
265
        print(f"Player state: Buffering ({cache}%)")
266
    
267
    def on_playing(self, event):
268
        print("Player state: Playing")
269
    
270
    def on_paused(self, event):
271
        print("Player state: Paused")
272
    
273
    def on_stopped(self, event):
274
        print("Player state: Stopped")
275
    
276
    def on_end_reached(self, event):
277
        print("Player state: End reached")
278
    
279
    def on_error(self, event):
280
        print("Player state: Error encountered")
281
    
282
    def on_media_changed(self, event):
283
        print("Media changed")
284
    
285
    def on_length_changed(self, event):
286
        length = event.u.new_length
287
        print(f"Media length: {length}ms")
288
    
289
    def on_seekable_changed(self, event):
290
        seekable = event.u.new_seekable
291
        print(f"Seekable: {seekable}")
292
    
293
    def on_pausable_changed(self, event):
294
        pausable = event.u.new_pausable
295
        print(f"Pausable: {pausable}")
296

297
# Create handler and player
298
handler = PlayerEventHandler()
299
player = vlc.MediaPlayer('/path/to/video.mp4')
300
em = player.event_manager()
301

302
# Attach all events
303
event_handlers = {
304
    vlc.EventType.MediaPlayerNothingSpecial: handler.on_nothing_special,
305
    vlc.EventType.MediaPlayerOpening: handler.on_opening,
306
    vlc.EventType.MediaPlayerBuffering: handler.on_buffering,
307
    vlc.EventType.MediaPlayerPlaying: handler.on_playing,
308
    vlc.EventType.MediaPlayerPaused: handler.on_paused,
309
    vlc.EventType.MediaPlayerStopped: handler.on_stopped,
310
    vlc.EventType.MediaPlayerEndReached: handler.on_end_reached,
311
    vlc.EventType.MediaPlayerEncounteredError: handler.on_error,
312
    vlc.EventType.MediaPlayerMediaChanged: handler.on_media_changed,
313
    vlc.EventType.MediaPlayerLengthChanged: handler.on_length_changed,
314
    vlc.EventType.MediaPlayerSeekableChanged: handler.on_seekable_changed,
315
    vlc.EventType.MediaPlayerPausableChanged: handler.on_pausable_changed,
316
}
317

318
for event_type, callback in event_handlers.items():
319
    em.event_attach(event_type, callback)
320

321
# Test playback with events
322
player.play()
323
time.sleep(5)
324
player.pause()
325
time.sleep(2)
326
player.play()
327
time.sleep(5)
328
player.stop()
329
```
330

331
### Media Parsing Events
332

333
```python
334
import vlc
335
import time
336

337
def on_meta_changed(event):
338
    """Handle metadata changes."""
339
    meta_type = event.u.meta_type
340
    print(f"Metadata changed: type {meta_type}")
341

342
def on_parsed_changed(event):
343
    """Handle parsing status changes."""
344
    status = event.u.new_status
345
    print(f"Parse status changed: {status}")
346

347
def on_duration_changed(event):
348
    """Handle duration changes."""
349
    duration = event.u.new_duration
350
    print(f"Duration changed: {duration}ms")
351

352
# Create media and attach events
353
media = vlc.Media('/path/to/video.mp4')
354
em = media.event_manager()
355

356
em.event_attach(vlc.EventType.MediaMetaChanged, on_meta_changed)
357
em.event_attach(vlc.EventType.MediaParsedChanged, on_parsed_changed)
358
em.event_attach(vlc.EventType.MediaDurationChanged, on_duration_changed)
359

360
# Start parsing (triggers events)
361
print("Starting media parsing...")
362
media.parse_async()
363

364
# Wait for parsing to complete
365
time.sleep(3)
366

367
# Get parsed metadata
368
title = media.get_meta(vlc.Meta.Title)
369
duration = media.get_duration()
370
print(f"Title: {title}")
371
print(f"Duration: {duration}ms")
372
```
373

374
### Audio and Video Track Events
375

376
```python
377
import vlc
378
import time
379

380
def on_es_added(event):
381
    """Handle elementary stream (track) added."""
382
    print("New elementary stream added")
383

384
def on_es_deleted(event):
385
    """Handle elementary stream (track) deleted."""
386
    print("Elementary stream deleted")
387

388
def on_es_selected(event):
389
    """Handle elementary stream (track) selected."""
390
    print("Elementary stream selected")
391

392
def on_audio_volume(event):
393
    """Handle audio volume changes."""
394
    volume = event.u.volume
395
    print(f"Audio volume changed: {volume}")
396

397
def on_audio_device(event):
398
    """Handle audio device changes."""
399
    device = event.u.device
400
    print(f"Audio device changed: {device}")
401

402
# Create player with track events
403
player = vlc.MediaPlayer('/path/to/multilingual_video.mkv')
404
em = player.event_manager()
405

406
# Attach track and audio events
407
em.event_attach(vlc.EventType.MediaPlayerESAdded, on_es_added)
408
em.event_attach(vlc.EventType.MediaPlayerESDeleted, on_es_deleted)
409
em.event_attach(vlc.EventType.MediaPlayerESSelected, on_es_selected)
410
em.event_attach(vlc.EventType.MediaPlayerAudioVolume, on_audio_volume)
411
em.event_attach(vlc.EventType.MediaPlayerAudioDevice, on_audio_device)
412

413
# Start playbook and test track changes
414
player.play()
415
time.sleep(2)
416

417
# Change volume (triggers event)
418
player.audio_set_volume(75)
419

420
# Change audio track if available (triggers events)
421
track_count = player.audio_get_track_count()
422
if track_count > 1:
423
    player.audio_set_track(1)
424

425
time.sleep(5)
426
player.stop()
427
```
428

429
### Media List Events
430

431
```python
432
import vlc
433
import time
434

435
def on_item_added(event):
436
    """Handle media list item added."""
437
    item = event.u.item
438
    index = event.u.index
439
    print(f"Item added at index {index}: {item.get_mrl()}")
440

441
def on_will_add_item(event):
442
    """Handle media list will add item."""
443
    item = event.u.item
444
    index = event.u.index
445
    print(f"Will add item at index {index}")
446

447
def on_item_deleted(event):
448
    """Handle media list item deleted."""
449
    item = event.u.item
450
    index = event.u.index
451
    print(f"Item deleted from index {index}")
452

453
def on_end_reached(event):
454
    """Handle media list end reached."""
455
    print("End of media list reached")
456

457
# Create media list with events
458
instance = vlc.Instance()
459
media_list = instance.media_list_new()
460
em = media_list.event_manager()
461

462
# Attach media list events
463
em.event_attach(vlc.EventType.MediaListItemAdded, on_item_added)
464
em.event_attach(vlc.EventType.MediaListWillAddItem, on_will_add_item)
465
em.event_attach(vlc.EventType.MediaListItemDeleted, on_item_deleted)
466
em.event_attach(vlc.EventType.MediaListEndReached, on_end_reached)
467

468
# Add items (triggers events)
469
media1 = instance.media_new('/path/to/song1.mp3')
470
media2 = instance.media_new('/path/to/song2.mp3')
471

472
print("Adding media items...")
473
media_list.add_media(media1)
474
media_list.add_media(media2)
475

476
time.sleep(1)
477

478
# Remove item (triggers events)
479
print("Removing media item...")
480
media_list.remove_index(0)
481

482
time.sleep(1)
483
```
484

485
### Event Detachment and Cleanup
486

487
```python
488
import vlc
489
import time
490

491
def temp_callback(event):
492
    print("Temporary callback triggered")
493

494
# Create player and attach event
495
player = vlc.MediaPlayer('/path/to/video.mp4')
496
em = player.event_manager()
497

498
# Attach event
499
em.event_attach(vlc.EventType.MediaPlayerPlaying, temp_callback)
500

501
# Start playback (triggers event)
502
player.play()
503
time.sleep(2)
504

505
# Detach event
506
print("Detaching event...")
507
em.event_detach(vlc.EventType.MediaPlayerPlaying)
508

509
# Pause and resume (no longer triggers callback)
510
player.pause()
511
time.sleep(1)
512
player.play()  # Won't trigger temp_callback anymore
513
time.sleep(2)
514

515
player.stop()
516
```
517

518
### Custom Event Handler Class
519

520
```python
521
import vlc
522
import time
523

524
class MediaPlayerMonitor:
525
    def __init__(self, player):
526
        self.player = player
527
        self.event_manager = player.event_manager()
528
        self.setup_events()
529
        
530
    def setup_events(self):
531
        """Setup all event handlers."""
532
        events = {
533
            vlc.EventType.MediaPlayerPlaying: self.on_playing,
534
            vlc.EventType.MediaPlayerPaused: self.on_paused,
535
            vlc.EventType.MediaPlayerStopped: self.on_stopped,
536
            vlc.EventType.MediaPlayerEndReached: self.on_ended,
537
            vlc.EventType.MediaPlayerTimeChanged: self.on_time_changed,
538
            vlc.EventType.MediaPlayerPositionChanged: self.on_position_changed,
539
            vlc.EventType.MediaPlayerEncounteredError: self.on_error,
540
            vlc.EventType.MediaPlayerBuffering: self.on_buffering,
541
        }
542
        
543
        for event_type, handler in events.items():
544
            self.event_manager.event_attach(event_type, handler)
545
    
546
    def on_playing(self, event):
547
        print("▶️  Playing")
548
    
549
    def on_paused(self, event):
550
        print("⏸️  Paused")
551
    
552
    def on_stopped(self, event):
553
        print("⏹️  Stopped")
554
    
555
    def on_ended(self, event):
556
        print("🏁 Playback ended")
557
    
558
    def on_time_changed(self, event):
559
        time_ms = event.u.new_time
560
        minutes = time_ms // 60000
561
        seconds = (time_ms % 60000) // 1000
562
        print(f"⏰ Time: {minutes:02d}:{seconds:02d}")
563
    
564
    def on_position_changed(self, event):
565
        position = event.u.new_position
566
        print(f"📍 Position: {position:.1%}")
567
    
568
    def on_error(self, event):
569
        print("❌ Playback error occurred")
570
    
571
    def on_buffering(self, event):
572
        cache = event.u.new_cache
573
        print(f"📶 Buffering: {cache}%")
574
    
575
    def cleanup(self):
576
        """Detach all events."""
577
        events = [
578
            vlc.EventType.MediaPlayerPlaying,
579
            vlc.EventType.MediaPlayerPaused,
580
            vlc.EventType.MediaPlayerStopped,
581
            vlc.EventType.MediaPlayerEndReached,
582
            vlc.EventType.MediaPlayerTimeChanged,
583
            vlc.EventType.MediaPlayerPositionChanged,
584
            vlc.EventType.MediaPlayerEncounteredError,
585
            vlc.EventType.MediaPlayerBuffering,
586
        ]
587
        
588
        for event_type in events:
589
            self.event_manager.event_detach(event_type)
590

591
# Usage
592
player = vlc.MediaPlayer('/path/to/video.mp4')
593
monitor = MediaPlayerMonitor(player)
594

595
# Test playback with comprehensive monitoring
596
player.play()
597
time.sleep(10)
598
player.pause()
599
time.sleep(2)
600
player.play()
601
time.sleep(5)
602
player.stop()
603

604
# Cleanup when done
605
monitor.cleanup()
606
```