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