a937b6aa73
Change
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.
to
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
# do eiusmod tempor incididunt ut labore et dolore magna aliqua.
See recent commit "qapi: Relax doc string @name: description
indentation rules" for rationale.
Reflow paragraphs to 70 columns width, and consistently use two spaces
to separate sentences.
To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3". Finds no
differences. Comparing with diff is not useful, as the reflown
paragraphs are visible there.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-18-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Acked-by: Lukas Straub <lukasstraub2@web.de>
[Straightforward conflicts in qapi/audio.json qapi/misc-target.json
qapi/run-state.json resolved]
524 lines
13 KiB
Python
524 lines
13 KiB
Python
# -*- mode: python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Copyright (C) 2015-2019 Zoltán Kővágó <DirtY.iCE.hu@gmail.com>
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2 or later.
|
|
# See the COPYING file in the top-level directory.
|
|
|
|
##
|
|
# = Audio
|
|
##
|
|
|
|
##
|
|
# @AudiodevPerDirectionOptions:
|
|
#
|
|
# General audio backend options that are used for both playback and
|
|
# recording.
|
|
#
|
|
# @mixing-engine: use QEMU's mixing engine to mix all streams inside
|
|
# QEMU and convert audio formats when not supported by the
|
|
# backend. When set to off, fixed-settings must be also off
|
|
# (default on, since 4.2)
|
|
#
|
|
# @fixed-settings: use fixed settings for host input/output. When
|
|
# off, frequency, channels and format must not be specified
|
|
# (default true)
|
|
#
|
|
# @frequency: frequency to use when using fixed settings (default
|
|
# 44100)
|
|
#
|
|
# @channels: number of channels when using fixed settings (default 2)
|
|
#
|
|
# @voices: number of voices to use (default 1)
|
|
#
|
|
# @format: sample format to use when using fixed settings (default
|
|
# s16)
|
|
#
|
|
# @buffer-length: the buffer length in microseconds
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*mixing-engine': 'bool',
|
|
'*fixed-settings': 'bool',
|
|
'*frequency': 'uint32',
|
|
'*channels': 'uint32',
|
|
'*voices': 'uint32',
|
|
'*format': 'AudioFormat',
|
|
'*buffer-length': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevGenericOptions:
|
|
#
|
|
# Generic driver-specific options.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevGenericOptions',
|
|
'data': {
|
|
'*in': 'AudiodevPerDirectionOptions',
|
|
'*out': 'AudiodevPerDirectionOptions' } }
|
|
|
|
##
|
|
# @AudiodevAlsaPerDirectionOptions:
|
|
#
|
|
# Options of the ALSA backend that are used for both playback and
|
|
# recording.
|
|
#
|
|
# @dev: the name of the ALSA device to use (default 'default')
|
|
#
|
|
# @period-length: the period length in microseconds
|
|
#
|
|
# @try-poll: attempt to use poll mode, falling back to non-polling
|
|
# access on failure (default true)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevAlsaPerDirectionOptions',
|
|
'base': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*dev': 'str',
|
|
'*period-length': 'uint32',
|
|
'*try-poll': 'bool' } }
|
|
|
|
##
|
|
# @AudiodevAlsaOptions:
|
|
#
|
|
# Options of the ALSA audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# @threshold: set the threshold (in microseconds) when playback starts
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevAlsaOptions',
|
|
'data': {
|
|
'*in': 'AudiodevAlsaPerDirectionOptions',
|
|
'*out': 'AudiodevAlsaPerDirectionOptions',
|
|
'*threshold': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevSndioOptions:
|
|
#
|
|
# Options of the sndio audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# @dev: the name of the sndio device to use (default 'default')
|
|
#
|
|
# @latency: play buffer size (in microseconds)
|
|
#
|
|
# Since: 7.2
|
|
##
|
|
{ 'struct': 'AudiodevSndioOptions',
|
|
'data': {
|
|
'*in': 'AudiodevPerDirectionOptions',
|
|
'*out': 'AudiodevPerDirectionOptions',
|
|
'*dev': 'str',
|
|
'*latency': 'uint32'} }
|
|
|
|
##
|
|
# @AudiodevCoreaudioPerDirectionOptions:
|
|
#
|
|
# Options of the Core Audio backend that are used for both playback
|
|
# and recording.
|
|
#
|
|
# @buffer-count: number of buffers
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevCoreaudioPerDirectionOptions',
|
|
'base': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*buffer-count': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevCoreaudioOptions:
|
|
#
|
|
# Options of the coreaudio audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevCoreaudioOptions',
|
|
'data': {
|
|
'*in': 'AudiodevCoreaudioPerDirectionOptions',
|
|
'*out': 'AudiodevCoreaudioPerDirectionOptions' } }
|
|
|
|
##
|
|
# @AudiodevDsoundOptions:
|
|
#
|
|
# Options of the DirectSound audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# @latency: add extra latency to playback in microseconds (default
|
|
# 10000)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevDsoundOptions',
|
|
'data': {
|
|
'*in': 'AudiodevPerDirectionOptions',
|
|
'*out': 'AudiodevPerDirectionOptions',
|
|
'*latency': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevJackPerDirectionOptions:
|
|
#
|
|
# Options of the JACK backend that are used for both playback and
|
|
# recording.
|
|
#
|
|
# @server-name: select from among several possible concurrent server
|
|
# instances (default: environment variable $JACK_DEFAULT_SERVER if
|
|
# set, else "default")
|
|
#
|
|
# @client-name: the client name to use. The server will modify this
|
|
# name to create a unique variant, if needed unless @exact-name is
|
|
# true (default: the guest's name)
|
|
#
|
|
# @connect-ports: if set, a regular expression of JACK client port
|
|
# name(s) to monitor for and automatically connect to
|
|
#
|
|
# @start-server: start a jack server process if one is not already
|
|
# present (default: false)
|
|
#
|
|
# @exact-name: use the exact name requested otherwise JACK
|
|
# automatically generates a unique one, if needed (default: false)
|
|
#
|
|
# Since: 5.1
|
|
##
|
|
{ 'struct': 'AudiodevJackPerDirectionOptions',
|
|
'base': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*server-name': 'str',
|
|
'*client-name': 'str',
|
|
'*connect-ports': 'str',
|
|
'*start-server': 'bool',
|
|
'*exact-name': 'bool' } }
|
|
|
|
##
|
|
# @AudiodevJackOptions:
|
|
#
|
|
# Options of the JACK audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# Since: 5.1
|
|
##
|
|
{ 'struct': 'AudiodevJackOptions',
|
|
'data': {
|
|
'*in': 'AudiodevJackPerDirectionOptions',
|
|
'*out': 'AudiodevJackPerDirectionOptions' } }
|
|
|
|
##
|
|
# @AudiodevOssPerDirectionOptions:
|
|
#
|
|
# Options of the OSS backend that are used for both playback and
|
|
# recording.
|
|
#
|
|
# @dev: file name of the OSS device (default '/dev/dsp')
|
|
#
|
|
# @buffer-count: number of buffers
|
|
#
|
|
# @try-poll: attempt to use poll mode, falling back to non-polling
|
|
# access on failure (default true)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevOssPerDirectionOptions',
|
|
'base': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*dev': 'str',
|
|
'*buffer-count': 'uint32',
|
|
'*try-poll': 'bool' } }
|
|
|
|
##
|
|
# @AudiodevOssOptions:
|
|
#
|
|
# Options of the OSS audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# @try-mmap: try using memory-mapped access, falling back to
|
|
# non-memory-mapped access on failure (default true)
|
|
#
|
|
# @exclusive: open device in exclusive mode (vmix won't work) (default
|
|
# false)
|
|
#
|
|
# @dsp-policy: set the timing policy of the device (between 0 and 10,
|
|
# where smaller number means smaller latency but higher CPU usage)
|
|
# or -1 to use fragment mode (option ignored on some platforms)
|
|
# (default 5)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevOssOptions',
|
|
'data': {
|
|
'*in': 'AudiodevOssPerDirectionOptions',
|
|
'*out': 'AudiodevOssPerDirectionOptions',
|
|
'*try-mmap': 'bool',
|
|
'*exclusive': 'bool',
|
|
'*dsp-policy': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevPaPerDirectionOptions:
|
|
#
|
|
# Options of the Pulseaudio backend that are used for both playback
|
|
# and recording.
|
|
#
|
|
# @name: name of the sink/source to use
|
|
#
|
|
# @stream-name: name of the PulseAudio stream created by qemu. Can be
|
|
# used to identify the stream in PulseAudio when you create
|
|
# multiple PulseAudio devices or run multiple qemu instances
|
|
# (default: audiodev's id, since 4.2)
|
|
#
|
|
# @latency: latency you want PulseAudio to achieve in microseconds
|
|
# (default 15000)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevPaPerDirectionOptions',
|
|
'base': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*name': 'str',
|
|
'*stream-name': 'str',
|
|
'*latency': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevPaOptions:
|
|
#
|
|
# Options of the PulseAudio audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# @server: PulseAudio server address (default: let PulseAudio choose)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevPaOptions',
|
|
'data': {
|
|
'*in': 'AudiodevPaPerDirectionOptions',
|
|
'*out': 'AudiodevPaPerDirectionOptions',
|
|
'*server': 'str' } }
|
|
|
|
##
|
|
# @AudiodevPipewirePerDirectionOptions:
|
|
#
|
|
# Options of the Pipewire backend that are used for both playback and
|
|
# recording.
|
|
#
|
|
# @name: name of the sink/source to use
|
|
#
|
|
# @stream-name: name of the Pipewire stream created by qemu. Can be
|
|
# used to identify the stream in Pipewire when you create multiple
|
|
# Pipewire devices or run multiple qemu instances (default:
|
|
# audiodev's id)
|
|
#
|
|
# @latency: latency you want Pipewire to achieve in microseconds
|
|
# (default 46000)
|
|
#
|
|
# Since: 8.1
|
|
##
|
|
{ 'struct': 'AudiodevPipewirePerDirectionOptions',
|
|
'base': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*name': 'str',
|
|
'*stream-name': 'str',
|
|
'*latency': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevPipewireOptions:
|
|
#
|
|
# Options of the Pipewire audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# Since: 8.1
|
|
##
|
|
{ 'struct': 'AudiodevPipewireOptions',
|
|
'data': {
|
|
'*in': 'AudiodevPipewirePerDirectionOptions',
|
|
'*out': 'AudiodevPipewirePerDirectionOptions' } }
|
|
|
|
##
|
|
# @AudiodevSdlPerDirectionOptions:
|
|
#
|
|
# Options of the SDL audio backend that are used for both playback and
|
|
# recording.
|
|
#
|
|
# @buffer-count: number of buffers (default 4)
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'struct': 'AudiodevSdlPerDirectionOptions',
|
|
'base': 'AudiodevPerDirectionOptions',
|
|
'data': {
|
|
'*buffer-count': 'uint32' } }
|
|
|
|
##
|
|
# @AudiodevSdlOptions:
|
|
#
|
|
# Options of the SDL audio backend.
|
|
#
|
|
# @in: options of the recording stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'struct': 'AudiodevSdlOptions',
|
|
'data': {
|
|
'*in': 'AudiodevSdlPerDirectionOptions',
|
|
'*out': 'AudiodevSdlPerDirectionOptions' } }
|
|
|
|
##
|
|
# @AudiodevWavOptions:
|
|
#
|
|
# Options of the wav audio backend.
|
|
#
|
|
# @in: options of the capture stream
|
|
#
|
|
# @out: options of the playback stream
|
|
#
|
|
# @path: name of the wav file to record (default 'qemu.wav')
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'struct': 'AudiodevWavOptions',
|
|
'data': {
|
|
'*in': 'AudiodevPerDirectionOptions',
|
|
'*out': 'AudiodevPerDirectionOptions',
|
|
'*path': 'str' } }
|
|
|
|
##
|
|
# @AudioFormat:
|
|
#
|
|
# An enumeration of possible audio formats.
|
|
#
|
|
# @u8: unsigned 8 bit integer
|
|
#
|
|
# @s8: signed 8 bit integer
|
|
#
|
|
# @u16: unsigned 16 bit integer
|
|
#
|
|
# @s16: signed 16 bit integer
|
|
#
|
|
# @u32: unsigned 32 bit integer
|
|
#
|
|
# @s32: signed 32 bit integer
|
|
#
|
|
# @f32: single precision floating-point (since 5.0)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'enum': 'AudioFormat',
|
|
'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] }
|
|
|
|
##
|
|
# @AudiodevDriver:
|
|
#
|
|
# An enumeration of possible audio backend drivers.
|
|
#
|
|
# @jack: JACK audio backend (since 5.1)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'enum': 'AudiodevDriver',
|
|
'data': [ 'none',
|
|
{ 'name': 'alsa', 'if': 'CONFIG_AUDIO_ALSA' },
|
|
{ 'name': 'coreaudio', 'if': 'CONFIG_AUDIO_COREAUDIO' },
|
|
{ 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
|
|
{ 'name': 'dsound', 'if': 'CONFIG_AUDIO_DSOUND' },
|
|
{ 'name': 'jack', 'if': 'CONFIG_AUDIO_JACK' },
|
|
{ 'name': 'oss', 'if': 'CONFIG_AUDIO_OSS' },
|
|
{ 'name': 'pa', 'if': 'CONFIG_AUDIO_PA' },
|
|
{ 'name': 'pipewire', 'if': 'CONFIG_AUDIO_PIPEWIRE' },
|
|
{ 'name': 'sdl', 'if': 'CONFIG_AUDIO_SDL' },
|
|
{ 'name': 'sndio', 'if': 'CONFIG_AUDIO_SNDIO' },
|
|
{ 'name': 'spice', 'if': 'CONFIG_SPICE' },
|
|
'wav' ] }
|
|
|
|
##
|
|
# @Audiodev:
|
|
#
|
|
# Options of an audio backend.
|
|
#
|
|
# @id: identifier of the backend
|
|
#
|
|
# @driver: the backend driver to use
|
|
#
|
|
# @timer-period: timer period (in microseconds, 0: use lowest
|
|
# possible)
|
|
#
|
|
# Since: 4.0
|
|
##
|
|
{ 'union': 'Audiodev',
|
|
'base': {
|
|
'id': 'str',
|
|
'driver': 'AudiodevDriver',
|
|
'*timer-period': 'uint32' },
|
|
'discriminator': 'driver',
|
|
'data': {
|
|
'none': 'AudiodevGenericOptions',
|
|
'alsa': { 'type': 'AudiodevAlsaOptions',
|
|
'if': 'CONFIG_AUDIO_ALSA' },
|
|
'coreaudio': { 'type': 'AudiodevCoreaudioOptions',
|
|
'if': 'CONFIG_AUDIO_COREAUDIO' },
|
|
'dbus': { 'type': 'AudiodevGenericOptions',
|
|
'if': 'CONFIG_DBUS_DISPLAY' },
|
|
'dsound': { 'type': 'AudiodevDsoundOptions',
|
|
'if': 'CONFIG_AUDIO_DSOUND' },
|
|
'jack': { 'type': 'AudiodevJackOptions',
|
|
'if': 'CONFIG_AUDIO_JACK' },
|
|
'oss': { 'type': 'AudiodevOssOptions',
|
|
'if': 'CONFIG_AUDIO_OSS' },
|
|
'pa': { 'type': 'AudiodevPaOptions',
|
|
'if': 'CONFIG_AUDIO_PA' },
|
|
'pipewire': { 'type': 'AudiodevPipewireOptions',
|
|
'if': 'CONFIG_AUDIO_PIPEWIRE' },
|
|
'sdl': { 'type': 'AudiodevSdlOptions',
|
|
'if': 'CONFIG_AUDIO_SDL' },
|
|
'sndio': { 'type': 'AudiodevSndioOptions',
|
|
'if': 'CONFIG_AUDIO_SNDIO' },
|
|
'spice': { 'type': 'AudiodevGenericOptions',
|
|
'if': 'CONFIG_SPICE' },
|
|
'wav': 'AudiodevWavOptions' } }
|
|
|
|
##
|
|
# @query-audiodevs:
|
|
#
|
|
# Returns information about audiodev configuration
|
|
#
|
|
# Returns: array of @Audiodev
|
|
#
|
|
# Since: 8.0
|
|
##
|
|
{ 'command': 'query-audiodevs',
|
|
'returns': ['Audiodev'] }
|