0
# Python-VLC
1

2
Comprehensive Python ctypes-based bindings for LibVLC, enabling developers to embed video and audio playback functionality directly into Python applications. Python-VLC provides both high-level wrapper classes with pythonic APIs and low-level direct access to all LibVLC functions for advanced use cases.
3

4
## Package Information
5

6
- **Package Name**: python-vlc
7
- **Language**: Python
8
- **Installation**: `pip install python-vlc`
9
- **Version**: 3.0.21203
10
- **LibVLC Version**: 3.0.21
11

12
## Core Imports
13

14
```python
15
import vlc
16
```
17

18
All functionality is available through the `vlc` module namespace.
19

20
## Basic Usage
21

22
### Simple Media Player
23

24
```python
25
import vlc
26

27
# Create a media player with a file
28
player = vlc.MediaPlayer('file:///path/to/video.mp4')
29
player.play()
30

31
# Control playback
32
player.pause()
33
player.stop()
34

35
# Get playback information
36
duration = player.get_length()  # in milliseconds
37
current_time = player.get_time()  # in milliseconds
38
```
39

40
### Using Instance for Advanced Control
41

42
```python
43
import vlc
44

45
# Create VLC instance with options
46
instance = vlc.Instance('--no-audio', '--quiet')
47

48
# Create media and player from instance
49
media = instance.media_new('file:///path/to/video.mp4')
50
player = instance.media_player_new()
51
player.set_media(media)
52

53
# Start playback
54
player.play()
55

56
# Access metadata
57
media.parse()
58
title = media.get_meta(vlc.Meta.Title)
59
duration = media.get_duration()
60
```
61

62
### Event Handling
63

64
```python
65
import vlc
66

67
def media_state_callback(event):
68
    print(f"Media state changed: {event.u.new_state}")
69

70
player = vlc.MediaPlayer()
71
event_manager = player.event_manager()
72
event_manager.event_attach(vlc.EventType.MediaPlayerMediaChanged, media_state_callback)
73
```
74

75
## Architecture
76

77
Python-VLC provides a layered architecture for maximum flexibility:
78

79
- **High-level Wrapper Classes**: Pythonic interface (`Instance`, `MediaPlayer`, `Media`, etc.)
80
- **Low-level Function Access**: Direct access to all `libvlc_*` functions
81
- **Event System**: Comprehensive event handling for media state changes
82
- **Cross-platform Support**: Automatic library discovery on Linux, Windows, and macOS
83
- **UI Framework Integration**: Examples for Qt, GTK, Tkinter, wxPython, and Cocoa
84

85
The wrapper classes provide convenient Python idioms while maintaining access to the full LibVLC API for advanced use cases.
86

87
## Capabilities
88

89
### Core Media Playback
90

91
Essential media playback functionality including media players, media objects, and basic playback control. These classes form the foundation for any media application.
92

93
```python { .api }
94
class Instance:
95
    def __init__(self, *args): ...
96
    def media_player_new(self, uri=None): ...
97
    def media_new(self, mrl, *options): ...
98
    def media_new_path(self, path): ...
99

100
class MediaPlayer:
101
    def __init__(self, *args): ...
102
    def play(self): ...
103
    def pause(self): ...
104
    def stop(self): ...
105
    def set_media(self, media): ...
106
    def get_media(self): ...
107
    def get_time(self): ...
108
    def set_time(self, time): ...
109
    def get_length(self): ...
110
    def add_slave(self, i_type, psz_uri, b_select): ...  # LibVLC 3.0.0+
111
    def set_renderer(self, p_renderer): ...  # LibVLC 3.0.0+
112

113
class Media:
114
    def parse_with_options(self, parse_flag, timeout): ...  # LibVLC 3.0.0+ [RECOMMENDED]
115
    def get_parsed_status(self): ...  # LibVLC 3.0.0+
116
    def parse(self): ...  # [DEPRECATED - use parse_with_options]
117
    def get_meta(self, meta_type): ...
118
    def get_duration(self): ...
119
    def get_mrl(self): ...
120
    def slaves_add(self, i_type, i_priority, psz_uri): ...  # LibVLC 3.0.0+
121
```
122

123
[Core Media Playback](./core-playback.md)
124

125
### Audio Control
126

127
Comprehensive audio control including volume, equalizer, audio tracks, and audio output device management.
128

129
```python { .api }
130
# Audio control methods on MediaPlayer
131
def audio_get_volume(self): ...
132
def audio_set_volume(self, volume): ...
133
def audio_get_track(self): ...
134
def audio_set_track(self, track): ...
135
def audio_get_delay(self): ...
136
def audio_set_delay(self, delay): ...
137
def audio_output_device_get(self): ...  # LibVLC 3.0.0+
138

139
class AudioEqualizer:
140
    def __init__(self): ...
141
    def set_preamp(self, preamp): ...
142
    def get_preamp(self): ...
143
    def set_amp_at_index(self, amp, band): ...
144
    def get_amp_at_index(self, band): ...
145
    def release(self): ...
146
```
147

