Re: [Qemu-devel] [libvirt] [PATCH v5 03/14] audio: -audiodev command line option: documentation

[Daniel P . Berrangé]

On Wed, Feb 20, 2019 at 10:37:32PM +0100, Kővágó, Zoltán wrote:
> This patch adds documentation of an -audiodev command line option, that
> deprecates the old QEMU_* environment variables for audio backend
> configuration.  It's syntax is similar to existing options (-netdev,
> -device, etc):
> 
>   -audiodev driver_name,property=value,...
> 
> Although now it's possible to specify multiple -audiodev options on
> command line, multiple audio backends are not supported yet.

So happy to see the audio backends come into the modern world at last !

> 
> Signed-off-by: Kővágó, Zoltán <address@hidden>
> ---
> 
> Notes:
>     Changes from v4:
>     
>     * deprecated QEMU_AUDIO_ env vars

Libvirt does currently use these, so we'll need to update libvirt
code to use the new cli args

>     * updated to reflect qapi changes
>     * added info to qemu-deprecated.texi
> 
>  qemu-deprecated.texi |   7 ++
>  qemu-options.hx      | 236 ++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 240 insertions(+), 3 deletions(-)
> 
> diff --git a/qemu-deprecated.texi b/qemu-deprecated.texi
> index 45c57952da..5c07ad4acb 100644
> --- a/qemu-deprecated.texi
> +++ b/qemu-deprecated.texi
> @@ -60,6 +60,13 @@ Support for invalid topologies will be removed, the user 
> must ensure
>  topologies described with -smp include all possible cpus, i.e.
>    @address@hidden * @var{cores} * @var{threads} = @var{maxcpus}}.
>  
> address@hidden QEMU_AUDIO_ environment variables and -audio-help (since 4.0)
> +
> +The ``-audiodev'' argument is now the preferred way to specify audio
> +backend settings instead of environment variables.  To ease migration to
> +the new format, the ``-audiodev-help'' option can be used to convert
> +the current values of the environment variables to ``-audiodev'' options.
> +
>  @section QEMU Machine Protocol (QMP) commands
>  
>  @subsection block-dirty-bitmap-add "autoload" parameter (since 2.12.0)
> diff --git a/qemu-options.hx b/qemu-options.hx
> index 77bd98e20b..f77f4d89a7 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -416,14 +416,244 @@ The default is @code{en-us}.
>  ETEXI
>  
>  
> +HXCOMM Deprecated by -audiodev
>  DEF("audio-help", 0, QEMU_OPTION_audio_help,
> -    "-audio-help     print list of audio drivers and their options\n",
> +    "-audio-help     show -audiodev equivalent of the currently specified 
> audio settings\n",
>      QEMU_ARCH_ALL)
>  STEXI
>  @item -audio-help
>  @findex -audio-help
> -Will show the audio subsystem help: list of drivers, tunable
> -parameters.
> +Will show the -audiodev equivalent of the currently specified
> +(deprecated) environment variables.
> +ETEXI
> +
> +DEF("audiodev", HAS_ARG, QEMU_OPTION_audiodev,
> +    "-audiodev [driver=]driver,id=id[,prop[=value][,...]]\n"
> +    "                specifies the audio backend to use\n"
> +    "                id= identifier of the backend\n"
> +    "                timer-period= timer period in microseconds\n"
> +    "                in|out.fixed-settings= use fixed settings for host 
> audio\n"
> +    "                in|out.frequency= frequency to use with fixed 
> settings\n"
> +    "                in|out.channels= number of channels to use with fixed 
> settings\n"
> +    "                in|out.format= sample format to use with fixed 
> settings\n"
> +    "                valid values: s8, s16, s32, u8, u16, u32\n"
> +    "                in|out.voices= number of voices to use\n"
> +    "                in|out.buffer-len= length of buffer in microseconds\n"
> +    "-audiodev none,id=id,[,prop[=value][,...]]\n"
> +    "                dummy driver that discards all output\n"
> +#ifdef CONFIG_ALSA
> +    "-audiodev alsa,id=id[,prop[=value][,...]]\n"
> +    "                in|out.dev= name of the audio device to use\n"
> +    "                in|out.period-len= length of period in microseconds\n"
> +    "                in|out.try-poll= attempt to use poll mode\n"
> +    "                threshold= threshold (in microseconds) when playback 
> starts\n"
> +#endif
> +#ifdef CONFIG_COREAUDIO
> +    "-audiodev coreaudio,id=id[,prop[=value][,...]]\n"
> +    "                in|out.buffer-count= number of buffers\n"
> +#endif
> +#ifdef CONFIG_DSOUND
> +    "-audiodev dsound,id=id[,prop[=value][,...]]\n"
> +    "                latency= add extra latency to playback in 
> microseconds\n"
> +#endif
> +#ifdef CONFIG_OSS
> +    "-audiodev oss,id=id[,prop[=value][,...]]\n"
> +    "                in|out.dev= path of the audio device to use\n"
> +    "                in|out.buffer-count= number of buffers\n"
> +    "                in|out.try-poll= attempt to use poll mode\n"
> +    "                try-mmap= try using memory mapped access\n"
> +    "                exclusive= open device in exclusive mode\n"
> +    "                dsp-policy= set timing policy (0..10), -1 to use 
> fragment mode\n"
> +#endif
> +#ifdef CONFIG_PA
> +    "-audiodev pa,id=id[,prop[=value][,...]]\n"
> +    "                server= PulseAudio server address\n"
> +    "                in|out.name= source/sink device name\n"
> +#endif
> +#ifdef CONFIG_SDL
> +    "-audiodev sdl,id=id[,prop[=value][,...]]\n"
> +#endif
> +#ifdef CONFIG_SPICE
> +    "-audiodev spice,id=id[,prop[=value][,...]]\n"
> +#endif
> +    "-audiodev wav,id=id[,prop[=value][,...]]\n"
> +    "                path= path of wav file to record\n",
> +    QEMU_ARCH_ALL)
> +STEXI
> address@hidden -audiodev address@hidden,address@hidden,@address@hidden,...]]
> address@hidden -audiodev
> +Adds a new audio backend @var{driver} identified by @var{id}.  There are
> +global and driver specific properties.  Some values can be set
> +differently for input and output, they're marked with @code{in|out.}.
> +You can set the input's property with @address@hidden and the
> +output's property with @address@hidden For example:
> address@hidden
> +-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
> +-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
> address@hidden example
> +
> +Valid global options are:
> +
> address@hidden @option
> address@hidden address@hidden
> +Identifies the audio backend.
> +
> address@hidden address@hidden
> +Sets the timer @var{period} used by the audio subsystem in microseconds.
> +Default is 10000 (10 ms).
> +
> address@hidden in|out.fixed-settings=on|off
> +Use fixed settings for host audio.  When off, it will change based on
> +how the guest opens the sound card.  In this case you must not specify
> address@hidden, @var{channels} or @var{format}.  Default is on.
> +
> address@hidden in|address@hidden
> +Specify the @var{frequency} to use when using @var{fixed-settings}.
> +Default is 44100Hz.
> +
> address@hidden in|address@hidden
> +Specify the number of @var{channels} to use when using
> address@hidden Default is 2 (stereo).
> +
> address@hidden in|address@hidden
> +Specify the sample @var{format} to use when using @var{fixed-settings}.
> +Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
> address@hidden, @code{u32}. Default is @code{s16}.
> +
> address@hidden in|address@hidden
> +Specify the number of @var{voices} to use.  Default is 1.
> +
> address@hidden in|address@hidden
> +Sets the size of the buffer in microseconds.
> +
> address@hidden table
> +
> address@hidden -audiodev none,address@hidden,@address@hidden,...]]
> +Creates a dummy backend that discards all outputs.  This backend has no
> +backend specific properties.
> +
> address@hidden -audiodev alsa,address@hidden,@address@hidden,...]]
> +Creates backend using the ALSA.  This backend is only available on
> +Linux.
> +
> +ALSA specific options are:
> +
> address@hidden @option
> +
> address@hidden in|address@hidden
> +Specify the ALSA @var{device} to use for input and/or output.  Default
> +is @code{default}.
> +
> address@hidden in|address@hidden
> +Sets the period length in microseconds.
> +
> address@hidden in|out.try-poll=on|off
> +Attempt to use poll mode with the device.  Default is on.
> +
> address@hidden address@hidden
> +Threshold (in microseconds) when playback starts.  Default is 0.
> +
> address@hidden table
> +
> address@hidden -audiodev coreaudio,address@hidden,@address@hidden,...]]
> +Creates a backend using Apple's Core Audio.  This backend is only
> +available on Mac OS and only supports playback.
> +
> +Core Audio specific options are:
> +
> address@hidden @option
> +
> address@hidden in|address@hidden
> +Sets the @var{count} of the buffers.
> +
> address@hidden table
> +
> address@hidden -audiodev dsound,address@hidden,@address@hidden,...]]
> +Creates a backend using Microsoft's DirectSound.  This backend is only
> +available on Windows and only supports playback.
> +
> +DirectSound specific options are:
> +
> address@hidden @option
> +
> address@hidden address@hidden
> +Add extra @var{usecs} microseconds latency to playback.  Default is
> +10000 (10 ms).
> +
> address@hidden table
> +
> address@hidden -audiodev oss,address@hidden,@address@hidden,...]]
> +Creates a backend using OSS.  This backend is available on most
> +Unix-like systems.
> +
> +OSS specific options are:
> +
> address@hidden @option
> +
> address@hidden in|address@hidden
> +Specify the file name of the OSS @var{device} to use.  Default is
> address@hidden/dev/dsp}.
> +
> address@hidden in|address@hidden
> +Sets the @var{count} of the buffers.
> +
> address@hidden in|out.try-poll=on|of
> +Attempt to use poll mode with the device.  Default is on.
> +
> address@hidden try-mmap=on|off
> +Try using memory mapped device access.  Default is off.
> +
> address@hidden exclusive=on|off
> +Open the device in exclusive mode (vmix won't work in this case).
> +Default is off.
> +
> address@hidden address@hidden
> +Sets the timing policy (between 0 and 10, where smaller number means
> +smaller latency but higher CPU usage).  Use -1 to use buffer sizes
> +specified by @code{buffer} and @code{buffer-count}.  This option is
> +ignored if you do not have OSS 4. Default is 5.
> +
> address@hidden table
> +
> address@hidden -audiodev pa,address@hidden,@address@hidden,...]]
> +Creates a backend using PulseAudio.  This backend is available on most
> +systems.
> +
> +PulseAudio specific options are:
> +
> address@hidden @option
> +
> address@hidden address@hidden
> +Sets the PulseAudio @var{server} to connect to.
> +
> address@hidden in|address@hidden
> +Use the specified source/sink for recording/playback.
> +
> address@hidden table
> +
> address@hidden -audiodev sdl,address@hidden,@address@hidden,...]]
> +Creates a backend using SDL.  This backend is available on most systems,
> +but you should use your platform's native backend if possible.  This
> +backend has no backend specific properties.
> +
> address@hidden -audiodev spice,address@hidden,@address@hidden,...]]
> +Creates a backend that sends audio through SPICE.  This backend requires
> address@hidden and automatically selected in that case, so usually you
> +can ignore this option.  This backend has no backend specific
> +properties.
> +
> address@hidden -audiodev wav,address@hidden,@address@hidden,...]]
> +Creates a backend that writes audio to a WAV file.
> +
> +Backend specific options are:
> +
> address@hidden @option
> +
> address@hidden address@hidden
> +Write recorded audio into the specified file.  Default is
> address@hidden
> +
> address@hidden table
>  ETEXI
>  
>  DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
> -- 
> 2.20.1
> 
> --
> libvir-list mailing list
> address@hidden
> https://www.redhat.com/mailman/listinfo/libvir-list

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|