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 # = 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 # @AudiodevWavOptions:
 306 #
 307 # Options of the wav audio backend.
 308 #
 309 # @in: options of the capture stream
 310 #
 311 # @out: options of the playback stream
 312 #
 313 # @path: name of the wav file to record (default 'qemu.wav')
 314 #
 315 # Since: 4.0
 316 ##
 317 { 'struct': 'AudiodevWavOptions',
 318   'data': {
 319     '*in':   'AudiodevPerDirectionOptions',
 320     '*out':  'AudiodevPerDirectionOptions',
 321     '*path': 'str' } }
 322
 323
 324 ##
 325 # @AudioFormat:
 326 #
 327 # An enumeration of possible audio formats.
 328 #
 329 # @u8: unsigned 8 bit integer
 330 #
 331 # @s8: signed 8 bit integer
 332 #
 333 # @u16: unsigned 16 bit integer
 334 #
 335 # @s16: signed 16 bit integer
 336 #
 337 # @u32: unsigned 32 bit integer
 338 #
 339 # @s32: signed 32 bit integer
 340 #
 341 # @f32: single precision floating-point (since 5.0)
 342 #
 343 # Since: 4.0
 344 ##
 345 { 'enum': 'AudioFormat',
 346   'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] }
 347
 348 ##
 349 # @AudiodevDriver:
 350 #
 351 # An enumeration of possible audio backend drivers.
 352 #
 353 # @jack: JACK audio backend (since 5.1)
 354 #
 355 # Since: 4.0
 356 ##
 357 { 'enum': 'AudiodevDriver',
 358   'data': [ 'none', 'alsa', 'coreaudio', 'dsound', 'jack', 'oss', 'pa',
 359             'sdl', 'spice', 'wav' ] }
 360
 361 ##
 362 # @Audiodev:
 363 #
 364 # Options of an audio backend.
 365 #
 366 # @id: identifier of the backend
 367 #
 368 # @driver: the backend driver to use
 369 #
 370 # @timer-period: timer period (in microseconds, 0: use lowest possible)
 371 #
 372 # Since: 4.0
 373 ##
 374 { 'union': 'Audiodev',
 375   'base': {
 376     'id':            'str',
 377     'driver':        'AudiodevDriver',
 378     '*timer-period': 'uint32' },
 379   'discriminator': 'driver',
 380   'data': {
 381     'none':      'AudiodevGenericOptions',
 382     'alsa':      'AudiodevAlsaOptions',
 383     'coreaudio': 'AudiodevCoreaudioOptions',
 384     'dsound':    'AudiodevDsoundOptions',
 385     'jack':      'AudiodevJackOptions',
 386     'oss':       'AudiodevOssOptions',
 387     'pa':        'AudiodevPaOptions',
 388     'sdl':       'AudiodevGenericOptions',
 389     'spice':     'AudiodevGenericOptions',
 390     'wav':       'AudiodevWavOptions' } }