1.\" $OpenBSD: audio.4,v 1.62 2010/07/15 03:43:11 jakemsr 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: July 15 2010 $ 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 bps; /* value for bps parameter */ 243 int msb; /* value for msb parameter */ 244 int flags; 245#define AUDIO_ENCODINGFLAG_EMULATED 1 /* software emulation mode */ 246} audio_encoding_t; 247.Ed 248.Pp 249To query 250all the supported encodings, start with an index field of 0 and 251continue with successive encodings (1, 2, ...) until the command returns 252an error. 253.Pp 254.It Dv AUDIO_SETFD Fa "int *" 255This command sets the device into full-duplex operation if its integer 256argument has a non-zero value, or into half-duplex operation if it 257contains a zero value. 258If the device does not support full-duplex 259operation, attempting to set full-duplex mode returns an error. 260.Pp 261.It Dv AUDIO_GETPROPS Fa "int *" 262This command gets a bit set of hardware properties. 263If the hardware 264has a certain property, the corresponding bit is set, otherwise it is not. 265The properties can have the following values: 266.Pp 267.Bl -tag -width AUDIO_PROP_INDEPENDENT -compact 268.It Dv AUDIO_PROP_FULLDUPLEX 269The device admits full-duplex operation. 270.It Dv AUDIO_PROP_MMAP 271The device can be used with 272.Xr mmap 2 . 273.It Dv AUDIO_PROP_INDEPENDENT 274The device can set the playing and recording encoding parameters 275independently. 276.El 277.Pp 278.It Dv AUDIO_GETIOFFS Fa "audio_offset_t *" 279.It Dv AUDIO_GETOOFFS Fa "audio_offset_t *" 280These commands fetch the current offset in the input (output) buffer where 281the audio hardware's DMA engine will be putting (getting) data. 282They are mostly useful when the device 283buffer is available in user space via the 284.Xr mmap 2 285call. 286The information is returned in the 287.Vt audio_offset 288structure. 289.Bd -literal 290typedef struct audio_offset { 291 u_int samples; /* Total number of bytes transferred */ 292 u_int deltablks; /* Blocks transferred since last checked */ 293 u_int offset; /* Physical transfer offset in buffer */ 294} audio_offset_t; 295.Ed 296.Pp 297.It Dv AUDIO_GETRRINFO Fa "audio_bufinto_t *" 298.It Dv AUDIO_GETPRINFO Fa "audio_bufinfo_t *" 299These commands fetch the current information about the input or 300output buffer, respectively. 301The block size, high and low water marks and current position 302are returned in the 303.Vt audio_bufinfo 304structure. 305.Bd -literal 306typedef struct audio_bufinfo { 307 u_int blksize; /* block size */ 308 u_int hiwat; /* high water mark */ 309 u_int lowat; /* low water mark */ 310 u_int seek; /* current position */ 311} audio_bufinfo_t; 312.Ed 313.Pp 314This information is mostly useful in input or output loops to determine 315how much data to read or write, respectively. 316Note, these ioctls were added to aid in porting third party applications 317and libraries, and should not be used in new code. 318.Pp 319.It Dv AUDIO_GETINFO Fa "audio_info_t *" 320.It Dv AUDIO_SETINFO Fa "audio_info_t *" 321Get or set audio information as encoded in the 322.Vt audio_info 323structure. 324.Bd -literal 325typedef struct audio_info { 326 struct audio_prinfo play; /* info for play (output) side */ 327 struct audio_prinfo record; /* info for record (input) side */ 328 u_int monitor_gain; /* input to output mix */ 329 /* BSD extensions */ 330 u_int blocksize; /* H/W read/write block size */ 331 u_int hiwat; /* output high water mark */ 332 u_int lowat; /* output low water mark */ 333 u_char output_muted; /* toggle play mute */ 334 u_char cspare[3]; 335 u_int mode; /* current device mode */ 336#define AUMODE_PLAY 0x01 337#define AUMODE_RECORD 0x02 338#define AUMODE_PLAY_ALL 0x04 /* do not do real-time correction */ 339} audio_info_t; 340.Ed 341.Pp 342When setting the current state with 343.Dv AUDIO_SETINFO , 344the 345.Vt audio_info 346structure should first be initialized with 347.Pp 348.Dl "AUDIO_INITINFO(&info);" 349.Pp 350and then the particular values to be changed should be set. 351This allows the audio driver to only set those things that you wish 352to change and eliminates the need to query the device with 353.Dv AUDIO_GETINFO 354first. 355.Pp 356The 357.Va mode 358field should be set to 359.Dv AUMODE_PLAY , 360.Dv AUMODE_RECORD , 361.Dv AUMODE_PLAY_ALL , 362or a bitwise OR combination of the three. 363Only full-duplex audio devices support 364simultaneous record and playback. 365.Pp 366.Va blocksize 367is used to attempt to set both play and record block sizes 368to the same value, it is left for compatibility only and 369its use is discouraged. 370.Pp 371.Va hiwat 372and 373.Va lowat 374are used to control write behavior. 375Writes to the audio devices will queue up blocks until the high-water 376mark is reached, at which point any more write calls will block 377until the queue is drained to the low-water mark. 378.Va hiwat 379and 380.Va lowat 381set those high- and low-water marks (in audio blocks). 382The default for 383.Va hiwat 384is the maximum value and for 385.Va lowat 38675% of 387.Va hiwat . 388.Bd -literal 389struct audio_prinfo { 390 u_int sample_rate; /* sample rate in bit/s */ 391 u_int channels; /* number of channels, usually 1 or 2 */ 392 u_int precision; /* number of bits/sample */ 393 u_int bps; /* number of bytes/sample */ 394 u_int msb; /* data alignment */ 395 u_int encoding; /* data encoding (AUDIO_ENCODING_* below) */ 396 u_int gain; /* volume level */ 397 u_int port; /* selected I/O port */ 398 u_int seek; /* BSD extension */ 399 u_int avail_ports; /* available I/O ports */ 400 u_int buffer_size; /* total size audio buffer */ 401 u_int block_size; /* size a block */ 402 /* Current state of device: */ 403 u_int samples; /* number of samples */ 404 u_int eof; /* End Of File (zero-size writes) counter */ 405 u_char pause; /* non-zero if paused, zero to resume */ 406 u_char error; /* non-zero if underflow/overflow occurred */ 407 u_char waiting; /* non-zero if another process hangs in open */ 408 u_char balance; /* stereo channel balance */ 409 u_char cspare[2]; 410 u_char open; /* non-zero if currently open */ 411 u_char active; /* non-zero if I/O is currently active */ 412}; 413.Ed 414.Pp 415Note: many hardware audio drivers require identical playback and 416recording sample rates, sample encodings, and channel counts. 417The playing information is always set last and will prevail on such hardware. 418If the hardware can handle different settings the 419.Dv AUDIO_PROP_INDEPENDENT 420property is set. 421.Pp 422The 423.Va encoding 424parameter can have the following values: 425.Pp 426.Bl -tag -width AUDIO_ENCODING_SLINEAR_BE -compact 427.It Dv AUDIO_ENCODING_ULAW 428mu-law encoding, 8 bits/sample 429.It Dv AUDIO_ENCODING_ALAW 430A-law encoding, 8 bits/sample 431.It Dv AUDIO_ENCODING_SLINEAR 432two's complement signed linear encoding with the platform byte order 433.It Dv AUDIO_ENCODING_ULINEAR 434unsigned linear encoding with the platform byte order 435.It Dv AUDIO_ENCODING_ADPCM 436ADPCM encoding, 8 bits/sample 437.It Dv AUDIO_ENCODING_SLINEAR_LE 438two's complement signed linear encoding with little endian byte order 439.It Dv AUDIO_ENCODING_SLINEAR_BE 440two's complement signed linear encoding with big endian byte order 441.It Dv AUDIO_ENCODING_ULINEAR_LE 442unsigned linear encoding with little endian byte order 443.It Dv AUDIO_ENCODING_ULINEAR_BE 444unsigned linear encoding with big endian byte order 445.El 446.Pp 447The 448.Va precision 449parameter describes the number of bits of audio data per sample. 450The 451.Va bps 452parameter describes the number of bytes of audio data per sample. 453The 454.Va msb 455parameter describes the alignment of the data in the sample. 456It is only meaningful when 457.Va precision 458/ NBBY < 459.Va bps . 460A value of 1 means the data is aligned to the most significant bit. 461.Pp 462The 463.Va gain , 464.Va port , 465and 466.Va balance 467settings provide simple shortcuts to the richer 468.Nm mixer 469interface described below. 470The 471.Va gain 472should be in the range 473.Bq Dv AUDIO_MIN_GAIN , Dv AUDIO_MAX_GAIN 474and the balance in the range 475.Bq Dv AUDIO_LEFT_BALANCE , Dv AUDIO_RIGHT_BALANCE 476with the normal setting at 477.Dv AUDIO_MID_BALANCE . 478.Pp 479The input port should be a combination of: 480.Pp 481.Bl -tag -width AUDIO_MICROPHONE -compact 482.It Dv AUDIO_MICROPHONE 483to select microphone input. 484.It Dv AUDIO_LINE_IN 485to select line input. 486.It Dv AUDIO_CD 487to select CD input. 488.El 489.Pp 490The output port should be a combination of: 491.Pp 492.Bl -tag -width AUDIO_HEADPHONE -compact 493.It Dv AUDIO_SPEAKER 494to select speaker output. 495.It Dv AUDIO_HEADPHONE 496to select headphone output. 497.It Dv AUDIO_LINE_OUT 498to select line output. 499.El 500.Pp 501The available ports can be found in 502.Va avail_ports . 503.Pp 504.Va buffer_size 505is the total size of the audio buffer. 506The buffer size divided by the 507.Va block_size 508gives the maximum value for 509.Va hiwat . 510Currently the 511.Va buffer_size 512can only be read and not set. 513.Pp 514.Va block_size 515sets the current audio block size. 516The generic 517.Nm audio 518driver layer and the hardware driver have the 519opportunity to adjust this block size to get it within 520implementation-required limits. 521Upon return from an 522.Dv AUDIO_SETINFO 523call, the actual block_size set is returned in this field. 524Normally the 525.Va block_size 526is calculated to correspond to 50ms of sound and it is recalculated 527when the encoding parameter changes, but if the 528.Va block_size 529is set explicitly this value becomes sticky, i.e., it remains 530even when the encoding is changed. 531The stickiness can be cleared by reopening the device or setting the 532.Va block_size 533to 0. 534.Pp 535Care should be taken when setting the 536.Va block_size 537before other parameters. 538If the device does not natively support the audio parameters, then the 539internal block size may be scaled to a larger size to accommodate 540conversion to a native format. 541If the 542.Va block_size 543has been set, the internal block size will not be rescaled when the 544parameters, and thus possibly the scaling factor, change. 545This can result in a block size much larger than was originally requested. 546It is recommended to set 547.Va block_size 548at the same time as, or after, all other parameters have been set. 549.Pp 550The 551.Va seek 552and 553.Va samples 554fields are only used for 555.Dv AUDIO_GETINFO . 556.Va seek 557represents the count of 558bytes pending; 559.Va samples 560represents the total number of bytes recorded or played, less those 561that were dropped due to inadequate consumption/production rates. 562.Pp 563.Va pause 564returns the current pause/unpause state for recording or playback. 565For 566.Dv AUDIO_SETINFO , 567if the pause value is specified it will either pause 568or unpause the particular direction. 569.El 570.Sh MIXER DEVICE 571The 572.Nm mixer 573device, 574.Pa /dev/mixer , 575may be manipulated with 576.Xr ioctl 2 577but does not support 578.Xr read 2 579or 580.Xr write 2 . 581It supports the following 582.Xr ioctl 2 583commands: 584.Pp 585.Bl -tag -width Ds -compact 586.It Dv AUDIO_GETDEV Fa "audio_device_t *" 587This command is the same as described above for the sampling devices. 588.Pp 589.It Dv AUDIO_MIXER_READ Fa "mixer_ctrl_t *" 590.It Dv AUDIO_MIXER_WRITE Fa "mixer_ctrl_t *" 591These commands read the current mixer state or set new mixer state for 592the specified device 593.Va dev . 594.Va type 595identifies which type of value is supplied in the 596.Vt mixer_ctrl_t * 597argument. 598.Bd -literal 599#define AUDIO_MIXER_CLASS 0 600#define AUDIO_MIXER_ENUM 1 601#define AUDIO_MIXER_SET 2 602#define AUDIO_MIXER_VALUE 3 603typedef struct mixer_ctrl { 604 int dev; /* input: nth device */ 605 int type; 606 union { 607 int ord; /* enum */ 608 int mask; /* set */ 609 mixer_level_t value; /* value */ 610 } un; 611} mixer_ctrl_t; 612 613#define AUDIO_MIN_GAIN 0 614#define AUDIO_MAX_GAIN 255 615typedef struct mixer_level { 616 int num_channels; 617 u_char level[8]; /* [num_channels] */ 618} mixer_level_t; 619#define AUDIO_MIXER_LEVEL_MONO 0 620#define AUDIO_MIXER_LEVEL_LEFT 0 621#define AUDIO_MIXER_LEVEL_RIGHT 1 622.Ed 623.Pp 624For a mixer value, the 625.Va value 626field specifies both the number of channels and the values for each 627channel. 628If the channel count does not match the current channel count, the 629attempt to change the setting may fail (depending on the hardware 630device driver implementation). 631For an enumeration value, the 632.Va ord 633field should be set to one of the possible values as returned by a prior 634.Dv AUDIO_MIXER_DEVINFO 635command. 636The type 637.Dv AUDIO_MIXER_CLASS 638is only used for classifying particular 639.Nm mixer 640device types and is not used for 641.Dv AUDIO_MIXER_READ 642or 643.Dv AUDIO_MIXER_WRITE . 644.Pp 645.It Dv AUDIO_MIXER_DEVINFO Fa "mixer_devinfo_t *" 646This command is used iteratively to fetch audio 647.Nm mixer 648device information into the input/output 649.Vt mixer_devinfo_t * 650argument. 651To query all the supported devices, start with an index field of 6520 and continue with successive devices (1, 2, ...) until the 653command returns an error. 654.Bd -literal 655typedef struct mixer_devinfo { 656 int index; /* input: nth mixer device */ 657 audio_mixer_name_t label; 658 int type; 659 int mixer_class; 660 int next, prev; 661#define AUDIO_MIXER_LAST -1 662 union { 663 struct audio_mixer_enum { 664 int num_mem; 665 struct { 666 audio_mixer_name_t label; 667 int ord; 668 } member[32]; 669 } e; 670 struct audio_mixer_set { 671 int num_mem; 672 struct { 673 audio_mixer_name_t label; 674 int mask; 675 } member[32]; 676 } s; 677 struct audio_mixer_value { 678 audio_mixer_name_t units; 679 int num_channels; 680 int delta; 681 } v; 682 } un; 683} mixer_devinfo_t; 684.Ed 685.Pp 686The 687.Va label 688field identifies the name of this particular mixer control. 689The 690.Va index 691field may be used as the 692.Va dev 693field in 694.Dv AUDIO_MIXER_READ 695and 696.Dv AUDIO_MIXER_WRITE 697commands. 698The 699.Va type 700field identifies the type of this mixer control. 701Enumeration types are typically used for on/off style controls (e.g., a 702mute control) or for input/output device selection (e.g., select 703recording input source from CD, line in, or microphone). 704Set types are similar to enumeration types but any combination 705of the mask bits can be used. 706.Pp 707The 708.Va mixer_class 709field identifies what class of control this is. 710This value is set to the index value used to query the class itself. 711The 712.Pq arbitrary 713value set by the hardware driver may be determined by examining the 714.Va mixer_class 715field of the class itself, 716a mixer of type 717.Dv AUDIO_MIXER_CLASS . 718For example, a mixer level controlling the input gain on the 719.Dq line in 720circuit would have a 721.Va mixer_class 722that matches an input class device with the name 723.Dq inputs 724.Dv ( AudioCinputs ) 725and would have a 726.Va label 727of 728.Dq line 729.Dv ( AudioNline ) . 730Mixer controls which control audio circuitry for a particular audio 731source (e.g., line-in, CD in, DAC output) are collected under the input class, 732while those which control all audio sources (e.g., master volume, 733equalization controls) are under the output class. 734Hardware devices capable of recording typically also have a record class, 735for controls that only affect recording, 736and also a monitor class. 737.Pp 738The 739.Va next 740and 741.Va prev 742may be used by the hardware device driver to provide hints for the next 743and previous devices in a related set (for example, the line in level 744control would have the line in mute as its 745.Dq next 746value). 747If there is no relevant next or previous value, 748.Dv AUDIO_MIXER_LAST 749is specified. 750.Pp 751For 752.Dv AUDIO_MIXER_ENUM 753mixer control types, 754the enumeration values and their corresponding names are filled in. 755For example, a mute control would return appropriate values paired with 756.Dv AudioNon 757and 758.Dv AudioNoff . 759For the 760.Dv AUDIO_MIXER_VALUE 761and 762.Dv AUDIO_MIXER_SET 763mixer control types, the channel count is 764returned; the units name specifies what the level controls (typical 765values are 766.Dv AudioNvolume , 767.Dv AudioNtreble , 768and 769.Dv AudioNbass ) . 770.\" For AUDIO_MIXER_SET mixer control types, what is what? 771.El 772.Pp 773By convention, all the mixer devices can be distinguished from other 774mixer controls because they use a name from one of the 775.Dv AudioC* 776string values. 777.Sh FILES 778.Bl -tag -width /dev/audioctl -compact 779.It Pa /dev/audio 780.It Pa /dev/audioctl 781.It Pa /dev/sound 782.It Pa /dev/mixer 783.El 784.Sh SEE ALSO 785.Xr aucat 1 , 786.Xr audioctl 1 , 787.Xr cdio 1 , 788.Xr mixerctl 1 , 789.Xr ioctl 2 , 790.Xr ossaudio 3 , 791.Xr sio_open 3 , 792.Xr ac97 4 , 793.Xr uaudio 4 , 794.Xr audio 9 795.Sh BUGS 796If the device is used in 797.Xr mmap 2 798it is currently always mapped for writing (playing) due to 799VM system weirdness. 800