src/audio_output/output.c

   1 /*****************************************************************************
   2  * output.c : internal management of output streams for the audio output
   3  *****************************************************************************
   4  * Copyright (C) 2002-2004 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Christophe Massiot <massiot@via.ecp.fr>
   8  *
   9  * This program is free software; you can redistribute it and/or modify it
  10  * under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation; either version 2.1 of the License, or
  12  * (at your option) any later version.
  13  *
  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 Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this program; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  22  *****************************************************************************/
  23
  24 #ifdef HAVE_CONFIG_H
  25 # include "config.h"
  26 #endif
  27
  28 #include <stdlib.h>
  29 #include <assert.h>
  30
  31 #include <vlc_common.h>
  32 #include <vlc_aout.h>
  33 #include <vlc_modules.h>
  34
  35 #include "libvlc.h"
  36 #include "aout_internal.h"
  37
  38 static const char unset_str[1] = ""; /* Non-NULL constant string pointer */
  39
  40 /* Local functions */
  41 static void aout_OutputAssertLocked (audio_output_t *aout)
  42 {
  43     aout_owner_t *owner = aout_owner (aout);
  44
  45     vlc_assert_locked (&owner->lock);
  46 }
  47
  48 static void aout_Destructor( vlc_object_t * p_this );
  49
  50 static int var_Copy (vlc_object_t *src, const char *name, vlc_value_t prev,
  51                      vlc_value_t value, void *data)
  52 {
  53     vlc_object_t *dst = data;
  54
  55     (void) src; (void) prev;
  56     return var_Set (dst, name, value);
  57 }
  58
  59 /**
  60  * Supply or update the current custom ("hardware") volume.
  61  * @note This only makes sense after calling aout_VolumeHardInit().
  62  * @param volume current custom volume
  63  *
  64  * @warning The caller (i.e. the audio output plug-in) is responsible for
  65  * interlocking and synchronizing call to this function and to the
  66  * audio_output_t.volume_set callback. This ensures that VLC gets correct
  67  * volume information (possibly with a latency).
  68  */
  69 static void aout_VolumeNotify (audio_output_t *aout, float volume)
  70 {
  71     var_SetFloat (aout, "volume", volume);
  72 }
  73
  74 static void aout_MuteNotify (audio_output_t *aout, bool mute)
  75 {
  76     var_SetBool (aout, "mute", mute);
  77 }
  78
  79 static void aout_PolicyNotify (audio_output_t *aout, bool cork)
  80 {
  81     (cork ? var_IncInteger : var_DecInteger) (aout->p_parent, "corks");
  82 }
  83
  84 static void aout_DeviceNotify (audio_output_t *aout, const char *id)
  85 {
  86     var_SetString (aout, "device", (id != NULL) ? id : "");
  87 }
  88
  89 static void aout_RestartNotify (audio_output_t *aout, unsigned mode)
  90 {
  91     aout_RequestRestart (aout, mode);
  92 }
  93
  94 static int aout_GainNotify (audio_output_t *aout, float gain)
  95 {
  96     aout_owner_t *owner = aout_owner (aout);
  97
  98     aout_OutputAssertLocked (aout);
  99     aout_volume_SetVolume (owner->volume, gain);
 100     /* XXX: ideally, return -1 if format cannot be amplified */
 101     return 0;
 102 }
 103
 104 #undef aout_New
 105 /**
 106  * Creates an audio output object and initializes an output module.
 107  */
 108 audio_output_t *aout_New (vlc_object_t *parent)
 109 {
 110     vlc_value_t val, text;
 111
 112     audio_output_t *aout = vlc_custom_create (parent, sizeof (aout_instance_t),
 113                                               "audio output");
 114     if (unlikely(aout == NULL))
 115         return NULL;
 116
 117     aout_owner_t *owner = aout_owner (aout);
 118
 119     vlc_mutex_init (&owner->lock);
 120     vlc_mutex_init (&owner->req.lock);
 121     owner->req.device = (char *)unset_str;
 122     owner->req.volume = -1.f;
 123     owner->req.mute = -1;
 124
 125     vlc_object_set_destructor (aout, aout_Destructor);
 126
 127     /* Audio output module callbacks */
 128     var_Create (aout, "volume", VLC_VAR_FLOAT);
 129     var_AddCallback (aout, "volume", var_Copy, parent);
 130     var_Create (aout, "mute", VLC_VAR_BOOL | VLC_VAR_DOINHERIT);
 131     var_AddCallback (aout, "mute", var_Copy, parent);
 132     var_Create (aout, "device", VLC_VAR_STRING);
 133
 134     aout->event.volume_report = aout_VolumeNotify;
 135     aout->event.mute_report = aout_MuteNotify;
 136     aout->event.device_report = aout_DeviceNotify;
 137     aout->event.policy_report = aout_PolicyNotify;
 138     aout->event.gain_request = aout_GainNotify;
 139     aout->event.restart_request = aout_RestartNotify;
 140
 141     /* Audio output module initialization */
 142     aout->start = NULL;
 143     aout->stop = NULL;
 144     aout->volume_set = NULL;
 145     aout->mute_set = NULL;
 146     aout->device_enum = NULL;
 147     aout->device_select = NULL;
 148     owner->module = module_need (aout, "audio output", "$aout", false);
 149     if (owner->module == NULL)
 150     {
 151         msg_Err (aout, "no suitable audio output module");
 152         vlc_object_release (aout);
 153         return NULL;
 154     }
 155
 156     /*
 157      * Persistent audio output variables
 158      */
 159     module_config_t *cfg;
 160     char *str;
 161
 162     /* Visualizations */
 163     var_Create (aout, "visual", VLC_VAR_STRING | VLC_VAR_HASCHOICE);
 164     text.psz_string = _("Visualizations");
 165     var_Change (aout, "visual", VLC_VAR_SETTEXT, &text, NULL);
 166     val.psz_string = (char *)"";
 167     text.psz_string = _("Disable");
 168     var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 169     val.psz_string = (char *)"spectrometer";
 170     text.psz_string = _("Spectrometer");
 171     var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 172     val.psz_string = (char *)"scope";
 173     text.psz_string = _("Scope");
 174     var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 175     val.psz_string = (char *)"spectrum";
 176     text.psz_string = _("Spectrum");
 177     var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 178     val.psz_string = (char *)"vuMeter";
 179     text.psz_string = _("Vu meter");
 180     var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 181     /* Look for goom plugin */
 182     if (module_exists ("goom"))
 183     {
 184         val.psz_string = (char *)"goom";
 185         text.psz_string = (char *)"Goom";
 186         var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 187     }
 188     /* Look for libprojectM plugin */
 189     if (module_exists ("projectm"))
 190     {
 191         val.psz_string = (char *)"projectm";
 192         text.psz_string = (char*)"projectM";
 193         var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 194     }
 195     /* Look for VSXu plugin */
 196     if (module_exists ("vsxu"))
 197     {
 198         val.psz_string = (char *)"vsxu";
 199         text.psz_string = (char*)"Vovoid VSXu";
 200         var_Change (aout, "visual", VLC_VAR_ADDCHOICE, &val, &text);
 201     }
 202     str = var_GetNonEmptyString (aout, "effect-list");
 203     if (str != NULL)
 204     {
 205         var_SetString (aout, "visual", str);
 206         free (str);
 207     }
 208
 209     /* Equalizer */
 210     var_Create (aout, "equalizer", VLC_VAR_STRING | VLC_VAR_HASCHOICE);
 211     text.psz_string = _("Equalizer");
 212     var_Change (aout, "equalizer", VLC_VAR_SETTEXT, &text, NULL);
 213     val.psz_string = (char*)"";
 214     text.psz_string = _("Disable");
 215     var_Change (aout, "equalizer", VLC_VAR_ADDCHOICE, &val, &text);
 216     cfg = config_FindConfig (VLC_OBJECT(aout), "equalizer-preset");
 217     if (likely(cfg != NULL))
 218         for (unsigned i = 0; i < cfg->list_count; i++)
 219         {
 220             val.psz_string = cfg->list.psz[i];
 221             text.psz_string = vlc_gettext(cfg->list_text[i]);
 222             var_Change (aout, "equalizer", VLC_VAR_ADDCHOICE, &val, &text);
 223         }
 224
 225     var_Create (aout, "audio-filter", VLC_VAR_STRING | VLC_VAR_DOINHERIT);
 226     text.psz_string = _("Audio filters");
 227     var_Change (aout, "audio-filter", VLC_VAR_SETTEXT, &text, NULL);
 228
 229
 230     var_Create (aout, "audio-visual", VLC_VAR_STRING | VLC_VAR_DOINHERIT);
 231     text.psz_string = _("Audio visualizations");
 232     var_Change (aout, "audio-visual", VLC_VAR_SETTEXT, &text, NULL);
 233
 234     /* Replay gain */
 235     var_Create (aout, "audio-replay-gain-mode",
 236                 VLC_VAR_STRING | VLC_VAR_DOINHERIT );
 237     text.psz_string = _("Replay gain");
 238     var_Change (aout, "audio-replay-gain-mode", VLC_VAR_SETTEXT, &text, NULL);
 239     cfg = config_FindConfig (VLC_OBJECT(aout), "audio-replay-gain-mode");
 240     if (likely(cfg != NULL))
 241         for (unsigned i = 0; i < cfg->list_count; i++)
 242         {
 243             val.psz_string = cfg->list.psz[i];
 244             text.psz_string = vlc_gettext(cfg->list_text[i]);
 245             var_Change (aout, "audio-replay-gain-mode", VLC_VAR_ADDCHOICE,
 246                             &val, &text);
 247         }
 248
 249     return aout;
 250 }
 251
 252 /**
 253  * Deinitializes an audio output module and destroys an audio output object.
 254  */
 255 void aout_Destroy (audio_output_t *aout)
 256 {
 257     aout_owner_t *owner = aout_owner (aout);
 258
 259     aout_OutputLock (aout);
 260     module_unneed (aout, owner->module);
 261     /* Protect against late call from intf.c */
 262     aout->volume_set = NULL;
 263     aout->mute_set = NULL;
 264     aout_OutputUnlock (aout);
 265
 266     var_DelCallback (aout, "mute", var_Copy, aout->p_parent);
 267     var_SetFloat (aout, "volume", -1.f);
 268     var_DelCallback (aout, "volume", var_Copy, aout->p_parent);
 269     vlc_object_release (aout);
 270 }
 271
 272 /**
 273  * Destroys the audio output lock used (asynchronously) by interface functions.
 274  */
 275 static void aout_Destructor (vlc_object_t *obj)
 276 {
 277     audio_output_t *aout = (audio_output_t *)obj;
 278     aout_owner_t *owner = aout_owner (aout);
 279
 280     assert (owner->req.device == unset_str);
 281     vlc_mutex_destroy (&owner->req.lock);
 282     vlc_mutex_destroy (&owner->lock);
 283 }
 284
 285 /**
 286  * Starts an audio output stream.
 287  * \param fmt audio output stream format [IN/OUT]
 288  * \warning The caller must hold the audio output lock.
 289  */
 290 int aout_OutputNew (audio_output_t *aout, audio_sample_format_t *restrict fmt)
 291 {
 292     aout_OutputAssertLocked (aout);
 293
 294     /* Ideally, the audio filters would be created before the audio output,
 295      * and the ideal audio format would be the output of the filters chain.
 296      * But that scheme would not really play well with digital pass-through. */
 297     if (AOUT_FMT_LINEAR(fmt))
 298     {   /* Try to stay in integer domain if possible for no/slow FPU. */
 299         fmt->i_format = (fmt->i_bitspersample > 16) ? VLC_CODEC_FL32
 300                                                     : VLC_CODEC_S16N;
 301         aout_FormatPrepare (fmt);
 302     }
 303
 304     if (aout->start (aout, fmt))
 305     {
 306         msg_Err (aout, "module not functional");
 307         return -1;
 308     }
 309
 310     if (!var_Type (aout, "stereo-mode"))
 311         var_Create (aout, "stereo-mode",
 312                     VLC_VAR_INTEGER | VLC_VAR_HASCHOICE | VLC_VAR_DOINHERIT);
 313
 314     /* The user may have selected a different channels configuration. */
 315     var_AddCallback (aout, "stereo-mode", aout_ChannelsRestart, NULL);
 316     switch (var_GetInteger (aout, "stereo-mode"))
 317     {
 318         case AOUT_VAR_CHAN_RSTEREO:
 319             fmt->i_original_channels |= AOUT_CHAN_REVERSESTEREO;
 320             break;
 321         case AOUT_VAR_CHAN_STEREO:
 322             fmt->i_original_channels = AOUT_CHANS_STEREO;
 323             break;
 324         case AOUT_VAR_CHAN_LEFT:
 325             fmt->i_original_channels = AOUT_CHAN_LEFT;
 326             break;
 327         case AOUT_VAR_CHAN_RIGHT:
 328             fmt->i_original_channels = AOUT_CHAN_RIGHT;
 329             break;
 330         case AOUT_VAR_CHAN_DOLBYS:
 331             fmt->i_original_channels = AOUT_CHANS_STEREO|AOUT_CHAN_DOLBYSTEREO;
 332             break;
 333         default:
 334         {
 335             if ((fmt->i_original_channels & AOUT_CHAN_PHYSMASK)
 336                                                           != AOUT_CHANS_STEREO)
 337                  break;
 338
 339             vlc_value_t val, txt;
 340             val.i_int = 0;
 341             var_Change (aout, "stereo-mode", VLC_VAR_DELCHOICE, &val, NULL);
 342             txt.psz_string = _("Stereo audio mode");
 343             var_Change (aout, "stereo-mode", VLC_VAR_SETTEXT, &txt, NULL);
 344             if (fmt->i_original_channels & AOUT_CHAN_DOLBYSTEREO)
 345             {
 346                 val.i_int = AOUT_VAR_CHAN_DOLBYS;
 347                 txt.psz_string = _("Dolby Surround");
 348             }
 349             else
 350             {
 351                 val.i_int = AOUT_VAR_CHAN_STEREO;
 352                 txt.psz_string = _("Stereo");
 353             }
 354             var_Change (aout, "stereo-mode", VLC_VAR_ADDCHOICE, &val, &txt);
 355             var_Change (aout, "stereo-mode", VLC_VAR_SETVALUE, &val, NULL);
 356             val.i_int = AOUT_VAR_CHAN_LEFT;
 357             txt.psz_string = _("Left");
 358             var_Change (aout, "stereo-mode", VLC_VAR_ADDCHOICE, &val, &txt);
 359             if (fmt->i_original_channels & AOUT_CHAN_DUALMONO)
 360             {   /* Go directly to the left channel. */
 361                 fmt->i_original_channels = AOUT_CHAN_LEFT;
 362                 var_Change (aout, "stereo-mode", VLC_VAR_SETVALUE, &val, NULL);
 363             }
 364             val.i_int = AOUT_VAR_CHAN_RIGHT;
 365             txt.psz_string = _("Right");
 366             var_Change (aout, "stereo-mode", VLC_VAR_ADDCHOICE, &val, &txt);
 367             val.i_int = AOUT_VAR_CHAN_RSTEREO;
 368             txt.psz_string = _("Reverse stereo");
 369             var_Change (aout, "stereo-mode", VLC_VAR_ADDCHOICE, &val, &txt);
 370         }
 371     }
 372
 373     aout_FormatPrepare (fmt);
 374     aout_FormatPrint (aout, "output", fmt);
 375     return 0;
 376 }
 377
 378 /**
 379  * Stops the audio output stream (undoes aout_OutputNew()).
 380  * \note This can only be called after a succesful aout_OutputNew().
 381  * \warning The caller must hold the audio output lock.
 382  */
 383 void aout_OutputDelete (audio_output_t *aout)
 384 {
 385     aout_OutputAssertLocked (aout);
 386
 387     var_DelCallback (aout, "stereo-mode", aout_ChannelsRestart, NULL);
 388     if (aout->stop != NULL)
 389         aout->stop (aout);
 390 }
 391
 392 int aout_OutputTimeGet (audio_output_t *aout, mtime_t *delay)
 393 {
 394     aout_OutputAssertLocked (aout);
 395
 396     if (aout->time_get == NULL)
 397         return -1;
 398     return aout->time_get (aout, delay);
 399 }
 400
 401 /**
 402  * Plays a decoded audio buffer.
 403  * \note This can only be called after a succesful aout_OutputNew().
 404  * \warning The caller must hold the audio output lock.
 405  */
 406 void aout_OutputPlay (audio_output_t *aout, block_t *block)
 407 {
 408     aout_OutputAssertLocked (aout);
 409     aout->play (aout, block);
 410 }
 411
 412 static void PauseDefault (audio_output_t *aout, bool pause, mtime_t date)
 413 {
 414     if (pause)
 415         aout_OutputFlush (aout, false);
 416     (void) date;
 417 }
 418
 419 /**
 420  * Notifies the audio output (if any) of pause/resume events.
 421  * This enables the output to expedite pause, instead of waiting for its
 422  * buffers to drain.
 423  * \note This can only be called after a succesful aout_OutputNew().
 424  * \warning The caller must hold the audio output lock.
 425  */
 426 void aout_OutputPause( audio_output_t *aout, bool pause, mtime_t date )
 427 {
 428     aout_OutputAssertLocked (aout);
 429     ((aout->pause != NULL) ? aout->pause : PauseDefault) (aout, pause, date);
 430 }
 431
 432 /**
 433  * Flushes or drains the audio output buffers.
 434  * This enables the output to expedite seek and stop.
 435  * \param wait if true, wait for buffer playback (i.e. drain),
 436  *             if false, discard the buffers immediately (i.e. flush)
 437  * \note This can only be called after a succesful aout_OutputNew().
 438  * \warning The caller must hold the audio output lock.
 439  */
 440 void aout_OutputFlush( audio_output_t *aout, bool wait )
 441 {
 442     aout_OutputAssertLocked( aout );
 443     aout->flush (aout, wait);
 444 }
 445
 446 static int aout_OutputVolumeSet (audio_output_t *aout, float vol)
 447 {
 448     aout_OutputAssertLocked (aout);
 449     return (aout->volume_set != NULL) ? aout->volume_set (aout, vol) : -1;
 450 }
 451
 452 static int aout_OutputMuteSet (audio_output_t *aout, bool mute)
 453 {
 454     aout_OutputAssertLocked (aout);
 455     return (aout->mute_set != NULL) ? aout->mute_set (aout, mute) : -1;
 456 }
 457
 458 static int aout_OutputDeviceSet (audio_output_t *aout, const char *id)
 459 {
 460     aout_OutputAssertLocked (aout);
 461     return (aout->device_select != NULL) ? aout->device_select (aout, id) : -1;
 462 }
 463
 464 static int aout_OutputDevicesEnum (audio_output_t *aout,
 465                                    char ***ids, char ***names)
 466 {
 467     aout_OutputAssertLocked (aout);
 468     return (aout->device_enum != NULL) ? aout->device_enum (aout, ids, names)
 469                                        : -1;
 470 }
 471
 472 void aout_OutputLock (audio_output_t *aout)
 473 {
 474     aout_owner_t *owner = aout_owner (aout);
 475
 476     vlc_mutex_lock (&owner->lock);
 477 }
 478
 479 static int aout_OutputTryLock (audio_output_t *aout)
 480 {
 481     aout_owner_t *owner = aout_owner (aout);
 482
 483     return vlc_mutex_trylock (&owner->lock);
 484 }
 485
 486 void aout_OutputUnlock (audio_output_t *aout)
 487 {
 488     aout_owner_t *owner = aout_owner (aout);
 489
 490     vlc_assert_locked (&owner->lock);
 491     vlc_mutex_lock (&owner->req.lock);
 492
 493     if (owner->req.device != unset_str)
 494     {
 495         aout_OutputDeviceSet (aout, owner->req.device);
 496         free (owner->req.device);
 497         owner->req.device = (char *)unset_str;
 498     }
 499
 500     if (owner->req.volume >= 0.f)
 501     {
 502         aout_OutputVolumeSet (aout, owner->req.volume);
 503         owner->req.volume = -1.f;
 504     }
 505
 506     if (owner->req.mute >= 0)
 507     {
 508         aout_OutputMuteSet (aout, owner->req.mute);
 509         owner->req.mute = -1;
 510     }
 511
 512     vlc_mutex_unlock (&owner->lock);
 513     /* If another thread is blocked waiting for owner->req.lock at this point,
 514      * this aout_OutputUnlock() call will not see and apply its change request.
 515      * The other thread will need to apply the change request itself, which
 516      * implies it is able to (try-)lock owner->lock. Therefore this thread must
 517      * release owner->lock _before_ owner->req.lock. Do not reorder!!! */
 518     vlc_mutex_unlock (&owner->req.lock);
 519 }
 520
 521 /**
 522  * Gets the volume of the audio output stream (independent of mute).
 523  * \return Current audio volume (0. = silent, 1. = nominal),
 524  * or a strictly negative value if undefined.
 525  */
 526 float aout_VolumeGet (audio_output_t *aout)
 527 {
 528     return var_GetFloat (aout, "volume");
 529 }
 530
 531 /**
 532  * Sets the volume of the audio output stream.
 533  * \note The mute status is not changed.
 534  * \return 0 on success, -1 on failure (TODO).
 535  */
 536 int aout_VolumeSet (audio_output_t *aout, float vol)
 537 {
 538     aout_owner_t *owner = aout_owner (aout);
 539
 540     assert (vol >= 0.f);
 541     vlc_mutex_lock (&owner->req.lock);
 542     owner->req.volume = vol;
 543     vlc_mutex_unlock (&owner->req.lock);
 544
 545     if (aout_OutputTryLock (aout) == 0)
 546         aout_OutputUnlock (aout);
 547     return 0;
 548 }
 549
 550 /**
 551  * Gets the audio output stream mute flag.
 552  * \return 0 if not muted, 1 if muted, -1 if undefined.
 553  */
 554 int aout_MuteGet (audio_output_t *aout)
 555 {
 556     return var_InheritBool (aout, "mute");
 557 }
 558
 559 /**
 560  * Sets the audio output stream mute flag.
 561  * \return 0 on success, -1 on failure (TODO).
 562  */
 563 int aout_MuteSet (audio_output_t *aout, bool mute)
 564 {
 565     aout_owner_t *owner = aout_owner (aout);
 566
 567     vlc_mutex_lock (&owner->req.lock);
 568     owner->req.mute = mute;
 569     vlc_mutex_unlock (&owner->req.lock);
 570
 571     if (aout_OutputTryLock (aout) == 0)
 572         aout_OutputUnlock (aout);
 573     return 0;
 574 }
 575
 576 /**
 577  * Gets the currently selected device.
 578  * \return the selected device ID (caller must free() it)
 579  *         NULL if no device is selected or in case of error.
 580  */
 581 char *aout_DeviceGet (audio_output_t *aout)
 582 {
 583     return var_GetNonEmptyString (aout, "device");
 584 }
 585
 586 /**
 587  * Selects an audio output device.
 588  * \param id device ID to select, or NULL for the default device
 589  * \return zero on success, non-zero on error (TODO).
 590  */
 591 int aout_DeviceSet (audio_output_t *aout, const char *id)
 592 {
 593     aout_owner_t *owner = aout_owner (aout);
 594
 595     char *dev = NULL;
 596     if (id != NULL)
 597     {
 598         dev = strdup (id);
 599         if (unlikely(dev == NULL))
 600             return -1;
 601     }
 602
 603     vlc_mutex_lock (&owner->req.lock);
 604     if (owner->req.device != unset_str)
 605         free (owner->req.device);
 606     owner->req.device = dev;
 607     vlc_mutex_unlock (&owner->req.lock);
 608
 609     if (aout_OutputTryLock (aout) == 0)
 610         aout_OutputUnlock (aout);
 611     return 0;
 612 }
 613
 614 /**
 615  * Enumerates possible audio output devices.
 616  *
 617  * The function will heap-allocate two tables of heap-allocated strings;
 618  * the caller is responsible for freeing all strings and both tables.
 619  *
 620  * \param ids pointer to a table of device identifiers [OUT]
 621  * \param names pointer to a table of device human-readable descriptions [OUT]
 622  * \return the number of devices, or negative on error.
 623  * \note In case of error, *ids and *names are undefined.
 624  */
 625 int aout_DevicesList (audio_output_t *aout, char ***ids, char ***names)
 626 {
 627     int ret;
 628
 629     aout_OutputLock (aout);
 630     ret = aout_OutputDevicesEnum (aout, ids, names);
 631     aout_OutputUnlock (aout);
 632     return ret;
 633 }