blob: 3b843878d2353d89ed9d8a3f621322c72cb2fdf3 [file] [log] [blame]
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +01001# -*- 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#
Kővágó, Zoltán8efac072019-10-13 21:57:58 +020014# @mixing-engine: use QEMU's mixing engine to mix all streams inside QEMU and
15# convert audio formats when not supported by the backend. When
16# set to off, fixed-settings must be also off (default on,
17# since 4.2)
18#
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +010019# @fixed-settings: use fixed settings for host input/output. When off,
20# frequency, channels and format must not be
21# specified (default true)
22#
23# @frequency: frequency to use when using fixed settings
24# (default 44100)
25#
26# @channels: number of channels when using fixed settings (default 2)
27#
28# @voices: number of voices to use (default 1)
29#
30# @format: sample format to use when using fixed settings
31# (default s16)
32#
33# @buffer-length: the buffer length in microseconds
34#
35# Since: 4.0
36##
37{ 'struct': 'AudiodevPerDirectionOptions',
38 'data': {
Kővágó, Zoltán8efac072019-10-13 21:57:58 +020039 '*mixing-engine': 'bool',
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +010040 '*fixed-settings': 'bool',
41 '*frequency': 'uint32',
42 '*channels': 'uint32',
43 '*voices': 'uint32',
44 '*format': 'AudioFormat',
45 '*buffer-length': 'uint32' } }
46
47##
48# @AudiodevGenericOptions:
49#
50# Generic driver-specific options.
51#
52# @in: options of the capture stream
53#
54# @out: options of the playback stream
55#
56# Since: 4.0
57##
58{ 'struct': 'AudiodevGenericOptions',
59 'data': {
60 '*in': 'AudiodevPerDirectionOptions',
61 '*out': 'AudiodevPerDirectionOptions' } }
62
63##
64# @AudiodevAlsaPerDirectionOptions:
65#
66# Options of the ALSA backend that are used for both playback and
67# recording.
68#
69# @dev: the name of the ALSA device to use (default 'default')
70#
71# @period-length: the period length in microseconds
72#
73# @try-poll: attempt to use poll mode, falling back to non-polling
74# access on failure (default true)
75#
76# Since: 4.0
77##
78{ 'struct': 'AudiodevAlsaPerDirectionOptions',
79 'base': 'AudiodevPerDirectionOptions',
80 'data': {
81 '*dev': 'str',
82 '*period-length': 'uint32',
83 '*try-poll': 'bool' } }
84
85##
86# @AudiodevAlsaOptions:
87#
88# Options of the ALSA audio backend.
89#
90# @in: options of the capture stream
91#
92# @out: options of the playback stream
93#
94# @threshold: set the threshold (in microseconds) when playback starts
95#
96# Since: 4.0
97##
98{ 'struct': 'AudiodevAlsaOptions',
99 'data': {
100 '*in': 'AudiodevAlsaPerDirectionOptions',
101 '*out': 'AudiodevAlsaPerDirectionOptions',
102 '*threshold': 'uint32' } }
103
104##
105# @AudiodevCoreaudioPerDirectionOptions:
106#
107# Options of the Core Audio backend that are used for both playback and
108# recording.
109#
110# @buffer-count: number of buffers
111#
112# Since: 4.0
113##
114{ 'struct': 'AudiodevCoreaudioPerDirectionOptions',
115 'base': 'AudiodevPerDirectionOptions',
116 'data': {
117 '*buffer-count': 'uint32' } }
118
119##
120# @AudiodevCoreaudioOptions:
121#
122# Options of the coreaudio audio backend.
123#
124# @in: options of the capture stream
125#
126# @out: options of the playback stream
127#
128# Since: 4.0
129##
130{ 'struct': 'AudiodevCoreaudioOptions',
131 'data': {
132 '*in': 'AudiodevCoreaudioPerDirectionOptions',
133 '*out': 'AudiodevCoreaudioPerDirectionOptions' } }
134
135##
136# @AudiodevDsoundOptions:
137#
138# Options of the DirectSound audio backend.
139#
140# @in: options of the capture stream
141#
142# @out: options of the playback stream
143#
144# @latency: add extra latency to playback in microseconds
145# (default 10000)
146#
147# Since: 4.0
148##
149{ 'struct': 'AudiodevDsoundOptions',
150 'data': {
151 '*in': 'AudiodevPerDirectionOptions',
152 '*out': 'AudiodevPerDirectionOptions',
153 '*latency': 'uint32' } }
154
155##
Geoffrey McRae2e445702020-04-29 15:53:58 +1000156# @AudiodevJackPerDirectionOptions:
157#
158# Options of the JACK backend that are used for both playback and
159# recording.
160#
161# @server-name: select from among several possible concurrent server instances
Peter Maydellb2f1c132020-08-10 20:50:01 +0100162# (default: environment variable $JACK_DEFAULT_SERVER if set, else "default")
Geoffrey McRae2e445702020-04-29 15:53:58 +1000163#
164# @client-name: the client name to use. The server will modify this name to
Peter Maydellb2f1c132020-08-10 20:50:01 +0100165# create a unique variant, if needed unless @exact-name is true (default: the
166# guest's name)
Geoffrey McRae2e445702020-04-29 15:53:58 +1000167#
168# @connect-ports: if set, a regular expression of JACK client port name(s) to
Peter Maydellb2f1c132020-08-10 20:50:01 +0100169# monitor for and automatically connect to
Geoffrey McRae2e445702020-04-29 15:53:58 +1000170#
171# @start-server: start a jack server process if one is not already present
Peter Maydellb2f1c132020-08-10 20:50:01 +0100172# (default: false)
Geoffrey McRae2e445702020-04-29 15:53:58 +1000173#
174# @exact-name: use the exact name requested otherwise JACK automatically
Peter Maydellb2f1c132020-08-10 20:50:01 +0100175# generates a unique one, if needed (default: false)
Geoffrey McRae2e445702020-04-29 15:53:58 +1000176#
177# Since: 5.1
178##
179{ 'struct': 'AudiodevJackPerDirectionOptions',
180 'base': 'AudiodevPerDirectionOptions',
181 'data': {
182 '*server-name': 'str',
183 '*client-name': 'str',
184 '*connect-ports': 'str',
185 '*start-server': 'bool',
186 '*exact-name': 'bool' } }
187
188##
189# @AudiodevJackOptions:
190#
191# Options of the JACK audio backend.
192#
193# @in: options of the capture stream
194#
195# @out: options of the playback stream
196#
197# Since: 5.1
198##
199{ 'struct': 'AudiodevJackOptions',
200 'data': {
201 '*in': 'AudiodevJackPerDirectionOptions',
202 '*out': 'AudiodevJackPerDirectionOptions' } }
203
204##
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100205# @AudiodevOssPerDirectionOptions:
206#
207# Options of the OSS backend that are used for both playback and
208# recording.
209#
210# @dev: file name of the OSS device (default '/dev/dsp')
211#
212# @buffer-count: number of buffers
213#
214# @try-poll: attempt to use poll mode, falling back to non-polling
215# access on failure (default true)
216#
217# Since: 4.0
218##
219{ 'struct': 'AudiodevOssPerDirectionOptions',
220 'base': 'AudiodevPerDirectionOptions',
221 'data': {
222 '*dev': 'str',
223 '*buffer-count': 'uint32',
224 '*try-poll': 'bool' } }
225
226##
227# @AudiodevOssOptions:
228#
229# Options of the OSS audio backend.
230#
231# @in: options of the capture stream
232#
233# @out: options of the playback stream
234#
235# @try-mmap: try using memory-mapped access, falling back to
236# non-memory-mapped access on failure (default true)
237#
238# @exclusive: open device in exclusive mode (vmix won't work)
239# (default false)
240#
241# @dsp-policy: set the timing policy of the device (between 0 and 10,
242# where smaller number means smaller latency but higher
243# CPU usage) or -1 to use fragment mode (option ignored
244# on some platforms) (default 5)
245#
246# Since: 4.0
247##
248{ 'struct': 'AudiodevOssOptions',
249 'data': {
250 '*in': 'AudiodevOssPerDirectionOptions',
251 '*out': 'AudiodevOssPerDirectionOptions',
252 '*try-mmap': 'bool',
253 '*exclusive': 'bool',
254 '*dsp-policy': 'uint32' } }
255
256##
257# @AudiodevPaPerDirectionOptions:
258#
259# Options of the Pulseaudio backend that are used for both playback and
260# recording.
261#
262# @name: name of the sink/source to use
263#
Kővágó, Zoltánf47dffe82019-09-11 01:26:20 +0200264# @stream-name: name of the PulseAudio stream created by qemu. Can be
265# used to identify the stream in PulseAudio when you
266# create multiple PulseAudio devices or run multiple qemu
267# instances (default: audiodev's id, since 4.2)
268#
Martin Schrodtf6142772019-03-15 09:46:52 +0100269# @latency: latency you want PulseAudio to achieve in microseconds
270# (default 15000)
271#
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100272# Since: 4.0
273##
274{ 'struct': 'AudiodevPaPerDirectionOptions',
275 'base': 'AudiodevPerDirectionOptions',
276 'data': {
Martin Schrodtf6142772019-03-15 09:46:52 +0100277 '*name': 'str',
Kővágó, Zoltánf47dffe82019-09-11 01:26:20 +0200278 '*stream-name': 'str',
Martin Schrodtf6142772019-03-15 09:46:52 +0100279 '*latency': 'uint32' } }
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100280
281##
282# @AudiodevPaOptions:
283#
284# Options of the PulseAudio audio backend.
285#
286# @in: options of the capture stream
287#
288# @out: options of the playback stream
289#
290# @server: PulseAudio server address (default: let PulseAudio choose)
291#
292# Since: 4.0
293##
294{ 'struct': 'AudiodevPaOptions',
295 'data': {
296 '*in': 'AudiodevPaPerDirectionOptions',
297 '*out': 'AudiodevPaPerDirectionOptions',
298 '*server': 'str' } }
299
300##
301# @AudiodevWavOptions:
302#
303# Options of the wav audio backend.
304#
305# @in: options of the capture stream
306#
307# @out: options of the playback stream
308#
309# @path: name of the wav file to record (default 'qemu.wav')
310#
311# Since: 4.0
312##
313{ 'struct': 'AudiodevWavOptions',
314 'data': {
315 '*in': 'AudiodevPerDirectionOptions',
316 '*out': 'AudiodevPerDirectionOptions',
317 '*path': 'str' } }
318
319
320##
321# @AudioFormat:
322#
323# An enumeration of possible audio formats.
324#
Volker Rümelin019b5ba2020-03-08 20:33:16 +0100325# @u8: unsigned 8 bit integer
326#
327# @s8: signed 8 bit integer
328#
329# @u16: unsigned 16 bit integer
330#
331# @s16: signed 16 bit integer
332#
333# @u32: unsigned 32 bit integer
334#
335# @s32: signed 32 bit integer
336#
337# @f32: single precision floating-point (since 5.0)
338#
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100339# Since: 4.0
340##
341{ 'enum': 'AudioFormat',
Kővágó, Zoltáned2a4a72020-02-02 20:38:07 +0100342 'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] }
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100343
344##
345# @AudiodevDriver:
346#
347# An enumeration of possible audio backend drivers.
348#
Geoffrey McRae2e445702020-04-29 15:53:58 +1000349# @jack: JACK audio backend (since 5.1)
350#
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100351# Since: 4.0
352##
353{ 'enum': 'AudiodevDriver',
Geoffrey McRae2e445702020-04-29 15:53:58 +1000354 'data': [ 'none', 'alsa', 'coreaudio', 'dsound', 'jack', 'oss', 'pa',
355 'sdl', 'spice', 'wav' ] }
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100356
357##
358# @Audiodev:
359#
360# Options of an audio backend.
361#
362# @id: identifier of the backend
363#
364# @driver: the backend driver to use
365#
366# @timer-period: timer period (in microseconds, 0: use lowest possible)
367#
368# Since: 4.0
369##
370{ 'union': 'Audiodev',
371 'base': {
372 'id': 'str',
373 'driver': 'AudiodevDriver',
374 '*timer-period': 'uint32' },
375 'discriminator': 'driver',
376 'data': {
377 'none': 'AudiodevGenericOptions',
378 'alsa': 'AudiodevAlsaOptions',
379 'coreaudio': 'AudiodevCoreaudioOptions',
380 'dsound': 'AudiodevDsoundOptions',
Geoffrey McRae2e445702020-04-29 15:53:58 +1000381 'jack': 'AudiodevJackOptions',
Kővágó, Zoltán8c3a7d02019-03-08 23:34:12 +0100382 'oss': 'AudiodevOssOptions',
383 'pa': 'AudiodevPaOptions',
384 'sdl': 'AudiodevGenericOptions',
385 'spice': 'AudiodevGenericOptions',
386 'wav': 'AudiodevWavOptions' } }