audio/out: deprecate "exclusive" sub-options

And introduce a global option which does this. Or more precisely, this
deprecates the global wasapi and coreaudio options, and adds a new one
that merges their functionality. (Due to the way the sub-option
deprecation mechanism works, this is simpler.)

DOCS/interface-changes.rst

@@ -25,6 +25,8 @@ Interface changes
       "--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.
+    - deprecate "--ao=wasapi:exclusive" and "--ao=coreaudio:exclusive",
+      use --audio-exclusive 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

@@ -107,10 +107,12 @@ Available audio output drivers are:
         utility. Note that this does not affect the selected speaker setup.
 
     ``--coreaudio-exclusive``
+        Deprecated, use ``--audio-exclusive``.
         Use exclusive mode access. This merely redirects to
         ``coreaudio_exclusive``, but should be preferred over using that AO
         directly.
 
+
 ``coreaudio_exclusive`` (Mac OS X only)
     Native Mac OS X audio output driver using direct device access and
     exclusive mode (bypasses the sound server).
@@ -263,6 +265,7 @@ Available audio output drivers are:
     The following global options are supported by this audio output:
 
     ``--ao-wasapi-exclusive``
+        Deprecated, use ``--audio-exclusive``.
         Requests exclusive, direct hardware access. By definition prevents
         sound playback of any other program until mpv exits.
     ``--ao-wasapi-device=<id>``

DOCS/man/options.rst

@@ -1008,6 +1008,15 @@ Audio
     manually. For example ``name/foobar`` forces the AO ``name`` to use the
     device ``foobar``.
 
+``--audio-exclusive=<yes|no>``
+    Enable exclusive output mode. In this mode, the system is usually locked
+    out, and only mpv will be able to output audio.
+
+    This only works for some audio outputs, such as ``wasapi`` and
+    ``coreaudio``. Other audio outputs silently ignore this options. They either
+    have no concept of exclusive mode, or the mpv side of the implementation is
+    missing.
+
 ``--audio-fallback-to-null=<yes|no>``
     If no audio device can be opened, behave as if ``--ao=null`` was given. This
     is useful in combination with ``--audio-device``: instead of causing an

audio/out/ao.h

@@ -58,6 +58,8 @@ enum {
     AO_INIT_SAFE_MULTICHANNEL_ONLY = 1 << 1,
     // Stream silence as long as no audio is playing.
     AO_INIT_STREAM_SILENCE = 1 << 2,
+    // Force exclusive mode, i.e. lock out the system mixer.
+    AO_INIT_EXCLUSIVE = 1 << 3,
 };
 
 typedef struct ao_control_vol {

audio/out/ao_coreaudio.c

@@ -143,6 +143,8 @@ static int init(struct ao *ao)
 {
     struct priv *p = ao->priv;
 
+    p->exclusive |= ao->init_flags & AO_INIT_EXCLUSIVE;
+
     if (!af_fmt_is_pcm(ao->format) || p->exclusive) {
         MP_VERBOSE(ao, "redirecting to coreaudio_exclusive\n");
         ao->redirect = "coreaudio_exclusive";
@@ -427,7 +429,8 @@ const struct ao_driver audio_out_coreaudio = {
     .priv_size      = sizeof(struct priv),
     .options = (const struct m_option[]){
         OPT_FLAG("change-physical-format", change_physical_format, 0),
-        OPT_FLAG("exclusive", exclusive, 0),
+        OPT_FLAG("exclusive", exclusive, 0,
+                 .deprecation_message = "use --audio-exclusive"),
         {0}
     },
     .legacy_prefix = "coreaudio",

audio/out/ao_wasapi.c

@@ -275,6 +275,8 @@ static int init(struct ao *ao)
     struct wasapi_state *state = ao->priv;
     state->log = ao->log;
 
+    state->opt_exclusive |= ao->init_flags & AO_INIT_EXCLUSIVE;
+
     state->deviceID = wasapi_find_deviceID(ao);
     if (!state->deviceID) {
         uninit(ao);
@@ -495,7 +497,8 @@ const struct ao_driver audio_out_wasapi = {
     .hotplug_uninit = hotplug_uninit,
     .priv_size      = sizeof(wasapi_state),
     .options        = (const struct m_option[]) {
-        OPT_FLAG("exclusive", opt_exclusive, 0),
+        OPT_FLAG("exclusive", opt_exclusive, 0,
+                 .deprecation_message = "use --audio-exclusive"),
         OPT_STRING("device", opt_device, 0, DEVICE_OPT_DEPRECATION),
         {NULL},
     },

options/options.c

@@ -481,6 +481,7 @@ const m_option_t mp_opts[] = {
     OPT_SETTINGSLIST("ao-defaults", ao_defs, 0, &ao_obj_list,
                      .deprecation_message = "deprecated, use global options"),
     OPT_STRING("audio-device", audio_device, 0),
+    OPT_FLAG("audio-exclusive", audio_exclusive, 0),
     OPT_STRING("audio-client-name", audio_client_name, 0),
     OPT_FLAG("audio-fallback-to-null", ao_null_fallback, 0),
     OPT_FLAG("audio-stream-silence", audio_stream_silence, 0),

options/options.h

@@ -86,6 +86,7 @@ typedef struct MPOpts {
 
     struct m_obj_settings *audio_driver_list, *ao_defs;
     char *audio_device;
+    int audio_exclusive;
     char *audio_client_name;
     int ao_null_fallback;
     int audio_stream_silence;

player/audio.c

@@ -382,6 +382,9 @@ static void reinit_audio_filters_and_output(struct MPContext *mpctx)
         if (opts->audio_stream_silence)
             ao_flags |= AO_INIT_STREAM_SILENCE;
 
+        if (opts->audio_exclusive)
+            ao_flags |= AO_INIT_EXCLUSIVE;
+
         if (af_fmt_is_pcm(afs->output.format)) {
             if (!opts->audio_output_channels.set ||
                 opts->audio_output_channels.auto_safe)