usr.sbin/mixer/mixer.8

   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 .\" $FreeBSD$
  23 .\"
  24 .Dd March 20, 2022
  25 .Dt MIXER 8
  26 .Os
  27 .Sh NAME
  28 .Nm mixer
  29 .Nd manipulate soundcard mixer controls
  30 .Sh SYNOPSIS
  31 .Nm
  32 .Op Fl f Ar device
  33 .Op Fl d Ar unit
  34 .Op Fl os
  35 .Op Ar dev Ns Op Cm \&. Ns Ar control Ns Op Cm \&= Ns Ar value
  36 .Ar ...
  37 .Nm
  38 .Op Fl d Ar unit
  39 .Op Fl os
  40 .Fl a
  41 .Nm
  42 .Fl h
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility is used to set and display soundcard mixer device controls.
  47 .Pp
  48 The options are as follows:
  49 .Bl -tag -width "-f device"
  50 .It Fl a
  51 Print the values for all mixer devices available in the system
  52 .Pq see Sx FILES .
  53 .It Fl d Ar unit
  54 Change the default audio card to
  55 .Ar unit .
  56 The unit has to be an integer value.
  57 To see what unit values are available, look at the number each mixer device has by running
  58 .Nm .
  59 .It Fl f Ar device
  60 Open
  61 .Ar device
  62 as the mixer device
  63 .Pq see Sx FILES .
  64 .It Fl h
  65 Print a help message.
  66 .It Fl o
  67 Print mixer values in a format suitable for use inside scripts.
  68 The mixer's header (name, audio card name, ...) will not be printed.
  69 .It Fl s
  70 Print only the recording source(s) of the mixer device.
  71 .El
  72 .Pp
  73 The list of mixer devices that may be modified are:
  74 .Bd -ragged -offset indent
  75 .Cm vol , bass , treble , synth , pcm , speaker , line , mic , cd , mix ,
  76 .Cm pcm2 , rec ,
  77 .Cm igain , ogain ,
  78 .Cm line1 , line2 , line3 ,
  79 .Cm dig1 , dig2 , dig3 ,
  80 .Cm phin , phout , video , radio ,
  81 and
  82 .Cm monitor .
  83 .Ed
  84 .Pp
  85 Not all mixer devices are available.
  86 .Pp
  87 Without any arguments,
  88 .Nm
  89 displays all information for each one of the mixer's supported devices to
  90 .Ar stdout .
  91 If the
  92 .Ar dev
  93 argument is specified,
  94 .Nm
  95 displays only the values for
  96 .Ar dev .
  97 More than one device may be specified.
  98 .Pp
  99 Commands use the following format:
 100 .Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent
 101 .It Sy Name Ta Sy Action
 102 .It Ar dev Ta Display all controls
 103 .It Ar dev Ns Cm \&. Ns Ar control Ta Display only the specified control
 104 .It Ar dev Ns Cm \&. Ns Ar control Ns Cm \&= Ns Ar value Ta Set control value
 105 .El
 106 .Pp
 107 The available controls are as follows (replace
 108 .Ar dev
 109 with one of the available devices):
 110 .Sm off
 111 .Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent
 112 .It Sy Name Ta Sy Value
 113 .It Ar dev Cm .volume Ta Xo
 114 .Ar vol |
 115 .Oo Cm \&+ | Cm \&- Oc Ar lvol
 116 .Oo Cm \&: Oo Cm \&+ | Cm \&- Oc Ar rvol Oc
 117 .Xc
 118 .It Ar dev Cm .mute Ta Cm 0 | 1 | ^
 119 .It Ar dev Cm .recsrc Ta Cm ^ | + | - | =
 120 .El
 121 .Sm on
 122 .Pp
 123 The
 124 .Ar dev Ns Cm .volume
 125 control modifies a device's volume.
 126 The optional
 127 .Ar lvol
 128 and/or
 129 .Ar rvol
 130 values have to be specified.
 131 The values have to be normalized 32-bit floats, from 0.0 to 1.0 inclusively.
 132 If no
 133 .Ql \&.
 134 character is present, the value is treated like a percentage, for backwards compatibility.
 135 If the left or right volume values are prefixed with
 136 .Cm +
 137 or
 138 .Cm - ,
 139 the value following will be used as a relative adjustment, modifying the
 140 current settings by the amount specified.
 141 .Pp
 142 Volume can also be set using the shorthand
 143 .Ar dev Ns Cm =value .
 144 This syntax does not apply to other controls.
 145 .Pp
 146 The
 147 .Ar dev Ns Cm .mute
 148 control (un)mutes a device.
 149 The following values are available:
 150 .Bl -tag -width = -offset indent
 151 .It Cm 0
 152 unmutes
 153 .Ar dev
 154 .It Cm 1
 155 mutes
 156 .Ar dev
 157 .It Cm ^
 158 toggles the mute of
 159 .Ar dev
 160 .El
 161 .Pp
 162 The
 163 .Ar dev Ns Cm .recsrc
 164 control modifies the recording sources of a mixer.
 165 .Nm
 166 marks devices which can be used as a recording source with
 167 .Sy rec .
 168 Recording sources are marked with
 169 .Sy src .
 170 To modify the recording source you can use one of the following modifiers
 171 on a
 172 .Sy rec
 173 device:
 174 .Bl -tag -width = -offset indent
 175 .It Cm ^
 176 toggles
 177 .Ar dev
 178 of possible recording devices
 179 .It Cm +
 180 adds
 181 .Ar dev
 182 to possible recording devices
 183 .It Cm -
 184 removes
 185 .Ar dev
 186 from possible recording devices
 187 .It Cm =
 188 sets the recording device to
 189 .Ar dev
 190 .El
 191 .Sh FILES
 192 .Bl -tag -width /dev/mixerN -compact
 193 .It Pa /dev/mixerN
 194 The mixer device, where
 195 .Ar N
 196 is the number of that device, for example
 197 .Ar /dev/mixer0 .
 198 PCM cards and mixers have a 1:1 relationship, which means that
 199 .Pa /dev/mixer0
 200 is the mixer for
 201 .Pa /dev/pcm0
 202 and so on.
 203 By default,
 204 .Nm
 205 prints both the audio card's number and the mixer associated with it
 206 in the form of
 207 .Ar pcmN:mixer .
 208 The
 209 .Pa /dev/mixer
 210 file, although it does not exist in the filesystem, points to the default
 211 mixer device and is the file
 212 .Nm
 213 opens when the
 214 .Fl f Ar device
 215 option has not been specified.
 216 .El
 217 .Sh EXAMPLES
 218 Change the volume for the
 219 .Cm vol
 220 device of the
 221 .Pa /dev/mixer0
 222 mixer device to 0.65:
 223 .Bd -literal -offset indent
 224 $ mixer -f /dev/mixer0 vol.volume=0.65
 225 .Ed
 226 .Pp
 227 Increase the
 228 .Cm mic
 229 device's left volume by 0.10 and decrease the right
 230 volume by 0.05:
 231 .Bd -literal -offset indent
 232 $ mixer mic.volume=+0.10:-0.05
 233 .Ed
 234 .Pp
 235 Toggle the mute for
 236 .Cm vol :
 237 .Bd -literal -offset indent
 238 $ mixer vol.mute=^
 239 .Ed
 240 .Pp
 241 Set
 242 .Cm mic
 243 and toggle
 244 .Cm line
 245 recording sources:
 246 .Bd -literal -offset indent
 247 $ mixer mic.recsrc=+ line.recsrc=^
 248 .Ed
 249 .Pp
 250 Dump
 251 .Pa /dev/mixer0
 252 information to a file and retrieve back later:
 253 .Bd -literal -offset indent
 254 $ mixer -f /dev/mixer0 -o > info
 255 \&...
 256 $ mixer -f /dev/mixer0 `cat info`
 257 .Ed
 258 .Sh SEE ALSO
 259 .Xr mixer 3 ,
 260 .Xr sound 4 ,
 261 .Xr sysctl 8
 262 .Sh HISTORY
 263 The
 264 .Nm
 265 utility first appeared in
 266 .Fx 2.0.5
 267 and was rewritten completely in
 268 .Fx 14.0 .
 269 .Sh AUTHORS
 270 .An Christos Margiolis Aq Mt christos@FreeBSD.org