148
[Audio Control](./audio-control.md)
149

150
### Video Control
151

152
Video control capabilities including video tracks, aspect ratio, cropping, subtitle management, video effects, and display settings.
153

154
```python { .api }
155
# Video control methods on MediaPlayer
156
def video_get_width(self): ...
157
def video_get_height(self): ...
158
def video_get_aspect_ratio(self): ...
159
def video_set_aspect_ratio(self, ratio): ...
160
def video_get_crop_geometry(self): ...
161
def video_set_crop_geometry(self, geometry): ...
162
def video_take_snapshot(self, num, filepath, width, height): ...
163
def video_get_spu(self): ...
164
def video_set_spu(self, spu): ...
165
def video_set_subtitle_file(self, filename): ...
166
```
167

168
[Video Control](./video-control.md)
169

170
### Media Lists and Playlists
171

172
Media list management for creating and controlling playlists with sequential or custom playback modes.
173

174
```python { .api }
175
class MediaList:
176
    def __init__(self, instance=None): ...
177
    def add_media(self, media): ...
178
    def insert_media(self, media, index): ...
179
    def remove_index(self, index): ...
180
    def count(self): ...
181
    def item_at_index(self, index): ...
182

183
class MediaListPlayer:
184
    def __init__(self, instance=None): ...
185
    def set_media_list(self, media_list): ...
186
    def play(self): ...
187
    def pause(self): ...
188
    def stop(self): ...
189
    def next(self): ...
190
    def previous(self): ...
191
    def set_playback_mode(self, mode): ...
192
```
193

194
[Media Lists and Playlists](./media-lists.md)
195

196
### Event System
197

198
Comprehensive event handling system for responding to media state changes, playback events, and user interactions.
199

200
```python { .api }
201
class EventManager:
202
    def event_attach(self, event_type, callback, user_data=None): ...
203
    def event_detach(self, event_type): ...
204

205
class EventType:
206
    MediaMetaChanged = ...
207
    MediaPlayerTimeChanged = ...
208
    MediaPlayerPositionChanged = ...
209
    MediaPlayerPlaying = ...
210
    MediaPlayerPaused = ...
211
    MediaPlayerStopped = ...
212
    # ... many more event types
213
```
214

215
[Event System](./event-system.md)
216

217
### Media Discovery and Renderers
218

219
Network media discovery, renderer discovery for casting, and media library management capabilities.
220

221
```python { .api }
222
class MediaDiscoverer:
223
    def __init__(self, instance, service_name): ...
224
    def start(self): ...
225
    def stop(self): ...
226
    def media_list(self): ...
227

228
class RendererDiscoverer: 
229
    def start(self): ...
230
    def stop(self): ...
231
    def event_manager(self): ...
232
    def release(self): ...
233

234
class Renderer:
235
    def name(self): ...
236
    def type(self): ...
237
    def flags(self): ...
238
    def icon_uri(self): ...
239
    def hold(self): ...
240
    def release(self): ...
241
```
242

243
[Media Discovery and Renderers](./discovery-renderers.md)
244

245
### Low-Level LibVLC Functions
246

247
Direct access to all LibVLC C API functions for advanced use cases and maximum control.
248

249
```python { .api }
250
# Core functions (400+ available in LibVLC 3.0)
251
def libvlc_new(argc, argv): ...
252
def libvlc_release(instance): ...
253
def libvlc_media_new_location(instance, mrl): ...
254
def libvlc_media_new_callbacks(instance, open_cb, read_cb, seek_cb, close_cb, opaque): ...  # 3.0.0+
255
def libvlc_media_player_play(player): ...
256
def libvlc_media_player_set_renderer(player, renderer): ...  # 3.0.0+
257
def libvlc_audio_set_volume(player, volume): ...
258
def libvlc_video_get_size(player, num): ...
259
def libvlc_renderer_discoverer_new(instance, service_name): ...  # 3.0.0+
260
# ... hundreds more libvlc_* functions
261
```
262

263
[Low-Level LibVLC Functions](./low-level-functions.md)
264

265
### Data Structures and Enums
266

267
Complete type definitions, enumerations, and data structures used throughout the API.
268

269
```python { .api }
270
class State:
271
    NothingSpecial = 0
272
    Opening = 1
273
    Buffering = 2
274
    Playing = 3
275
    Paused = 4
276
    Stopped = 5
277
    Ended = 6
278
    Error = 7
279

280
class Meta:
281
    Title = 0
282
    Artist = 1
283
    Genre = 2
284
    Copyright = 3
285
    Album = 4
286
    # ... more metadata types
287

288
class MediaType:
289
    Unknown = 0
290
    File = 1
291
    Directory = 2
292
    Disc = 3
293
    Stream = 4
294
    Playlist = 5
295
```
296

297
[Data Structures and Enums](./data-structures.md)