0
# Audio Control
1

2
Comprehensive audio control including volume, equalizer, audio tracks, and audio output device management. These capabilities provide complete control over audio playback and processing.
3

4
## Capabilities
5

6
### Audio Playback Control
7

8
Basic audio control methods available on MediaPlayer for managing volume, mute state, and audio tracks.
9

10
```python { .api }
11
# Audio control methods on MediaPlayer
12
def audio_get_volume(self):
13
    """Get the current audio volume.
14
    
15
    Returns:
16
        int: Volume level (0-100), or -1 on error
17
    """
18
    ...
19

20
def audio_set_volume(self, volume):
21
    """Set the audio volume.
22
    
23
    Args:
24
        volume (int): Volume level (0-100)
25
        
26
    Returns:
27
        int: 0 on success, -1 on error
28
    """
29
    ...
30

31
def audio_get_mute(self):
32
    """Get the mute status.
33
    
34
    Returns:
35
        bool: True if muted, False otherwise
36
    """
37
    ...
38

39
def audio_set_mute(self, mute):
40
    """Set the mute status.
41
    
42
    Args:
43
        mute (bool): True to mute, False to unmute
44
    """
45
    ...
46

47
def audio_toggle_mute(self):
48
    """Toggle the mute status."""
49
    ...
50

51
def audio_get_track_count(self):
52
    """Get the number of available audio tracks.
53
    
54
    Returns:
55
        int: Number of audio tracks
56
    """
57
    ...
58

59
def audio_get_track(self):
60
    """Get the current audio track.
61
    
62
    Returns:
63
        int: Current audio track ID, or -1 if none
64
    """
65
    ...
66

67
def audio_set_track(self, track):
68
    """Set the current audio track.
69
    
70
    Args:
71
        track (int): Audio track ID to select
72
        
73
    Returns:
74
        int: 0 on success, -1 on error
75
    """
76
    ...
77

78
def audio_get_track_description(self):
79
    """Get descriptions of available audio tracks.
80
    
81
    Returns:
82
        list: List of (track_id, track_name) tuples
83
    """
84
    ...
85

86
def audio_get_delay(self):
87
    """Get the current audio delay in microseconds.
88
    
89
    Returns:
90
        int: Audio delay in microseconds
91
    """
92
    ...
93

94
def audio_set_delay(self, delay):
95
    """Set the audio delay.
96
    
97
    Args:
98
        delay (int): Audio delay in microseconds
99
        
100
    Returns:
101
        int: 0 on success, -1 on error
102
    """
103
    ...
104

105
def audio_get_channel(self):
106
    """Get the audio channel configuration.
107
    
108
    Returns:
109
        AudioOutputChannel: Current audio channel mode
110
    """
111
    ...
112

113
def audio_set_channel(self, channel):
114
    """Set the audio channel configuration.
115
    
116
    Args:
117
        channel (AudioOutputChannel): Channel configuration to set
118
        
119
    Returns:
120
        int: 0 on success, -1 on error
121
    """
122
    ...
123
```
124

125
### Audio Equalizer
126

127
The AudioEqualizer class provides comprehensive equalizer control with frequency band adjustment and preset management.
128

