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 April 29, 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 Oo % Oc
 116 .Oo Cm \&: Oo Cm \&+ | Cm \&- Oc Ar rvol Oo % Oc 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 should typically be decimal numbers between 0 and 1 with at most 2
 132 digits after the decimal point.
 133 A trailing percent sign indicates that the value should be treated as a
 134 percentage of 1.0, rather than an absolute value.
 135 Thus, 70% means the same as 0.7.
 136 If the left or right volume values are prefixed with
 137 .Cm +
 138 or
 139 .Cm - ,
 140 the value following will be used as a relative adjustment, modifying the
 141 current settings by the amount specified.
 142 Note that relative percentages are still relative to 1.0, not to the current
 143 value.
 144 If the volume is currently 0.40 and an adjustment of +20% is specified, then
 145 thet final volume will be set to 0.60.
 146 .Pp
 147 Volume can also be set using the shorthand
 148 .Ar dev Ns Cm =value .
 149 This syntax does not apply to other controls.
 150 .Pp
 151 The
 152 .Ar dev Ns Cm .mute
 153 control (un)mutes a device.
 154 The following values are available:
 155 .Bl -tag -width = -offset indent
 156 .It Cm 0
 157 unmutes
 158 .Ar dev
 159 .It Cm 1
 160 mutes
 161 .Ar dev
 162 .It Cm ^
 163 toggles the mute of
 164 .Ar dev
 165 .El
 166 .Pp
 167 The
 168 .Ar dev Ns Cm .recsrc
 169 control modifies the recording sources of a mixer.
 170 .Nm
 171 marks devices which can be used as a recording source with
 172 .Sy rec .
 173 Recording sources are marked with
 174 .Sy src .
 175 To modify the recording source you can use one of the following modifiers
 176 on a
 177 .Sy rec
 178 device:
 179 .Bl -tag -width = -offset indent
 180 .It Cm ^
 181 toggles
 182 .Ar dev
 183 of possible recording devices
 184 .It Cm +
 185 adds
 186 .Ar dev
 187 to possible recording devices
 188 .It Cm -
 189 removes
 190 .Ar dev
 191 from possible recording devices
 192 .It Cm =
 193 sets the recording device to
 194 .Ar dev
 195 .El
 196 .Sh FILES
 197 .Bl -tag -width /dev/mixerN -compact
 198 .It Pa /dev/mixerN
 199 The mixer device, where
 200 .Ar N
 201 is the number of that device, for example
 202 .Ar /dev/mixer0 .
 203 PCM cards and mixers have a 1:1 relationship, which means that
 204 .Pa /dev/mixer0
 205 is the mixer for
 206 .Pa /dev/pcm0
 207 and so on.
 208 By default,
 209 .Nm
 210 prints both the audio card's number and the mixer associated with it
 211 in the form of
 212 .Ar pcmN:mixer .
 213 The
 214 .Pa /dev/mixer
 215 file, although it does not exist in the filesystem, points to the default
 216 mixer device and is the file
 217 .Nm
 218 opens when the
 219 .Fl f Ar device
 220 option has not been specified.
 221 .El
 222 .Sh EXAMPLES
 223 Change the volume for the
 224 .Cm vol
 225 device of the
 226 .Pa /dev/mixer0
 227 mixer device to 0.65:
 228 .Bd -literal -offset indent
 229 $ mixer -f /dev/mixer0 vol.volume=0.65
 230 .Ed
 231 .Pp
 232 Increase the
 233 .Cm mic
 234 device's left volume by 0.10 and decrease the right
 235 volume by 0.05:
 236 .Bd -literal -offset indent
 237 $ mixer mic.volume=+0.10:-0.05
 238 .Ed
 239 .Pp
 240 Toggle the mute for
 241 .Cm vol :
 242 .Bd -literal -offset indent
 243 $ mixer vol.mute=^
 244 .Ed
 245 .Pp
 246 Set
 247 .Cm mic
 248 and toggle
 249 .Cm line
 250 recording sources:
 251 .Bd -literal -offset indent
 252 $ mixer mic.recsrc=+ line.recsrc=^
 253 .Ed
 254 .Pp
 255 Dump
 256 .Pa /dev/mixer0
 257 information to a file and retrieve back later:
 258 .Bd -literal -offset indent
 259 $ mixer -f /dev/mixer0 -o > info
 260 \&...
 261 $ mixer -f /dev/mixer0 `cat info`
 262 .Ed
 263 .Sh SEE ALSO
 264 .Xr mixer 3 ,
 265 .Xr sound 4 ,
 266 .Xr sysctl 8
 267 .Sh HISTORY
 268 The
 269 .Nm
 270 utility first appeared in
 271 .Fx 2.0.5
 272 and was rewritten completely in
 273 .Fx 14.0 .
 274 .Sh AUTHORS
 275 .An Christos Margiolis Aq Mt christos@FreeBSD.org