1.\" $OpenBSD: audio.4,v 1.73 2016/09/01 10:08:23 ratchov Exp $ 2.\" $NetBSD: audio.4,v 1.20 1998/05/28 17:27:15 augustss Exp $ 3.\" 4.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by John T. Kohl. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: September 1 2016 $ 32.Dt AUDIO 4 33.Os 34.Sh NAME 35.Nm audio , 36.Nm mixer 37.Nd device-independent audio driver layer 38.Sh SYNOPSIS 39.Cd "audio* at ..." 40.Pp 41.In sys/types.h 42.In sys/ioctl.h 43.In sys/audioio.h 44.In string.h 45.Sh DESCRIPTION 46The 47.Nm audio 48driver provides support for various audio peripherals. 49It provides a uniform programming interface layer above different 50underlying audio hardware drivers. 51The audio layer provides full-duplex operation if the 52underlying hardware configuration supports it. 53.Pp 54There are four device files available for audio operation: 55.Pa /dev/audio , 56.Pa /dev/sound , 57.Pa /dev/audioctl , 58and 59.Pa /dev/mixer . 60.Pa /dev/audio 61and 62.Pa /dev/sound 63are used for recording or playback of digital samples. 64.Pa /dev/mixer 65is used to manipulate volume, recording source, or other audio mixer 66functions. 67.Pa /dev/audioctl 68accepts the same 69.Xr ioctl 2 70operations as 71.Pa /dev/sound , 72but no other operations. 73In contrast to 74.Pa /dev/sound , 75which has the exclusive open property, 76.Pa /dev/audioctl 77can be opened at any time and can be used to manipulate the 78.Nm audio 79device while it is in use. 80.Sh SAMPLING DEVICES 81When 82.Pa /dev/audio 83or 84.Pa /dev/sound 85is opened, it attempts to maintain the previous audio sample format and 86record/playback mode. 87In addition, if it is opened read-only 88(write-only) the device is set to half-duplex record (play) mode with 89recording (playing) unpaused. 90In all respects 91.Pa /dev/audio 92and 93.Pa /dev/sound 94are identical. 95.Pp 96Only one process may hold open a sampling device at a given time 97(although file descriptors may be shared between processes once the 98first open completes). 99.Pp 100On a half-duplex device, either reads or writes are allowed, 101but not both. 102On a full-duplex device, reads and writes may operate 103concurrently without interference. 104.Pp 105If a writing process does not call 106.Xr write 2 107frequently enough to provide samples at the pace the hardware 108consumes them silence is inserted. 109If a reading process does not call 110.Xr read 2 111frequently enough, it will simply miss samples. 112.Pp 113The 114.Nm audio 115device is accessed with 116.Xr read 2 117or 118.Xr write 2 . 119.Pp 120The 121.Nm audio 122device, like most devices, can be used in 123.Xr poll 2 , 124.Pp 125The following 126.Xr ioctl 2 127commands are supported on the sample devices: 128.Pp 129.Bl -tag -width Ds -compact 130.It Dv AUDIO_GETDEV Fa "audio_device_t *" 131This command fetches the current hardware device information into the 132.Vt audio_device_t * 133argument. 134.Bd -literal 135typedef struct audio_device { 136 char name[MAX_AUDIO_DEV_LEN]; 137 char version[MAX_AUDIO_DEV_LEN]; 138 char config[MAX_AUDIO_DEV_LEN]; 139} audio_device_t; 140.Ed 141.Pp 142.It Dv AUDIO_SETPAR Fa "struct audio_swpar *" 143.It Dv AUDIO_GETPAR Fa "struct audio_swpar *" 144Set or get audio parameters as encoded in the 145.Vt audio_swpar 146structure. 147.Bd -literal 148struct audio_swpar { 149 unsigned int sig; /* if 1, encoding is signed */ 150 unsigned int le; /* if 1, encoding is little-endian */ 151 unsigned int bits; /* bits per sample */ 152 unsigned int bps; /* bytes per sample */ 153 unsigned int msb; /* if 1, bits are msb-aligned */ 154 unsigned int rate; /* common play & rec sample rate */ 155 unsigned int pchan; /* play channels */ 156 unsigned int rchan; /* rec channels */ 157 unsigned int nblks; /* number of blocks in play buffer */ 158 unsigned int round; /* common frames per block */ 159}; 160.Ed 161.Pp 162When setting the device parameters with 163.Dv AUDIO_SETPAR , 164the 165.Vt audio_swpar 166structure should first be initialized with 167.Bd -literal 168struct audio_swpar ap; 169 170AUDIO_INITPAR(&ap); 171.Ed 172.Pp 173and then only the values to be changed should be set. 174This ensures that the software will work with future versions 175of the driver. 176The driver will attempt to set the given parameters; if the 177device doesn't support them, it will choose other parameters. 178Then the software must call 179.Dv AUDIO_GETPAR 180to obtain the parameters in use. 181.Pp 182The parameters are as follows: 183.Bl -tag -width "round" 184.It Va bits 185Number of bits per sample: must be between 1 and 32. 186.It Va bps 187Bytes per sample; if specified, it must be large enough to hold all bits. 188By default it's set to the smallest power of two large enough to hold 189.Va bits . 190.It Va sig 191If set (i.e. non-zero) then the samples are signed, 192otherwise they are unsigned. 193.It Va le 194If set, then the byte order is little endian; 195if not it is big endian; 196it's meaningful only if 197.Va bps 198> 1. 199.It Va msb 200If set, then the 201.Va bits 202are aligned in the packet to the most significant bit 203(i.e. lower bits are padded), 204otherwise to the least significant bit 205(i.e. higher bits are padded). 206It's meaningful only if 207.Va bits 208< 209.Va bps 210* 8. 211.It Va rchan 212The number of recorded channels; meaningful only if the 213device is opened for reading. 214.It Va pchan 215The number of channels playing; meaningful only if 216the device is opened for writing. 217.It Va rate 218The sampling frequency in Hz. 219.It Va nblks 220The number of blocks in the play buffer. 221.It Va round 222The audio block size. 223.El 224.Pp 225.It Dv AUDIO_START 226Start playback and/or recording immediately. 227If the device is open for writing (playback), then 228the play buffer must be filled with the 229.Xr write 2 230syscall. 231The buffer size is obtained by multiplying 232the 233.Va nblks , 234.Va round , 235and 236.Va bps 237parameters obtained with 238.Dv AUDIO_GETPAR . 239.Pp 240.It Dv AUDIO_STOP 241Stop playback and recording immediately. 242.Pp 243.It Dv AUDIO_GETPOS Fa "struct audio_pos *" 244Fetch an atomic snapshot of device timing information in the 245.Vt audio_pos 246structure. 247.Bd -literal 248struct audio_pos { 249 unsigned int play_pos; /* total bytes played */ 250 unsigned int play_xrun; /* bytes of silence inserted */ 251 unsigned int rec_pos; /* total bytes recorded */ 252 unsigned int rec_xrun; /* bytes dropped */ 253}; 254.Ed 255.Pp 256The properties have the following meaning: 257.Bl -tag -width "play_xrun" 258.It Va play_pos 259Total number of bytes played by the device since playback started 260(a.k.a the device wall clock). 261.It Va play_xrun 262The number of bytes corresponding to silence played because 263.Xr write 2 264wasn't called fast enough. 265.It Va rec_pos 266Total number of bytes recorded by the device since recording started 267(a.k.a the device wall clock). 268.It Va rec_xrun 269The number of bytes dropped because 270.Xr read 2 271wasn't called fast enough. 272.El 273.Pp 274.It Dv AUDIO_GETSTATUS Fa "struct audio_status *" 275Fetch the current device status from the audio driver in the 276.Vt audio_status 277structure. 278This 279.Xr ioctl 2 280is intended for use with diagnostic tools 281and is of no use to audio programs. 282.Bd -literal 283struct audio_status { 284#define AUMODE_PLAY 0x01 285#define AUMODE_RECORD 0x02 286 int mode; /* current mode */ 287 int pause; /* not started yet */ 288 int active; /* playing/recording in progress */ 289}; 290.Ed 291.Pp 292The properties have the following meaning: 293.Bl -tag -width "active" 294.It Va mode 295The current mode determined by 296.Xr open 2 297flags. 298.It Va pause 299If set, indicates that 300.Dv AUDIO_STOP 301was called, and the device is not attempting to start. 302.It Va active 303If set, indicates that the device is playing and/or recording. 304.El 305.El 306.Sh MIXER DEVICE 307The 308.Nm mixer 309device, 310.Pa /dev/mixer , 311may be manipulated with 312.Xr ioctl 2 313but does not support 314.Xr read 2 315or 316.Xr write 2 . 317It supports the following 318.Xr ioctl 2 319commands: 320.Pp 321.Bl -tag -width Ds -compact 322.It Dv AUDIO_GETDEV Fa "audio_device_t *" 323This command is the same as described above for the sampling devices. 324.Pp 325.It Dv AUDIO_MIXER_READ Fa "mixer_ctrl_t *" 326.It Dv AUDIO_MIXER_WRITE Fa "mixer_ctrl_t *" 327These commands read the current mixer state or set new mixer state for 328the specified device 329.Va dev . 330.Va type 331identifies which type of value is supplied in the 332.Vt mixer_ctrl_t * 333argument. 334.Bd -literal 335#define AUDIO_MIXER_CLASS 0 336#define AUDIO_MIXER_ENUM 1 337#define AUDIO_MIXER_SET 2 338#define AUDIO_MIXER_VALUE 3 339typedef struct mixer_ctrl { 340 int dev; /* input: nth device */ 341 int type; 342 union { 343 int ord; /* enum */ 344 int mask; /* set */ 345 mixer_level_t value; /* value */ 346 } un; 347} mixer_ctrl_t; 348 349#define AUDIO_MIN_GAIN 0 350#define AUDIO_MAX_GAIN 255 351typedef struct mixer_level { 352 int num_channels; 353 u_char level[8]; /* [num_channels] */ 354} mixer_level_t; 355#define AUDIO_MIXER_LEVEL_MONO 0 356#define AUDIO_MIXER_LEVEL_LEFT 0 357#define AUDIO_MIXER_LEVEL_RIGHT 1 358.Ed 359.Pp 360For a mixer value, the 361.Va value 362field specifies both the number of channels and the values for each 363channel. 364If the channel count does not match the current channel count, the 365attempt to change the setting may fail (depending on the hardware 366device driver implementation). 367For an enumeration value, the 368.Va ord 369field should be set to one of the possible values as returned by a prior 370.Dv AUDIO_MIXER_DEVINFO 371command. 372The type 373.Dv AUDIO_MIXER_CLASS 374is only used for classifying particular 375.Nm mixer 376device types and is not used for 377.Dv AUDIO_MIXER_READ 378or 379.Dv AUDIO_MIXER_WRITE . 380.Pp 381.It Dv AUDIO_MIXER_DEVINFO Fa "mixer_devinfo_t *" 382This command is used iteratively to fetch audio 383.Nm mixer 384device information into the input/output 385.Vt mixer_devinfo_t * 386argument. 387To query all the supported devices, start with an index field of 3880 and continue with successive devices (1, 2, ...) until the 389command returns an error. 390.Bd -literal 391typedef struct mixer_devinfo { 392 int index; /* input: nth mixer device */ 393 audio_mixer_name_t label; 394 int type; 395 int mixer_class; 396 int next, prev; 397#define AUDIO_MIXER_LAST -1 398 union { 399 struct audio_mixer_enum { 400 int num_mem; 401 struct { 402 audio_mixer_name_t label; 403 int ord; 404 } member[32]; 405 } e; 406 struct audio_mixer_set { 407 int num_mem; 408 struct { 409 audio_mixer_name_t label; 410 int mask; 411 } member[32]; 412 } s; 413 struct audio_mixer_value { 414 audio_mixer_name_t units; 415 int num_channels; 416 int delta; 417 } v; 418 } un; 419} mixer_devinfo_t; 420.Ed 421.Pp 422The 423.Va label 424field identifies the name of this particular mixer control. 425The 426.Va index 427field may be used as the 428.Va dev 429field in 430.Dv AUDIO_MIXER_READ 431and 432.Dv AUDIO_MIXER_WRITE 433commands. 434The 435.Va type 436field identifies the type of this mixer control. 437Enumeration types are typically used for on/off style controls (e.g., a 438mute control) or for input/output device selection (e.g., select 439recording input source from CD, line in, or microphone). 440Set types are similar to enumeration types but any combination 441of the mask bits can be used. 442.Pp 443The 444.Va mixer_class 445field identifies what class of control this is. 446This value is set to the index value used to query the class itself. 447The 448.Pq arbitrary 449value set by the hardware driver may be determined by examining the 450.Va mixer_class 451field of the class itself, 452a mixer of type 453.Dv AUDIO_MIXER_CLASS . 454For example, a mixer level controlling the input gain on the 455.Dq line in 456circuit would have a 457.Va mixer_class 458that matches an input class device with the name 459.Dq inputs 460.Dv ( AudioCinputs ) 461and would have a 462.Va label 463of 464.Dq line 465.Dv ( AudioNline ) . 466Mixer controls which control audio circuitry for a particular audio 467source (e.g., line-in, CD in, DAC output) are collected under the input class, 468while those which control all audio sources (e.g., master volume, 469equalization controls) are under the output class. 470Hardware devices capable of recording typically also have a record class, 471for controls that only affect recording, 472and also a monitor class. 473.Pp 474The 475.Va next 476and 477.Va prev 478may be used by the hardware device driver to provide hints for the next 479and previous devices in a related set (for example, the line in level 480control would have the line in mute as its 481.Dq next 482value). 483If there is no relevant next or previous value, 484.Dv AUDIO_MIXER_LAST 485is specified. 486.Pp 487For 488.Dv AUDIO_MIXER_ENUM 489mixer control types, 490the enumeration values and their corresponding names are filled in. 491For example, a mute control would return appropriate values paired with 492.Dv AudioNon 493and 494.Dv AudioNoff . 495For the 496.Dv AUDIO_MIXER_VALUE 497and 498.Dv AUDIO_MIXER_SET 499mixer control types, the channel count is 500returned; the units name specifies what the level controls (typical 501values are 502.Dv AudioNvolume , 503.Dv AudioNtreble , 504and 505.Dv AudioNbass ) . 506.\" For AUDIO_MIXER_SET mixer control types, what is what? 507.El 508.Pp 509By convention, all the mixer devices can be distinguished from other 510mixer controls because they use a name from one of the 511.Dv AudioC* 512string values. 513.Sh FILES 514.Bl -tag -width /dev/audioctl -compact 515.It Pa /dev/audio 516.It Pa /dev/audioctl 517.It Pa /dev/sound 518.It Pa /dev/mixer 519.El 520.Sh SEE ALSO 521.Xr aucat 1 , 522.Xr audioctl 1 , 523.Xr cdio 1 , 524.Xr mixerctl 1 , 525.Xr ioctl 2 , 526.Xr sio_open 3 , 527.Xr ac97 4 , 528.Xr uaudio 4 , 529.Xr audio 9 530.\" .Sh BUGS 531