qapi/audio.json

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