129
```python { .api }
130
class AudioEqualizer:
131
    def __init__(self):
132
        """Create a new audio equalizer."""
133
        ...
134
    
135
    @staticmethod
136
    def create():
137
        """Create a new audio equalizer instance.
138
        
139
        Note: Use AudioEqualizer() constructor directly in Python-VLC.
140
        
141
        Returns:
142
            AudioEqualizer: New equalizer instance
143
        """
144
        ...
145
    
146
    def release(self):
147
        """Release the equalizer instance."""
148
        ...
149
    
150
    def set_preamp(self, preamp):
151
        """Set the equalizer pre-amplification value.
152
        
153
        Args:
154
            preamp (float): Pre-amplification value in dB (-20.0 to 20.0)
155
            
156
        Returns:
157
            int: 0 on success, -1 on error
158
        """
159
        ...
160
    
161
    def get_preamp(self):
162
        """Get the equalizer pre-amplification value.
163
        
164
        Returns:
165
            float: Pre-amplification value in dB
166
        """
167
        ...
168
    
169
    def set_amp_at_index(self, amp, band):
170
        """Set the amplification value for a specific frequency band.
171
        
172
        Args:
173
            amp (float): Amplification value in dB (-20.0 to 20.0)
174
            band (int): Band index (0-9 for 10-band equalizer)
175
            
176
        Returns:
177
            int: 0 on success, -1 on error
178
        """
179
        ...
180
    
181
    def get_amp_at_index(self, band):
182
        """Get the amplification value for a specific frequency band.
183
        
184
        Args:
185
            band (int): Band index (0-9 for 10-band equalizer)
186
            
187
        Returns:
188
            float: Amplification value in dB
189
        """
190
        ...
191
    
192
    @staticmethod
193
    def get_band_count():
194
        """Get the number of equalizer bands.
195
        
196
        Note: Use vlc.libvlc_audio_equalizer_get_band_count() in Python-VLC.
197
        
198
        Returns:
199
            int: Number of bands (typically 10)
200
        """
201
        ...
202
    
203
    @staticmethod
204
    def get_band_frequency(band):
205
        """Get the frequency for a specific band.
206
        
207
        Note: Use vlc.libvlc_audio_equalizer_get_band_frequency() in Python-VLC.
208
        
209
        Args:
210
            band (int): Band index (0-based)
211
            
212
        Returns:
213
            float: Frequency in Hz, or -1.0 if invalid band
214
        """
215
        ...
216
    
217
    @staticmethod
218
    def get_preset_count():
219
        """Get the number of available equalizer presets.
220
        
221
        Note: Use vlc.libvlc_audio_equalizer_get_preset_count() in Python-VLC.
222
        
223
        Returns:
224
            int: Number of presets
225
        """
226
        ...
227
    
228
    @staticmethod
229
    def get_preset_name(preset):
230
        """Get the name of a specific preset.
231
        
232
        Note: Use vlc.libvlc_audio_equalizer_get_preset_name() in Python-VLC.
233
        
234
        Args:
235
            preset (int): Preset index (0-based)
236
            
237
        Returns:
238
            str: Preset name or None if invalid
239
        """
240
        ...
241
    
242
    @staticmethod
243
    def create_from_preset(preset):
244
        """Create an equalizer from a preset.
245
        
246
        Note: Use vlc.libvlc_audio_equalizer_new_from_preset() in Python-VLC.
247
        
248
        Args:
249
            preset (int): Preset index (0-based)
250
            
251
        Returns:
252
            AudioEqualizer: New equalizer with preset values or None on error
253
        """
254
        ...
255
```
256

257
### Audio Output Management
258

259
Audio output device enumeration and selection capabilities available through the Instance class.
260

261
```python { .api }
262
# Audio output methods on Instance
263
def audio_output_enumerate(self):
264
    """Enumerate available audio output modules.
265
    
266
    Returns:
267
        list: List of (module_name, description) tuples
268
    """
269
    ...
270

271
def audio_output_enumerate_devices(self, audio_output=None):
272
    """Enumerate available audio output devices.
273
    
274
    Args:
275
        audio_output (str, optional): Audio output module name
276
        
277
    Returns:
278
        list: List of (device_id, device_name) tuples
279
    """
280
    ...
281

282
def audio_output_set_device_type(self, device_type):
283
    """Set the audio output device type.
284
    
285
    Args:
286
        device_type (AudioOutputDeviceType): Device type to set
287
        
288
    Returns:
289
        int: 0 on success, -1 on error
290
    """
291
    ...
292

293
def audio_output_get_device_type(self):
294
    """Get the current audio output device type.
295
    
296
    Returns:
297
        AudioOutputDeviceType: Current device type
298
    """
299
    ...
300

301
# Audio output methods on MediaPlayer
302
def audio_output_set(self, audio_output):
303
    """Set the audio output module.
304
    
305
    Args:
306
        audio_output (str): Audio output module name
307
        
308
    Returns:
309
        int: 0 on success, -1 on error
310
    """
311
    ...
312

313
def audio_output_device_enum(self):
314
    """Enumerate audio output devices for current output module.
315
    
316
    Returns:
317
        list: List of available audio devices
318
    """
319
    ...
320

321
def audio_output_device_set(self, device_id):
322
    """Set the audio output device.
323
    
324
    Args:
325
        device_id (str): Device identifier
326
        
327
    Returns:
328
        int: 0 on success, -1 on error
329
    """
330
    ...
331

332
def audio_output_device_get(self):
333
    """Get the current audio output device. (LibVLC 3.0.0+)
334
    
335
    Returns:
336
        str: Current device identifier or None
337
    """
338
    ...
339
```
340

341
### Audio Channel Configuration
342

343
Enumeration for audio channel configurations.
344

345
```python { .api }
346
class AudioOutputChannel:
347
    """Audio output channel configuration."""
348
    Error = -1
349
    Stereo = 1
350
    RStereo = 2
351
    Left = 3
352
    Right = 4
353
    Dolby = 5
354
```
355

