audio: deprecate HMP audio commands

The command is niche and better served by the host audio system.
There is no QMP equivalent, fortunately. You can capture the audio
stream via remote desktop protocols too (dbus, vnc, spice).

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Acked-by: Dr. David Alan Gilbert <dave@treblig.org>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20251022105753.1474739-1-marcandre.lureau@redhat.com>

audio/audio-hmp-cmds.c

@@ -28,6 +28,7 @@
 #include "monitor/monitor.h"
 #include "qapi/error.h"
 #include "qobject/qdict.h"
+#include "qemu/error-report.h"
 
 static QLIST_HEAD (capture_list_head, CaptureState) capture_head;
 
@@ -36,6 +37,8 @@ void hmp_info_capture(Monitor *mon, const QDict *qdict)
     int i;
     CaptureState *s;
 
+    warn_report_once("'info capture' is deprecated since v10.2, to be removed");
+
     for (s = capture_head.lh_first, i = 0; s; s = s->entries.le_next, ++i) {
         monitor_printf(mon, "[%d]: ", i);
         s->ops.info (s->opaque);
@@ -48,6 +51,8 @@ void hmp_stopcapture(Monitor *mon, const QDict *qdict)
     int n = qdict_get_int(qdict, "n");
     CaptureState *s;
 
+    warn_report_once("'stopcapture' is deprecated since v10.2, to be removed");
+
     for (s = capture_head.lh_first, i = 0; s; s = s->entries.le_next, ++i) {
         if (i == n) {
             s->ops.destroy (s->opaque);
@@ -69,6 +74,8 @@ void hmp_wavcapture(Monitor *mon, const QDict *qdict)
     Error *local_err = NULL;
     AudioBackend *as = audio_be_by_name(audiodev, &local_err);
 
+    warn_report_once("'wavcapture' is deprecated since v10.2, to be removed");
+
     if (!as) {
         error_report_err(local_err);
         return;

audio/meson.build

@@ -1,12 +1,13 @@
 system_ss.add(files(
   'audio.c',
-  'audio-hmp-cmds.c',
   'mixeng.c',
   'noaudio.c',
   'wavaudio.c',
-  'wavcapture.c',
 ))
 
+# deprecated since v10.2, to be removed
+system_ss.add(files('audio-hmp-cmds.c', 'wavcapture.c'))
+
 system_ss.add(when: coreaudio, if_true: files('coreaudio.m'))
 system_ss.add(when: dsound, if_true: files('dsoundaudio.c', 'audio_win_int.c'))
 

docs/about/deprecated.rst

@@ -169,6 +169,26 @@ Use ``job-finalize`` instead.
 
 This argument has always been ignored.
 
+Human Machine Protocol (HMP) commands
+-------------------------------------
+
+``wavcapture`` (since 10.2)
+''''''''''''''''''''''''''''
+
+The ``wavcapture`` command is deprecated and will be removed in a future release.
+
+Use ``-audiodev wav`` or your host audio system to capture audio.
+
+``stopcapture`` (since 10.2)
+''''''''''''''''''''''''''''
+
+The ``stopcapture`` command is deprecated and will be removed in a future release.
+
+``info`` argument ``capture`` (since 10.2)
+''''''''''''''''''''''''''''''''''''''''''
+
+The ``info capture`` command is deprecated and will be removed in a future release.
+
 Host Architectures
 ------------------
 

hmp-commands-info.hx

@@ -363,18 +363,20 @@ SRST
     Show host USB devices.
 ERST
 
+/* BEGIN deprecated */
     {
         .name       = "capture",
         .args_type  = "",
         .params     = "",
-        .help       = "show capture information",
+        .help       = "show capture information (deprecated)",
         .cmd        = hmp_info_capture,
     },
 
 SRST
   ``info capture``
-    Show capture information.
+    Show capture information (deprecated).
 ERST
+/* END deprecated */
 
     {
         .name       = "snapshots",

hmp-commands.hx

@@ -764,11 +764,12 @@ SRST
 
 ERST
 
+/* BEGIN deprecated */
     {
         .name       = "wavcapture",
         .args_type  = "path:F,audiodev:s,freq:i?,bits:i?,nchannels:i?",
         .params     = "path audiodev [frequency [bits [channels]]]",
-        .help       = "capture audio to a wave file (default frequency=44100 bits=16 channels=2)",
+        .help       = "capture audio to a wave file (deprecated, default frequency=44100 bits=16 channels=2)",
         .cmd        = hmp_wavcapture,
     },
 SRST
@@ -782,13 +783,15 @@ SRST
   - Sample rate = 44100 Hz - CD quality
   - Bits = 16
   - Number of channels = 2 - Stereo
+
+  Deprecated.
 ERST
 
     {
         .name       = "stopcapture",
         .args_type  = "n:i",
         .params     = "capture index",
-        .help       = "stop capture",
+        .help       = "stop capture (deprecated)",
         .cmd        = hmp_stopcapture,
     },
 SRST
@@ -797,7 +800,9 @@ SRST
 
     info capture
 
+  Deprecated.
 ERST
+/* END deprecated */
 
     {
         .name       = "memsave",