qga/qapi-schema: Reformat doc comments to conform to current conventions

[mirror_qemu.git] / qapi / audio.json

# -*- 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'] }