]> git.proxmox.com Git - mirror_qemu.git/blob - qapi/audio.json
qapi: Generalize command policy checking
[mirror_qemu.git] / 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 # = Audio
10 ##
11
12 ##
13 # @AudiodevPerDirectionOptions:
14 #
15 # General audio backend options that are used for both playback and
16 # recording.
17 #
18 # @mixing-engine: use QEMU's mixing engine to mix all streams inside QEMU and
19 # convert audio formats when not supported by the backend. When
20 # set to off, fixed-settings must be also off (default on,
21 # since 4.2)
22 #
23 # @fixed-settings: use fixed settings for host input/output. When off,
24 # frequency, channels and format must not be
25 # specified (default true)
26 #
27 # @frequency: frequency to use when using fixed settings
28 # (default 44100)
29 #
30 # @channels: number of channels when using fixed settings (default 2)
31 #
32 # @voices: number of voices to use (default 1)
33 #
34 # @format: sample format to use when using fixed settings
35 # (default s16)
36 #
37 # @buffer-length: the buffer length in microseconds
38 #
39 # Since: 4.0
40 ##
41 { 'struct': 'AudiodevPerDirectionOptions',
42 'data': {
43 '*mixing-engine': 'bool',
44 '*fixed-settings': 'bool',
45 '*frequency': 'uint32',
46 '*channels': 'uint32',
47 '*voices': 'uint32',
48 '*format': 'AudioFormat',
49 '*buffer-length': 'uint32' } }
50
51 ##
52 # @AudiodevGenericOptions:
53 #
54 # Generic driver-specific options.
55 #
56 # @in: options of the capture stream
57 #
58 # @out: options of the playback stream
59 #
60 # Since: 4.0
61 ##
62 { 'struct': 'AudiodevGenericOptions',
63 'data': {
64 '*in': 'AudiodevPerDirectionOptions',
65 '*out': 'AudiodevPerDirectionOptions' } }
66
67 ##
68 # @AudiodevAlsaPerDirectionOptions:
69 #
70 # Options of the ALSA backend that are used for both playback and
71 # recording.
72 #
73 # @dev: the name of the ALSA device to use (default 'default')
74 #
75 # @period-length: the period length in microseconds
76 #
77 # @try-poll: attempt to use poll mode, falling back to non-polling
78 # access on failure (default true)
79 #
80 # Since: 4.0
81 ##
82 { 'struct': 'AudiodevAlsaPerDirectionOptions',
83 'base': 'AudiodevPerDirectionOptions',
84 'data': {
85 '*dev': 'str',
86 '*period-length': 'uint32',
87 '*try-poll': 'bool' } }
88
89 ##
90 # @AudiodevAlsaOptions:
91 #
92 # Options of the ALSA audio backend.
93 #
94 # @in: options of the capture stream
95 #
96 # @out: options of the playback stream
97 #
98 # @threshold: set the threshold (in microseconds) when playback starts
99 #
100 # Since: 4.0
101 ##
102 { 'struct': 'AudiodevAlsaOptions',
103 'data': {
104 '*in': 'AudiodevAlsaPerDirectionOptions',
105 '*out': 'AudiodevAlsaPerDirectionOptions',
106 '*threshold': 'uint32' } }
107
108 ##
109 # @AudiodevCoreaudioPerDirectionOptions:
110 #
111 # Options of the Core Audio backend that are used for both playback and
112 # recording.
113 #
114 # @buffer-count: number of buffers
115 #
116 # Since: 4.0
117 ##
118 { 'struct': 'AudiodevCoreaudioPerDirectionOptions',
119 'base': 'AudiodevPerDirectionOptions',
120 'data': {
121 '*buffer-count': 'uint32' } }
122
123 ##
124 # @AudiodevCoreaudioOptions:
125 #
126 # Options of the coreaudio audio backend.
127 #
128 # @in: options of the capture stream
129 #
130 # @out: options of the playback stream
131 #
132 # Since: 4.0
133 ##
134 { 'struct': 'AudiodevCoreaudioOptions',
135 'data': {
136 '*in': 'AudiodevCoreaudioPerDirectionOptions',
137 '*out': 'AudiodevCoreaudioPerDirectionOptions' } }
138
139 ##
140 # @AudiodevDsoundOptions:
141 #
142 # Options of the DirectSound audio backend.
143 #
144 # @in: options of the capture stream
145 #
146 # @out: options of the playback stream
147 #
148 # @latency: add extra latency to playback in microseconds
149 # (default 10000)
150 #
151 # Since: 4.0
152 ##
153 { 'struct': 'AudiodevDsoundOptions',
154 'data': {
155 '*in': 'AudiodevPerDirectionOptions',
156 '*out': 'AudiodevPerDirectionOptions',
157 '*latency': 'uint32' } }
158
159 ##
160 # @AudiodevJackPerDirectionOptions:
161 #
162 # Options of the JACK backend that are used for both playback and
163 # recording.
164 #
165 # @server-name: select from among several possible concurrent server instances
166 # (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
167 #
168 # @client-name: the client name to use. The server will modify this name to
169 # create a unique variant, if needed unless @exact-name is true (default: the
170 # guest's name)
171 #
172 # @connect-ports: if set, a regular expression of JACK client port name(s) to
173 # monitor for and automatically connect to
174 #
175 # @start-server: start a jack server process if one is not already present
176 # (default: false)
177 #
178 # @exact-name: use the exact name requested otherwise JACK automatically
179 # generates a unique one, if needed (default: false)
180 #
181 # Since: 5.1
182 ##
183 { 'struct': 'AudiodevJackPerDirectionOptions',
184 'base': 'AudiodevPerDirectionOptions',
185 'data': {
186 '*server-name': 'str',
187 '*client-name': 'str',
188 '*connect-ports': 'str',
189 '*start-server': 'bool',
190 '*exact-name': 'bool' } }
191
192 ##
193 # @AudiodevJackOptions:
194 #
195 # Options of the JACK audio backend.
196 #
197 # @in: options of the capture stream
198 #
199 # @out: options of the playback stream
200 #
201 # Since: 5.1
202 ##
203 { 'struct': 'AudiodevJackOptions',
204 'data': {
205 '*in': 'AudiodevJackPerDirectionOptions',
206 '*out': 'AudiodevJackPerDirectionOptions' } }
207
208 ##
209 # @AudiodevOssPerDirectionOptions:
210 #
211 # Options of the OSS backend that are used for both playback and
212 # recording.
213 #
214 # @dev: file name of the OSS device (default '/dev/dsp')
215 #
216 # @buffer-count: number of buffers
217 #
218 # @try-poll: attempt to use poll mode, falling back to non-polling
219 # access on failure (default true)
220 #
221 # Since: 4.0
222 ##
223 { 'struct': 'AudiodevOssPerDirectionOptions',
224 'base': 'AudiodevPerDirectionOptions',
225 'data': {
226 '*dev': 'str',
227 '*buffer-count': 'uint32',
228 '*try-poll': 'bool' } }
229
230 ##
231 # @AudiodevOssOptions:
232 #
233 # Options of the OSS audio backend.
234 #
235 # @in: options of the capture stream
236 #
237 # @out: options of the playback stream
238 #
239 # @try-mmap: try using memory-mapped access, falling back to
240 # non-memory-mapped access on failure (default true)
241 #
242 # @exclusive: open device in exclusive mode (vmix won't work)
243 # (default false)
244 #
245 # @dsp-policy: set the timing policy of the device (between 0 and 10,
246 # where smaller number means smaller latency but higher
247 # CPU usage) or -1 to use fragment mode (option ignored
248 # on some platforms) (default 5)
249 #
250 # Since: 4.0
251 ##
252 { 'struct': 'AudiodevOssOptions',
253 'data': {
254 '*in': 'AudiodevOssPerDirectionOptions',
255 '*out': 'AudiodevOssPerDirectionOptions',
256 '*try-mmap': 'bool',
257 '*exclusive': 'bool',
258 '*dsp-policy': 'uint32' } }
259
260 ##
261 # @AudiodevPaPerDirectionOptions:
262 #
263 # Options of the Pulseaudio backend that are used for both playback and
264 # recording.
265 #
266 # @name: name of the sink/source to use
267 #
268 # @stream-name: name of the PulseAudio stream created by qemu. Can be
269 # used to identify the stream in PulseAudio when you
270 # create multiple PulseAudio devices or run multiple qemu
271 # instances (default: audiodev's id, since 4.2)
272 #
273 # @latency: latency you want PulseAudio to achieve in microseconds
274 # (default 15000)
275 #
276 # Since: 4.0
277 ##
278 { 'struct': 'AudiodevPaPerDirectionOptions',
279 'base': 'AudiodevPerDirectionOptions',
280 'data': {
281 '*name': 'str',
282 '*stream-name': 'str',
283 '*latency': 'uint32' } }
284
285 ##
286 # @AudiodevPaOptions:
287 #
288 # Options of the PulseAudio audio backend.
289 #
290 # @in: options of the capture stream
291 #
292 # @out: options of the playback stream
293 #
294 # @server: PulseAudio server address (default: let PulseAudio choose)
295 #
296 # Since: 4.0
297 ##
298 { 'struct': 'AudiodevPaOptions',
299 'data': {
300 '*in': 'AudiodevPaPerDirectionOptions',
301 '*out': 'AudiodevPaPerDirectionOptions',
302 '*server': 'str' } }
303
304 ##
305 # @AudiodevSdlPerDirectionOptions:
306 #
307 # Options of the SDL audio backend that are used for both playback and
308 # recording.
309 #
310 # @buffer-count: number of buffers (default 4)
311 #
312 # Since: 6.0
313 ##
314 { 'struct': 'AudiodevSdlPerDirectionOptions',
315 'base': 'AudiodevPerDirectionOptions',
316 'data': {
317 '*buffer-count': 'uint32' } }
318
319 ##
320 # @AudiodevSdlOptions:
321 #
322 # Options of the SDL audio backend.
323 #
324 # @in: options of the recording stream
325 #
326 # @out: options of the playback stream
327 #
328 # Since: 6.0
329 ##
330 { 'struct': 'AudiodevSdlOptions',
331 'data': {
332 '*in': 'AudiodevSdlPerDirectionOptions',
333 '*out': 'AudiodevSdlPerDirectionOptions' } }
334
335 ##
336 # @AudiodevWavOptions:
337 #
338 # Options of the wav audio backend.
339 #
340 # @in: options of the capture stream
341 #
342 # @out: options of the playback stream
343 #
344 # @path: name of the wav file to record (default 'qemu.wav')
345 #
346 # Since: 4.0
347 ##
348 { 'struct': 'AudiodevWavOptions',
349 'data': {
350 '*in': 'AudiodevPerDirectionOptions',
351 '*out': 'AudiodevPerDirectionOptions',
352 '*path': 'str' } }
353
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', '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 'dsound': 'AudiodevDsoundOptions',
416 'jack': 'AudiodevJackOptions',
417 'oss': 'AudiodevOssOptions',
418 'pa': 'AudiodevPaOptions',
419 'sdl': 'AudiodevSdlOptions',
420 'spice': 'AudiodevGenericOptions',
421 'wav': 'AudiodevWavOptions' } }