0
# Video Control
1
2
Video control capabilities including video tracks, aspect ratio, cropping, subtitle management, video effects, and display settings. These features provide comprehensive control over video playback and presentation.
3
4
## Capabilities
5
6
### Video Display Control
7
8
Basic video display and sizing methods available on MediaPlayer for managing video output and dimensions.
9
10
```python { .api }
11
# Video display methods on MediaPlayer
12
def video_get_width(self):
13
"""Get the video width in pixels.
14
15
Returns:
16
int: Video width, or 0 if no video
17
"""
18
...
19
20
def video_get_height(self):
21
"""Get the video height in pixels.
22
23
Returns:
24
int: Video height, or 0 if no video
25
"""
26
...
27
28
def video_get_size(self, num=0):
29
"""Get video dimensions as a tuple.
30
31
Args:
32
num (int): Video output number (usually 0)
33
34
Returns:
35
tuple: (width, height) or (0, 0) if no video
36
"""
37
...
38
39
def video_get_cursor(self, num=0):
40
"""Get cursor coordinates over video.
41
42
Args:
43
num (int): Video output number (usually 0)
44
45
Returns:
46
tuple: (x, y) cursor coordinates
47
"""
48
...
49
50
def video_get_scale(self):
51
"""Get the current video scaling factor.
52
53
Returns:
54
float: Scaling factor (1.0 = original size)
55
"""
56
...
57
58
def video_set_scale(self, scale):
59
"""Set the video scaling factor.
60
61
Args:
62
scale (float): Scaling factor (0 = fit to window, 1.0 = original size)
63
"""
64
...
65
66
def video_get_aspect_ratio(self):
67
"""Get the current video aspect ratio.
68
69
Returns:
70
str: Aspect ratio string (e.g., "4:3", "16:9") or None
71
"""
72
...
73
74
def video_set_aspect_ratio(self, ratio):
75
"""Set the video aspect ratio.
76
77
Args:
78
ratio (str): Aspect ratio string (e.g., "4:3", "16:9") or None for original
79
"""
80
...
81
```
82
83
### Video Cropping and Geometry
84
85
Methods for controlling video cropping and geometric transformations.
86
87
```python { .api }
88
# Video cropping methods on MediaPlayer
89
def video_get_crop_geometry(self):
90
"""Get the current video crop geometry.
91
92
Returns:
93
str: Crop geometry string or None
94
"""
95
...
96
97
def video_set_crop_geometry(self, geometry):
98
"""Set the video crop geometry.
99
100
Args:
101
geometry (str): Crop geometry string (e.g., "640x480+10+10") or None
102
"""
103
...
104
105
def video_get_teletext(self):
106
"""Get the current teletext page.
107
108
Returns:
109
int: Current teletext page number
110
"""
111
...
112
113
def video_set_teletext(self, page):
114
"""Set the teletext page.
115
116
Args:
117
page (int): Teletext page number
118
"""
119
...
120
121
def video_take_snapshot(self, num, filepath, width, height):
122
"""Take a video snapshot.
123
124
Args:
125
num (int): Video output number (usually 0)
126
filepath (str): Path to save the snapshot
127
width (int): Snapshot width (0 for original)
128
height (int): Snapshot height (0 for original)
129
130
Returns:
131
int: 0 on success, -1 on error
132
"""
133
...
134
135
def video_update_viewpoint(self, p_viewpoint, b_absolute):
136
"""Update viewpoint for 360° video navigation. (LibVLC 3.0.0+)
137
138
Args:
139
p_viewpoint: Video viewpoint structure (from libvlc_video_new_viewpoint())
140
b_absolute (bool): True to replace old viewpoint, False to increase/decrease
141
142
Returns:
143
int: 0 on success, -1 on error
144
"""
145
...
146
```
147
148
### 360° Video Support
149
150
Methods for controlling 360°/VR video playback and viewpoint navigation (LibVLC 3.0.0+).
151
152
```python { .api }
153
# 360° video support functions
154
def libvlc_video_new_viewpoint():
155
"""Create a video viewpoint structure for 360° video control.
156
157
Returns:
158
VideoViewpoint: New viewpoint structure (must be freed with libvlc_free)
159
"""
160
...
161
162
def video_update_viewpoint(self, p_viewpoint, b_absolute):
163
"""Update viewpoint for 360° video navigation.
164
165
Args:
166
p_viewpoint: Video viewpoint structure
167
b_absolute (bool): True to replace old viewpoint, False to modify current
168
169
Returns:
170
int: 0 on success, -1 on error
171
"""
172
...
173
```
174
175
### Video Track Management
176
177
Methods for managing video tracks in multi-track media.
178
179
```python { .api }
180
# Video track methods on MediaPlayer
181
def video_get_track_count(self):
182
"""Get the number of available video tracks.
183
184
Returns:
185
int: Number of video tracks
186
"""
187
...
188
189
def video_get_track(self):
190
"""Get the current video track.
191
192
Returns:
193
int: Current video track ID, or -1 if none
194
"""
195
...
196
197
def video_set_track(self, track):
198
"""Set the current video track.
199
200
Args:
201
track (int): Video track ID to select
202
203
Returns:
204
int: 0 on success, -1 on error
205
"""
206
...
207
208
def video_get_track_description(self):
209
"""Get descriptions of available video tracks.
210
211
Returns:
212
list: List of (track_id, track_name) tuples
213
"""
214
...
215
```
216
217
### Subtitle Management
218
219
Comprehensive subtitle control including subtitle track selection and subtitle file loading.
220
221
```python { .api }
222
# Subtitle methods on MediaPlayer
223
def video_get_spu_count(self):
224
"""Get the number of available subtitle tracks.
225
226
Returns:
227
int: Number of subtitle tracks
228
"""
229
...
230
231
def video_get_spu(self):
232
"""Get the current subtitle track.
233
234
Returns:
235
int: Current subtitle track ID, or -1 if none
236
"""
237
...
238
239
def video_set_spu(self, spu):
240
"""Set the current subtitle track.
241
242
Args:
243
spu (int): Subtitle track ID to select (-1 to disable)
244
245
Returns:
246
int: 0 on success, -1 on error
247
"""
248
...
249
250
def video_get_spu_description(self):
251
"""Get descriptions of available subtitle tracks.
252
253
Returns:
254
list: List of (spu_id, spu_name) tuples
255
"""
256
...
257
258
def video_set_subtitle_file(self, filename):
259
"""Load a subtitle file.
260
261
Args:
262
filename (str): Path to subtitle file
263
264
Returns:
265
bool: True on success, False on error
266
"""
267
...
268
269
def video_get_spu_delay(self):
270
"""Get the current subtitle delay in microseconds.
271
272
Returns:
273
int: Subtitle delay in microseconds
274
"""
275
...
276
277
def video_set_spu_delay(self, delay):
278
"""Set the subtitle delay.
279
280
Args:
281
delay (int): Subtitle delay in microseconds
282
283
Returns:
284
int: 0 on success, -1 on error
285
"""
286
...
287
```
288
289
### Video Filters and Effects
290
291
Methods for applying video filters and effects.
292
293
```python { .api }
294
# Video filter methods on MediaPlayer
295
def video_get_adjust_int(self, option):
296
"""Get a video adjustment integer value.
297
298
Args:
299
option (VideoAdjustOption): Adjustment option
300
301
Returns:
302
int: Current value
303
"""
304
...
305
306
def video_set_adjust_int(self, option, value):
307
"""Set a video adjustment integer value.
308
309
Args:
310
option (VideoAdjustOption): Adjustment option
311
value (int): Value to set
312
"""
313
...
314
315
def video_get_adjust_float(self, option):
316
"""Get a video adjustment float value.
317
318
Args:
319
option (VideoAdjustOption): Adjustment option
320
321
Returns:
322
float: Current value
323
"""
324
...
325
326
def video_set_adjust_float(self, option, value):
327
"""Set a video adjustment float value.
328
329
Args:
330
option (VideoAdjustOption): Adjustment option
331
value (float): Value to set
332
"""
333
...
334
335
def video_get_logo_int(self, option):
336
"""Get a video logo integer option.
337
338
Args:
339
option (VideoLogoOption): Logo option
340
341
Returns:
342
int: Current value
343
"""
344
...
345
346
def video_set_logo_int(self, option, value):
347
"""Set a video logo integer option.
348
349
Args:
350
option (VideoLogoOption): Logo option
351
value (int): Value to set
352
"""
353
...
354
355
def video_set_logo_string(self, option, value):
356
"""Set a video logo string option.
357
358
Args:
359
option (VideoLogoOption): Logo option
360
value (str): Value to set
361
"""
362
...
363
364
def video_get_marquee_int(self, option):
365
"""Get a video marquee integer option.
366
367
Args:
368
option (VideoMarqueeOption): Marquee option
369
370
Returns:
371
int: Current value
372
"""
373
...
374
375
def video_set_marquee_int(self, option, value):
376
"""Set a video marquee integer option.
377
378
Args:
379
option (VideoMarqueeOption): Marquee option
380
value (int): Value to set
381
"""
382
...
383
384
def video_set_marquee_string(self, option, value):
385
"""Set a video marquee string option.
386
387
Args:
388
option (VideoMarqueeOption): Marquee option
389
value (str): Value to set
390
"""
391
...
392
```
393
394
### Platform-Specific Display Integration
395
396
Methods for integrating with platform-specific display systems.
397
398
```python { .api }
399
# Platform display methods on MediaPlayer
400
def set_hwnd(self, hwnd):
401
"""Set Win32 window handle for video output.
402
403
Args:
404
hwnd (int): Windows window handle
405
"""
406
...
407
408
def get_hwnd(self):
409
"""Get the current Win32 window handle.
410
411
Returns:
412
int: Current window handle or 0
413
"""
414
...
415
416
def set_xwindow(self, xwindow):
417
"""Set X11 window ID for video output.
418
419
Args:
420
xwindow (int): X11 window ID
421
"""
422
...
423
424
def get_xwindow(self):
425
"""Get the current X11 window ID.
426
427
Returns:
428
int: Current X11 window ID or 0
429
"""
430
...
431
432
def set_nsobject(self, nsobject):
433
"""Set macOS NSObject for video output.
434
435
Args:
436
nsobject: macOS NSView or NSWindow object
437
"""
438
...
439
440
def get_nsobject(self):
441
"""Get the current macOS NSObject.
442
443
Returns:
444
NSObject or None
445
"""
446
...
447
448
def set_agl(self, agl):
449
"""Set macOS AGL context for video output.
450
451
Args:
452
agl: AGL context
453
"""
454
...
455
456
def get_agl(self):
457
"""Get the current macOS AGL context.
458
459
Returns:
460
AGL context or 0
461
"""
462
...
463
```
464
465
### Video Adjustment Options
466
467
Enumeration for video adjustment parameters.
468
469
```python { .api }
470
class VideoAdjustOption:
471
"""Video adjustment options for filters."""
472
Enable = 0
473
Contrast = 1
474
Brightness = 2
475
Hue = 3
476
Saturation = 4
477
Gamma = 5
478
```
479
480
### Video Logo Options
481
482
Enumeration for video logo overlay parameters.
483
484
```python { .api }
485
class VideoLogoOption:
486
"""Video logo overlay options."""
487
Enable = 0
488
File = 1
489
X = 2
490
Y = 3
491
Delay = 4
492
Repeat = 5
493
Opacity = 6
494
Position = 7
495
Size = 8
496
```
497
498
### Video Marquee Options
499
500
Enumeration for video marquee text overlay parameters.
501
502
```python { .api }
503
class VideoMarqueeOption:
504
"""Video marquee text overlay options."""
505
Enable = 0
506
Text = 1
507
Color = 2
508
Opacity = 3
509
Position = 4
510
Refresh = 5
511
Size = 6
512
Timeout = 7
513
X = 8
514
Y = 9
515
```
516
517
## Usage Examples
518
519
### Basic Video Information
520
521
```python
522
import vlc
523
524
player = vlc.MediaPlayer('/path/to/video.mp4')
525
player.play()
526
527
# Wait for video to start
528
import time
529
time.sleep(1)
530
531
# Get video dimensions
532
width = player.video_get_width()
533
height = player.video_get_height()
534
print(f"Video size: {width}x{height}")
535
536
# Get video size as tuple
537
size = player.video_get_size()
538
print(f"Video size tuple: {size}")
539
540
# Get and set aspect ratio
541
ratio = player.video_get_aspect_ratio()
542
print(f"Current aspect ratio: {ratio}")
543
player.video_set_aspect_ratio("16:9")
544
```
545
546
### Video Scaling and Cropping
547
548
```python
549
import vlc
550
551
player = vlc.MediaPlayer('/path/to/video.mp4')
552
player.play()
553
554
# Scale video to 150% of original size
555
player.video_set_scale(1.5)
556
current_scale = player.video_get_scale()
557
print(f"Current scale: {current_scale}")
558
559
# Set custom crop geometry (width x height + x_offset + y_offset)
560
player.video_set_crop_geometry("640x480+10+10")
561
crop = player.video_get_crop_geometry()
562
print(f"Current crop: {crop}")
563
564
# Reset to original size and no cropping
565
player.video_set_scale(1.0)
566
player.video_set_crop_geometry(None)
567
```
568
569
### Video Track Selection
570
571
```python
572
import vlc
573
574
player = vlc.MediaPlayer('/path/to/multi_video_stream.mkv')
575
player.play()
576
577
# List available video tracks
578
track_count = player.video_get_track_count()
579
print(f"Available video tracks: {track_count}")
580
581
tracks = player.video_get_track_description()
582
for track_id, track_name in tracks:
583
print(f"Video Track {track_id}: {track_name}")
584
585
# Select specific video track
586
if track_count > 1:
587
player.video_set_track(1)
588
current_track = player.video_get_track()
589
print(f"Current video track: {current_track}")
590
```
591
592
### Subtitle Management
593
594
```python
595
import vlc
596
597
player = vlc.MediaPlayer('/path/to/video.mp4')
598
player.play()
599
600
# Load external subtitle file
601
subtitle_loaded = player.video_set_subtitle_file('/path/to/subtitles.srt')
602
print(f"Subtitle loaded: {subtitle_loaded}")
603
604
# List available subtitle tracks
605
spu_count = player.video_get_spu_count()
606
print(f"Available subtitle tracks: {spu_count}")
607
608
spus = player.video_get_spu_description()
609
for spu_id, spu_name in spus:
610
print(f"Subtitle Track {spu_id}: {spu_name}")
611
612
# Select subtitle track
613
if spu_count > 0:
614
player.video_set_spu(1) # Enable first subtitle track
615
current_spu = player.video_get_spu()
616
print(f"Current subtitle track: {current_spu}")
617
618
# Adjust subtitle delay (100ms forward)
619
player.video_set_spu_delay(100000) # 100000 microseconds = 100ms
620
delay = player.video_get_spu_delay()
621
print(f"Subtitle delay: {delay} microseconds")
622
```
623
624
### Taking Video Snapshots
625
626
```python
627
import vlc
628
import time
629
630
player = vlc.MediaPlayer('/path/to/video.mp4')
631
player.play()
632
633
# Wait for video to start
634
time.sleep(2)
635
636
# Take snapshot with original dimensions
637
result = player.video_take_snapshot(0, '/path/to/snapshot.png', 0, 0)
638
if result == 0:
639
print("Snapshot saved successfully")
640
else:
641
print("Failed to take snapshot")
642
643
# Take snapshot with custom dimensions
644
result = player.video_take_snapshot(0, '/path/to/thumbnail.png', 320, 240)
645
if result == 0:
646
print("Thumbnail saved successfully")
647
```
648
649
### Video Filters and Effects
650
651
```python
652
import vlc
653
654
player = vlc.MediaPlayer('/path/to/video.mp4')
655
player.play()
656
657
# Enable and adjust video brightness/contrast
658
player.video_set_adjust_int(vlc.VideoAdjustOption.Enable, 1)
659
player.video_set_adjust_float(vlc.VideoAdjustOption.Brightness, 1.2) # 20% brighter
660
player.video_set_adjust_float(vlc.VideoAdjustOption.Contrast, 1.5) # 50% more contrast
661
662
# Get current adjustment values
663
brightness = player.video_get_adjust_float(vlc.VideoAdjustOption.Brightness)
664
contrast = player.video_get_adjust_float(vlc.VideoAdjustOption.Contrast)
665
print(f"Brightness: {brightness}, Contrast: {contrast}")
666
667
# Add logo overlay
668
player.video_set_logo_int(vlc.VideoLogoOption.Enable, 1)
669
player.video_set_logo_string(vlc.VideoLogoOption.File, '/path/to/logo.png')
670
player.video_set_logo_int(vlc.VideoLogoOption.X, 10)
671
player.video_set_logo_int(vlc.VideoLogoOption.Y, 10)
672
player.video_set_logo_int(vlc.VideoLogoOption.Opacity, 128) # 50% opacity
673
674
# Add text marquee
675
player.video_set_marquee_int(vlc.VideoMarqueeOption.Enable, 1)
676
player.video_set_marquee_string(vlc.VideoMarqueeOption.Text, "Sample Video")
677
player.video_set_marquee_int(vlc.VideoMarqueeOption.X, 100)
678
player.video_set_marquee_int(vlc.VideoMarqueeOption.Y, 50)
679
player.video_set_marquee_int(vlc.VideoMarqueeOption.Opacity, 255) # Fully opaque
680
```
681
682
### Platform-Specific Display Integration
683
684
```python
685
import vlc
686
687
# Windows example
688
if hasattr(vlc.MediaPlayer, 'set_hwnd'):
689
import tkinter as tk
690
691
root = tk.Tk()
692
root.geometry("640x480")
693
694
player = vlc.MediaPlayer('/path/to/video.mp4')
695
# Get window handle (Windows specific)
696
hwnd = root.winfo_id()
697
player.set_hwnd(hwnd)
698
player.play()
699
700
root.mainloop()
701
702
# Linux X11 example
703
elif hasattr(vlc.MediaPlayer, 'set_xwindow'):
704
import tkinter as tk
705
706
root = tk.Tk()
707
root.geometry("640x480")
708
709
player = vlc.MediaPlayer('/path/to/video.mp4')
710
# Get X11 window ID
711
xwindow = root.winfo_id()
712
player.set_xwindow(xwindow)
713
player.play()
714
715
root.mainloop()
716
```