1.\" $OpenBSD: audio.4,v 1.60 2009/03/24 15:47:36 sobrado 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: March 24 2009 $ 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.Fd #include <sys/types.h> 42.Fd #include <sys/ioctl.h> 43.Fd #include <sys/audioio.h> 44.Fd #include <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 83is opened, it automatically configures the underlying driver for the 84hardware's default sample format, or monaural 8-bit mu-law if a default 85sample format has not been specified by the underlying driver. 86In addition, if it is opened read-only 87(write-only) the device is set to half-duplex record (play) mode with 88recording (playing) unpaused and playing (recording) paused. 89When 90.Pa /dev/sound 91is opened, it maintains the previous audio sample format and 92record/playback mode. 93In all other respects 94.Pa /dev/audio 95and 96.Pa /dev/sound 97are identical. 98.Pp 99Only one process may hold open a sampling device at a given time 100(although file descriptors may be shared between processes once the 101first open completes). 102.Pp 103On a half-duplex device, writes while recording is in progress will be 104immediately discarded. 105Similarly, reads while playback is in progress 106will be filled with silence but delayed to return at the current 107sampling rate. 108If both playback and recording are requested on a half-duplex 109device, playback mode takes precedence and recordings will get silence. 110On a full-duplex device, reads and writes may operate 111concurrently without interference. 112If a full-duplex capable 113.Nm audio 114device is opened for both reading and writing, 115it will start in half-duplex play mode with recording paused. 116For proper full-duplex operation, after the device is opened for reading 117and writing, full-duplex mode must be set and then recording must be unpaused. 118On either type of device, if the playback mode is paused then silence is 119played instead of the provided samples and, if recording is paused, then 120the process blocks in 121.Xr read 2 122until recording is unpaused. 123.Pp 124If a writing process does not call 125.Xr write 2 126frequently enough to provide samples at the pace the hardware 127consumes them silence is inserted. 128If the 129.Dv AUMODE_PLAY_ALL 130mode is not set the writing process must 131provide enough data via 132subsequent write calls to 133.Dq catch up 134in time to the current audio 135block before any more process-provided samples will be played. 136If a reading process does not call 137.Xr read 2 138frequently enough, it will simply miss samples. 139.Pp 140The 141.Nm audio 142device is normally accessed with 143.Xr read 2 144or 145.Xr write 2 146calls, but it can also be mapped into user memory with 147.Xr mmap 2 148(when supported by the device). 149Once the device has been mapped it can no longer be accessed 150by read or write; all access is by reading and writing to 151the mapped memory. 152The device appears as a block of memory 153of size 154.Va buffer_size 155(as available via 156.Dv AUDIO_GETINFO ) . 157The device driver will continuously move data from this buffer 158from/to the audio hardware, wrapping around at the end of the buffer. 159To find out where the hardware is currently accessing data in the buffer the 160.Dv AUDIO_GETIOFFS 161and 162.Dv AUDIO_GETOOFFS 163calls can be used. 164The playing and recording buffers are distinct and must be 165mapped separately if both are to be used. 166Only encodings that are not emulated (i.e., where 167.Dv AUDIO_ENCODINGFLAG_EMULATED 168is not set) work properly for a mapped device. 169.Pp 170The 171.Nm audio 172device, like most devices, can be used in 173.Xr select 2 , 174can be set in non-blocking mode, and can be set (with an 175.Dv FIOASYNC 176.Xr ioctl 2 ) 177to send a 178.Dv SIGIO 179when I/O is possible. 180The mixer device can be set to generate a 181.Dv SIGIO 182whenever a mixer value is changed. 183.Pp 184The following 185.Xr ioctl 2 186commands are supported on the sample devices: 187.Pp 188.Bl -tag -width Ds -compact 189.It Dv AUDIO_FLUSH 190This command stops all playback and recording, clears all queued 191buffers, resets error counters, and restarts recording and playback as 192appropriate for the current sampling mode. 193.Pp 194.It Dv AUDIO_RERROR Fa "int *" 195.It Dv AUDIO_PERROR Fa "int *" 196These commands fetch the count of dropped input or output samples into 197the 198.Vt int * 199argument, respectively. 200There is no information regarding when in the sample stream 201they were dropped. 202.Pp 203.It Dv AUDIO_WSEEK Fa "u_long *" 204This command fetches the count of bytes that are queued ahead of the 205first sample in the most recent sample block written into its 206.Vt u_long * 207argument. 208.Pp 209.It Dv AUDIO_DRAIN 210This command suspends the calling process until all queued playback 211samples have been played by the hardware. 212.Pp 213.It Dv AUDIO_GETDEV Fa "audio_device_t *" 214This command fetches the current hardware device information into the 215.Vt audio_device_t * 216argument. 217.Bd -literal 218typedef struct audio_device { 219 char name[MAX_AUDIO_DEV_LEN]; 220 char version[MAX_AUDIO_DEV_LEN]; 221 char config[MAX_AUDIO_DEV_LEN]; 222} audio_device_t; 223.Ed 224.Pp 225.It Dv AUDIO_GETFD Fa "int *" 226This command returns the current setting of the full-duplex mode. 227.Pp 228.It Dv AUDIO_GETENC Fa "audio_encoding_t *" 229This command is used iteratively to fetch sample encoding 230.Va name Ns s 231and 232.Va format_id Ns s 233into the input/output 234.Vt audio_encoding_t * 235argument. 236.Bd -literal 237typedef struct audio_encoding { 238 int index; /* input: nth encoding */ 239 char name[MAX_AUDIO_DEV_LEN]; /* name of encoding */ 240 int encoding; /* value for encoding parameter */ 241 int precision; /* value for precision parameter */ 242 int flags; 243#define AUDIO_ENCODINGFLAG_EMULATED 1 /* software emulation mode */ 244} audio_encoding_t; 245.Ed 246.Pp 247To query 248all the supported encodings, start with an index field of 0 and 249continue with successive encodings (1, 2, ...) until the command returns 250an error. 251.Pp 252.It Dv AUDIO_SETFD Fa "int *" 253This command sets the device into full-duplex operation if its integer 254argument has a non-zero value, or into half-duplex operation if it 255contains a zero value. 256If the device does not support full-duplex 257operation, attempting to set full-duplex mode returns an error. 258.Pp 259.It Dv AUDIO_GETPROPS Fa "int *" 260This command gets a bit set of hardware properties. 261If the hardware 262has a certain property, the corresponding bit is set, otherwise it is not. 263The properties can have the following values: 264.Pp 265.Bl -tag -width AUDIO_PROP_INDEPENDENT -compact 266.It Dv AUDIO_PROP_FULLDUPLEX 267The device admits full-duplex operation. 268.It Dv AUDIO_PROP_MMAP 269The device can be used with 270.Xr mmap 2 . 271.It Dv AUDIO_PROP_INDEPENDENT 272The device can set the playing and recording encoding parameters 273independently. 274.El 275.Pp 276.It Dv AUDIO_GETIOFFS Fa "audio_offset_t *" 277.It Dv AUDIO_GETOOFFS Fa "audio_offset_t *" 278These commands fetch the current offset in the input (output) buffer where 279the audio hardware's DMA engine will be putting (getting) data. 280They are mostly useful when the device 281buffer is available in user space via the 282.Xr mmap 2 283call. 284The information is returned in the 285.Vt audio_offset 286structure. 287.Bd -literal 288typedef struct audio_offset { 289 u_int samples; /* Total number of bytes transferred */ 290 u_int deltablks; /* Blocks transferred since last checked */ 291 u_int offset; /* Physical transfer offset in buffer */ 292} audio_offset_t; 293.Ed 294.Pp 295.It Dv AUDIO_GETRRINFO Fa "audio_bufinto_t *" 296.It Dv AUDIO_GETPRINFO Fa "audio_bufinfo_t *" 297These commands fetch the current information about the input or 298output buffer, respectively. 299The block size, high and low water marks and current position 300are returned in the 301.Vt audio_bufinfo 302structure. 303.Bd -literal 304typedef struct audio_bufinfo { 305 u_int blksize; /* block size */ 306 u_int hiwat; /* high water mark */ 307 u_int lowat; /* low water mark */ 308 u_int seek; /* current position */ 309} audio_bufinfo_t; 310.Ed 311.Pp 312This information is mostly useful in input or output loops to determine 313how much data to read or write, respectively. 314Note, these ioctls were added to aid in porting third party applications 315and libraries, and should not be used in new code. 316.Pp 317.It Dv AUDIO_GETINFO Fa "audio_info_t *" 318.It Dv AUDIO_SETINFO Fa "audio_info_t *" 319Get or set audio information as encoded in the 320.Vt audio_info 321structure. 322.Bd -literal 323typedef struct audio_info { 324 struct audio_prinfo play; /* info for play (output) side */ 325 struct audio_prinfo record; /* info for record (input) side */ 326 u_int monitor_gain; /* input to output mix */ 327 /* BSD extensions */ 328 u_int blocksize; /* H/W read/write block size */ 329 u_int hiwat; /* output high water mark */ 330 u_int lowat; /* output low water mark */ 331 u_char output_muted; /* toggle play mute */ 332 u_char cspare[3]; 333 u_int mode; /* current device mode */ 334#define AUMODE_PLAY 0x01 335#define AUMODE_RECORD 0x02 336#define AUMODE_PLAY_ALL 0x04 /* do not do real-time correction */ 337} audio_info_t; 338.Ed 339.Pp 340When setting the current state with 341.Dv AUDIO_SETINFO , 342the 343.Vt audio_info 344structure should first be initialized with 345.Pp 346.Dl "AUDIO_INITINFO(&info);" 347.Pp 348and then the particular values to be changed should be set. 349This allows the audio driver to only set those things that you wish 350to change and eliminates the need to query the device with 351.Dv AUDIO_GETINFO 352first. 353.Pp 354The 355.Va mode 356field should be set to 357.Dv AUMODE_PLAY , 358.Dv AUMODE_RECORD , 359.Dv AUMODE_PLAY_ALL , 360or a bitwise OR combination of the three. 361Only full-duplex audio devices support 362simultaneous record and playback. 363.Pp 364.Va blocksize 365is used to attempt to set both play and record block sizes 366to the same value, it is left for compatibility only and 367its use is discouraged. 368.Pp 369.Va hiwat 370and 371.Va lowat 372are used to control write behavior. 373Writes to the audio devices will queue up blocks until the high-water 374mark is reached, at which point any more write calls will block 375until the queue is drained to the low-water mark. 376.Va hiwat 377and 378.Va lowat 379set those high- and low-water marks (in audio blocks). 380The default for 381.Va hiwat 382is the maximum value and for 383.Va lowat 38475% of 385.Va hiwat . 386.Bd -literal 387struct audio_prinfo { 388 u_int sample_rate; /* sample rate in samples/s */ 389 u_int channels; /* number of channels, usually 1 or 2 */ 390 u_int precision; /* number of bits/sample */ 391 u_int encoding; /* data encoding (AUDIO_ENCODING_* below) */ 392 u_int gain; /* volume level */ 393 u_int port; /* selected I/O port */ 394 u_int seek; /* BSD extension */ 395 u_int avail_ports; /* available I/O ports */ 396 u_int buffer_size; /* total size audio buffer */ 397 u_int _ispare[1]; 398 /* Current state of device: */ 399 u_int samples; /* number of samples */ 400 u_int eof; /* End Of File (zero-size writes) counter */ 401 u_char pause; /* non-zero if paused, zero to resume */ 402 u_char error; /* non-zero if underflow/overflow occurred */ 403 u_char waiting; /* non-zero if another process hangs in open */ 404 u_char balance; /* stereo channel balance */ 405 u_char cspare[2]; 406 u_char open; /* non-zero if currently open */ 407 u_char active; /* non-zero if I/O is currently active */ 408}; 409.Ed 410.Pp 411Note: many hardware audio drivers require identical playback and 412recording sample rates, sample encodings, and channel counts. 413The playing information is always set last and will prevail on such hardware. 414If the hardware can handle different settings the 415.Dv AUDIO_PROP_INDEPENDENT 416property is set. 417.Pp 418The 419.Va encoding 420parameter can have the following values: 421.Pp 422.Bl -tag -width AUDIO_ENCODING_SLINEAR_BE -compact 423.It Dv AUDIO_ENCODING_ULAW 424mu-law encoding, 8 bits/sample 425.It Dv AUDIO_ENCODING_ALAW 426A-law encoding, 8 bits/sample 427.It Dv AUDIO_ENCODING_SLINEAR 428two's complement signed linear encoding with the platform byte order 429.It Dv AUDIO_ENCODING_ULINEAR 430unsigned linear encoding with the platform byte order 431.It Dv AUDIO_ENCODING_ADPCM 432ADPCM encoding, 8 bits/sample 433.It Dv AUDIO_ENCODING_SLINEAR_LE 434two's complement signed linear encoding with little endian byte order 435.It Dv AUDIO_ENCODING_SLINEAR_BE 436two's complement signed linear encoding with big endian byte order 437.It Dv AUDIO_ENCODING_ULINEAR_LE 438unsigned linear encoding with little endian byte order 439.It Dv AUDIO_ENCODING_ULINEAR_BE 440unsigned linear encoding with big endian byte order 441.El 442.Pp 443The 444.Va precision 445parameter describes the number of bits of audio data per sample. 446For sample formats such as 8, 16, and 32-bit, where the number of audio data 447bits is a power of 2, 448.Va precision 449is also exactly the size of each sample. 450For other sample formats the sample size is the smallest power of 4512 bits that the data can fit into. 452For example the sample size of 20 and 24-bit formats is 32 bits. 453.Pp 454The 455.Va gain , 456.Va port , 457and 458.Va balance 459settings provide simple shortcuts to the richer 460.Nm mixer 461interface described below. 462The 463.Va gain 464should be in the range 465.Bq Dv AUDIO_MIN_GAIN , Dv AUDIO_MAX_GAIN 466and the balance in the range 467.Bq Dv AUDIO_LEFT_BALANCE , Dv AUDIO_RIGHT_BALANCE 468with the normal setting at 469.Dv AUDIO_MID_BALANCE . 470.Pp 471The input port should be a combination of: 472.Pp 473.Bl -tag -width AUDIO_MICROPHONE -compact 474.It Dv AUDIO_MICROPHONE 475to select microphone input. 476.It Dv AUDIO_LINE_IN 477to select line input. 478.It Dv AUDIO_CD 479to select CD input. 480.El 481.Pp 482The output port should be a combination of: 483.Pp 484.Bl -tag -width AUDIO_HEADPHONE -compact 485.It Dv AUDIO_SPEAKER 486to select speaker output. 487.It Dv AUDIO_HEADPHONE 488to select headphone output. 489.It Dv AUDIO_LINE_OUT 490to select line output. 491.El 492.Pp 493The available ports can be found in 494.Va avail_ports . 495.Pp 496.Va buffer_size 497is the total size of the audio buffer. 498The buffer size divided by the 499.Va block_size 500gives the maximum value for 501.Va hiwat . 502Currently the 503.Va buffer_size 504can only be read and not set. 505.Pp 506.Va block_size 507sets the current audio block size. 508The generic 509.Nm audio 510driver layer and the hardware driver have the 511opportunity to adjust this block size to get it within 512implementation-required limits. 513Upon return from an 514.Dv AUDIO_SETINFO 515call, the actual block_size set is returned in this field. 516Normally the 517.Va block_size 518is calculated to correspond to 50ms of sound and it is recalculated 519when the encoding parameter changes, but if the 520.Va block_size 521is set explicitly this value becomes sticky, i.e., it remains 522even when the encoding is changed. 523The stickiness can be cleared by reopening the device or setting the 524.Va block_size 525to 0. 526.Pp 527Care should be taken when setting the 528.Va block_size 529before other parameters. 530If the device does not natively support the audio parameters, then the 531internal block size may be scaled to a larger size to accommodate 532conversion to a native format. 533If the 534.Va block_size 535has been set, the internal block size will not be rescaled when the 536parameters, and thus possibly the scaling factor, change. 537This can result in a block size much larger than was originally requested. 538It is recommended to set 539.Va block_size 540at the same time as, or after, all other parameters have been set. 541.Pp 542The 543.Va seek 544and 545.Va samples 546fields are only used for 547.Dv AUDIO_GETINFO . 548.Va seek 549represents the count of 550bytes pending; 551.Va samples 552represents the total number of bytes recorded or played, less those 553that were dropped due to inadequate consumption/production rates. 554.Pp 555.Va pause 556returns the current pause/unpause state for recording or playback. 557For 558.Dv AUDIO_SETINFO , 559if the pause value is specified it will either pause 560or unpause the particular direction. 561.El 562.Sh MIXER DEVICE 563The 564.Nm mixer 565device, 566.Pa /dev/mixer , 567may be manipulated with 568.Xr ioctl 2 569but does not support 570.Xr read 2 571or 572.Xr write 2 . 573It supports the following 574.Xr ioctl 2 575commands: 576.Pp 577.Bl -tag -width Ds -compact 578.It Dv AUDIO_GETDEV Fa "audio_device_t *" 579This command is the same as described above for the sampling devices. 580.Pp 581.It Dv AUDIO_MIXER_READ Fa "mixer_ctrl_t *" 582.It Dv AUDIO_MIXER_WRITE Fa "mixer_ctrl_t *" 583These commands read the current mixer state or set new mixer state for 584the specified device 585.Va dev . 586.Va type 587identifies which type of value is supplied in the 588.Vt mixer_ctrl_t * 589argument. 590.Bd -literal 591#define AUDIO_MIXER_CLASS 0 592#define AUDIO_MIXER_ENUM 1 593#define AUDIO_MIXER_SET 2 594#define AUDIO_MIXER_VALUE 3 595typedef struct mixer_ctrl { 596 int dev; /* input: nth device */ 597 int type; 598 union { 599 int ord; /* enum */ 600 int mask; /* set */ 601 mixer_level_t value; /* value */ 602 } un; 603} mixer_ctrl_t; 604 605#define AUDIO_MIN_GAIN 0 606#define AUDIO_MAX_GAIN 255 607typedef struct mixer_level { 608 int num_channels; 609 u_char level[8]; /* [num_channels] */ 610} mixer_level_t; 611#define AUDIO_MIXER_LEVEL_MONO 0 612#define AUDIO_MIXER_LEVEL_LEFT 0 613#define AUDIO_MIXER_LEVEL_RIGHT 1 614.Ed 615.Pp 616For a mixer value, the 617.Va value 618field specifies both the number of channels and the values for each 619channel. 620If the channel count does not match the current channel count, the 621attempt to change the setting may fail (depending on the hardware 622device driver implementation). 623For an enumeration value, the 624.Va ord 625field should be set to one of the possible values as returned by a prior 626.Dv AUDIO_MIXER_DEVINFO 627command. 628The type 629.Dv AUDIO_MIXER_CLASS 630is only used for classifying particular 631.Nm mixer 632device types and is not used for 633.Dv AUDIO_MIXER_READ 634or 635.Dv AUDIO_MIXER_WRITE . 636.Pp 637.It Dv AUDIO_MIXER_DEVINFO Fa "mixer_devinfo_t *" 638This command is used iteratively to fetch audio 639.Nm mixer 640device information into the input/output 641.Vt mixer_devinfo_t * 642argument. 643To query all the supported devices, start with an index field of 6440 and continue with successive devices (1, 2, ...) until the 645command returns an error. 646.Bd -literal 647typedef struct mixer_devinfo { 648 int index; /* input: nth mixer device */ 649 audio_mixer_name_t label; 650 int type; 651 int mixer_class; 652 int next, prev; 653#define AUDIO_MIXER_LAST -1 654 union { 655 struct audio_mixer_enum { 656 int num_mem; 657 struct { 658 audio_mixer_name_t label; 659 int ord; 660 } member[32]; 661 } e; 662 struct audio_mixer_set { 663 int num_mem; 664 struct { 665 audio_mixer_name_t label; 666 int mask; 667 } member[32]; 668 } s; 669 struct audio_mixer_value { 670 audio_mixer_name_t units; 671 int num_channels; 672 int delta; 673 } v; 674 } un; 675} mixer_devinfo_t; 676.Ed 677.Pp 678The 679.Va label 680field identifies the name of this particular mixer control. 681The 682.Va index 683field may be used as the 684.Va dev 685field in 686.Dv AUDIO_MIXER_READ 687and 688.Dv AUDIO_MIXER_WRITE 689commands. 690The 691.Va type 692field identifies the type of this mixer control. 693Enumeration types are typically used for on/off style controls (e.g., a 694mute control) or for input/output device selection (e.g., select 695recording input source from CD, line in, or microphone). 696Set types are similar to enumeration types but any combination 697of the mask bits can be used. 698.Pp 699The 700.Va mixer_class 701field identifies what class of control this is. 702This value is set to the index value used to query the class itself. 703The 704.Pq arbitrary 705value set by the hardware driver may be determined by examining the 706.Va mixer_class 707field of the class itself, 708a mixer of type 709.Dv AUDIO_MIXER_CLASS . 710For example, a mixer level controlling the input gain on the 711.Dq line in 712circuit would have a 713.Va mixer_class 714that matches an input class device with the name 715.Dq inputs 716.Dv ( AudioCinputs ) 717and would have a 718.Va label 719of 720.Dq line 721.Dv ( AudioNline ) . 722Mixer controls which control audio circuitry for a particular audio 723source (e.g., line-in, CD in, DAC output) are collected under the input class, 724while those which control all audio sources (e.g., master volume, 725equalization controls) are under the output class. 726Hardware devices capable of recording typically also have a record class, 727for controls that only affect recording, 728and also a monitor class. 729.Pp 730The 731.Va next 732and 733.Va prev 734may be used by the hardware device driver to provide hints for the next 735and previous devices in a related set (for example, the line in level 736control would have the line in mute as its 737.Dq next 738value). 739If there is no relevant next or previous value, 740.Dv AUDIO_MIXER_LAST 741is specified. 742.Pp 743For 744.Dv AUDIO_MIXER_ENUM 745mixer control types, 746the enumeration values and their corresponding names are filled in. 747For example, a mute control would return appropriate values paired with 748.Dv AudioNon 749and 750.Dv AudioNoff . 751For the 752.Dv AUDIO_MIXER_VALUE 753and 754.Dv AUDIO_MIXER_SET 755mixer control types, the channel count is 756returned; the units name specifies what the level controls (typical 757values are 758.Dv AudioNvolume , 759.Dv AudioNtreble , 760and 761.Dv AudioNbass ) . 762.\" For AUDIO_MIXER_SET mixer control types, what is what? 763.El 764.Pp 765By convention, all the mixer devices can be distinguished from other 766mixer controls because they use a name from one of the 767.Dv AudioC* 768string values. 769.Sh FILES 770.Bl -tag -width /dev/audioctl -compact 771.It Pa /dev/audio 772.It Pa /dev/audioctl 773.It Pa /dev/sound 774.It Pa /dev/mixer 775.El 776.Sh SEE ALSO 777.Xr aucat 1 , 778.Xr audioctl 1 , 779.Xr cdio 1 , 780.Xr mixerctl 1 , 781.Xr ioctl 2 , 782.Xr ossaudio 3 , 783.Xr sio_open 3 , 784.Xr ac97 4 , 785.Xr uaudio 4 , 786.Xr audio 9 787.Sh BUGS 788If the device is used in 789.Xr mmap 2 790it is currently always mapped for writing (playing) due to 791VM system weirdness. 792