qapi/audio.json

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