qapi/audio.json

   1 # -*- mode: python -*-
   2 # vim: filetype=python
   3 #
   4 # Copyright (C) 2015-2019 Zoltán Kővágó <[email protected]>
   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 QEMU and
  20 #                 convert audio formats when not supported by the backend. When
  21 #                 set to off, fixed-settings must be also off (default on,
  22 #                 since 4.2)
  23 #
  24 # @fixed-settings: use fixed settings for host input/output. When off,
  25 #                  frequency, channels and format must not be
  26 #                  specified (default true)
  27 #
  28 # @frequency: frequency to use when using fixed settings
  29 #             (default 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
  36 #          (default 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 # @AudiodevCoreaudioPerDirectionOptions:
 111 #
 112 # Options of the Core Audio backend that are used for both playback and
 113 # recording.
 114 #
 115 # @buffer-count: number of buffers
 116 #
 117 # Since: 4.0
 118 ##
 119 { 'struct': 'AudiodevCoreaudioPerDirectionOptions',
 120   'base': 'AudiodevPerDirectionOptions',
 121   'data': {
 122     '*buffer-count': 'uint32' } }
 123
 124 ##
 125 # @AudiodevCoreaudioOptions:
 126 #
 127 # Options of the coreaudio audio backend.
 128 #
 129 # @in: options of the capture stream
 130 #
 131 # @out: options of the playback stream
 132 #
 133 # Since: 4.0
 134 ##
 135 { 'struct': 'AudiodevCoreaudioOptions',
 136   'data': {
 137     '*in':  'AudiodevCoreaudioPerDirectionOptions',
 138     '*out': 'AudiodevCoreaudioPerDirectionOptions' } }
 139
 140 ##
 141 # @AudiodevDsoundOptions:
 142 #
 143 # Options of the DirectSound audio backend.
 144 #
 145 # @in: options of the capture stream
 146 #
 147 # @out: options of the playback stream
 148 #
 149 # @latency: add extra latency to playback in microseconds
 150 #           (default 10000)
 151 #
 152 # Since: 4.0
 153 ##
 154 { 'struct': 'AudiodevDsoundOptions',
 155   'data': {
 156     '*in':      'AudiodevPerDirectionOptions',
 157     '*out':     'AudiodevPerDirectionOptions',
 158     '*latency': 'uint32' } }
 159
 160 ##
 161 # @AudiodevJackPerDirectionOptions:
 162 #
 163 # Options of the JACK backend that are used for both playback and
 164 # recording.
 165 #
 166 # @server-name: select from among several possible concurrent server instances
 167 #               (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
 168 #
 169 # @client-name: the client name to use. The server will modify this name to
 170 #               create a unique variant, if needed unless @exact-name is true (default: the
 171 #               guest's name)
 172 #
 173 # @connect-ports: if set, a regular expression of JACK client port name(s) to
 174 #                 monitor for and automatically connect to
 175 #
 176 # @start-server: start a jack server process if one is not already present
 177 #                (default: false)
 178 #
 179 # @exact-name: use the exact name requested otherwise JACK automatically
 180 #              generates a unique one, if needed (default: false)
 181 #
 182 # Since: 5.1
 183 ##
 184 { 'struct': 'AudiodevJackPerDirectionOptions',
 185   'base': 'AudiodevPerDirectionOptions',
 186   'data': {
 187     '*server-name':   'str',
 188     '*client-name':   'str',
 189     '*connect-ports': 'str',
 190     '*start-server':  'bool',
 191     '*exact-name':    'bool' } }
 192
 193 ##
 194 # @AudiodevJackOptions:
 195 #
 196 # Options of the JACK audio backend.
 197 #
 198 # @in: options of the capture stream
 199 #
 200 # @out: options of the playback stream
 201 #
 202 # Since: 5.1
 203 ##
 204 { 'struct': 'AudiodevJackOptions',
 205   'data': {
 206     '*in':  'AudiodevJackPerDirectionOptions',
 207     '*out': 'AudiodevJackPerDirectionOptions' } }
 208
 209 ##
 210 # @AudiodevOssPerDirectionOptions:
 211 #
 212 # Options of the OSS backend that are used for both playback and
 213 # recording.
 214 #
 215 # @dev: file name of the OSS device (default '/dev/dsp')
 216 #
 217 # @buffer-count: number of buffers
 218 #
 219 # @try-poll: attempt to use poll mode, falling back to non-polling
 220 #            access on failure (default true)
 221 #
 222 # Since: 4.0
 223 ##
 224 { 'struct': 'AudiodevOssPerDirectionOptions',
 225   'base': 'AudiodevPerDirectionOptions',
 226   'data': {
 227     '*dev':          'str',
 228     '*buffer-count': 'uint32',
 229     '*try-poll':     'bool' } }
 230
 231 ##
 232 # @AudiodevOssOptions:
 233 #
 234 # Options of the OSS audio backend.
 235 #
 236 # @in: options of the capture stream
 237 #
 238 # @out: options of the playback stream
 239 #
 240 # @try-mmap: try using memory-mapped access, falling back to
 241 #            non-memory-mapped access on failure (default true)
 242 #
 243 # @exclusive: open device in exclusive mode (vmix won't work)
 244 #             (default false)
 245 #
 246 # @dsp-policy: set the timing policy of the device (between 0 and 10,
 247 #              where smaller number means smaller latency but higher
 248 #              CPU usage) or -1 to use fragment mode (option ignored
 249 #              on some platforms) (default 5)
 250 #
 251 # Since: 4.0
 252 ##
 253 { 'struct': 'AudiodevOssOptions',
 254   'data': {
 255     '*in':         'AudiodevOssPerDirectionOptions',
 256     '*out':        'AudiodevOssPerDirectionOptions',
 257     '*try-mmap':   'bool',
 258     '*exclusive':  'bool',
 259     '*dsp-policy': 'uint32' } }
 260
 261 ##
 262 # @AudiodevPaPerDirectionOptions:
 263 #
 264 # Options of the Pulseaudio backend that are used for both playback and
 265 # recording.
 266 #
 267 # @name: name of the sink/source to use
 268 #
 269 # @stream-name: name of the PulseAudio stream created by qemu.  Can be
 270 #               used to identify the stream in PulseAudio when you
 271 #               create multiple PulseAudio devices or run multiple qemu
 272 #               instances (default: audiodev's id, since 4.2)
 273 #
 274 # @latency: latency you want PulseAudio to achieve in microseconds
 275 #           (default 15000)
 276 #
 277 # Since: 4.0
 278 ##
 279 { 'struct': 'AudiodevPaPerDirectionOptions',
 280   'base': 'AudiodevPerDirectionOptions',
 281   'data': {
 282     '*name': 'str',
 283     '*stream-name': 'str',
 284     '*latency': 'uint32' } }
 285
 286 ##
 287 # @AudiodevPaOptions:
 288 #
 289 # Options of the PulseAudio audio backend.
 290 #
 291 # @in: options of the capture stream
 292 #
 293 # @out: options of the playback stream
 294 #
 295 # @server: PulseAudio server address (default: let PulseAudio choose)
 296 #
 297 # Since: 4.0
 298 ##
 299 { 'struct': 'AudiodevPaOptions',
 300   'data': {
 301     '*in':     'AudiodevPaPerDirectionOptions',
 302     '*out':    'AudiodevPaPerDirectionOptions',
 303     '*server': 'str' } }
 304
 305 ##
 306 # @AudiodevSdlPerDirectionOptions:
 307 #
 308 # Options of the SDL audio backend that are used for both playback and
 309 # recording.
 310 #
 311 # @buffer-count: number of buffers (default 4)
 312 #
 313 # Since: 6.0
 314 ##
 315 { 'struct': 'AudiodevSdlPerDirectionOptions',
 316   'base': 'AudiodevPerDirectionOptions',
 317   'data': {
 318     '*buffer-count': 'uint32' } }
 319
 320 ##
 321 # @AudiodevSdlOptions:
 322 #
 323 # Options of the SDL audio backend.
 324 #
 325 # @in: options of the recording stream
 326 #
 327 # @out: options of the playback stream
 328 #
 329 # Since: 6.0
 330 ##
 331 { 'struct': 'AudiodevSdlOptions',
 332   'data': {
 333     '*in':  'AudiodevSdlPerDirectionOptions',
 334     '*out': 'AudiodevSdlPerDirectionOptions' } }
 335
 336 ##
 337 # @AudiodevWavOptions:
 338 #
 339 # Options of the wav audio backend.
 340 #
 341 # @in: options of the capture stream
 342 #
 343 # @out: options of the playback stream
 344 #
 345 # @path: name of the wav file to record (default 'qemu.wav')
 346 #
 347 # Since: 4.0
 348 ##
 349 { 'struct': 'AudiodevWavOptions',
 350   'data': {
 351     '*in':   'AudiodevPerDirectionOptions',
 352     '*out':  'AudiodevPerDirectionOptions',
 353     '*path': 'str' } }
 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', 'dbus', '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     'dbus':      'AudiodevGenericOptions',
 416     'dsound':    'AudiodevDsoundOptions',
 417     'jack':      'AudiodevJackOptions',
 418     'oss':       'AudiodevOssOptions',
 419     'pa':        'AudiodevPaOptions',
 420     'sdl':       'AudiodevSdlOptions',
 421     'spice':     'AudiodevGenericOptions',
 422     'wav':       'AudiodevWavOptions' } }