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 # @fixed-settings: use fixed settings for host input/output. When off,
  15 #                  frequency, channels and format must not be
  16 #                  specified (default true)
  17 #
  18 # @frequency: frequency to use when using fixed settings
  19 #             (default 44100)
  20 #
  21 # @channels: number of channels when using fixed settings (default 2)
  22 #
  23 # @voices: number of voices to use (default 1)
  24 #
  25 # @format: sample format to use when using fixed settings
  26 #          (default s16)
  27 #
  28 # @buffer-length: the buffer length in microseconds
  29 #
  30 # Since: 4.0
  31 ##
  32 { 'struct': 'AudiodevPerDirectionOptions',
  33   'data': {
  34     '*fixed-settings': 'bool',
  35     '*frequency':      'uint32',
  36     '*channels':       'uint32',
  37     '*voices':         'uint32',
  38     '*format':         'AudioFormat',
  39     '*buffer-length':  'uint32' } }
  40
  41 ##
  42 # @AudiodevGenericOptions:
  43 #
  44 # Generic driver-specific options.
  45 #
  46 # @in: options of the capture stream
  47 #
  48 # @out: options of the playback stream
  49 #
  50 # Since: 4.0
  51 ##
  52 { 'struct': 'AudiodevGenericOptions',
  53   'data': {
  54     '*in':  'AudiodevPerDirectionOptions',
  55     '*out': 'AudiodevPerDirectionOptions' } }
  56
  57 ##
  58 # @AudiodevAlsaPerDirectionOptions:
  59 #
  60 # Options of the ALSA backend that are used for both playback and
  61 # recording.
  62 #
  63 # @dev: the name of the ALSA device to use (default 'default')
  64 #
  65 # @period-length: the period length in microseconds
  66 #
  67 # @try-poll: attempt to use poll mode, falling back to non-polling
  68 #            access on failure (default true)
  69 #
  70 # Since: 4.0
  71 ##
  72 { 'struct': 'AudiodevAlsaPerDirectionOptions',
  73   'base': 'AudiodevPerDirectionOptions',
  74   'data': {
  75     '*dev':           'str',
  76     '*period-length': 'uint32',
  77     '*try-poll':      'bool' } }
  78
  79 ##
  80 # @AudiodevAlsaOptions:
  81 #
  82 # Options of the ALSA audio backend.
  83 #
  84 # @in: options of the capture stream
  85 #
  86 # @out: options of the playback stream
  87 #
  88 # @threshold: set the threshold (in microseconds) when playback starts
  89 #
  90 # Since: 4.0
  91 ##
  92 { 'struct': 'AudiodevAlsaOptions',
  93   'data': {
  94     '*in':        'AudiodevAlsaPerDirectionOptions',
  95     '*out':       'AudiodevAlsaPerDirectionOptions',
  96     '*threshold': 'uint32' } }
  97
  98 ##
  99 # @AudiodevCoreaudioPerDirectionOptions:
 100 #
 101 # Options of the Core Audio backend that are used for both playback and
 102 # recording.
 103 #
 104 # @buffer-count: number of buffers
 105 #
 106 # Since: 4.0
 107 ##
 108 { 'struct': 'AudiodevCoreaudioPerDirectionOptions',
 109   'base': 'AudiodevPerDirectionOptions',
 110   'data': {
 111     '*buffer-count': 'uint32' } }
 112
 113 ##
 114 # @AudiodevCoreaudioOptions:
 115 #
 116 # Options of the coreaudio audio backend.
 117 #
 118 # @in: options of the capture stream
 119 #
 120 # @out: options of the playback stream
 121 #
 122 # Since: 4.0
 123 ##
 124 { 'struct': 'AudiodevCoreaudioOptions',
 125   'data': {
 126     '*in':  'AudiodevCoreaudioPerDirectionOptions',
 127     '*out': 'AudiodevCoreaudioPerDirectionOptions' } }
 128
 129 ##
 130 # @AudiodevDsoundOptions:
 131 #
 132 # Options of the DirectSound audio backend.
 133 #
 134 # @in: options of the capture stream
 135 #
 136 # @out: options of the playback stream
 137 #
 138 # @latency: add extra latency to playback in microseconds
 139 #           (default 10000)
 140 #
 141 # Since: 4.0
 142 ##
 143 { 'struct': 'AudiodevDsoundOptions',
 144   'data': {
 145     '*in':      'AudiodevPerDirectionOptions',
 146     '*out':     'AudiodevPerDirectionOptions',
 147     '*latency': 'uint32' } }
 148
 149 ##
 150 # @AudiodevOssPerDirectionOptions:
 151 #
 152 # Options of the OSS backend that are used for both playback and
 153 # recording.
 154 #
 155 # @dev: file name of the OSS device (default '/dev/dsp')
 156 #
 157 # @buffer-count: number of buffers
 158 #
 159 # @try-poll: attempt to use poll mode, falling back to non-polling
 160 #            access on failure (default true)
 161 #
 162 # Since: 4.0
 163 ##
 164 { 'struct': 'AudiodevOssPerDirectionOptions',
 165   'base': 'AudiodevPerDirectionOptions',
 166   'data': {
 167     '*dev':          'str',
 168     '*buffer-count': 'uint32',
 169     '*try-poll':     'bool' } }
 170
 171 ##
 172 # @AudiodevOssOptions:
 173 #
 174 # Options of the OSS audio backend.
 175 #
 176 # @in: options of the capture stream
 177 #
 178 # @out: options of the playback stream
 179 #
 180 # @try-mmap: try using memory-mapped access, falling back to
 181 #            non-memory-mapped access on failure (default true)
 182 #
 183 # @exclusive: open device in exclusive mode (vmix won't work)
 184 #             (default false)
 185 #
 186 # @dsp-policy: set the timing policy of the device (between 0 and 10,
 187 #              where smaller number means smaller latency but higher
 188 #              CPU usage) or -1 to use fragment mode (option ignored
 189 #              on some platforms) (default 5)
 190 #
 191 # Since: 4.0
 192 ##
 193 { 'struct': 'AudiodevOssOptions',
 194   'data': {
 195     '*in':         'AudiodevOssPerDirectionOptions',
 196     '*out':        'AudiodevOssPerDirectionOptions',
 197     '*try-mmap':   'bool',
 198     '*exclusive':  'bool',
 199     '*dsp-policy': 'uint32' } }
 200
 201 ##
 202 # @AudiodevPaPerDirectionOptions:
 203 #
 204 # Options of the Pulseaudio backend that are used for both playback and
 205 # recording.
 206 #
 207 # @name: name of the sink/source to use
 208 #
 209 # @stream-name: name of the PulseAudio stream created by qemu.  Can be
 210 #               used to identify the stream in PulseAudio when you
 211 #               create multiple PulseAudio devices or run multiple qemu
 212 #               instances (default: audiodev's id, since 4.2)
 213 #
 214 # @latency: latency you want PulseAudio to achieve in microseconds
 215 #           (default 15000)
 216 #
 217 # Since: 4.0
 218 ##
 219 { 'struct': 'AudiodevPaPerDirectionOptions',
 220   'base': 'AudiodevPerDirectionOptions',
 221   'data': {
 222     '*name': 'str',
 223     '*stream-name': 'str',
 224     '*latency': 'uint32' } }
 225
 226 ##
 227 # @AudiodevPaOptions:
 228 #
 229 # Options of the PulseAudio audio backend.
 230 #
 231 # @in: options of the capture stream
 232 #
 233 # @out: options of the playback stream
 234 #
 235 # @server: PulseAudio server address (default: let PulseAudio choose)
 236 #
 237 # Since: 4.0
 238 ##
 239 { 'struct': 'AudiodevPaOptions',
 240   'data': {
 241     '*in':     'AudiodevPaPerDirectionOptions',
 242     '*out':    'AudiodevPaPerDirectionOptions',
 243     '*server': 'str' } }
 244
 245 ##
 246 # @AudiodevWavOptions:
 247 #
 248 # Options of the wav audio backend.
 249 #
 250 # @in: options of the capture stream
 251 #
 252 # @out: options of the playback stream
 253 #
 254 # @path: name of the wav file to record (default 'qemu.wav')
 255 #
 256 # Since: 4.0
 257 ##
 258 { 'struct': 'AudiodevWavOptions',
 259   'data': {
 260     '*in':   'AudiodevPerDirectionOptions',
 261     '*out':  'AudiodevPerDirectionOptions',
 262     '*path': 'str' } }
 263
 264
 265 ##
 266 # @AudioFormat:
 267 #
 268 # An enumeration of possible audio formats.
 269 #
 270 # Since: 4.0
 271 ##
 272 { 'enum': 'AudioFormat',
 273   'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32' ] }
 274
 275 ##
 276 # @AudiodevDriver:
 277 #
 278 # An enumeration of possible audio backend drivers.
 279 #
 280 # Since: 4.0
 281 ##
 282 { 'enum': 'AudiodevDriver',
 283   'data': [ 'none', 'alsa', 'coreaudio', 'dsound', 'oss', 'pa', 'sdl',
 284             'spice', 'wav' ] }
 285
 286 ##
 287 # @Audiodev:
 288 #
 289 # Options of an audio backend.
 290 #
 291 # @id: identifier of the backend
 292 #
 293 # @driver: the backend driver to use
 294 #
 295 # @timer-period: timer period (in microseconds, 0: use lowest possible)
 296 #
 297 # Since: 4.0
 298 ##
 299 { 'union': 'Audiodev',
 300   'base': {
 301     'id':            'str',
 302     'driver':        'AudiodevDriver',
 303     '*timer-period': 'uint32' },
 304   'discriminator': 'driver',
 305   'data': {
 306     'none':      'AudiodevGenericOptions',
 307     'alsa':      'AudiodevAlsaOptions',
 308     'coreaudio': 'AudiodevCoreaudioOptions',
 309     'dsound':    'AudiodevDsoundOptions',
 310     'oss':       'AudiodevOssOptions',
 311     'pa':        'AudiodevPaOptions',
 312     'sdl':       'AudiodevGenericOptions',
 313     'spice':     'AudiodevGenericOptions',
 314     'wav':       'AudiodevWavOptions' } }