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