qemu/qapi/audio.json
<<
>>
Prefs
   1# -*- mode: python -*-
   2#
   3# Copyright (C) 2015-2019 Zoltán Kővágó <DirtY.iCE.hu@gmail.com>
   4#
   5# This work is licensed under the terms of the GNU GPL, version 2 or later.
   6# See the COPYING file in the top-level directory.
   7
   8##
   9# = Audio
  10##
  11
  12##
  13# @AudiodevPerDirectionOptions:
  14#
  15# General audio backend options that are used for both playback and
  16# recording.
  17#
  18# @mixing-engine: use QEMU's mixing engine to mix all streams inside QEMU and
  19#                 convert audio formats when not supported by the backend. When
  20#                 set to off, fixed-settings must be also off (default on,
  21#                 since 4.2)
  22#
  23# @fixed-settings: use fixed settings for host input/output. When off,
  24#                  frequency, channels and format must not be
  25#                  specified (default true)
  26#
  27# @frequency: frequency to use when using fixed settings
  28#             (default 44100)
  29#
  30# @channels: number of channels when using fixed settings (default 2)
  31#
  32# @voices: number of voices to use (default 1)
  33#
  34# @format: sample format to use when using fixed settings
  35#          (default s16)
  36#
  37# @buffer-length: the buffer length in microseconds
  38#
  39# Since: 4.0
  40##
  41{ 'struct': 'AudiodevPerDirectionOptions',
  42  'data': {
  43    '*mixing-engine':  'bool',
  44    '*fixed-settings': 'bool',
  45    '*frequency':      'uint32',
  46    '*channels':       'uint32',
  47    '*voices':         'uint32',
  48    '*format':         'AudioFormat',
  49    '*buffer-length':  'uint32' } }
  50
  51##
  52# @AudiodevGenericOptions:
  53#
  54# Generic driver-specific options.
  55#
  56# @in: options of the capture stream
  57#
  58# @out: options of the playback stream
  59#
  60# Since: 4.0
  61##
  62{ 'struct': 'AudiodevGenericOptions',
  63  'data': {
  64    '*in':  'AudiodevPerDirectionOptions',
  65    '*out': 'AudiodevPerDirectionOptions' } }
  66
  67##
  68# @AudiodevAlsaPerDirectionOptions:
  69#
  70# Options of the ALSA backend that are used for both playback and
  71# recording.
  72#
  73# @dev: the name of the ALSA device to use (default 'default')
  74#
  75# @period-length: the period length in microseconds
  76#
  77# @try-poll: attempt to use poll mode, falling back to non-polling
  78#            access on failure (default true)
  79#
  80# Since: 4.0
  81##
  82{ 'struct': 'AudiodevAlsaPerDirectionOptions',
  83  'base': 'AudiodevPerDirectionOptions',
  84  'data': {
  85    '*dev':           'str',
  86    '*period-length': 'uint32',
  87    '*try-poll':      'bool' } }
  88
  89##
  90# @AudiodevAlsaOptions:
  91#
  92# Options of the ALSA audio backend.
  93#
  94# @in: options of the capture stream
  95#
  96# @out: options of the playback stream
  97#
  98# @threshold: set the threshold (in microseconds) when playback starts
  99#
 100# Since: 4.0
 101##
 102{ 'struct': 'AudiodevAlsaOptions',
 103  'data': {
 104    '*in':        'AudiodevAlsaPerDirectionOptions',
 105    '*out':       'AudiodevAlsaPerDirectionOptions',
 106    '*threshold': 'uint32' } }
 107
 108##
 109# @AudiodevCoreaudioPerDirectionOptions:
 110#
 111# Options of the Core Audio backend that are used for both playback and
 112# recording.
 113#
 114# @buffer-count: number of buffers
 115#
 116# Since: 4.0
 117##
 118{ 'struct': 'AudiodevCoreaudioPerDirectionOptions',
 119  'base': 'AudiodevPerDirectionOptions',
 120  'data': {
 121    '*buffer-count': 'uint32' } }
 122
 123##
 124# @AudiodevCoreaudioOptions:
 125#
 126# Options of the coreaudio audio backend.
 127#
 128# @in: options of the capture stream
 129#
 130# @out: options of the playback stream
 131#
 132# Since: 4.0
 133##
 134{ 'struct': 'AudiodevCoreaudioOptions',
 135  'data': {
 136    '*in':  'AudiodevCoreaudioPerDirectionOptions',
 137    '*out': 'AudiodevCoreaudioPerDirectionOptions' } }
 138
 139##
 140# @AudiodevDsoundOptions:
 141#
 142# Options of the DirectSound audio backend.
 143#
 144# @in: options of the capture stream
 145#
 146# @out: options of the playback stream
 147#
 148# @latency: add extra latency to playback in microseconds
 149#           (default 10000)
 150#
 151# Since: 4.0
 152##
 153{ 'struct': 'AudiodevDsoundOptions',
 154  'data': {
 155    '*in':      'AudiodevPerDirectionOptions',
 156    '*out':     'AudiodevPerDirectionOptions',
 157    '*latency': 'uint32' } }
 158
 159##
 160# @AudiodevJackPerDirectionOptions:
 161#
 162# Options of the JACK backend that are used for both playback and
 163# recording.
 164#
 165# @server-name: select from among several possible concurrent server instances
 166#               (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
 167#
 168# @client-name: the client name to use. The server will modify this name to
 169#               create a unique variant, if needed unless @exact-name is true (default: the
 170#               guest's name)
 171#
 172# @connect-ports: if set, a regular expression of JACK client port name(s) to
 173#                 monitor for and automatically connect to
 174#
 175# @start-server: start a jack server process if one is not already present
 176#                (default: false)
 177#
 178# @exact-name: use the exact name requested otherwise JACK automatically
 179#              generates a unique one, if needed (default: false)
 180#
 181# Since: 5.1
 182##
 183{ 'struct': 'AudiodevJackPerDirectionOptions',
 184  'base': 'AudiodevPerDirectionOptions',
 185  'data': {
 186    '*server-name':   'str',
 187    '*client-name':   'str',
 188    '*connect-ports': 'str',
 189    '*start-server':  'bool',
 190    '*exact-name':    'bool' } }
 191
 192##
 193# @AudiodevJackOptions:
 194#
 195# Options of the JACK audio backend.
 196#
 197# @in: options of the capture stream
 198#
 199# @out: options of the playback stream
 200#
 201# Since: 5.1
 202##
 203{ 'struct': 'AudiodevJackOptions',
 204  'data': {
 205    '*in':  'AudiodevJackPerDirectionOptions',
 206    '*out': 'AudiodevJackPerDirectionOptions' } }
 207
 208##
 209# @AudiodevOssPerDirectionOptions:
 210#
 211# Options of the OSS backend that are used for both playback and
 212# recording.
 213#
 214# @dev: file name of the OSS device (default '/dev/dsp')
 215#
 216# @buffer-count: number of buffers
 217#
 218# @try-poll: attempt to use poll mode, falling back to non-polling
 219#            access on failure (default true)
 220#
 221# Since: 4.0
 222##
 223{ 'struct': 'AudiodevOssPerDirectionOptions',
 224  'base': 'AudiodevPerDirectionOptions',
 225  'data': {
 226    '*dev':          'str',
 227    '*buffer-count': 'uint32',
 228    '*try-poll':     'bool' } }
 229
 230##
 231# @AudiodevOssOptions:
 232#
 233# Options of the OSS audio backend.
 234#
 235# @in: options of the capture stream
 236#
 237# @out: options of the playback stream
 238#
 239# @try-mmap: try using memory-mapped access, falling back to
 240#            non-memory-mapped access on failure (default true)
 241#
 242# @exclusive: open device in exclusive mode (vmix won't work)
 243#             (default false)
 244#
 245# @dsp-policy: set the timing policy of the device (between 0 and 10,
 246#              where smaller number means smaller latency but higher
 247#              CPU usage) or -1 to use fragment mode (option ignored
 248#              on some platforms) (default 5)
 249#
 250# Since: 4.0
 251##
 252{ 'struct': 'AudiodevOssOptions',
 253  'data': {
 254    '*in':         'AudiodevOssPerDirectionOptions',
 255    '*out':        'AudiodevOssPerDirectionOptions',
 256    '*try-mmap':   'bool',
 257    '*exclusive':  'bool',
 258    '*dsp-policy': 'uint32' } }
 259
 260##
 261# @AudiodevPaPerDirectionOptions:
 262#
 263# Options of the Pulseaudio backend that are used for both playback and
 264# recording.
 265#
 266# @name: name of the sink/source to use
 267#
 268# @stream-name: name of the PulseAudio stream created by qemu.  Can be
 269#               used to identify the stream in PulseAudio when you
 270#               create multiple PulseAudio devices or run multiple qemu
 271#               instances (default: audiodev's id, since 4.2)
 272#
 273# @latency: latency you want PulseAudio to achieve in microseconds
 274#           (default 15000)
 275#
 276# Since: 4.0
 277##
 278{ 'struct': 'AudiodevPaPerDirectionOptions',
 279  'base': 'AudiodevPerDirectionOptions',
 280  'data': {
 281    '*name': 'str',
 282    '*stream-name': 'str',
 283    '*latency': 'uint32' } }
 284
 285##
 286# @AudiodevPaOptions:
 287#
 288# Options of the PulseAudio audio backend.
 289#
 290# @in: options of the capture stream
 291#
 292# @out: options of the playback stream
 293#
 294# @server: PulseAudio server address (default: let PulseAudio choose)
 295#
 296# Since: 4.0
 297##
 298{ 'struct': 'AudiodevPaOptions',
 299  'data': {
 300    '*in':     'AudiodevPaPerDirectionOptions',
 301    '*out':    'AudiodevPaPerDirectionOptions',
 302    '*server': 'str' } }
 303
 304##
 305# @AudiodevSdlPerDirectionOptions:
 306#
 307# Options of the SDL audio backend that are used for both playback and
 308# recording.
 309#
 310# @buffer-count: number of buffers (default 4)
 311#
 312# Since: 6.0
 313##
 314{ 'struct': 'AudiodevSdlPerDirectionOptions',
 315  'base': 'AudiodevPerDirectionOptions',
 316  'data': {
 317    '*buffer-count': 'uint32' } }
 318
 319##
 320# @AudiodevSdlOptions:
 321#
 322# Options of the SDL audio backend.
 323#
 324# @in: options of the recording stream
 325#
 326# @out: options of the playback stream
 327#
 328# Since: 6.0
 329##
 330{ 'struct': 'AudiodevSdlOptions',
 331  'data': {
 332    '*in':  'AudiodevSdlPerDirectionOptions',
 333    '*out': 'AudiodevSdlPerDirectionOptions' } }
 334
 335##
 336# @AudiodevWavOptions:
 337#
 338# Options of the wav audio backend.
 339#
 340# @in: options of the capture stream
 341#
 342# @out: options of the playback stream
 343#
 344# @path: name of the wav file to record (default 'qemu.wav')
 345#
 346# Since: 4.0
 347##
 348{ 'struct': 'AudiodevWavOptions',
 349  'data': {
 350    '*in':   'AudiodevPerDirectionOptions',
 351    '*out':  'AudiodevPerDirectionOptions',
 352    '*path': 'str' } }
 353
 354
 355##
 356# @AudioFormat:
 357#
 358# An enumeration of possible audio formats.
 359#
 360# @u8: unsigned 8 bit integer
 361#
 362# @s8: signed 8 bit integer
 363#
 364# @u16: unsigned 16 bit integer
 365#
 366# @s16: signed 16 bit integer
 367#
 368# @u32: unsigned 32 bit integer
 369#
 370# @s32: signed 32 bit integer
 371#
 372# @f32: single precision floating-point (since 5.0)
 373#
 374# Since: 4.0
 375##
 376{ 'enum': 'AudioFormat',
 377  'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] }
 378
 379##
 380# @AudiodevDriver:
 381#
 382# An enumeration of possible audio backend drivers.
 383#
 384# @jack: JACK audio backend (since 5.1)
 385#
 386# Since: 4.0
 387##
 388{ 'enum': 'AudiodevDriver',
 389  'data': [ 'none', 'alsa', 'coreaudio', 'dsound', 'jack', 'oss', 'pa',
 390            'sdl', 'spice', 'wav' ] }
 391
 392##
 393# @Audiodev:
 394#
 395# Options of an audio backend.
 396#
 397# @id: identifier of the backend
 398#
 399# @driver: the backend driver to use
 400#
 401# @timer-period: timer period (in microseconds, 0: use lowest possible)
 402#
 403# Since: 4.0
 404##
 405{ 'union': 'Audiodev',
 406  'base': {
 407    'id':            'str',
 408    'driver':        'AudiodevDriver',
 409    '*timer-period': 'uint32' },
 410  'discriminator': 'driver',
 411  'data': {
 412    'none':      'AudiodevGenericOptions',
 413    'alsa':      'AudiodevAlsaOptions',
 414    'coreaudio': 'AudiodevCoreaudioOptions',
 415    'dsound':    'AudiodevDsoundOptions',
 416    'jack':      'AudiodevJackOptions',
 417    'oss':       'AudiodevOssOptions',
 418    'pa':        'AudiodevPaOptions',
 419    'sdl':       'AudiodevSdlOptions',
 420    'spice':     'AudiodevGenericOptions',
 421    'wav':       'AudiodevWavOptions' } }
 422