[libvirt] [PATCH v5 03/14] audio: -audiodev command line option: documentation
Daniel P. Berrangé
berrange at redhat.com
Fri Feb 22 13:40:42 UTC 2019
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 <DirtY.iCE.hu at gmail.com>
> ---
>
> 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.
> @math{@var{sockets} * @var{cores} * @var{threads} = @var{maxcpus}}.
>
> + at subsection 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
> + at item -audiodev [driver=]@var{driver},id=@var{id}[, at var{prop}[=@var{value}][,...]]
> + at findex -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 @code{in. at var{prop}} and the
> +output's property with @code{out. at var{prop}}. For example:
> + at example
> +-audiodev alsa,id=example,in.frequency=44110,out.frequency=8000
> +-audiodev alsa,id=example,out.channels=1 # leaves in.channels unspecified
> + at end example
> +
> +Valid global options are:
> +
> + at table @option
> + at item id=@var{identifier}
> +Identifies the audio backend.
> +
> + at item timer-period=@var{period}
> +Sets the timer @var{period} used by the audio subsystem in microseconds.
> +Default is 10000 (10 ms).
> +
> + at item 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
> + at var{frequency}, @var{channels} or @var{format}. Default is on.
> +
> + at item in|out.frequency=@var{frequency}
> +Specify the @var{frequency} to use when using @var{fixed-settings}.
> +Default is 44100Hz.
> +
> + at item in|out.channels=@var{channels}
> +Specify the number of @var{channels} to use when using
> + at var{fixed-settings}. Default is 2 (stereo).
> +
> + at item in|out.format=@var{format}
> +Specify the sample @var{format} to use when using @var{fixed-settings}.
> +Valid values are: @code{s8}, @code{s16}, @code{s32}, @code{u8},
> + at code{u16}, @code{u32}. Default is @code{s16}.
> +
> + at item in|out.voices=@var{voices}
> +Specify the number of @var{voices} to use. Default is 1.
> +
> + at item in|out.buffer=@var{usecs}
> +Sets the size of the buffer in microseconds.
> +
> + at end table
> +
> + at item -audiodev none,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +Creates a dummy backend that discards all outputs. This backend has no
> +backend specific properties.
> +
> + at item -audiodev alsa,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +Creates backend using the ALSA. This backend is only available on
> +Linux.
> +
> +ALSA specific options are:
> +
> + at table @option
> +
> + at item in|out.dev=@var{device}
> +Specify the ALSA @var{device} to use for input and/or output. Default
> +is @code{default}.
> +
> + at item in|out.period-len=@var{usecs}
> +Sets the period length in microseconds.
> +
> + at item in|out.try-poll=on|off
> +Attempt to use poll mode with the device. Default is on.
> +
> + at item threshold=@var{threshold}
> +Threshold (in microseconds) when playback starts. Default is 0.
> +
> + at end table
> +
> + at item -audiodev coreaudio,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +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:
> +
> + at table @option
> +
> + at item in|out.buffer-count=@var{count}
> +Sets the @var{count} of the buffers.
> +
> + at end table
> +
> + at item -audiodev dsound,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +Creates a backend using Microsoft's DirectSound. This backend is only
> +available on Windows and only supports playback.
> +
> +DirectSound specific options are:
> +
> + at table @option
> +
> + at item latency=@var{usecs}
> +Add extra @var{usecs} microseconds latency to playback. Default is
> +10000 (10 ms).
> +
> + at end table
> +
> + at item -audiodev oss,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +Creates a backend using OSS. This backend is available on most
> +Unix-like systems.
> +
> +OSS specific options are:
> +
> + at table @option
> +
> + at item in|out.dev=@var{device}
> +Specify the file name of the OSS @var{device} to use. Default is
> + at code{/dev/dsp}.
> +
> + at item in|out.buffer-count=@var{count}
> +Sets the @var{count} of the buffers.
> +
> + at item in|out.try-poll=on|of
> +Attempt to use poll mode with the device. Default is on.
> +
> + at item try-mmap=on|off
> +Try using memory mapped device access. Default is off.
> +
> + at item exclusive=on|off
> +Open the device in exclusive mode (vmix won't work in this case).
> +Default is off.
> +
> + at item dsp-policy=@var{policy}
> +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.
> +
> + at end table
> +
> + at item -audiodev pa,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +Creates a backend using PulseAudio. This backend is available on most
> +systems.
> +
> +PulseAudio specific options are:
> +
> + at table @option
> +
> + at item server=@var{server}
> +Sets the PulseAudio @var{server} to connect to.
> +
> + at item in|out.name=@var{sink}
> +Use the specified source/sink for recording/playback.
> +
> + at end table
> +
> + at item -audiodev sdl,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +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.
> +
> + at item -audiodev spice,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +Creates a backend that sends audio through SPICE. This backend requires
> + at code{-spice} and automatically selected in that case, so usually you
> +can ignore this option. This backend has no backend specific
> +properties.
> +
> + at item -audiodev wav,id=@var{id}[, at var{prop}[=@var{value}][,...]]
> +Creates a backend that writes audio to a WAV file.
> +
> +Backend specific options are:
> +
> + at table @option
> +
> + at item path=@var{path}
> +Write recorded audio into the specified file. Default is
> + at code{qemu.wav}.
> +
> + at end table
> ETEXI
>
> DEF("soundhw", HAS_ARG, QEMU_OPTION_soundhw,
> --
> 2.20.1
>
> --
> libvir-list mailing list
> libvir-list at redhat.com
> 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 :|
More information about the libvir-list
mailing list