Merge tag 'edgar/xilinx-next-2022-09-21.for-upstream' of https://github.com/edgarigl...
[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 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 #
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': {
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 # @AudiodevCoreaudioPerDirectionOptions:
111 #
112 # Options of the Core Audio backend that are used for both playback and
113 # recording.
114 #
115 # @buffer-count: number of buffers
116 #
117 # Since: 4.0
118 ##
119 { 'struct': 'AudiodevCoreaudioPerDirectionOptions',
120   'base': 'AudiodevPerDirectionOptions',
121   'data': {
122     '*buffer-count': 'uint32' } }
123
124 ##
125 # @AudiodevCoreaudioOptions:
126 #
127 # Options of the coreaudio audio backend.
128 #
129 # @in: options of the capture stream
130 #
131 # @out: options of the playback stream
132 #
133 # Since: 4.0
134 ##
135 { 'struct': 'AudiodevCoreaudioOptions',
136   'data': {
137     '*in':  'AudiodevCoreaudioPerDirectionOptions',
138     '*out': 'AudiodevCoreaudioPerDirectionOptions' } }
139
140 ##
141 # @AudiodevDsoundOptions:
142 #
143 # Options of the DirectSound audio backend.
144 #
145 # @in: options of the capture stream
146 #
147 # @out: options of the playback stream
148 #
149 # @latency: add extra latency to playback in microseconds
150 #           (default 10000)
151 #
152 # Since: 4.0
153 ##
154 { 'struct': 'AudiodevDsoundOptions',
155   'data': {
156     '*in':      'AudiodevPerDirectionOptions',
157     '*out':     'AudiodevPerDirectionOptions',
158     '*latency': 'uint32' } }
159
160 ##
161 # @AudiodevJackPerDirectionOptions:
162 #
163 # Options of the JACK backend that are used for both playback and
164 # recording.
165 #
166 # @server-name: select from among several possible concurrent server instances
167 #               (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
168 #
169 # @client-name: the client name to use. The server will modify this name to
170 #               create a unique variant, if needed unless @exact-name is true (default: the
171 #               guest's name)
172 #
173 # @connect-ports: if set, a regular expression of JACK client port name(s) to
174 #                 monitor for and automatically connect to
175 #
176 # @start-server: start a jack server process if one is not already present
177 #                (default: false)
178 #
179 # @exact-name: use the exact name requested otherwise JACK automatically
180 #              generates a unique one, if needed (default: false)
181 #
182 # Since: 5.1
183 ##
184 { 'struct': 'AudiodevJackPerDirectionOptions',
185   'base': 'AudiodevPerDirectionOptions',
186   'data': {
187     '*server-name':   'str',
188     '*client-name':   'str',
189     '*connect-ports': 'str',
190     '*start-server':  'bool',
191     '*exact-name':    'bool' } }
192
193 ##
194 # @AudiodevJackOptions:
195 #
196 # Options of the JACK audio backend.
197 #
198 # @in: options of the capture stream
199 #
200 # @out: options of the playback stream
201 #
202 # Since: 5.1
203 ##
204 { 'struct': 'AudiodevJackOptions',
205   'data': {
206     '*in':  'AudiodevJackPerDirectionOptions',
207     '*out': 'AudiodevJackPerDirectionOptions' } }
208
209 ##
210 # @AudiodevOssPerDirectionOptions:
211 #
212 # Options of the OSS backend that are used for both playback and
213 # recording.
214 #
215 # @dev: file name of the OSS device (default '/dev/dsp')
216 #
217 # @buffer-count: number of buffers
218 #
219 # @try-poll: attempt to use poll mode, falling back to non-polling
220 #            access on failure (default true)
221 #
222 # Since: 4.0
223 ##
224 { 'struct': 'AudiodevOssPerDirectionOptions',
225   'base': 'AudiodevPerDirectionOptions',
226   'data': {
227     '*dev':          'str',
228     '*buffer-count': 'uint32',
229     '*try-poll':     'bool' } }
230
231 ##
232 # @AudiodevOssOptions:
233 #
234 # Options of the OSS audio backend.
235 #
236 # @in: options of the capture stream
237 #
238 # @out: options of the playback stream
239 #
240 # @try-mmap: try using memory-mapped access, falling back to
241 #            non-memory-mapped access on failure (default true)
242 #
243 # @exclusive: open device in exclusive mode (vmix won't work)
244 #             (default false)
245 #
246 # @dsp-policy: set the timing policy of the device (between 0 and 10,
247 #              where smaller number means smaller latency but higher
248 #              CPU usage) or -1 to use fragment mode (option ignored
249 #              on some platforms) (default 5)
250 #
251 # Since: 4.0
252 ##
253 { 'struct': 'AudiodevOssOptions',
254   'data': {
255     '*in':         'AudiodevOssPerDirectionOptions',
256     '*out':        'AudiodevOssPerDirectionOptions',
257     '*try-mmap':   'bool',
258     '*exclusive':  'bool',
259     '*dsp-policy': 'uint32' } }
260
261 ##
262 # @AudiodevPaPerDirectionOptions:
263 #
264 # Options of the Pulseaudio backend that are used for both playback and
265 # recording.
266 #
267 # @name: name of the sink/source to use
268 #
269 # @stream-name: name of the PulseAudio stream created by qemu.  Can be
270 #               used to identify the stream in PulseAudio when you
271 #               create multiple PulseAudio devices or run multiple qemu
272 #               instances (default: audiodev's id, since 4.2)
273 #
274 # @latency: latency you want PulseAudio to achieve in microseconds
275 #           (default 15000)
276 #
277 # Since: 4.0
278 ##
279 { 'struct': 'AudiodevPaPerDirectionOptions',
280   'base': 'AudiodevPerDirectionOptions',
281   'data': {
282     '*name': 'str',
283     '*stream-name': 'str',
284     '*latency': 'uint32' } }
285
286 ##
287 # @AudiodevPaOptions:
288 #
289 # Options of the PulseAudio audio backend.
290 #
291 # @in: options of the capture stream
292 #
293 # @out: options of the playback stream
294 #
295 # @server: PulseAudio server address (default: let PulseAudio choose)
296 #
297 # Since: 4.0
298 ##
299 { 'struct': 'AudiodevPaOptions',
300   'data': {
301     '*in':     'AudiodevPaPerDirectionOptions',
302     '*out':    'AudiodevPaPerDirectionOptions',
303     '*server': 'str' } }
304
305 ##
306 # @AudiodevSdlPerDirectionOptions:
307 #
308 # Options of the SDL audio backend that are used for both playback and
309 # recording.
310 #
311 # @buffer-count: number of buffers (default 4)
312 #
313 # Since: 6.0
314 ##
315 { 'struct': 'AudiodevSdlPerDirectionOptions',
316   'base': 'AudiodevPerDirectionOptions',
317   'data': {
318     '*buffer-count': 'uint32' } }
319
320 ##
321 # @AudiodevSdlOptions:
322 #
323 # Options of the SDL audio backend.
324 #
325 # @in: options of the recording stream
326 #
327 # @out: options of the playback stream
328 #
329 # Since: 6.0
330 ##
331 { 'struct': 'AudiodevSdlOptions',
332   'data': {
333     '*in':  'AudiodevSdlPerDirectionOptions',
334     '*out': 'AudiodevSdlPerDirectionOptions' } }
335
336 ##
337 # @AudiodevWavOptions:
338 #
339 # Options of the wav audio backend.
340 #
341 # @in: options of the capture stream
342 #
343 # @out: options of the playback stream
344 #
345 # @path: name of the wav file to record (default 'qemu.wav')
346 #
347 # Since: 4.0
348 ##
349 { 'struct': 'AudiodevWavOptions',
350   'data': {
351     '*in':   'AudiodevPerDirectionOptions',
352     '*out':  'AudiodevPerDirectionOptions',
353     '*path': 'str' } }
354
355 ##
356 # @AudioFormat:
357 #
358 # An enumeration of possible audio formats.
359 #
360 # @u8: unsigned 8 bit integer
361 #
362 # @s8: signed 8 bit integer
363 #
364 # @u16: unsigned 16 bit integer
365 #
366 # @s16: signed 16 bit integer
367 #
368 # @u32: unsigned 32 bit integer
369 #
370 # @s32: signed 32 bit integer
371 #
372 # @f32: single precision floating-point (since 5.0)
373 #
374 # Since: 4.0
375 ##
376 { 'enum': 'AudioFormat',
377   'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] }
378
379 ##
380 # @AudiodevDriver:
381 #
382 # An enumeration of possible audio backend drivers.
383 #
384 # @jack: JACK audio backend (since 5.1)
385 #
386 # Since: 4.0
387 ##
388 { 'enum': 'AudiodevDriver',
389   'data': [ 'none', 'alsa', 'coreaudio', 'dbus', 'dsound', 'jack', 'oss', 'pa',
390             'sdl', 'spice', 'wav' ] }
391
392 ##
393 # @Audiodev:
394 #
395 # Options of an audio backend.
396 #
397 # @id: identifier of the backend
398 #
399 # @driver: the backend driver to use
400 #
401 # @timer-period: timer period (in microseconds, 0: use lowest possible)
402 #
403 # Since: 4.0
404 ##
405 { 'union': 'Audiodev',
406   'base': {
407     'id':            'str',
408     'driver':        'AudiodevDriver',
409     '*timer-period': 'uint32' },
410   'discriminator': 'driver',
411   'data': {
412     'none':      'AudiodevGenericOptions',
413     'alsa':      'AudiodevAlsaOptions',
414     'coreaudio': 'AudiodevCoreaudioOptions',
415     'dbus':      'AudiodevGenericOptions',
416     'dsound':    'AudiodevDsoundOptions',
417     'jack':      'AudiodevJackOptions',
418     'oss':       'AudiodevOssOptions',
419     'pa':        'AudiodevPaOptions',
420     'sdl':       'AudiodevSdlOptions',
421     'spice':     'AudiodevGenericOptions',
422     'wav':       'AudiodevWavOptions' } }