From 13786dc643fe250a9560792ef342751585ea15e9 Mon Sep 17 00:00:00 2001 From: wm4 Date: Mon, 5 Sep 2016 21:07:30 +0200 Subject: audio/out: deprecate device sub-options We have --audio-device, which can force the device. Also add something describing to this extent to the manpage. --- DOCS/interface-changes.rst | 1 + DOCS/man/ao.rst | 13 ++++++++----- DOCS/man/options.rst | 19 ++++++++----------- audio/out/ao_alsa.c | 2 +- audio/out/ao_openal.c | 3 ++- audio/out/ao_oss.c | 2 +- audio/out/ao_pulse.c | 2 +- audio/out/ao_rsound.c | 6 ++++-- audio/out/ao_sndio.c | 3 ++- audio/out/ao_wasapi.c | 2 +- audio/out/internal.h | 3 +++ 11 files changed, 32 insertions(+), 24 deletions(-) diff --git a/DOCS/interface-changes.rst b/DOCS/interface-changes.rst index ef9d61e931..3b2ff485ad 100644 --- a/DOCS/interface-changes.rst +++ b/DOCS/interface-changes.rst @@ -24,6 +24,7 @@ Interface changes replaced by global options, which do exactly the same. For example, "--vo=opengl:scale=nearest" turns into "--scale=nearest". In some cases, the global option is prefixed. + - deprecate the device/sink options on all AOs. Use --audio-device instead. - subtle changes in how "--no-..." options are treated mean that they are not accessible under "options/..." anymore (instead, these are resolved at parsing time). This does not affect options which start with "--no-", diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst index 4583acff14..e82c541024 100644 --- a/DOCS/man/ao.rst +++ b/DOCS/man/ao.rst @@ -51,6 +51,7 @@ Available audio output drivers are: ``--oss-device`` Sets the audio output device (default: ``/dev/dsp``). + Deprecated, use ``--audio-device``. ``--oss-mixer-device`` Sets the audio mixer device (default: ``/dev/mixer``). ``--oss-mixer-channel`` @@ -129,6 +130,7 @@ Available audio output drivers are: Specify the host and optionally output sink to use. An empty string uses a local connection, "localhost" uses network transfer (most likely not what you want). + Deprecated, use ``--audio-device``. ``--pulse-buffer=<1-2000|native>`` Set the audio buffer size in milliseconds. A higher value buffers @@ -238,6 +240,9 @@ Available audio output drivers are: Set the TCP port used for connecting to the server (default: 12345). Not used if connecting to a Unix domain socket. + These options are deprecated. If anyone cares enough, their functionality + can be added back using ``--audio-device``. + ``sndio`` Audio output to the OpenBSD sndio sound system @@ -250,6 +255,7 @@ Available audio output drivers are: ``--ao-sndio-device=`` sndio device to use (default: ``$AUDIODEVICE``, resp. ``snd0``). + Deprecated, use ``--audio-device``. ``wasapi`` Audio output to the Windows Audio Session API. @@ -260,6 +266,8 @@ Available audio output drivers are: Requests exclusive, direct hardware access. By definition prevents sound playback of any other program until mpv exits. ``--ao-wasapi-device=`` + Deprecated, use ``--audio-device``. + Uses the requested endpoint instead of the system's default audio endpoint. Both an ordinal number (0,1,2,...) and the GUID String are valid; the GUID string is guaranteed to not change @@ -267,8 +275,3 @@ Available audio output drivers are: Also supports searching active devices by human-readable name. If more than one device matches the name, refuses loading it. - - This option is mostly deprecated in favour of the more general - ``--audio-device`` option. That said, ``--audio-device=help`` will give - a list of valid device GUIDs (prefixed with ``wasapi/``), as well as - their human readable names, which should work here. diff --git a/DOCS/man/options.rst b/DOCS/man/options.rst index 6668849320..5d361d10b3 100644 --- a/DOCS/man/options.rst +++ b/DOCS/man/options.rst @@ -995,21 +995,18 @@ Audio ``--audio-device=`` Use the given audio device. This consists of the audio output name, e.g. ``alsa``, followed by ``/``, followed by the audio output specific device - name. + name. The default value for this option is ``auto``, which tries every audio + output in preference order with the default device. You can list audio devices with ``--audio-device=help``. This outputs the device name in quotes, followed by a description. The device name is what - you have to pass to the ``--audio-device`` option. - - The default value for this option is ``auto``, which tries every audio - output in preference order with the default device. - - Note that many AOs have a ``device`` sub-option, which overrides the - device selection of this option (but not the audio output selection). - Likewise, forcing an AO with ``--ao`` will override the audio output - selection of ``--audio-device`` (but not the device selection). + you have to pass to the ``--audio-device`` option. The list of audio devices + can be retrieved by API by using the ``audio-device-list`` property. - Currently not implemented for most AOs. + While the option normally takes one of the strings as indicated by the + methods above, you can also force the device for most AOs by building it + manually. For example ``name/foobar`` forces the AO ``name`` to use the + device ``foobar``. ``--audio-fallback-to-null=`` If no audio device can be opened, behave as if ``--ao=null`` was given. This diff --git a/audio/out/ao_alsa.c b/audio/out/ao_alsa.c index c542bee030..4d879b1565 100644 --- a/audio/out/ao_alsa.c +++ b/audio/out/ao_alsa.c @@ -62,7 +62,7 @@ struct ao_alsa_opts { #define OPT_BASE_STRUCT struct ao_alsa_opts static const struct m_sub_options ao_alsa_conf = { .opts = (const struct m_option[]) { - OPT_STRING("alsa-device", device, 0), + OPT_STRING("alsa-device", device, 0, DEVICE_OPT_DEPRECATION), OPT_FLAG("alsa-resample", resample, 0), OPT_STRING("alsa-mixer-device", mixer_device, 0), OPT_STRING("alsa-mixer-name", mixer_name, 0), diff --git a/audio/out/ao_openal.c b/audio/out/ao_openal.c index 41a1a03194..2c29b8923b 100644 --- a/audio/out/ao_openal.c +++ b/audio/out/ao_openal.c @@ -356,7 +356,8 @@ const struct ao_driver audio_out_openal = { .list_devs = list_devs, .priv_size = sizeof(struct priv), .options = (const struct m_option[]) { - OPT_STRING_VALIDATE("device", cfg_device, 0, validate_device_opt), + OPT_STRING_VALIDATE("device", cfg_device, 0, validate_device_opt, + DEVICE_OPT_DEPRECATION), {0} }, .legacy_prefix = "ao-openal", diff --git a/audio/out/ao_oss.c b/audio/out/ao_oss.c index cd08a046f7..5bf5fec29b 100644 --- a/audio/out/ao_oss.c +++ b/audio/out/ao_oss.c @@ -648,7 +648,7 @@ const struct ao_driver audio_out_oss = { .oss_mixer_device = PATH_DEV_MIXER, }, .options = (const struct m_option[]) { - OPT_STRING("device", dsp, 0), + OPT_STRING("device", dsp, 0, DEVICE_OPT_DEPRECATION), OPT_STRING("mixer-device", oss_mixer_device, 0), OPT_STRING("mixer-channel", cfg_oss_mixer_channel, 0), {0} diff --git a/audio/out/ao_pulse.c b/audio/out/ao_pulse.c index 6eedea2b07..5a68553e88 100644 --- a/audio/out/ao_pulse.c +++ b/audio/out/ao_pulse.c @@ -836,7 +836,7 @@ const struct ao_driver audio_out_pulse = { }, .options = (const struct m_option[]) { OPT_STRING("host", cfg_host, 0), - OPT_STRING("sink", cfg_sink, 0), + OPT_STRING("sink", cfg_sink, 0, DEVICE_OPT_DEPRECATION), OPT_CHOICE_OR_INT("buffer", cfg_buffer, 0, 1, 2000, ({"native", 0})), OPT_FLAG("latency-hacks", cfg_latency_hacks, 0), {0} diff --git a/audio/out/ao_rsound.c b/audio/out/ao_rsound.c index 8b80ddf1da..65196d0932 100644 --- a/audio/out/ao_rsound.c +++ b/audio/out/ao_rsound.c @@ -156,8 +156,10 @@ const struct ao_driver audio_out_rsound = { .resume = audio_resume, .priv_size = sizeof(struct priv), .options = (const struct m_option[]) { - OPT_STRING("host", host, 0), - OPT_STRING("port", port, 0), + OPT_STRING("host", host, 0, + .deprecation_message = "request --audio-device support on issue tracker"), + OPT_STRING("port", port, 0 + .deprecation_message = "request --audio-device support on issue tracker"), {0} }, .legacy_prefix = "rsound", diff --git a/audio/out/ao_sndio.c b/audio/out/ao_sndio.c index c53e01cb9e..f60fa303e5 100644 --- a/audio/out/ao_sndio.c +++ b/audio/out/ao_sndio.c @@ -320,7 +320,8 @@ const struct ao_driver audio_out_sndio = { .reset = reset, .priv_size = sizeof(struct priv), .options = (const struct m_option[]) { - OPT_STRING("device", dev, 0, OPTDEF_STR(SIO_DEVANY)), + OPT_STRING("device", dev, 0, OPTDEF_STR(SIO_DEVANY), + DEVICE_OPT_DEPRECATION), {0} }, .legacy_prefix = "ao-sndio", diff --git a/audio/out/ao_wasapi.c b/audio/out/ao_wasapi.c index 7cdde49ce9..23a958bb3b 100644 --- a/audio/out/ao_wasapi.c +++ b/audio/out/ao_wasapi.c @@ -496,7 +496,7 @@ const struct ao_driver audio_out_wasapi = { .priv_size = sizeof(wasapi_state), .options = (const struct m_option[]) { OPT_FLAG("exclusive", opt_exclusive, 0), - OPT_STRING("device", opt_device, 0), + OPT_STRING("device", opt_device, 0, DEVICE_OPT_DEPRECATION), {NULL}, }, .legacy_prefix = "ao-wasapi", diff --git a/audio/out/internal.h b/audio/out/internal.h index 3115fbfeb7..fdbb423f52 100644 --- a/audio/out/internal.h +++ b/audio/out/internal.h @@ -206,4 +206,7 @@ bool ao_chmap_sel_get_def(struct ao *ao, const struct mp_chmap_sel *s, void ao_device_list_add(struct ao_device_list *list, struct ao *ao, struct ao_device_desc *e); +#define DEVICE_OPT_DEPRECATION \ + .deprecation_message = "use --audio-device instead" + #endif -- cgit v1.2.3