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 August 14, 2024 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 pcmN | N 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 pcmN | N 51Change the default audio card to 52.Ar pcmN , 53where N is the 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/mixerN -compact 250.It Pa /dev/mixerN 251The mixer device, where 252.Ar N 253is the number of that device, for example 254.Ar /dev/mixer0 . 255PCM cards and mixers have a 1:1 relationship, which means that 256.Pa /dev/mixer0 257is the mixer for 258.Pa /dev/pcm0 259and so on. 260By default, 261.Nm 262prints both the audio card's number and the mixer associated with it 263in the form of 264.Ar pcmN:mixer . 265The 266.Pa /dev/mixer 267file, although it does not exist in the filesystem, points to the default 268mixer device and is the file 269.Nm 270opens when the 271.Fl f Ar device 272option has not been specified. 273.El 274.Sh EXAMPLES 275List all available audio devices in the system: 276.Bd -literal -offset indent 277$ mixer -a | grep ^pcm 278.Ed 279.Pp 280Increase the 281.Cm vol 282device's volume by 5%: 283.Bd -literal -offset indent 284$ mixer vol=+5% 285.Ed 286.Pp 287Change the volume for the 288.Cm vol 289device of the 290.Pa /dev/mixer0 291mixer device to 0.65: 292.Bd -literal -offset indent 293$ mixer -f /dev/mixer0 vol.volume=0.65 294.Ed 295.Pp 296Increase the 297.Cm mic 298device's left volume by 0.10 and decrease the right 299volume by 0.05: 300.Bd -literal -offset indent 301$ mixer mic.volume=+0.10:-0.05 302.Ed 303.Pp 304Toggle the mute for 305.Cm vol : 306.Bd -literal -offset indent 307$ mixer vol.mute=toggle 308.Ed 309.Pp 310Add 311.Cm mic 312and remove 313.Cm line 314from the recording devices: 315.Bd -literal -offset indent 316$ mixer mic.recsrc=add line.recsrc=remove 317.Ed 318.Pp 319Dump 320.Pa /dev/mixer0 321information to a file and retrieve back later: 322.Bd -literal -offset indent 323$ mixer -f /dev/mixer0 -o > info 324\&... 325$ mixer -f /dev/mixer0 `cat info` 326.Ed 327.Pp 328Suppose 329.Xr virtual_oss 8 330is running with 331.Pa /dev/vdsp.ctl 332as its control device, and 333.Pa pcm0 334as the playback device. 335Change the default device to 336.Pa pcm1 , 337and hot-swap to it for both recording and playback in 338.Xr virtual_oss 8 : 339.Bd -literal -offset indent 340$ mixer -d pcm1 -V /dev/vdsp.ctl:all 341.Ed 342.Sh SEE ALSO 343.Xr mixer 3 , 344.Xr sound 4 , 345.Xr sysctl 8 , 346.Xr virtual_oss 8 347.Sh HISTORY 348The 349.Nm 350utility first appeared in 351.Fx 2.0.5 352and was rewritten completely in 353.Fx 14.0 . 354.Sh AUTHORS 355.An Christos Margiolis Aq Mt christos@FreeBSD.org 356