]> git.proxmox.com Git - mirror_qemu.git/blob - qapi/audio.json
qapi/block-core: turn BlockJobInfo into a union
[mirror_qemu.git] / qapi / audio.json
1 # -*- mode: python -*-
2 # vim: filetype=python
3 #
4 # Copyright (C) 2015-2019 Zoltán Kővágó <DirtY.iCE.hu@gmail.com>
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
20 # QEMU and convert audio formats when not supported by the
21 # backend. When set to off, fixed-settings must be also off
22 # (default on, since 4.2)
23 #
24 # @fixed-settings: use fixed settings for host input/output. When
25 # off, frequency, channels and format must not be specified
26 # (default true)
27 #
28 # @frequency: frequency to use when using fixed settings (default
29 # 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 (default
36 # 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 # @AudiodevSndioOptions:
111 #
112 # Options of the sndio audio backend.
113 #
114 # @in: options of the capture stream
115 #
116 # @out: options of the playback stream
117 #
118 # @dev: the name of the sndio device to use (default 'default')
119 #
120 # @latency: play buffer size (in microseconds)
121 #
122 # Since: 7.2
123 ##
124 { 'struct': 'AudiodevSndioOptions',
125 'data': {
126 '*in': 'AudiodevPerDirectionOptions',
127 '*out': 'AudiodevPerDirectionOptions',
128 '*dev': 'str',
129 '*latency': 'uint32'} }
130
131 ##
132 # @AudiodevCoreaudioPerDirectionOptions:
133 #
134 # Options of the Core Audio backend that are used for both playback
135 # and recording.
136 #
137 # @buffer-count: number of buffers
138 #
139 # Since: 4.0
140 ##
141 { 'struct': 'AudiodevCoreaudioPerDirectionOptions',
142 'base': 'AudiodevPerDirectionOptions',
143 'data': {
144 '*buffer-count': 'uint32' } }
145
146 ##
147 # @AudiodevCoreaudioOptions:
148 #
149 # Options of the coreaudio audio backend.
150 #
151 # @in: options of the capture stream
152 #
153 # @out: options of the playback stream
154 #
155 # Since: 4.0
156 ##
157 { 'struct': 'AudiodevCoreaudioOptions',
158 'data': {
159 '*in': 'AudiodevCoreaudioPerDirectionOptions',
160 '*out': 'AudiodevCoreaudioPerDirectionOptions' } }
161
162 ##
163 # @AudiodevDsoundOptions:
164 #
165 # Options of the DirectSound audio backend.
166 #
167 # @in: options of the capture stream
168 #
169 # @out: options of the playback stream
170 #
171 # @latency: add extra latency to playback in microseconds (default
172 # 10000)
173 #
174 # Since: 4.0
175 ##
176 { 'struct': 'AudiodevDsoundOptions',
177 'data': {
178 '*in': 'AudiodevPerDirectionOptions',
179 '*out': 'AudiodevPerDirectionOptions',
180 '*latency': 'uint32' } }
181
182 ##
183 # @AudiodevJackPerDirectionOptions:
184 #
185 # Options of the JACK backend that are used for both playback and
186 # recording.
187 #
188 # @server-name: select from among several possible concurrent server
189 # instances (default: environment variable $JACK_DEFAULT_SERVER if
190 # set, else "default")
191 #
192 # @client-name: the client name to use. The server will modify this
193 # name to create a unique variant, if needed unless @exact-name is
194 # true (default: the guest's name)
195 #
196 # @connect-ports: if set, a regular expression of JACK client port
197 # name(s) to monitor for and automatically connect to
198 #
199 # @start-server: start a jack server process if one is not already
200 # present (default: false)
201 #
202 # @exact-name: use the exact name requested otherwise JACK
203 # automatically generates a unique one, if needed (default: false)
204 #
205 # Since: 5.1
206 ##
207 { 'struct': 'AudiodevJackPerDirectionOptions',
208 'base': 'AudiodevPerDirectionOptions',
209 'data': {
210 '*server-name': 'str',
211 '*client-name': 'str',
212 '*connect-ports': 'str',
213 '*start-server': 'bool',
214 '*exact-name': 'bool' } }
215
216 ##
217 # @AudiodevJackOptions:
218 #
219 # Options of the JACK audio backend.
220 #
221 # @in: options of the capture stream
222 #
223 # @out: options of the playback stream
224 #
225 # Since: 5.1
226 ##
227 { 'struct': 'AudiodevJackOptions',
228 'data': {
229 '*in': 'AudiodevJackPerDirectionOptions',
230 '*out': 'AudiodevJackPerDirectionOptions' } }
231
232 ##
233 # @AudiodevOssPerDirectionOptions:
234 #
235 # Options of the OSS backend that are used for both playback and
236 # recording.
237 #
238 # @dev: file name of the OSS device (default '/dev/dsp')
239 #
240 # @buffer-count: number of buffers
241 #
242 # @try-poll: attempt to use poll mode, falling back to non-polling
243 # access on failure (default true)
244 #
245 # Since: 4.0
246 ##
247 { 'struct': 'AudiodevOssPerDirectionOptions',
248 'base': 'AudiodevPerDirectionOptions',
249 'data': {
250 '*dev': 'str',
251 '*buffer-count': 'uint32',
252 '*try-poll': 'bool' } }
253
254 ##
255 # @AudiodevOssOptions:
256 #
257 # Options of the OSS audio backend.
258 #
259 # @in: options of the capture stream
260 #
261 # @out: options of the playback stream
262 #
263 # @try-mmap: try using memory-mapped access, falling back to
264 # non-memory-mapped access on failure (default true)
265 #
266 # @exclusive: open device in exclusive mode (vmix won't work) (default
267 # false)
268 #
269 # @dsp-policy: set the timing policy of the device (between 0 and 10,
270 # where smaller number means smaller latency but higher CPU usage)
271 # or -1 to use fragment mode (option ignored on some platforms)
272 # (default 5)
273 #
274 # Since: 4.0
275 ##
276 { 'struct': 'AudiodevOssOptions',
277 'data': {
278 '*in': 'AudiodevOssPerDirectionOptions',
279 '*out': 'AudiodevOssPerDirectionOptions',
280 '*try-mmap': 'bool',
281 '*exclusive': 'bool',
282 '*dsp-policy': 'uint32' } }
283
284 ##
285 # @AudiodevPaPerDirectionOptions:
286 #
287 # Options of the Pulseaudio backend that are used for both playback
288 # and recording.
289 #
290 # @name: name of the sink/source to use
291 #
292 # @stream-name: name of the PulseAudio stream created by qemu. Can be
293 # used to identify the stream in PulseAudio when you create
294 # multiple PulseAudio devices or run multiple qemu instances
295 # (default: audiodev's id, since 4.2)
296 #
297 # @latency: latency you want PulseAudio to achieve in microseconds
298 # (default 15000)
299 #
300 # Since: 4.0
301 ##
302 { 'struct': 'AudiodevPaPerDirectionOptions',
303 'base': 'AudiodevPerDirectionOptions',
304 'data': {
305 '*name': 'str',
306 '*stream-name': 'str',
307 '*latency': 'uint32' } }
308
309 ##
310 # @AudiodevPaOptions:
311 #
312 # Options of the PulseAudio audio backend.
313 #
314 # @in: options of the capture stream
315 #
316 # @out: options of the playback stream
317 #
318 # @server: PulseAudio server address (default: let PulseAudio choose)
319 #
320 # Since: 4.0
321 ##
322 { 'struct': 'AudiodevPaOptions',
323 'data': {
324 '*in': 'AudiodevPaPerDirectionOptions',
325 '*out': 'AudiodevPaPerDirectionOptions',
326 '*server': 'str' } }
327
328 ##
329 # @AudiodevPipewirePerDirectionOptions:
330 #
331 # Options of the PipeWire backend that are used for both playback and
332 # recording.
333 #
334 # @name: name of the sink/source to use
335 #
336 # @stream-name: name of the PipeWire stream created by qemu. Can be
337 # used to identify the stream in PipeWire when you create multiple
338 # PipeWire devices or run multiple qemu instances (default:
339 # audiodev's id)
340 #
341 # @latency: latency you want PipeWire to achieve in microseconds
342 # (default 46000)
343 #
344 # Since: 8.1
345 ##
346 { 'struct': 'AudiodevPipewirePerDirectionOptions',
347 'base': 'AudiodevPerDirectionOptions',
348 'data': {
349 '*name': 'str',
350 '*stream-name': 'str',
351 '*latency': 'uint32' } }
352
353 ##
354 # @AudiodevPipewireOptions:
355 #
356 # Options of the PipeWire audio backend.
357 #
358 # @in: options of the capture stream
359 #
360 # @out: options of the playback stream
361 #
362 # Since: 8.1
363 ##
364 { 'struct': 'AudiodevPipewireOptions',
365 'data': {
366 '*in': 'AudiodevPipewirePerDirectionOptions',
367 '*out': 'AudiodevPipewirePerDirectionOptions' } }
368
369 ##
370 # @AudiodevSdlPerDirectionOptions:
371 #
372 # Options of the SDL audio backend that are used for both playback and
373 # recording.
374 #
375 # @buffer-count: number of buffers (default 4)
376 #
377 # Since: 6.0
378 ##
379 { 'struct': 'AudiodevSdlPerDirectionOptions',
380 'base': 'AudiodevPerDirectionOptions',
381 'data': {
382 '*buffer-count': 'uint32' } }
383
384 ##
385 # @AudiodevSdlOptions:
386 #
387 # Options of the SDL audio backend.
388 #
389 # @in: options of the recording stream
390 #
391 # @out: options of the playback stream
392 #
393 # Since: 6.0
394 ##
395 { 'struct': 'AudiodevSdlOptions',
396 'data': {
397 '*in': 'AudiodevSdlPerDirectionOptions',
398 '*out': 'AudiodevSdlPerDirectionOptions' } }
399
400 ##
401 # @AudiodevWavOptions:
402 #
403 # Options of the wav audio backend.
404 #
405 # @in: options of the capture stream
406 #
407 # @out: options of the playback stream
408 #
409 # @path: name of the wav file to record (default 'qemu.wav')
410 #
411 # Since: 4.0
412 ##
413 { 'struct': 'AudiodevWavOptions',
414 'data': {
415 '*in': 'AudiodevPerDirectionOptions',
416 '*out': 'AudiodevPerDirectionOptions',
417 '*path': 'str' } }
418
419 ##
420 # @AudioFormat:
421 #
422 # An enumeration of possible audio formats.
423 #
424 # @u8: unsigned 8 bit integer
425 #
426 # @s8: signed 8 bit integer
427 #
428 # @u16: unsigned 16 bit integer
429 #
430 # @s16: signed 16 bit integer
431 #
432 # @u32: unsigned 32 bit integer
433 #
434 # @s32: signed 32 bit integer
435 #
436 # @f32: single precision floating-point (since 5.0)
437 #
438 # Since: 4.0
439 ##
440 { 'enum': 'AudioFormat',
441 'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] }
442
443 ##
444 # @AudiodevDriver:
445 #
446 # An enumeration of possible audio backend drivers.
447 #
448 # @jack: JACK audio backend (since 5.1)
449 #
450 # Since: 4.0
451 ##
452 { 'enum': 'AudiodevDriver',
453 'data': [ 'none',
454 { 'name': 'alsa', 'if': 'CONFIG_AUDIO_ALSA' },
455 { 'name': 'coreaudio', 'if': 'CONFIG_AUDIO_COREAUDIO' },
456 { 'name': 'dbus', 'if': 'CONFIG_DBUS_DISPLAY' },
457 { 'name': 'dsound', 'if': 'CONFIG_AUDIO_DSOUND' },
458 { 'name': 'jack', 'if': 'CONFIG_AUDIO_JACK' },
459 { 'name': 'oss', 'if': 'CONFIG_AUDIO_OSS' },
460 { 'name': 'pa', 'if': 'CONFIG_AUDIO_PA' },
461 { 'name': 'pipewire', 'if': 'CONFIG_AUDIO_PIPEWIRE' },
462 { 'name': 'sdl', 'if': 'CONFIG_AUDIO_SDL' },
463 { 'name': 'sndio', 'if': 'CONFIG_AUDIO_SNDIO' },
464 { 'name': 'spice', 'if': 'CONFIG_SPICE' },
465 'wav' ] }
466
467 ##
468 # @Audiodev:
469 #
470 # Options of an audio backend.
471 #
472 # @id: identifier of the backend
473 #
474 # @driver: the backend driver to use
475 #
476 # @timer-period: timer period (in microseconds, 0: use lowest
477 # possible)
478 #
479 # Since: 4.0
480 ##
481 { 'union': 'Audiodev',
482 'base': {
483 'id': 'str',
484 'driver': 'AudiodevDriver',
485 '*timer-period': 'uint32' },
486 'discriminator': 'driver',
487 'data': {
488 'none': 'AudiodevGenericOptions',
489 'alsa': { 'type': 'AudiodevAlsaOptions',
490 'if': 'CONFIG_AUDIO_ALSA' },
491 'coreaudio': { 'type': 'AudiodevCoreaudioOptions',
492 'if': 'CONFIG_AUDIO_COREAUDIO' },
493 'dbus': { 'type': 'AudiodevGenericOptions',
494 'if': 'CONFIG_DBUS_DISPLAY' },
495 'dsound': { 'type': 'AudiodevDsoundOptions',
496 'if': 'CONFIG_AUDIO_DSOUND' },
497 'jack': { 'type': 'AudiodevJackOptions',
498 'if': 'CONFIG_AUDIO_JACK' },
499 'oss': { 'type': 'AudiodevOssOptions',
500 'if': 'CONFIG_AUDIO_OSS' },
501 'pa': { 'type': 'AudiodevPaOptions',
502 'if': 'CONFIG_AUDIO_PA' },
503 'pipewire': { 'type': 'AudiodevPipewireOptions',
504 'if': 'CONFIG_AUDIO_PIPEWIRE' },
505 'sdl': { 'type': 'AudiodevSdlOptions',
506 'if': 'CONFIG_AUDIO_SDL' },
507 'sndio': { 'type': 'AudiodevSndioOptions',
508 'if': 'CONFIG_AUDIO_SNDIO' },
509 'spice': { 'type': 'AudiodevGenericOptions',
510 'if': 'CONFIG_SPICE' },
511 'wav': 'AudiodevWavOptions' } }
512
513 ##
514 # @query-audiodevs:
515 #
516 # Returns information about audiodev configuration
517 #
518 # Returns: array of @Audiodev
519 #
520 # Since: 8.0
521 ##
522 { 'command': 'query-audiodevs',
523 'returns': ['Audiodev'] }