356
### Audio Device Types
357

358
Enumeration for audio output device types.
359

360
```python { .api }
361
class AudioOutputDeviceType:
362
    """Audio output device types."""
363
    Error = -1
364
    Mono = 1
365
    Stereo = 2
366
    _2F2R = 4
367
    _3F2R = 5
368
    _5_1 = 6
369
    _6_1 = 7
370
    _7_1 = 8
371
    SPDIF = 10
372
```
373

374
## Usage Examples
375

376
### Basic Volume Control
377

378
```python
379
import vlc
380

381
player = vlc.MediaPlayer('/path/to/audio.mp3')
382
player.play()
383

384
# Set volume to 80%
385
player.audio_set_volume(80)
386

387
# Get current volume
388
volume = player.audio_get_volume()
389
print(f"Current volume: {volume}%")
390

391
# Mute/unmute
392
player.audio_set_mute(True)
393
print(f"Muted: {player.audio_get_mute()}")
394
player.audio_toggle_mute()
395
```
396

397
### Audio Track Selection
398

399
```python
400
import vlc
401

402
player = vlc.MediaPlayer('/path/to/multilingual_video.mp4')
403
player.play()
404

405
# Get available audio tracks
406
track_count = player.audio_get_track_count()
407
print(f"Available audio tracks: {track_count}")
408

409
# Get track descriptions
410
tracks = player.audio_get_track_description()
411
for track_id, track_name in tracks:
412
    print(f"Track {track_id}: {track_name}")
413

414
# Select a specific audio track
415
player.audio_set_track(1)
416
print(f"Current track: {player.audio_get_track()}")
417
```
418

419
### Equalizer Usage
420

421
```python
422
import vlc
423

424
# Create equalizer from preset (using global function)
425
eq = vlc.libvlc_audio_equalizer_new_from_preset(2)  # Rock preset
426
# Or create empty equalizer
427
eq = vlc.AudioEqualizer()
428

429
# Get preset information (using global functions)
430
preset_count = vlc.libvlc_audio_equalizer_get_preset_count()
431
for i in range(preset_count):
432
    name = vlc.libvlc_audio_equalizer_get_preset_name(i)
433
    print(f"Preset {i}: {name}")
434

435
# Customize equalizer
436
eq.set_preamp(3.0)  # Boost pre-amp by 3dB
437
eq.set_amp_at_index(5.0, 0)  # Boost first band by 5dB
438

439
# Apply equalizer to player
440
player = vlc.MediaPlayer('/path/to/audio.mp3')
441
player.audio_set_equalizer(eq)  # Apply the equalizer settings
442

443
# Get band information (using global functions)
444
band_count = vlc.libvlc_audio_equalizer_get_band_count()
445
for i in range(band_count):
446
    freq = vlc.libvlc_audio_equalizer_get_band_frequency(i)
447
    amp = eq.get_amp_at_index(i)
448
    print(f"Band {i}: {freq}Hz = {amp}dB")
449
```
450

451
### Audio Output Device Selection
452

453
```python
454
import vlc
455

456
instance = vlc.Instance()
457

458
# List available audio output modules
459
outputs = instance.audio_output_enumerate()
460
for module, description in outputs:
461
    print(f"Module: {module} - {description}")
462

463
# List audio devices for default output
464
devices = instance.audio_output_enumerate_devices()
465
for device_id, device_name in devices:
466
    print(f"Device: {device_id} - {device_name}")
467

468
# Set specific audio output device
469
player = vlc.MediaPlayer('/path/to/audio.mp3')
470
player.audio_output_device_set('pulse')  # Use PulseAudio on Linux
471

472
# Get current device
473
current_device = player.audio_output_device_get()
474
print(f"Current audio device: {current_device}")
475
```
476

477
### Audio Delay Adjustment
478

479
```python
480
import vlc
481

482
player = vlc.MediaPlayer('/path/to/video.mp4')
483
player.play()
484

485
# Get current audio delay
486
delay = player.audio_get_delay()
487
print(f"Current audio delay: {delay} microseconds")
488

489
# Adjust audio delay (positive = audio after video, negative = audio before video)
490
player.audio_set_delay(100000)  # 100ms delay
491

492
# Set audio channel configuration
493
player.audio_set_channel(vlc.AudioOutputChannel.Stereo)
494
current_channel = player.audio_get_channel()
495
print(f"Audio channel mode: {current_channel}")
496
```