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 # @AudiodevOssPerDirectionOptions:
 157 #
 158 # Options of the OSS backend that are used for both playback and
 159 # recording.
 160 #
 161 # @dev: file name of the OSS device (default '/dev/dsp')
 162 #
 163 # @buffer-count: number of buffers
 164 #
 165 # @try-poll: attempt to use poll mode, falling back to non-polling
 166 #            access on failure (default true)
 167 #
 168 # Since: 4.0
 169 ##
 170 { 'struct': 'AudiodevOssPerDirectionOptions',
 171   'base': 'AudiodevPerDirectionOptions',
 172   'data': {
 173     '*dev':          'str',
 174     '*buffer-count': 'uint32',
 175     '*try-poll':     'bool' } }
 176
 177 ##
 178 # @AudiodevOssOptions:
 179 #
 180 # Options of the OSS audio backend.
 181 #
 182 # @in: options of the capture stream
 183 #
 184 # @out: options of the playback stream
 185 #
 186 # @try-mmap: try using memory-mapped access, falling back to
 187 #            non-memory-mapped access on failure (default true)
 188 #
 189 # @exclusive: open device in exclusive mode (vmix won't work)
 190 #             (default false)
 191 #
 192 # @dsp-policy: set the timing policy of the device (between 0 and 10,
 193 #              where smaller number means smaller latency but higher
 194 #              CPU usage) or -1 to use fragment mode (option ignored
 195 #              on some platforms) (default 5)
 196 #
 197 # Since: 4.0
 198 ##
 199 { 'struct': 'AudiodevOssOptions',
 200   'data': {
 201     '*in':         'AudiodevOssPerDirectionOptions',
 202     '*out':        'AudiodevOssPerDirectionOptions',
 203     '*try-mmap':   'bool',
 204     '*exclusive':  'bool',
 205     '*dsp-policy': 'uint32' } }
 206
 207 ##
 208 # @AudiodevPaPerDirectionOptions:
 209 #
 210 # Options of the Pulseaudio backend that are used for both playback and
 211 # recording.
 212 #
 213 # @name: name of the sink/source to use
 214 #
 215 # @stream-name: name of the PulseAudio stream created by qemu.  Can be
 216 #               used to identify the stream in PulseAudio when you
 217 #               create multiple PulseAudio devices or run multiple qemu
 218 #               instances (default: audiodev's id, since 4.2)
 219 #
 220 # @latency: latency you want PulseAudio to achieve in microseconds
 221 #           (default 15000)
 222 #
 223 # Since: 4.0
 224 ##
 225 { 'struct': 'AudiodevPaPerDirectionOptions',
 226   'base': 'AudiodevPerDirectionOptions',
 227   'data': {
 228     '*name': 'str',
 229     '*stream-name': 'str',
 230     '*latency': 'uint32' } }
 231
 232 ##
 233 # @AudiodevPaOptions:
 234 #
 235 # Options of the PulseAudio audio backend.
 236 #
 237 # @in: options of the capture stream
 238 #
 239 # @out: options of the playback stream
 240 #
 241 # @server: PulseAudio server address (default: let PulseAudio choose)
 242 #
 243 # Since: 4.0
 244 ##
 245 { 'struct': 'AudiodevPaOptions',
 246   'data': {
 247     '*in':     'AudiodevPaPerDirectionOptions',
 248     '*out':    'AudiodevPaPerDirectionOptions',
 249     '*server': 'str' } }
 250
 251 ##
 252 # @AudiodevWavOptions:
 253 #
 254 # Options of the wav audio backend.
 255 #
 256 # @in: options of the capture stream
 257 #
 258 # @out: options of the playback stream
 259 #
 260 # @path: name of the wav file to record (default 'qemu.wav')
 261 #
 262 # Since: 4.0
 263 ##
 264 { 'struct': 'AudiodevWavOptions',
 265   'data': {
 266     '*in':   'AudiodevPerDirectionOptions',
 267     '*out':  'AudiodevPerDirectionOptions',
 268     '*path': 'str' } }
 269
 270
 271 ##
 272 # @AudioFormat:
 273 #
 274 # An enumeration of possible audio formats.
 275 #
 276 # @u8: unsigned 8 bit integer
 277 #
 278 # @s8: signed 8 bit integer
 279 #
 280 # @u16: unsigned 16 bit integer
 281 #
 282 # @s16: signed 16 bit integer
 283 #
 284 # @u32: unsigned 32 bit integer
 285 #
 286 # @s32: signed 32 bit integer
 287 #
 288 # @f32: single precision floating-point (since 5.0)
 289 #
 290 # Since: 4.0
 291 ##
 292 { 'enum': 'AudioFormat',
 293   'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] }
 294
 295 ##
 296 # @AudiodevDriver:
 297 #
 298 # An enumeration of possible audio backend drivers.
 299 #
 300 # Since: 4.0
 301 ##
 302 { 'enum': 'AudiodevDriver',
 303   'data': [ 'none', 'alsa', 'coreaudio', 'dsound', 'oss', 'pa', 'sdl',
 304             'spice', 'wav' ] }
 305
 306 ##
 307 # @Audiodev:
 308 #
 309 # Options of an audio backend.
 310 #
 311 # @id: identifier of the backend
 312 #
 313 # @driver: the backend driver to use
 314 #
 315 # @timer-period: timer period (in microseconds, 0: use lowest possible)
 316 #
 317 # Since: 4.0
 318 ##
 319 { 'union': 'Audiodev',
 320   'base': {
 321     'id':            'str',
 322     'driver':        'AudiodevDriver',
 323     '*timer-period': 'uint32' },
 324   'discriminator': 'driver',
 325   'data': {
 326     'none':      'AudiodevGenericOptions',
 327     'alsa':      'AudiodevAlsaOptions',
 328     'coreaudio': 'AudiodevCoreaudioOptions',
 329     'dsound':    'AudiodevDsoundOptions',
 330     'oss':       'AudiodevOssOptions',
 331     'pa':        'AudiodevPaOptions',
 332     'sdl':       'AudiodevGenericOptions',
 333     'spice':     'AudiodevGenericOptions',
 334     'wav':       'AudiodevWavOptions' } }