1.\"- 2.\" Copyright (c) 2021 Christos Margiolis <christos@FreeBSD.org> 3.\" 4.\" Permission is hereby granted, free of charge, to any person obtaining a copy 5.\" of this software and associated documentation files (the "Software"), to deal 6.\" in the Software without restriction, including without limitation the rights 7.\" to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 8.\" copies of the Software, and to permit persons to whom the Software is 9.\" furnished to do so, subject to the following conditions: 10.\" 11.\" The above copyright notice and this permission notice shall be included in 12.\" all copies or substantial portions of the Software. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15.\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16.\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 17.\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18.\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 19.\" OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 20.\" THE SOFTWARE. 21.\" 22.Dd October 31, 2025 23.Dt MIXER 8 24.Os 25.Sh NAME 26.Nm mixer 27.Nd manipulate soundcard mixer controls 28.Sh SYNOPSIS 29.Nm 30.Op Fl f Ar device 31.Op Fl d Ar pcmX | X Op Fl V Ar voss_device:mode 32.Op Fl os 33.Op Ar dev Ns Op Cm \&. Ns Ar control Ns Op Cm \&= Ns Ar value 34.Ar ... 35.Nm 36.Op Fl os 37.Fl a 38.Nm 39.Fl h 40.Sh DESCRIPTION 41The 42.Nm 43utility is used to set and display soundcard mixer device controls. 44.Pp 45The options are as follows: 46.Bl -tag -width "-V voss_device:mode" 47.It Fl a 48Print the values for all mixer devices available in the system 49.Pq see Sx FILES . 50.It Fl d Ar pcmX | X 51Change the default audio card to 52.Ar pcmX , 53where X is the device's unit number (e.g for pcm0, the unit number is 0). 54See 55.Sx EXAMPLES 56on how to list all available audio devices in the system. 57.Pp 58There is also the possibility of hot-swapping to the new default device if 59.Xr virtual_oss 8 60exists in the system and is running, in which case the 61.Fl V 62option needs to be specified as well. 63.Pp 64Hot-swapping generally cannot happen with plain 65.Xr sound 4 , 66so the user has to restart the track in order to get sound coming out of the 67new default device. 68This is because applications usually open a device at the start of the track 69and do not check for default device changes, in order to open the new device 70mid-track. 71.Xr virtual_oss 8 , 72on the other hand, can do hot-swapping, because it creates a virtual device for 73applications to open, and then does all the necessary routing and conversions 74to the appropriate device(s). 75.Pp 76Note that hot-swapping will work only for applications that are using 77.Xr virtual_oss 8 78devices, and not plain 79.Xr sound 4 80ones. 81.It Fl f Ar device 82Open 83.Ar device 84as the mixer device 85.Pq see Sx FILES . 86.It Fl h 87Print a help message. 88.It Fl o 89Print mixer values in a format suitable for use inside scripts. 90The mixer's header (name, audio card name, ...) will not be printed. 91.It Fl s 92Print only the recording source(s) of the mixer device. 93.It Fl V Ar voss_device:mode 94Specify a 95.Xr virtual_oss 8 96control device, as well as a mode (see below), in order to hot-swap devices. 97This option is meant to only be used in combination with the 98.Fl d 99option. 100.Pp 101The available modes are as follows: 102.Bl -column play 103.It Sy Mode Ta Sy Action 104.It all Ta Playback and recording 105.It play Ta Playback 106.It rec Ta Recording 107.El 108.Pp 109The 110.Pa mode 111part is needed, so that 112.Nm 113will not accidentally hot-swap both the recording and playback device in 114.Xr virtual_oss 8 , 115if only one direction is to be hot-swapped. 116.Pp 117See 118.Sx EXAMPLES 119on how to use this option. 120.El 121.Pp 122The list of mixer devices that may be modified are: 123.Bd -ragged -offset indent 124.Cm vol , bass , treble , synth , pcm , speaker , line , mic , cd , mix , 125.Cm pcm2 , rec , 126.Cm igain , ogain , 127.Cm line1 , line2 , line3 , 128.Cm dig1 , dig2 , dig3 , 129.Cm phin , phout , video , radio , 130and 131.Cm monitor . 132.Ed 133.Pp 134Not all mixer devices are available. 135.Pp 136Without any arguments, 137.Nm 138displays all information for each one of the mixer's supported devices to 139.Ar stdout . 140If the 141.Ar dev 142argument is specified, 143.Nm 144displays only the values for 145.Ar dev . 146More than one device may be specified. 147.Pp 148Commands use the following format: 149.Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent 150.It Sy Name Ta Sy Action 151.It Ar dev Ta Display all controls 152.It Ar dev Ns Cm \&. Ns Ar control Ta Display only the specified control 153.It Ar dev Ns Cm \&. Ns Ar control Ns Cm \&= Ns Ar value Ta Set control value 154.El 155.Pp 156The available controls are as follows (replace 157.Ar dev 158with one of the available devices): 159.Sm off 160.Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent 161.It Sy Name Ta Sy Value 162.It Ar dev Cm .volume Ta Xo 163.Ar vol | 164.Oo Cm \&+ | Cm \&- Oc Ar lvol Oo % Oc 165.Oo Cm \&: Oo Cm \&+ | Cm \&- Oc Ar rvol Oo % Oc Oc 166.Xc 167.It Ar dev Cm .mute Ta Cm 0 | 1 | ^ 168.It Ar dev Cm .mute Ta Cm off | on | toggle 169.It Ar dev Cm .recsrc Ta Cm ^ | + | - | = 170.It Ar dev Cm .recsrc Ta Cm toggle | add | remove | set 171.El 172.Sm on 173.Pp 174The 175.Ar dev Ns Cm .volume 176control modifies a device's volume. 177The optional 178.Ar lvol 179and/or 180.Ar rvol 181values have to be specified. 182The values should typically be decimal numbers between 0 and 1 with at most 2 183digits after the decimal point. 184A trailing percent sign indicates that the value should be treated as a 185percentage of 1.0, rather than an absolute value. 186Thus, 70% means the same as 0.7. 187If the left or right volume values are prefixed with 188.Cm + 189or 190.Cm - , 191the value following will be used as a relative adjustment, modifying the 192current settings by the amount specified. 193Note that relative percentages are still relative to 1.0, not to the current 194value. 195If the volume is currently 0.40 and an adjustment of +20% is specified, then 196thet final volume will be set to 0.60. 197.Pp 198Volume can also be set using the shorthand 199.Ar dev Ns Cm =value . 200This syntax does not apply to other controls. 201.Pp 202The 203.Ar dev Ns Cm .mute 204control (un)mutes a device. 205The following values are available: 206.Bl -tag -width "xxxxxxxxxx" -offset indent 207.It Cm 0 | off 208unmutes 209.Ar dev 210.It Cm 1 | on 211mutes 212.Ar dev 213.It Cm ^ | toggle 214toggles the mute of 215.Ar dev 216.El 217.Pp 218The 219.Ar dev Ns Cm .recsrc 220control modifies the recording sources of a mixer. 221.Nm 222marks devices which can be used as a recording source with 223.Sy rec . 224Recording sources are marked with 225.Sy src . 226To modify the recording source you can use one of the following modifiers 227on a 228.Sy rec 229device: 230.Bl -tag -width "xxxxxxxxxx" -offset indent 231.It Cm ^ | toggle 232toggles 233.Ar dev 234of possible recording devices 235.It Cm + | add 236adds 237.Ar dev 238to possible recording devices 239.It Cm - | remove 240removes 241.Ar dev 242from possible recording devices 243.It Cm = | set 244makes 245.Ar dev 246the only recording device. 247.El 248.Sh FILES 249.Bl -tag -width "/dev/mixerX" -compact 250.It Pa /dev/mixerX 251The mixer device, where X is the unit number of that device, 252.Pa /dev/dsp* 253devices and 254.Pa /dev/mixer* 255devices have a 1:1 relationship, which means that, for instance, 256.Pa /dev/mixer0 257is the mixer device for 258.Pa /dev/dsp0 . 259.It /dev/mixer 260Alias to the default device's mixer device. 261.Nm 262opens this when the 263.Fl f Ar device 264option is not specified. 265.El 266.Sh EXAMPLES 267List all available audio devices in the system: 268.Bd -literal -offset indent 269$ mixer -a | grep ^pcm 270.Ed 271.Pp 272Increase the 273.Cm vol 274device's volume by 5%: 275.Bd -literal -offset indent 276$ mixer vol=+5% 277.Ed 278.Pp 279Change the volume for the 280.Cm vol 281device of the 282.Pa /dev/mixer0 283mixer device to 0.65: 284.Bd -literal -offset indent 285$ mixer -f /dev/mixer0 vol.volume=0.65 286.Ed 287.Pp 288Increase the 289.Cm mic 290device's left volume by 0.10 and decrease the right 291volume by 0.05: 292.Bd -literal -offset indent 293$ mixer mic.volume=+0.10:-0.05 294.Ed 295.Pp 296Toggle the mute for 297.Cm vol : 298.Bd -literal -offset indent 299$ mixer vol.mute=toggle 300.Ed 301.Pp 302Add 303.Cm mic 304and remove 305.Cm line 306from the recording devices: 307.Bd -literal -offset indent 308$ mixer mic.recsrc=add line.recsrc=remove 309.Ed 310.Pp 311Dump 312.Pa /dev/mixer0 313information to a file and retrieve back later: 314.Bd -literal -offset indent 315$ mixer -f /dev/mixer0 -o > info 316\&... 317$ mixer -f /dev/mixer0 `cat info` 318.Ed 319.Pp 320Suppose 321.Xr virtual_oss 8 322is running with 323.Pa /dev/vdsp.ctl 324as its control device, and 325.Pa pcm0 326as the playback device. 327Change the default device to 328.Pa pcm1 , 329and hot-swap to it for both recording and playback in 330.Xr virtual_oss 8 : 331.Bd -literal -offset indent 332$ mixer -d pcm1 -V /dev/vdsp.ctl:all 333.Ed 334.Sh SEE ALSO 335.Xr mixer 3 , 336.Xr sound 4 , 337.Xr sysctl 8 , 338.Xr virtual_oss 8 339.Sh HISTORY 340The 341.Nm 342utility first appeared in 343.Fx 2.0.5 344and was rewritten completely in 345.Fx 14.0 . 346.Sh AUTHORS 347.An Christos Margiolis Aq Mt christos@FreeBSD.org 348