1.\" $NetBSD: audio.4,v 1.82 2017/10/30 15:53:51 wiz Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by John T. Kohl. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd October 27, 2017 31.Dt AUDIO 4 32.Os 33.Sh NAME 34.Nm audio 35.Nd device-independent audio driver layer 36.Sh SYNOPSIS 37.In sys/audioio.h 38.Sh DESCRIPTION 39The 40.Nm 41driver provides support for various audio peripherals. 42It provides a uniform programming interface layer above different 43underlying audio hardware drivers. 44The audio layer provides full-duplex operation if the 45underlying hardware configuration supports it. 46.Pp 47There are four device files available for audio operation: 48.Pa /dev/audio , 49.Pa /dev/sound , 50.Pa /dev/audioctl , 51and 52.Pa /dev/mixer . 53.Pp 54.Pa /dev/audio 55and 56.Pa /dev/sound 57are used for recording or playback of digital samples. 58.Pp 59.Pa /dev/mixer 60is used to manipulate volume, recording source, or other audio mixer 61functions. 62.Pp 63.Pa /dev/audioctl 64accepts the same 65.Xr ioctl 2 66operations as 67.Pa /dev/sound , 68but no other operations. 69.Pp 70.Pa /dev/sound 71and 72.Pa /dev/audio 73can be opened at 74.Em any 75time and audio sources of different precision and playback 76parameters i.e frequency will be mixed and played back simultaneously. 77.Pp 78.Pa /dev/audioctl 79can be used to manipulate the audio device 80while it is in use. 81.Sh SAMPLING DEVICES 82When 83.Pa /dev/audio 84is opened, it automatically directs the underlying driver to manipulate 85monaural 8-bit mu-law samples. 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 mode and 92record/playback mode most recently set on 93.Pa /dev/sound 94by any open channel. 95In all other respects 96.Pa /dev/audio 97and 98.Pa /dev/sound 99are identical. 100.Sh VIRTUAL CHANNELS 101Any process may open a sampling device at a given time. 102Any number of devices per process and file descriptors may be shared between 103processes. 104.Pp 105Virtual channels are converted to a common format, signed linear encoding, 106frequency channels and precision. 107These can be modified to taste by the following 108.Xr sysctl 8 109variables. 110.Bl -tag -width -compact 111.It hw.driverN.precision 112.It hw.driverN.frequency 113.It hw.driverN.channels 114.It hw.driverN.latency 115.It hw.driverN.multiuser 116.El 117.Pp 118Where 119.Em driverN 120corresponds to the underlying audio device driver and device number. 121e.g In the case of an hdafg supported device the variables would be: 122hw.hdafg0.channels, hw.hdafg0.precision, hw.hdafg0.frequency. 123.Pp 124For best results, values close to the underlying hardware should be chosen. 125These variables may only be changed when the sampling device is not in use. 126.Pp 127The hw.driverN.latency 128.Xr sysctl 8 129variable controls the latency of the in-kernel mixer by varying the hardware 130blocksize. 131It accepts a value in milliseconds(ms), fractional values are not allowed. 132A value of zero will default to 150ms. 133.Pp 134If a static blocksize is enforced by the underlying hardware driver this value 135cannot be changed. 136.Pp 137For audio applications that do not specify a preferred blocksize when configuring 138the audio device, this will be the latency these applications have. 139.Pp 140For audio applications that 141.Xr mmap 2 142the audio device for play back the resultant latency is a third (1/3) of the value 143of the hw.driverN.latency variable. 144.Pp 145The hw.driverN.multiuser 146.Xr sysctl 8 147variable determines if multiple users are allowed to access the sampling 148device. 149.Pp 150By default it is set to false. 151This means that the sampling device may be only used by 152.Em one 153user at a time. 154Other users (except root) attempting to open the sampling device will be 155denied. 156.Pp 157If set to true, all users may access the sampling device at any time. 158.Pp 159Each virtual channel has a corresponding mixer: 160.Bl -tag -width -compact 161.It vchan.dacN Output volume 162.It vchan.micN Recording volume 163.El 164.Pp 165Where N is the virtual channel number. 166e.g vchan.dac0 controlling playback volume and vchan.mic0 controlling 167recording volume for the first virtual channel. 168.Pp 169On a half-duplex device, writes while recording is in progress will be 170immediately discarded. 171Similarly, reads while playback is in progress 172will be filled with silence but delayed to return at the current 173sampling rate. 174If both playback and recording are requested on a half-duplex 175device, playback mode takes precedence and recordings will get silence. 176.Pp 177On a full-duplex device, reads and writes may operate 178concurrently without interference. 179If a full-duplex capable audio device is opened for both reading and writing 180it will start in half-duplex play mode; full-duplex mode has to be set 181explicitly. 182.Pp 183On either type of device, if the playback mode is paused then silence is 184played instead of the provided samples, and if recording is paused then 185the process blocks in 186.Xr read 2 187until recording is unpaused. 188.Pp 189If a writing process does not call 190.Xr write 2 191frequently enough to provide samples at the pace the hardware 192consumes them silence is inserted. 193If the 194.Dv AUMODE_PLAY_ALL 195mode is not set the writing process must 196provide enough data via 197subsequent write calls to 198.Dq catch up 199in time to the current audio 200block before any more process-provided samples will be played. 201If a reading process does not call 202.Xr read 2 203frequently enough, it will simply miss samples. 204.Pp 205The audio device is normally accessed with 206.Xr read 2 207or 208.Xr write 2 209calls, but it can also be mapped into user memory with 210.Xr mmap 2 211Once the device has been mapped it can no longer be accessed 212by read or write; all access is by reading and writing to 213the mapped memory. 214The device appears as a block of memory 215of size 216.Va buffersize 217(as available via 218.Dv AUDIO_GETINFO 219or 220.Dv AUDIO_GETBUFINFO ) . 221The device driver will continuously move data from this buffer 222from/to the audio hardware, wrapping around at the end of the buffer. 223To find out where the hardware is currently accessing data in the buffer the 224.Dv AUDIO_GETIOFFS 225and 226.Dv AUDIO_GETOOFFS 227calls can be used. 228The playing and recording buffers are distinct and must be 229mapped separately if both are to be used. 230Only encodings that are not emulated (i.e. where 231.Dv AUDIO_ENCODINGFLAG_EMULATED 232is not set) work properly for a mapped device. 233.Pp 234The audio device, like most devices, can be used in 235.Va select , 236can be set in non-blocking mode and can be set (with a 237.Dv FIOASYNC 238ioctl) to send a 239.Dv SIGIO 240when I/O is possible. 241The mixer device can be set to generate a 242.Dv SIGIO 243whenever a mixer value is changed. 244.Pp 245The following 246.Xr ioctl 2 247commands are supported on the sample devices: 248.Bl -tag -width indent 249.It Dv AUDIO_GETCHAN (int) 250This command will return the audio channel in use. 251.It Dv AUDIO_SETCHAN (int) 252This command will select the audio channel for subsequent ioctl calls. 253.It Dv AUDIO_FLUSH 254This command stops all playback and recording, clears all queued 255buffers, resets error counters, and restarts recording and playback as 256appropriate for the current sampling mode. 257.It Dv AUDIO_RERROR (int) 258This command fetches the count of dropped input samples into its integer 259argument. 260There is no information regarding when in the sample stream 261they were dropped. 262.It Dv AUDIO_WSEEK (u_long) 263This command fetches the count of samples that are queued ahead of the 264first sample in the most recent sample block written into its integer argument. 265.It Dv AUDIO_DRAIN 266This command suspends the calling process until all queued playback 267samples have been played by the hardware. 268.It Dv AUDIO_GETDEV (audio_device_t) 269This command fetches the current hardware device information into the 270audio_device_t argument. 271.Bd -literal 272typedef struct audio_device { 273 char name[MAX_AUDIO_DEV_LEN]; 274 char version[MAX_AUDIO_DEV_LEN]; 275 char config[MAX_AUDIO_DEV_LEN]; 276} audio_device_t; 277.Ed 278.It Dv AUDIO_GETFD (int) 279The command returns the current setting of the full duplex mode. 280.It Dv AUDIO_GETENC (audio_encoding_t) 281This command is used iteratively to fetch sample encoding names and 282format_ids into the input/output audio_encoding_t argument. 283.Bd -literal 284typedef struct audio_encoding { 285 int index; /* input: nth encoding */ 286 char name[MAX_AUDIO_DEV_LEN]; /* name of encoding */ 287 int encoding; /* value for encoding parameter */ 288 int precision; /* value for precision parameter */ 289 int flags; 290#define AUDIO_ENCODINGFLAG_EMULATED 1 /* software emulation mode */ 291} audio_encoding_t; 292.Ed 293.Pp 294To query 295all the supported encodings, start with an index field of 0 and 296continue with successive encodings (1, 2, ...) until the command returns 297an error. 298.It Dv AUDIO_SETFD (int) 299This command sets the device into full-duplex operation if its integer 300argument has a non-zero value, or into half-duplex operation if it 301contains a zero value. 302If the device does not support full-duplex 303operation, attempting to set full-duplex mode returns an error. 304.It Dv AUDIO_GETPROPS (int) 305This command gets a bit set of hardware properties. 306If the hardware 307has a certain property the corresponding bit is set, otherwise it is not. 308The properties can have the following values: 309.Pp 310.Bl -tag -width AUDIO_PROP_INDEPENDENT -compact 311.It Dv AUDIO_PROP_FULLDUPLEX 312the device admits full duplex operation. 313.It Dv AUDIO_PROP_MMAP 314the device can be used with 315.Xr mmap 2 . 316.It Dv AUDIO_PROP_INDEPENDENT 317the device can set the playing and recording encoding parameters 318independently. 319.It Dv AUDIO_PROP_PLAYBACK 320the device is capable of audio playback. 321.It Dv AUDIO_PROP_CAPTURE 322the device is capable of audio capture. 323.El 324.It Dv AUDIO_GETIOFFS (audio_offset_t) 325.It Dv AUDIO_GETOOFFS (audio_offset_t) 326This command fetches the current offset in the input(output) buffer where 327the audio hardware's DMA engine will be putting(getting) data. 328It mostly useful when the device 329buffer is available in user space via the 330.Xr mmap 2 331call. 332The information is returned in the audio_offset structure. 333.Bd -literal 334typedef struct audio_offset { 335 u_int samples; /* Total number of bytes transferred */ 336 u_int deltablks; /* Blocks transferred since last checked */ 337 u_int offset; /* Physical transfer offset in buffer */ 338} audio_offset_t; 339.Ed 340.It Dv AUDIO_GETINFO (audio_info_t) 341.It Dv AUDIO_GETBUFINFO (audio_info_t) 342.It Dv AUDIO_SETINFO (audio_info_t) 343Get or set audio information as encoded in the audio_info structure. 344.Bd -literal 345typedef struct audio_info { 346 struct audio_prinfo play; /* info for play (output) side */ 347 struct audio_prinfo record; /* info for record (input) side */ 348 u_int monitor_gain; /* input to output mix */ 349 /* BSD extensions */ 350 u_int blocksize; /* H/W read/write block size */ 351 u_int hiwat; /* output high water mark */ 352 u_int lowat; /* output low water mark */ 353 u_int _ispare1; 354 u_int mode; /* current device mode */ 355#define AUMODE_PLAY 0x01 356#define AUMODE_RECORD 0x02 357#define AUMODE_PLAY_ALL 0x04 /* do not do real-time correction */ 358} audio_info_t; 359.Ed 360.Pp 361When setting the current state with 362.Dv AUDIO_SETINFO , 363the audio_info structure should first be initialized with 364.Dv AUDIO_INITINFO Po &info Pc 365and then the particular values to be changed should be set. 366This allows the audio driver to only set those things that you wish 367to change and eliminates the need to query the device with 368.Dv AUDIO_GETINFO 369or 370.Dv AUDIO_GETBUFINFO 371first. 372.Pp 373The 374.Va mode 375field should be set to 376.Dv AUMODE_PLAY , 377.Dv AUMODE_RECORD , 378.Dv AUMODE_PLAY_ALL , 379or a bitwise OR combination of the three. 380Only full-duplex audio devices support 381simultaneous record and playback. 382.Pp 383.Va hiwat 384and 385.Va lowat 386are used to control write behavior. 387Writes to the audio devices will queue up blocks until the high-water 388mark is reached, at which point any more write calls will block 389until the queue is drained to the low-water mark. 390.Va hiwat 391and 392.Va lowat 393set those high- and low-water marks (in audio blocks). 394The default for 395.Va hiwat 396is the maximum value and for 397.Va lowat 39875 % of 399.Va hiwat . 400.Pp 401.Va blocksize 402sets the current audio blocksize. 403The generic audio driver layer and the hardware driver have the 404opportunity to adjust this block size to get it within 405implementation-required limits. 406Upon return from an 407.Dv AUDIO_SETINFO 408call, the actual blocksize set is returned in this field. 409Normally the 410.Va blocksize 411is calculated to correspond to 50ms of sound and it is recalculated 412when the encoding parameter changes, but if the 413.Va blocksize 414is set explicitly this value becomes sticky, i.e., it remains 415even when the encoding is changed. 416The stickiness can be cleared by reopening the device or setting the 417.Va blocksize 418to 0. 419.Bd -literal 420struct audio_prinfo { 421 u_int sample_rate; /* sample rate in samples/s */ 422 u_int channels; /* number of channels, usually 1 or 2 */ 423 u_int precision; /* number of bits/sample */ 424 u_int encoding; /* data encoding (AUDIO_ENCODING_* below) */ 425 u_int gain; /* volume level */ 426 u_int port; /* selected I/O port */ 427 u_long seek; /* BSD extension */ 428 u_int avail_ports; /* available I/O ports */ 429 u_int buffer_size; /* total size audio buffer */ 430 u_int _ispare[1]; 431 /* Current state of device: */ 432 u_int samples; /* number of samples */ 433 u_int eof; /* End Of File (zero-size writes) counter */ 434 u_char pause; /* non-zero if paused, zero to resume */ 435 u_char error; /* non-zero if underflow/overflow occurred */ 436 u_char waiting; /* non-zero if another process hangs in open */ 437 u_char balance; /* stereo channel balance */ 438 u_char cspare[2]; 439 u_char open; /* non-zero if currently open */ 440 u_char active; /* non-zero if I/O is currently active */ 441}; 442.Ed 443.Pp 444Note: many hardware audio drivers require identical playback and 445recording sample rates, sample encodings, and channel counts. 446The playing information is always set last and will prevail on such hardware. 447If the hardware can handle different settings the 448.Dv AUDIO_PROP_INDEPENDENT 449property is set. 450.Pp 451The encoding parameter can have the following values: 452.Pp 453.Bl -tag -width AUDIO_ENCODING_SLINEAR_BE -compact 454.It Dv AUDIO_ENCODING_ULAW 455mu-law encoding, 8 bits/sample 456.It Dv AUDIO_ENCODING_ALAW 457A-law encoding, 8 bits/sample 458.It Dv AUDIO_ENCODING_SLINEAR 459two's complement signed linear encoding with the platform byte order 460.It Dv AUDIO_ENCODING_ULINEAR 461unsigned linear encoding with the platform byte order 462.It Dv AUDIO_ENCODING_ADPCM 463ADPCM encoding, 8 bits/sample 464.It Dv AUDIO_ENCODING_SLINEAR_LE 465two's complement signed linear encoding with little endian byte order 466.It Dv AUDIO_ENCODING_SLINEAR_BE 467two's complement signed linear encoding with big endian byte order 468.It Dv AUDIO_ENCODING_ULINEAR_LE 469unsigned linear encoding with little endian byte order 470.It Dv AUDIO_ENCODING_ULINEAR_BE 471unsigned linear encoding with big endian byte order 472.It Dv AUDIO_ENCODING_AC3 473Dolby Digital AC3 474.El 475.Pp 476The 477.Va gain , 478.Va port 479and 480.Va balance 481settings provide simple shortcuts to the richer mixer 482interface described below and are not obtained by 483.Dv AUDIO_GETBUFINFO . 484The gain should be in the range 485.Bq Dv AUDIO_MIN_GAIN , Dv AUDIO_MAX_GAIN 486and the balance in the range 487.Bq Dv AUDIO_LEFT_BALANCE , Dv AUDIO_RIGHT_BALANCE 488with the normal setting at 489.Dv AUDIO_MID_BALANCE . 490.Pp 491The input port should be a combination of: 492.Pp 493.Bl -tag -width AUDIO_MICROPHONE -compact 494.It Dv AUDIO_MICROPHONE 495to select microphone input. 496.It Dv AUDIO_LINE_IN 497to select line input. 498.It Dv AUDIO_CD 499to select CD input. 500.El 501.Pp 502The output port should be a combination of: 503.Pp 504.Bl -tag -width AUDIO_HEADPHONE -compact 505.It Dv AUDIO_SPEAKER 506to select speaker output. 507.It Dv AUDIO_HEADPHONE 508to select headphone output. 509.It Dv AUDIO_LINE_OUT 510to select line output. 511.El 512.Pp 513The available ports can be found in 514.Va avail_ports 515.Dv ( AUDIO_GETBUFINFO 516only). 517.Pp 518.Va buffer_size 519is the total size of the audio buffer. 520The buffer size divided by the 521.Va blocksize 522gives the maximum value for 523.Va hiwat . 524Currently the 525.Va buffer_size 526can only be read and not set. 527.Pp 528The 529.Va seek 530and 531.Va samples 532fields are only used by 533.Dv AUDIO_GETINFO 534and 535.Dv AUDIO_GETBUFINFO . 536.Va seek 537represents the count of 538samples pending; 539.Va samples 540represents the total number of bytes recorded or played, less those 541that were dropped due to inadequate consumption/production rates. 542.Pp 543.Va pause 544returns the current pause/unpause state for recording or playback. 545For 546.Dv AUDIO_SETINFO , 547if the pause value is specified it will either pause 548or unpause the particular direction. 549.El 550.Sh MIXER DEVICE 551The mixer device, 552.Pa /dev/mixer , 553may be manipulated with 554.Xr ioctl 2 555but does not support 556.Xr read 2 557or 558.Xr write 2 . 559It supports the following 560.Xr ioctl 2 561commands: 562.Bl -tag -width indent 563.It Dv AUDIO_GETDEV (audio_device_t) 564This command is the same as described above for the sampling devices. 565.It Dv AUDIO_MIXER_READ (mixer_ctrl_t) 566.It Dv AUDIO_MIXER_WRITE (mixer_ctrl_t) 567These commands read the current mixer state or set new mixer state for 568the specified device 569.Va dev . 570.Va type 571identifies which type of value is supplied in the 572.Va mixer_ctrl_t 573argument. 574.Bd -literal 575#define AUDIO_MIXER_CLASS 0 576#define AUDIO_MIXER_ENUM 1 577#define AUDIO_MIXER_SET 2 578#define AUDIO_MIXER_VALUE 3 579typedef struct mixer_ctrl { 580 int dev; /* input: nth device */ 581 int type; 582 union { 583 int ord; /* enum */ 584 int mask; /* set */ 585 mixer_level_t value; /* value */ 586 } un; 587} mixer_ctrl_t; 588 589#define AUDIO_MIN_GAIN 0 590#define AUDIO_MAX_GAIN 255 591typedef struct mixer_level { 592 int num_channels; 593 u_char level[8]; /* [num_channels] */ 594} mixer_level_t; 595#define AUDIO_MIXER_LEVEL_MONO 0 596#define AUDIO_MIXER_LEVEL_LEFT 0 597#define AUDIO_MIXER_LEVEL_RIGHT 1 598.Ed 599.Pp 600For a mixer value, the 601.Va value 602field specifies both the number of channels and the values for each 603channel. 604If the channel count does not match the current channel count, the 605attempt to change the setting may fail (depending on the hardware 606device driver implementation). 607For an enumeration value, the 608.Va ord 609field should be set to one of the possible values as returned by a prior 610.Dv AUDIO_MIXER_DEVINFO 611command. 612The type 613.Dv AUDIO_MIXER_CLASS 614is only used for classifying particular mixer device 615types and is not used for 616.Dv AUDIO_MIXER_READ 617or 618.Dv AUDIO_MIXER_WRITE . 619.It Dv AUDIO_MIXER_DEVINFO (mixer_devinfo_t) 620This command is used iteratively to fetch audio mixer device information 621into the input/output mixer_devinfo_t argument. 622To query all the supported devices, start with an index field of 6230 and continue with successive devices (1, 2, ...) until the 624command returns an error. 625.Bd -literal 626typedef struct mixer_devinfo { 627 int index; /* input: nth mixer device */ 628 audio_mixer_name_t label; 629 int type; 630 int mixer_class; 631 int next, prev; 632#define AUDIO_MIXER_LAST -1 633 union { 634 struct audio_mixer_enum { 635 int num_mem; 636 struct { 637 audio_mixer_name_t label; 638 int ord; 639 } member[32]; 640 } e; 641 struct audio_mixer_set { 642 int num_mem; 643 struct { 644 audio_mixer_name_t label; 645 int mask; 646 } member[32]; 647 } s; 648 struct audio_mixer_value { 649 audio_mixer_name_t units; 650 int num_channels; 651 int delta; 652 } v; 653 } un; 654} mixer_devinfo_t; 655.Ed 656.Pp 657The 658.Va label 659field identifies the name of this particular mixer control. 660The 661.Va index 662field may be used as the 663.Va dev 664field in 665.Dv AUDIO_MIXER_READ 666and 667.Dv AUDIO_MIXER_WRITE 668commands. 669The 670.Va type 671field identifies the type of this mixer control. 672Enumeration types are typically used for on/off style controls (e.g. a 673mute control) or for input/output device selection (e.g. select 674recording input source from CD, line in, or microphone). 675Set types are similar to enumeration types but any combination 676of the mask bits can be used. 677.Pp 678The 679.Va mixer_class 680field identifies what class of control this is. 681The 682.Pq arbitrary 683value set by the hardware driver may be determined by examining the 684.Va mixer_class 685field of the class itself, 686a mixer of type 687.Dv AUDIO_MIXER_CLASS . 688For example, a mixer controlling the input gain on the line in circuit 689would have a 690.Va mixer_class 691that matches an input class device with the name 692.Dq inputs 693.Dv ( AudioCinputs ) , 694and would have a 695.Va label 696of 697.Dq line 698.Dv ( AudioNline ) . 699Mixer controls which control audio circuitry for a particular audio 700source (e.g. line-in, CD in, DAC output) are collected under the input class, 701while those which control all audio sources (e.g. master volume, 702equalization controls) are under the output class. 703Hardware devices capable of recording typically also have a record class, 704for controls that only affect recording, 705and also a monitor class. 706.Pp 707The 708.Va next 709and 710.Va prev 711may be used by the hardware device driver to provide hints for the next 712and previous devices in a related set (for example, the line in level 713control would have the line in mute as its 714.Dq next 715value). 716If there is no relevant next or previous value, 717.Dv AUDIO_MIXER_LAST 718is specified. 719.Pp 720For 721.Dv AUDIO_MIXER_ENUM 722mixer control types, 723the enumeration values and their corresponding names are filled in. 724For example, a mute control would return appropriate values paired with 725.Dv AudioNon 726and 727.Dv AudioNoff . 728For 729.Dv AUDIO_MIXER_VALUE 730and 731.Dv AUDIO_MIXER_SET 732mixer control types, the channel count is 733returned; the units name specifies what the level controls (typical 734values are 735.Dv AudioNvolume , 736.Dv AudioNtreble , 737.Dv AudioNbass ) . 738.\" For AUDIO_MIXER_SET mixer control types, what is what? 739.El 740.Pp 741By convention, all the mixer devices can be distinguished from other 742mixer controls because they use a name from one of the 743.Dv AudioC* 744string values. 745.Sh FILES 746.Bl -tag -width /dev/audioctl -compact 747.It Pa /dev/audio 748.It Pa /dev/audioctl 749.It Pa /dev/sound 750.It Pa /dev/mixer 751.El 752.Sh SEE ALSO 753.Xr audioctl 1 , 754.Xr mixerctl 1 , 755.Xr ioctl 2 , 756.Xr ossaudio 3 , 757.Xr midi 4 , 758.Xr radio 4 , 759.Xr sysctl 8 760.Ss ISA bus 761.Xr aria 4 , 762.Xr ess 4 , 763.Xr gus 4 , 764.Xr guspnp 4 , 765.Xr pas 4 , 766.Xr sb 4 , 767.Xr wss 4 , 768.Xr ym 4 769.Ss PCI bus 770.Xr auacer 4 , 771.Xr auich 4 , 772.Xr auixp 4 , 773.Xr autri 4 , 774.Xr auvia 4 , 775.Xr azalia 4 , 776.Xr clcs 4 , 777.Xr clct 4 , 778.Xr cmpci 4 , 779.Xr eap 4 , 780.Xr emuxki 4 , 781.Xr esa 4 , 782.Xr esm 4 , 783.Xr eso 4 , 784.Xr fms 4 , 785.Xr neo 4 , 786.Xr sv 4 , 787.Xr yds 4 788.Ss TURBOchannel 789.Xr bba 4 790.Ss USB 791.Xr uaudio 4 792.Sh HISTORY 793Support for virtual channels and mixing first appeared in 794.Nx 8.0 . 795