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 */
74 static void sink_input_info_cb(pa_context *, const pa_sink_input_info *,
78 static void context_cb(pa_context *ctx, pa_subscription_event_type_t type,
79 uint32_t idx, void *userdata)
81 audio_output_t *aout = userdata;
82 aout_sys_t *sys = aout->sys;
85 switch (type & PA_SUBSCRIPTION_EVENT_FACILITY_MASK)
87 case PA_SUBSCRIPTION_EVENT_SINK_INPUT:
88 if (idx != pa_stream_get_index(sys->stream))
89 break; /* only interested in our sink input */
91 /* Gee... PA will not provide the infos directly in the event. */
92 switch (type & PA_SUBSCRIPTION_EVENT_TYPE_MASK)
94 case PA_SUBSCRIPTION_EVENT_REMOVE:
95 msg_Err(aout, "sink input killed!");
99 op = pa_context_get_sink_input_info(ctx, idx, sink_input_info_cb,
101 if (likely(op != NULL))
102 pa_operation_unref(op);
107 default: /* unsubscribed facility?! */
114 static void sink_list_cb(pa_context *c, const pa_sink_info *i, int eol,
117 audio_output_t *aout = userdata;
118 vlc_value_t val, text;
124 msg_Dbg(aout, "listing sink %s (%"PRIu32"): %s", i->name, i->index,
126 val.i_int = i->index;
127 text.psz_string = (char *)i->description;
128 var_Change(aout, "audio-device", VLC_VAR_ADDCHOICE, &val, &text);
131 static void sink_info_cb(pa_context *c, const pa_sink_info *i, int eol,
134 audio_output_t *aout = userdata;
135 aout_sys_t *sys = aout->sys;
141 /* PulseAudio flat volume NORM / 100% / 0dB corresponds to no software
142 * amplification and maximum hardware amplification.
143 * VLC maps DEFAULT / 100% to no gain at all (software/hardware).
144 * Thus we need to use the sink base_volume as a multiplier,
145 * if and only if flat volume is active for our current sink. */
146 if (i->flags & PA_SINK_FLAT_VOLUME)
147 sys->base_volume = i->base_volume;
149 sys->base_volume = PA_VOLUME_NORM;
150 msg_Dbg(aout, "base volume: %f", pa_sw_volume_to_linear(sys->base_volume));
153 /*** Stream helpers ***/
154 static void stream_reset_sync(pa_stream *s, audio_output_t *aout)
156 aout_sys_t *sys = aout->sys;
157 const unsigned rate = aout->format.i_rate;
159 sys->pts = VLC_TS_INVALID;
161 pa_operation *op = pa_stream_update_sample_rate(s, rate, NULL, NULL);
162 if (unlikely(op == NULL))
164 pa_operation_unref(op);
168 static void stream_state_cb(pa_stream *s, void *userdata)
170 switch (pa_stream_get_state(s)) {
171 case PA_STREAM_READY:
172 case PA_STREAM_FAILED:
173 case PA_STREAM_TERMINATED:
181 /* Latency management and lip synchronization */
182 static void stream_latency_cb(pa_stream *s, void *userdata)
184 audio_output_t *aout = userdata;
185 aout_sys_t *sys = aout->sys;
186 mtime_t delta, change;
188 if (sys->pts == VLC_TS_INVALID)
190 msg_Dbg(aout, "missing latency from input");
194 /* Compute lip desynchronization */
199 if (pa_stream_get_latency(s, &latency, &negative)) {
200 vlc_pa_error(aout, "missing latency", sys->context);
203 delta = sys->pts - mdate();
204 if (unlikely(negative))
210 change = delta - sys->desync;
212 //msg_Dbg(aout, "desync: %+"PRId64" us (variation: %+"PRId64" us)",
215 if (delta < -AOUT_MAX_PTS_DELAY)
216 msg_Warn(aout, "too late by %"PRId64" us", -delta);
217 else if (delta > +AOUT_MAX_PTS_ADVANCE)
218 msg_Warn(aout, "too early by %"PRId64" us", delta);
220 /* Compute playback sample rate */
221 const unsigned inrate = aout->format.i_rate;
223 #define ADJUST_FACTOR 4
224 #define ADJUST_MAX 1000 /* Hz (max rate variation per call) */
225 /* This is empirical. Feel free to define something smarter. */
226 int adj = sys->rate * (delta + change) / (CLOCK_FREQ * ADJUST_FACTOR);
228 /* This avoids too fast rate variation. They sound ugly as hell and they
229 * make the algorithm unstable (e.g. oscillation around inrate). */
230 if (adj > +ADJUST_MAX)
232 if (adj < -ADJUST_MAX)
235 unsigned outrate = sys->rate - adj;
236 /* Favor native rate to avoid resampling (FIXME: really a good idea?) */
237 if (abs(outrate - inrate) < (inrate >> 10))
240 /* This keeps the effective rate within specified range
241 * (+/-AOUT_MAX_RESAMPLING% - see <vlc_aout.h>) of the nominal rate. */
242 const int limit = inrate * AOUT_MAX_RESAMPLING / 100;
243 if (outrate > inrate + limit)
244 outrate = inrate + limit;
245 if (outrate < inrate - limit)
246 outrate = inrate - limit;
248 /* Apply adjusted sample rate */
249 if (outrate == sys->rate)
251 pa_operation *op = pa_stream_update_sample_rate(s, outrate, NULL, NULL);
252 if (unlikely(op == NULL)) {
253 vlc_pa_error(aout, "cannot change sample rate", sys->context);
256 pa_operation_unref(op);
257 msg_Dbg(aout, "changed sample rate to %u Hz",outrate);
261 static void stream_moved_cb(pa_stream *s, void *userdata)
263 audio_output_t *aout = userdata;
264 aout_sys_t *sys = aout->sys;
266 uint32_t idx = pa_stream_get_device_index(s);
268 msg_Dbg(aout, "connected to sink %"PRIu32": %s", idx,
269 pa_stream_get_device_name(s));
270 op = pa_context_get_sink_info_by_index(sys->context, idx,
272 if (likely(op != NULL))
273 pa_operation_unref(op);
275 /* Update the variable if someone else moved our stream */
276 var_Change(aout, "audio-device", VLC_VAR_SETVALUE,
277 &(vlc_value_t){ .i_int = idx }, NULL);
280 static void stream_overflow_cb(pa_stream *s, void *userdata)
282 audio_output_t *aout = userdata;
284 msg_Err(aout, "overflow");
288 static void stream_started_cb(pa_stream *s, void *userdata)
290 audio_output_t *aout = userdata;
292 msg_Dbg(aout, "started");
296 static void stream_suspended_cb(pa_stream *s, void *userdata)
298 audio_output_t *aout = userdata;
300 msg_Dbg(aout, "suspended");
301 stream_reset_sync(s, aout);
304 static void stream_underflow_cb(pa_stream *s, void *userdata)
306 audio_output_t *aout = userdata;
309 msg_Warn(aout, "underflow");
310 op = pa_stream_cork(s, 1, NULL, NULL);
312 pa_operation_unref(op);
313 stream_reset_sync(s, aout);
316 static int stream_wait(pa_stream *stream)
318 pa_stream_state_t state;
320 while ((state = pa_stream_get_state(stream)) != PA_STREAM_READY) {
321 if (state == PA_STREAM_FAILED || state == PA_STREAM_TERMINATED)
328 #ifdef LIBPULSE_GETS_A_CLUE
329 static void stream_success_cb(pa_stream *s, int success, void *userdata)
332 (void) s; (void) success; (void) userdata;
335 # define stream_success_cb NULL
340 static void sink_input_info_cb(pa_context *ctx, const pa_sink_input_info *i,
341 int eol, void *userdata)
343 audio_output_t *aout = userdata;
344 aout_sys_t *sys = aout->sys;
351 sys->cvolume = i->volume;
352 volume = pa_sw_volume_to_linear(pa_cvolume_max(&i->volume));
353 aout_VolumeHardSet(aout, volume, i->mute);
357 /*** VLC audio output callbacks ***/
359 /* Memory free callback. The block_t address is in front of the data. */
360 static void data_free(void *data)
362 block_t **pp = data, *block;
364 memcpy(&block, pp - 1, sizeof (block));
365 block_Release(block);
368 static void *data_convert(block_t **pp)
370 block_t *block = *pp;
371 /* In most cases, there is enough head room, and this is really cheap: */
372 block = block_Realloc(block, sizeof (block), block->i_buffer);
374 if (unlikely(block == NULL))
377 memcpy(block->p_buffer, &block, sizeof (block));
378 block->p_buffer += sizeof (block);
379 block->i_buffer -= sizeof (block);
380 return block->p_buffer;
384 * Queue one audio frame to the playabck stream
386 static void Play(audio_output_t *aout)
388 aout_sys_t *sys = aout->sys;
389 pa_stream *s = sys->stream;
391 /* This function is called exactly once per block in the output FIFO. */
392 block_t *block = aout_FifoPop(&aout->fifo);
393 assert (block != NULL);
395 const void *ptr = data_convert(&block);
396 if (unlikely(ptr == NULL))
399 size_t len = block->i_buffer;
400 mtime_t pts = block->i_pts + block->i_length;
402 /* Note: The core already holds the output FIFO lock at this point.
403 * Therefore we must not under any circumstances (try to) acquire the
404 * output FIFO lock while the PulseAudio threaded main loop lock is held
405 * (including from PulseAudio stream callbacks). Otherwise lock inversion
406 * will take place, and sooner or later a deadlock. */
409 if (pa_stream_is_corked(s) > 0) {
410 /* Start or resume the stream. Zeroes are prepended to sync.
411 * This does not really work because PulseAudio latency measurement is
412 * garbage at start. */
417 if (pa_stream_get_latency(s, &latency, &negative) == 0)
418 msg_Dbg(aout, "starting with %c%"PRIu64" us latency",
419 negative ? '-' : '+', latency);
421 latency = negative = 0;
423 mtime_t advance = block->i_pts - mdate();
430 size_t nb = (advance * aout->format.i_rate) / CLOCK_FREQ;
431 size_t size = aout->format.i_bytes_per_frame;
432 float *zeroes = calloc (nb, size);
434 msg_Dbg(aout, "prepending %zu zeroes", nb);
435 #if 0 /* Fault injector: add delay */
436 pa_stream_write(s, zeroes, nb * size, NULL, 0, PA_SEEK_RELATIVE);
437 pa_stream_write(s, zeroes, nb * size, NULL, 0, PA_SEEK_RELATIVE);
439 if (likely(zeroes != NULL))
440 if (pa_stream_write(s, zeroes, nb * size, free, 0,
441 PA_SEEK_RELATIVE) < 0)
445 op = pa_stream_cork(s, 0, NULL, NULL);
447 pa_operation_unref(op);
448 op = pa_stream_trigger(s, NULL, NULL);
450 pa_operation_unref(op);
451 msg_Dbg(aout, "uncorking");
454 #if 0 /* Fault injector to test underrun recovery */
455 static volatile unsigned u = 0;
456 if ((++u % 1000) == 0) {
457 msg_Err(aout, "fault injection");
458 pa_operation_unref(pa_stream_flush(s, NULL, NULL));
462 if (pa_stream_write(s, ptr, len, data_free, 0, PA_SEEK_RELATIVE) < 0) {
463 vlc_pa_error(aout, "cannot write", sys->context);
464 block_Release(block);
472 * Cork or uncork the playback stream
474 static void Pause(audio_output_t *aout, bool b_paused, mtime_t i_date)
476 aout_sys_t *sys = aout->sys;
477 pa_stream *s = sys->stream;
480 return; /* nothing to do - yet */
484 pa_operation *op = pa_stream_cork(s, 1, NULL, NULL);
486 pa_operation_unref(op);
487 stream_reset_sync(s, aout);
493 static int VolumeSet(audio_output_t *aout, float vol, bool mute)
495 aout_sys_t *sys = aout->sys;
497 uint32_t idx = pa_stream_get_index(sys->stream);
499 pa_cvolume cvolume = sys->cvolume;
500 pa_volume_t volume = pa_sw_volume_multiply(pa_sw_volume_from_linear(vol),
503 pa_cvolume_scale(&cvolume, PA_VOLUME_NORM); /* preserve balance */
504 pa_sw_cvolume_multiply_scalar(&cvolume, &cvolume, volume);
505 assert(pa_cvolume_valid(&cvolume));
508 op = pa_context_set_sink_input_volume(sys->context, idx, &cvolume, NULL, NULL);
509 if (likely(op != NULL))
510 pa_operation_unref(op);
511 op = pa_context_set_sink_input_mute(sys->context, idx, mute, NULL, NULL);
512 if (likely(op != NULL))
513 pa_operation_unref(op);
519 static int StreamMove(vlc_object_t *obj, const char *varname, vlc_value_t old,
520 vlc_value_t val, void *userdata)
522 audio_output_t *aout = (audio_output_t *)obj;
523 aout_sys_t *sys = aout->sys;
524 pa_stream *s = userdata;
526 uint32_t idx = pa_stream_get_index(s);
527 uint32_t sink_idx = val.i_int;
529 (void) varname; (void) old;
532 op = pa_context_move_sink_input_by_index(sys->context, idx, sink_idx,
534 if (likely(op != NULL)) {
535 pa_operation_unref(op);
536 msg_Dbg(aout, "moving to sink %"PRIu32, sink_idx);
538 vlc_pa_error(obj, "cannot move sink", sys->context);
541 return (op != NULL) ? VLC_SUCCESS : VLC_EGENERIC;
546 * Create a PulseAudio playback stream, a.k.a. a sink input.
548 static int Open(vlc_object_t *obj)
550 audio_output_t *aout = (audio_output_t *)obj;
553 /* Sample format specification */
554 struct pa_sample_spec ss;
555 vlc_fourcc_t format = aout->format.i_format;
560 format = VLC_CODEC_F32B;
562 ss.format = PA_SAMPLE_FLOAT32BE;
565 format = VLC_CODEC_F32L;
567 ss.format = PA_SAMPLE_FLOAT32LE;
570 format = VLC_CODEC_FL32;
571 ss.format = PA_SAMPLE_FLOAT32NE;
574 ss.format = PA_SAMPLE_S32BE;
577 ss.format = PA_SAMPLE_S32LE;
580 ss.format = PA_SAMPLE_S24BE;
583 ss.format = PA_SAMPLE_S24LE;
586 ss.format = PA_SAMPLE_S16BE;
589 ss.format = PA_SAMPLE_S16LE;
592 format = VLC_CODEC_U8;
594 ss.format = PA_SAMPLE_U8;
599 format = VLC_CODEC_FL32;
600 ss.format = PA_SAMPLE_FLOAT32NE;
604 format = VLC_CODEC_S16N;
605 ss.format = PA_SAMPLE_S16NE;
610 ss.rate = aout->format.i_rate;
611 ss.channels = aout_FormatNbChannels(&aout->format);
612 if (!pa_sample_spec_valid(&ss)) {
613 msg_Err(aout, "unsupported sample specification");
617 /* Channel mapping (order defined in vlc_aout.h) */
618 struct pa_channel_map map;
621 if (aout->format.i_physical_channels & AOUT_CHAN_LEFT)
622 map.map[map.channels++] = PA_CHANNEL_POSITION_FRONT_LEFT;
623 if (aout->format.i_physical_channels & AOUT_CHAN_RIGHT)
624 map.map[map.channels++] = PA_CHANNEL_POSITION_FRONT_RIGHT;
625 if (aout->format.i_physical_channels & AOUT_CHAN_MIDDLELEFT)
626 map.map[map.channels++] = PA_CHANNEL_POSITION_SIDE_LEFT;
627 if (aout->format.i_physical_channels & AOUT_CHAN_MIDDLERIGHT)
628 map.map[map.channels++] = PA_CHANNEL_POSITION_SIDE_RIGHT;
629 if (aout->format.i_physical_channels & AOUT_CHAN_REARLEFT)
630 map.map[map.channels++] = PA_CHANNEL_POSITION_REAR_LEFT;
631 if (aout->format.i_physical_channels & AOUT_CHAN_REARRIGHT)
632 map.map[map.channels++] = PA_CHANNEL_POSITION_REAR_RIGHT;
633 if (aout->format.i_physical_channels & AOUT_CHAN_REARCENTER)
634 map.map[map.channels++] = PA_CHANNEL_POSITION_REAR_CENTER;
635 if (aout->format.i_physical_channels & AOUT_CHAN_CENTER)
637 if (ss.channels == 1)
638 map.map[map.channels++] = PA_CHANNEL_POSITION_MONO;
640 map.map[map.channels++] = PA_CHANNEL_POSITION_FRONT_CENTER;
642 if (aout->format.i_physical_channels & AOUT_CHAN_LFE)
643 map.map[map.channels++] = PA_CHANNEL_POSITION_LFE;
645 for (unsigned i = 0; map.channels < ss.channels; i++) {
646 map.map[map.channels++] = PA_CHANNEL_POSITION_AUX0 + i;
647 msg_Warn(aout, "mapping channel %"PRIu8" to AUX%u", map.channels, i);
650 if (!pa_channel_map_valid(&map)) {
651 msg_Err(aout, "unsupported channel map");
654 const char *name = pa_channel_map_to_name(&map);
655 msg_Dbg(aout, "using %s channel map", (name != NULL) ? name : "?");
658 /* Stream parameters */
659 const pa_stream_flags_t flags = PA_STREAM_START_CORKED
660 //| PA_STREAM_INTERPOLATE_TIMING
661 | PA_STREAM_AUTO_TIMING_UPDATE
662 | PA_STREAM_VARIABLE_RATE;
664 struct pa_buffer_attr attr;
666 /* PulseAudio assumes that tlength bytes are available in the buffer. Thus
667 * we need to be conservative and set the minimum value that the VLC
668 * audio decoder thread warrants. Otherwise, PulseAudio buffers will
669 * underrun on hardware with large buffers. VLC keeps at least
670 * AOUT_MIN_PREPARE and at most AOUT_MAX_PREPARE worth of audio buffers.
671 * TODO? tlength could be adaptively increased to reduce wakeups. */
672 attr.tlength = pa_usec_to_bytes(AOUT_MIN_PREPARE_TIME, &ss);
673 attr.prebuf = 0; /* trigger manually */
675 attr.fragsize = 0; /* not used for output */
677 /* Allocate structures */
678 aout_sys_t *sys = malloc(sizeof(*sys));
679 if (unlikely(sys == NULL))
682 pa_context *ctx = vlc_pa_connect (obj);
692 sys->pts = VLC_TS_INVALID;
697 const pa_subscription_mask_t mask = PA_SUBSCRIPTION_MASK_SINK_INPUT;
699 pa_context_set_subscribe_callback(ctx, context_cb, aout);
700 op = pa_context_subscribe(ctx, mask, NULL, NULL);
701 if (likely(op != NULL))
702 pa_operation_unref(op);
705 sys->base_volume = PA_VOLUME_NORM;
706 pa_cvolume_set(&sys->cvolume, ss.channels, PA_VOLUME_NORM);
709 /* Create a playback stream */
710 pa_stream *s = pa_stream_new(ctx, "audio stream", &ss, &map);
712 vlc_pa_error(obj, "stream creation failure", ctx);
716 pa_stream_set_state_callback(s, stream_state_cb, NULL);
717 pa_stream_set_latency_update_callback(s, stream_latency_cb, aout);
718 pa_stream_set_moved_callback(s, stream_moved_cb, aout);
719 pa_stream_set_overflow_callback(s, stream_overflow_cb, aout);
720 pa_stream_set_started_callback(s, stream_started_cb, aout);
721 pa_stream_set_suspended_callback(s, stream_suspended_cb, aout);
722 pa_stream_set_underflow_callback(s, stream_underflow_cb, aout);
724 if (pa_stream_connect_playback(s, NULL, &attr, flags, NULL, NULL) < 0
726 vlc_pa_error(obj, "stream connection failure", ctx);
730 const struct pa_buffer_attr *pba = pa_stream_get_buffer_attr(s);
731 msg_Dbg(aout, "using buffer metrics: maxlength=%u, tlength=%u, "
732 "prebuf=%u, minreq=%u",
733 pba->maxlength, pba->tlength, pba->prebuf, pba->minreq);
735 aout->i_nb_samples = pba->minreq / pa_frame_size(&ss);
737 var_Create(aout, "audio-device", VLC_VAR_INTEGER|VLC_VAR_HASCHOICE);
738 var_Change(aout, "audio-device", VLC_VAR_SETTEXT,
739 &(vlc_value_t){ .psz_string = (char *)_("Audio device") },
741 var_AddCallback (aout, "audio-device", StreamMove, s);
742 op = pa_context_get_sink_info_list(ctx, sink_list_cb, aout);
743 /* We may need to wait for completion... once LibVLC supports this */
745 pa_operation_unref(op);
746 stream_moved_cb(s, aout);
749 aout->format.i_format = format;
750 aout->pf_play = Play;
751 aout->pf_pause = Pause;
752 aout->pf_volume_set = VolumeSet;
762 * Removes a PulseAudio playback stream
764 static void Close (vlc_object_t *obj)
766 audio_output_t *aout = (audio_output_t *)obj;
767 aout_sys_t *sys = aout->sys;
768 pa_context *ctx = sys->context;
769 pa_stream *s = sys->stream;
772 /* The callback takes mainloop lock, so it CANNOT be held here! */
773 var_DelCallback (aout, "audio-device", StreamMove, s);
774 var_Destroy (aout, "audio-device");
781 if (pa_stream_is_corked(s) > 0)
782 /* Stream paused: discard all buffers */
783 op = pa_stream_flush(s, stream_success_cb, NULL);
785 /* Stream playing: wait until buffers are played */
786 op = pa_stream_drain(s, stream_success_cb, NULL);
787 if (likely(op != NULL)) {
788 #ifdef LIBPULSE_GETS_A_CLUE
789 while (pa_operation_get_state(op) == PA_OPERATION_RUNNING)
792 pa_operation_unref(op);
795 pa_stream_disconnect(s);
800 vlc_pa_disconnect(obj, ctx);