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