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

@@ -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-",

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 <host>
         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=<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=<id>``
+        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.

DOCS/man/options.rst

@@ -995,21 +995,18 @@ Audio
 ``--audio-device=<name>``
     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.
+    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.
 
-    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).
-
-    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=<yes|no>``
     If no audio device can be opened, behave as if ``--ao=null`` was given. This

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),

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",

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}

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}

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",

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",

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",

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