mixer

FreeBSD OSS mixer library implementation and a complete rewrite of mixer(8)
git clone git://git.margiolis.net/mixer.git
Log | Files | Refs | README | LICENSE

mixer.8 (6369B)


      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 18, 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