1 /*****************************************************************************
2 * pulse.c : Pulseaudio output plugin for vlc
3 *****************************************************************************
4 * Copyright (C) 2008 the VideoLAN team
5 * Copyright (C) 2009-2011 RĂ©mi Denis-Courmont
7 * Authors: Martin Hamrle <hamrle @ post . cz>
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22 *****************************************************************************/
28 #include <vlc_common.h>
29 #include <vlc_plugin.h>
33 #include <pulse/pulseaudio.h>
34 #include <vlc_pulse.h>
36 static int Open ( vlc_object_t * );
37 static void Close ( vlc_object_t * );
40 set_shortname( "PulseAudio" )
41 set_description( N_("Pulseaudio audio output") )
42 set_capability( "audio output", 160 )
43 set_category( CAT_AUDIO )
44 set_subcategory( SUBCAT_AUDIO_AOUT )
45 add_shortcut( "pulseaudio", "pa" )
46 set_callbacks( Open, Close )
50 * - pause input on policy event
51 * - resample to compensate for long term drift
52 * - select music or video stream property correctly (?)
53 * - set further appropriate stream properties
54 * - update output devices list dynamically
58 * Be careful what you do when the PulseAudio mainloop is held, which is to say
59 * within PulseAudio callbacks, or after vlc_pa_lock().
60 * In particular, a VLC variable callback cannot be triggered nor deleted with
61 * the PulseAudio mainloop lock held, if the callback acquires the lock. */
65 pa_stream *stream; /**< PulseAudio playback stream object */
66 pa_context *context; /**< PulseAudio connection context */
67 pa_volume_t base_volume; /**< 0dB reference volume */
68 pa_cvolume cvolume; /**< actual sink input volume */
69 mtime_t pts; /**< Play time of buffer write offset */
70 mtime_t desync; /**< Measured desynchronization */
71 unsigned rate; /**< Current stream sample rate */
75 static void sink_list_cb(pa_context *c, const pa_sink_info *i, int eol,
78 audio_output_t *aout = userdata;
79 vlc_value_t val, text;
85 msg_Dbg(aout, "listing sink %s (%"PRIu32"): %s", i->name, i->index,
88 text.psz_string = (char *)i->description;
89 var_Change(aout, "audio-device", VLC_VAR_ADDCHOICE, &val, &text);
92 static void sink_info_cb(pa_context *c, const pa_sink_info *i, int eol,
95 audio_output_t *aout = userdata;
96 aout_sys_t *sys = aout->sys;
102 /* PulseAudio flat volume NORM / 100% / 0dB corresponds to no software
103 * amplification and maximum hardware amplification.
104 * VLC maps DEFAULT / 100% to no gain at all (software/hardware).
105 * Thus we need to use the sink base_volume as a multiplier,
106 * if and only if flat volume is active for our current sink. */
107 if (i->flags & PA_SINK_FLAT_VOLUME)
108 sys->base_volume = i->base_volume;
110 sys->base_volume = PA_VOLUME_NORM;
111 msg_Dbg(aout, "base volume: %f", pa_sw_volume_to_linear(sys->base_volume));
114 /*** Stream helpers ***/
115 static void stream_reset_sync(pa_stream *s, audio_output_t *aout)
117 aout_sys_t *sys = aout->sys;
118 const unsigned rate = aout->format.i_rate;
120 sys->pts = VLC_TS_INVALID;
122 pa_operation *op = pa_stream_update_sample_rate(s, rate, NULL, NULL);
123 if (unlikely(op == NULL))
125 pa_operation_unref(op);
129 static void stream_state_cb(pa_stream *s, void *userdata)
131 switch (pa_stream_get_state(s)) {
132 case PA_STREAM_READY:
133 case PA_STREAM_FAILED:
134 case PA_STREAM_TERMINATED:
142 /* Latency management and lip synchronization */
143 static void stream_latency_cb(pa_stream *s, void *userdata)
145 audio_output_t *aout = userdata;
146 aout_sys_t *sys = aout->sys;
147 mtime_t delta, change;
149 if (sys->pts == VLC_TS_INVALID)
151 msg_Dbg(aout, "missing latency from input");
155 /* Compute lip desynchronization */
160 if (pa_stream_get_latency(s, &latency, &negative)) {
161 vlc_pa_error(aout, "missing latency", sys->context);
164 delta = sys->pts - mdate();
165 if (unlikely(negative))
171 change = delta - sys->desync;
173 //msg_Dbg(aout, "desync: %+"PRId64" us (variation: %+"PRId64" us)",
176 if (delta < -AOUT_MAX_PTS_DELAY)
177 msg_Warn(aout, "too late by %"PRId64" us", -delta);
178 else if (delta > +AOUT_MAX_PTS_ADVANCE)
179 msg_Warn(aout, "too early by %"PRId64" us", delta);
181 /* Compute playback sample rate */
182 const unsigned inrate = aout->format.i_rate;
184 #define ADJUST_FACTOR 4
185 #define ADJUST_MAX 1000 /* Hz (max rate variation per call) */
186 /* This is empirical. Feel free to define something smarter. */
187 int adj = sys->rate * (delta + change) / (CLOCK_FREQ * ADJUST_FACTOR);
189 /* This avoids too fast rate variation. They sound ugly as hell and they
190 * make the algorithm unstable (e.g. oscillation around inrate). */
191 if (adj > +ADJUST_MAX)
193 if (adj < -ADJUST_MAX)
196 unsigned outrate = sys->rate - adj;
197 /* Favor native rate to avoid resampling (FIXME: really a good idea?) */
198 if (abs(outrate - inrate) < (inrate >> 10))
201 /* This keeps the effective rate within specified range
202 * (+/-AOUT_MAX_RESAMPLING% - see <vlc_aout.h>) of the nominal rate. */
203 const int limit = inrate * AOUT_MAX_RESAMPLING / 100;
204 if (outrate > inrate + limit)
205 outrate = inrate + limit;
206 if (outrate < inrate - limit)
207 outrate = inrate - limit;
209 /* Apply adjusted sample rate */
210 if (outrate == sys->rate)
212 pa_operation *op = pa_stream_update_sample_rate(s, outrate, NULL, NULL);
213 if (unlikely(op == NULL)) {
214 vlc_pa_error(aout, "cannot change sample rate", sys->context);
217 pa_operation_unref(op);
218 msg_Dbg(aout, "changed sample rate to %u Hz",outrate);
222 static void stream_moved_cb(pa_stream *s, void *userdata)
224 audio_output_t *aout = userdata;
225 aout_sys_t *sys = aout->sys;
227 uint32_t idx = pa_stream_get_device_index(s);
229 msg_Dbg(aout, "connected to sink %"PRIu32": %s", idx,
230 pa_stream_get_device_name(s));
231 op = pa_context_get_sink_info_by_index(sys->context, idx,
233 if (likely(op != NULL))
234 pa_operation_unref(op);
236 /* Update the variable if someone else moved our stream */
237 var_Change(aout, "audio-device", VLC_VAR_SETVALUE,
238 &(vlc_value_t){ .i_int = idx }, NULL);
241 static void stream_overflow_cb(pa_stream *s, void *userdata)
243 audio_output_t *aout = userdata;
245 msg_Err(aout, "overflow");
249 static void stream_started_cb(pa_stream *s, void *userdata)
251 audio_output_t *aout = userdata;
253 msg_Dbg(aout, "started");
257 static void stream_suspended_cb(pa_stream *s, void *userdata)
259 audio_output_t *aout = userdata;
261 msg_Dbg(aout, "suspended");
262 stream_reset_sync(s, aout);
265 static void stream_underflow_cb(pa_stream *s, void *userdata)
267 audio_output_t *aout = userdata;
270 msg_Warn(aout, "underflow");
271 op = pa_stream_cork(s, 1, NULL, NULL);
273 pa_operation_unref(op);
274 stream_reset_sync(s, aout);
277 static int stream_wait(pa_stream *stream)
279 pa_stream_state_t state;
281 while ((state = pa_stream_get_state(stream)) != PA_STREAM_READY) {
282 if (state == PA_STREAM_FAILED || state == PA_STREAM_TERMINATED)
289 #ifdef LIBPULSE_GETS_A_CLUE
290 static void stream_success_cb(pa_stream *s, int success, void *userdata)
293 (void) s; (void) success; (void) userdata;
296 # define stream_success_cb NULL
299 /* Memory free callback. The block_t address is in front of the data. */
300 static void data_free(void *data)
302 block_t **pp = data, *block;
304 memcpy(&block, pp - 1, sizeof (block));
305 block_Release(block);
308 static void *data_convert(block_t **pp)
310 block_t *block = *pp;
311 /* In most cases, there is enough head room, and this is really cheap: */
312 block = block_Realloc(block, sizeof (block), block->i_buffer);
314 if (unlikely(block == NULL))
317 memcpy(block->p_buffer, &block, sizeof (block));
318 block->p_buffer += sizeof (block);
319 block->i_buffer -= sizeof (block);
320 return block->p_buffer;
324 * Queue one audio frame to the playabck stream
326 static void Play(audio_output_t *aout)
328 aout_sys_t *sys = aout->sys;
329 pa_stream *s = sys->stream;
331 /* This function is called exactly once per block in the output FIFO. */
332 block_t *block = aout_FifoPop(&aout->fifo);
333 assert (block != NULL);
335 const void *ptr = data_convert(&block);
336 if (unlikely(ptr == NULL))
339 size_t len = block->i_buffer;
340 mtime_t pts = block->i_pts + block->i_length;
342 /* Note: The core already holds the output FIFO lock at this point.
343 * Therefore we must not under any circumstances (try to) acquire the
344 * output FIFO lock while the PulseAudio threaded main loop lock is held
345 * (including from PulseAudio stream callbacks). Otherwise lock inversion
346 * will take place, and sooner or later a deadlock. */
349 if (pa_stream_is_corked(s) > 0) {
350 /* Start or resume the stream. Zeroes are prepended to sync.
351 * This does not really work because PulseAudio latency measurement is
352 * garbage at start. */
357 if (pa_stream_get_latency(s, &latency, &negative) == 0)
358 msg_Dbg(aout, "starting with %c%"PRIu64" us latency",
359 negative ? '-' : '+', latency);
361 latency = negative = 0;
363 mtime_t advance = block->i_pts - mdate();
370 size_t nb = (advance * aout->format.i_rate) / CLOCK_FREQ;
371 size_t size = aout->format.i_bytes_per_frame;
372 float *zeroes = calloc (nb, size);
374 msg_Dbg(aout, "prepending %zu zeroes", nb);
375 #if 0 /* Fault injector: add delay */
376 pa_stream_write(s, zeroes, nb * size, NULL, 0, PA_SEEK_RELATIVE);
377 pa_stream_write(s, zeroes, nb * size, NULL, 0, PA_SEEK_RELATIVE);
379 if (likely(zeroes != NULL))
380 if (pa_stream_write(s, zeroes, nb * size, free, 0,
381 PA_SEEK_RELATIVE) < 0)
385 op = pa_stream_cork(s, 0, NULL, NULL);
387 pa_operation_unref(op);
388 op = pa_stream_trigger(s, NULL, NULL);
390 pa_operation_unref(op);
391 msg_Dbg(aout, "uncorking");
394 #if 0 /* Fault injector to test underrun recovery */
395 static volatile unsigned u = 0;
396 if ((++u % 1000) == 0) {
397 msg_Err(aout, "fault injection");
398 pa_operation_unref(pa_stream_flush(s, NULL, NULL));
402 if (pa_stream_write(s, ptr, len, data_free, 0, PA_SEEK_RELATIVE) < 0) {
403 vlc_pa_error(aout, "cannot write", sys->context);
404 block_Release(block);
412 * Cork or uncork the playback stream
414 static void Pause(audio_output_t *aout, bool b_paused, mtime_t i_date)
416 aout_sys_t *sys = aout->sys;
417 pa_stream *s = sys->stream;
420 return; /* nothing to do - yet */
424 pa_operation *op = pa_stream_cork(s, 1, NULL, NULL);
426 pa_operation_unref(op);
427 stream_reset_sync(s, aout);
433 static int VolumeSet(audio_output_t *aout, float vol, bool mute)
435 aout_sys_t *sys = aout->sys;
438 uint32_t idx = pa_stream_get_index(sys->stream);
439 pa_volume_t volume = pa_sw_volume_from_linear(vol);
442 /* TODO: do not ruin the channel balance (if set outside VLC) */
443 /* TODO: notify UI about volume changes by other PulseAudio clients */
444 pa_cvolume_set(&sys->cvolume, sys->cvolume.channels, volume);
445 pa_sw_cvolume_multiply_scalar(&cvolume, &sys->cvolume, sys->base_volume);
446 assert(pa_cvolume_valid(&cvolume));
449 op = pa_context_set_sink_input_volume(sys->context, idx, &cvolume, NULL, NULL);
450 if (likely(op != NULL))
451 pa_operation_unref(op);
452 op = pa_context_set_sink_input_mute(sys->context, idx, mute, NULL, NULL);
453 if (likely(op != NULL))
454 pa_operation_unref(op);
460 static int StreamMove(vlc_object_t *obj, const char *varname, vlc_value_t old,
461 vlc_value_t val, void *userdata)
463 audio_output_t *aout = (audio_output_t *)obj;
464 aout_sys_t *sys = aout->sys;
465 pa_stream *s = userdata;
467 uint32_t idx = pa_stream_get_index(s);
468 uint32_t sink_idx = val.i_int;
470 (void) varname; (void) old;
473 op = pa_context_move_sink_input_by_index(sys->context, idx, sink_idx,
475 if (likely(op != NULL)) {
476 pa_operation_unref(op);
477 msg_Dbg(aout, "moving to sink %"PRIu32, sink_idx);
479 vlc_pa_error(obj, "cannot move sink", sys->context);
482 return (op != NULL) ? VLC_SUCCESS : VLC_EGENERIC;
487 * Create a PulseAudio playback stream, a.k.a. a sink input.
489 static int Open(vlc_object_t *obj)
491 audio_output_t *aout = (audio_output_t *)obj;
494 /* Sample format specification */
495 struct pa_sample_spec ss;
496 vlc_fourcc_t format = aout->format.i_format;
501 format = VLC_CODEC_F32B;
503 ss.format = PA_SAMPLE_FLOAT32BE;
506 format = VLC_CODEC_F32L;
508 ss.format = PA_SAMPLE_FLOAT32LE;
511 format = VLC_CODEC_FL32;
512 ss.format = PA_SAMPLE_FLOAT32NE;
515 ss.format = PA_SAMPLE_S32BE;
518 ss.format = PA_SAMPLE_S32LE;
521 ss.format = PA_SAMPLE_S24BE;
524 ss.format = PA_SAMPLE_S24LE;
527 ss.format = PA_SAMPLE_S16BE;
530 ss.format = PA_SAMPLE_S16LE;
533 format = VLC_CODEC_U8;
535 ss.format = PA_SAMPLE_U8;
540 format = VLC_CODEC_FL32;
541 ss.format = PA_SAMPLE_FLOAT32NE;
545 format = VLC_CODEC_S16N;
546 ss.format = PA_SAMPLE_S16NE;
551 ss.rate = aout->format.i_rate;
552 ss.channels = aout_FormatNbChannels(&aout->format);
553 if (!pa_sample_spec_valid(&ss)) {
554 msg_Err(aout, "unsupported sample specification");
558 /* Channel mapping (order defined in vlc_aout.h) */
559 struct pa_channel_map map;
562 if (aout->format.i_physical_channels & AOUT_CHAN_LEFT)
563 map.map[map.channels++] = PA_CHANNEL_POSITION_FRONT_LEFT;
564 if (aout->format.i_physical_channels & AOUT_CHAN_RIGHT)
565 map.map[map.channels++] = PA_CHANNEL_POSITION_FRONT_RIGHT;
566 if (aout->format.i_physical_channels & AOUT_CHAN_MIDDLELEFT)
567 map.map[map.channels++] = PA_CHANNEL_POSITION_SIDE_LEFT;
568 if (aout->format.i_physical_channels & AOUT_CHAN_MIDDLERIGHT)
569 map.map[map.channels++] = PA_CHANNEL_POSITION_SIDE_RIGHT;
570 if (aout->format.i_physical_channels & AOUT_CHAN_REARLEFT)
571 map.map[map.channels++] = PA_CHANNEL_POSITION_REAR_LEFT;
572 if (aout->format.i_physical_channels & AOUT_CHAN_REARRIGHT)
573 map.map[map.channels++] = PA_CHANNEL_POSITION_REAR_RIGHT;
574 if (aout->format.i_physical_channels & AOUT_CHAN_REARCENTER)
575 map.map[map.channels++] = PA_CHANNEL_POSITION_REAR_CENTER;
576 if (aout->format.i_physical_channels & AOUT_CHAN_CENTER)
578 if (ss.channels == 1)
579 map.map[map.channels++] = PA_CHANNEL_POSITION_MONO;
581 map.map[map.channels++] = PA_CHANNEL_POSITION_FRONT_CENTER;
583 if (aout->format.i_physical_channels & AOUT_CHAN_LFE)
584 map.map[map.channels++] = PA_CHANNEL_POSITION_LFE;
586 for (unsigned i = 0; map.channels < ss.channels; i++) {
587 map.map[map.channels++] = PA_CHANNEL_POSITION_AUX0 + i;
588 msg_Warn(aout, "mapping channel %"PRIu8" to AUX%u", map.channels, i);
591 if (!pa_channel_map_valid(&map)) {
592 msg_Err(aout, "unsupported channel map");
595 const char *name = pa_channel_map_to_name(&map);
596 msg_Dbg(aout, "using %s channel map", (name != NULL) ? name : "?");
599 /* Stream parameters */
600 const pa_stream_flags_t flags = PA_STREAM_START_CORKED
601 //| PA_STREAM_INTERPOLATE_TIMING
602 | PA_STREAM_AUTO_TIMING_UPDATE
603 | PA_STREAM_VARIABLE_RATE;
605 struct pa_buffer_attr attr;
607 /* PulseAudio assumes that tlength bytes are available in the buffer. Thus
608 * we need to be conservative and set the minimum value that the VLC
609 * audio decoder thread warrants. Otherwise, PulseAudio buffers will
610 * underrun on hardware with large buffers. VLC keeps at least
611 * AOUT_MIN_PREPARE and at most AOUT_MAX_PREPARE worth of audio buffers.
612 * TODO? tlength could be adaptively increased to reduce wakeups. */
613 attr.tlength = pa_usec_to_bytes(AOUT_MIN_PREPARE_TIME, &ss);
614 attr.prebuf = 0; /* trigger manually */
616 attr.fragsize = 0; /* not used for output */
618 /* Allocate structures */
619 aout_sys_t *sys = malloc(sizeof(*sys));
620 if (unlikely(sys == NULL))
623 pa_context *ctx = vlc_pa_connect (obj);
633 sys->pts = VLC_TS_INVALID;
638 sys->base_volume = PA_VOLUME_NORM;
639 pa_cvolume_set(&sys->cvolume, ss.channels, PA_VOLUME_NORM);
642 /* Create a playback stream */
643 pa_stream *s = pa_stream_new(ctx, "audio stream", &ss, &map);
645 vlc_pa_error(obj, "stream creation failure", ctx);
649 pa_stream_set_state_callback(s, stream_state_cb, NULL);
650 pa_stream_set_latency_update_callback(s, stream_latency_cb, aout);
651 pa_stream_set_moved_callback(s, stream_moved_cb, aout);
652 pa_stream_set_overflow_callback(s, stream_overflow_cb, aout);
653 pa_stream_set_started_callback(s, stream_started_cb, aout);
654 pa_stream_set_suspended_callback(s, stream_suspended_cb, aout);
655 pa_stream_set_underflow_callback(s, stream_underflow_cb, aout);
657 if (pa_stream_connect_playback(s, NULL, &attr, flags, NULL, NULL) < 0
659 vlc_pa_error(obj, "stream connection failure", ctx);
663 const struct pa_buffer_attr *pba = pa_stream_get_buffer_attr(s);
664 msg_Dbg(aout, "using buffer metrics: maxlength=%u, tlength=%u, "
665 "prebuf=%u, minreq=%u",
666 pba->maxlength, pba->tlength, pba->prebuf, pba->minreq);
668 aout->i_nb_samples = pba->minreq / pa_frame_size(&ss);
670 var_Create(aout, "audio-device", VLC_VAR_INTEGER|VLC_VAR_HASCHOICE);
671 var_Change(aout, "audio-device", VLC_VAR_SETTEXT,
672 &(vlc_value_t){ .psz_string = (char *)_("Audio device") },
674 var_AddCallback (aout, "audio-device", StreamMove, s);
675 op = pa_context_get_sink_info_list(ctx, sink_list_cb, aout);
676 /* We may need to wait for completion... once LibVLC supports this */
678 pa_operation_unref(op);
679 stream_moved_cb(s, aout);
682 aout->format.i_format = format;
683 aout->pf_play = Play;
684 aout->pf_pause = Pause;
685 aout->pf_volume_set = VolumeSet;
695 * Removes a PulseAudio playback stream
697 static void Close (vlc_object_t *obj)
699 audio_output_t *aout = (audio_output_t *)obj;
700 aout_sys_t *sys = aout->sys;
701 pa_context *ctx = sys->context;
702 pa_stream *s = sys->stream;
705 /* The callback takes mainloop lock, so it CANNOT be held here! */
706 var_DelCallback (aout, "audio-device", StreamMove, s);
707 var_Destroy (aout, "audio-device");
714 if (pa_stream_is_corked(s) > 0)
715 /* Stream paused: discard all buffers */
716 op = pa_stream_flush(s, stream_success_cb, NULL);
718 /* Stream playing: wait until buffers are played */
719 op = pa_stream_drain(s, stream_success_cb, NULL);
720 if (likely(op != NULL)) {
721 #ifdef LIBPULSE_GETS_A_CLUE
722 while (pa_operation_get_state(op) == PA_OPERATION_RUNNING)
725 pa_operation_unref(op);
728 pa_stream_disconnect(s);
733 vlc_pa_disconnect(obj, ctx);