diff --git a/lib/libmixer/mixer.3 b/lib/libmixer/mixer.3 --- a/lib/libmixer/mixer.3 +++ b/lib/libmixer/mixer.3 @@ -21,8 +21,7 @@ .\" .\" $FreeBSD$ .\" - -.Dd September 22, 2021 +.Dd March 18, 2022 .Dt MIXER 3 .Os .Sh NAME @@ -40,7 +39,7 @@ .Nm mixer_mod_recsrc , .Nm mixer_get_dunit , .Nm mixer_set_dunit , -.Nm mixer_get_mode, +.Nm mixer_get_mode , .Nm mixer_get_nmixers , .Nm MIX_ISDEV , .Nm MIX_ISMUTE , @@ -64,7 +63,7 @@ .Ft int .Fn mixer_add_ctl "struct mix_dev *parent" "int id" "const char *name" \ "int (*mod)(struct mix_dev *d, void *p)" \ - "int (*print)(struct mix_dev *d, void *p) + "int (*print)(struct mix_dev *d, void *p)" .Ft int .Fn mixer_add_ctl_s "mix_ctl_t *ctl" .Ft int @@ -105,7 +104,6 @@ library allows userspace programs to access and manipulate OSS sound mixers in a simple way. .Ss Mixer -.Pp A mixer is described by the following structure: .Bd -literal struct mixer { @@ -141,16 +139,19 @@ .It Fa devs A tail queue structure containing all supported mixer devices. .It Fa dev -A pointer to the currently selected device. The device is one of the elements in +A pointer to the currently selected device. +The device is one of the elements in .Ar devs . .It Fa mi -OSS information about the mixer. Look at the definition of the +OSS information about the mixer. +Look at the definition of the .Ft oss_mixerinfo structure in .In sys/soundcard.h to see its fields. .It Fa ci -OSS audio card information. This structure is also defined in +OSS audio card information. +This structure is also defined in .In sys/soundcard.h . .It Fa name Path to the mixer (e.g /dev/mixer0). @@ -158,40 +159,43 @@ File descriptor returned when the mixer is opened in .Fn mixer_open . .It Fa unit -Audio card unit. Since each mixer device maps to a pcmX device, +Audio card unit. +Since each mixer device maps to a pcmX device, .Ar unit -is always equal to the number of that pcmX device. For example, if the audio -device's number is 0 (i.e pcm0), then +is always equal to the number of that pcmX device. +For example, if the audio device's number is 0 (i.e pcm0), then .Ar unit -is 0 as well. This number is useful when checking if the mixer's audio -card is the default one. +is 0 as well. +This number is useful when checking if the mixer's audio card is the default one. .It Fa ndev Number of devices in .Ar devs . .It Fa devmask -Bit mask containing all supported devices for the mixer. For example -if device 10 is supported, then the 10th bit in the mask will be set. By default, +Bit mask containing all supported devices for the mixer. +For example, if device 10 is supported, then the 10th bit in the mask will be set. +By default, .Fn mixer_open stores only the supported devices in devs, so it's very unlikely this mask will be needed. .It Fa mutemask -Bit mask containing all muted devices. The logic is the same as with +Bit mask containing all muted devices. +The logic is the same as with .Ar devmask . .It Fa recmask -Bit mask containing all recording devices. Again, same logic as with the -other masks. +Bit mask containing all recording devices. +Again, same logic as with the other masks. .It Fa recsrc -Bit mask containing all recording sources. Yes, same logic again. +Bit mask containing all recording sources. +Yes, same logic again. .It Fa mode -Bit mask containing the supported modes for this audio device. It holds the value -of the +Bit mask containing the supported modes for this audio device. +It holds the value of the .Ar dev.pcm.X.mode sysctl. .It Fa f_default Flag which tells whether the mixer's audio card is the default one. .El .Ss Mixer device -.Pp Each mixer device stored in a mixer is described as follows: .Bd -literal struct mix_dev { @@ -217,7 +221,8 @@ .It Fa parent_mixer Pointer to the mixer the device is attached to. .It Fa name -Device name given by the OSS API. Devices can have one of the following names: +Device name given by the OSS API. +Devices can have one of the following names: .Bd -ragged vol, bass, treble, synth, pcm, speaker, line, mic, cd, mix, pcm2, rec, igain, ogain, line1, line2, line3, dig1, dig2, dig3, @@ -229,10 +234,11 @@ This number is used to check against the masks defined in the .Ar mixer structure. -.It Fa left, right -Left and right-ear volumes. Although the OSS API stores volumes in integers from -0-100, we normalize them to 32-bit floating point numbers. However, the volumes -can be denormalized using the +.It Fa left right +Left and right-ear volumes. +Although the OSS API stores volumes in integers from 0-100, \ +we normalize them to 32-bit floating point numbers. +However, the volumes can be denormalized using the .Ar MIX_VOLDENORM macro if needed. .It Fa nctl @@ -241,9 +247,8 @@ A tail queue containing user-defined mixer controls. .El .Ss User-defined mixer controls -.Pp -Each mixer device can have user-defined controls. The control structure -is defined as follows: +Each mixer device can have user-defined controls. +The control structure is defined as follows: .Bd -literal struct mix_ctl { struct mix_dev *parent_dev; /* parent device */ @@ -260,41 +265,46 @@ .It Fa parent_dev Pointer to the device the control is attached to. .It Fa id -Control ID assigned by the caller. Even though the library will -report it, care has to be taken to not give a control the same ID in case -the caller has to choose controls using their ID. +Control ID assigned by the caller. +Even though the library will report it, care has to be taken to not give \ +a control the same ID in case the caller has to choose controls using their ID. .It Fa name -Control name. As with +Control name. +As with .Ar id , the caller has to make sure the same name is not used more than once. .It Fa mod -Function pointer to a control modification function. As in +Function pointer to a control modification function. +As in .Xr mixer 8 , -each mixer control's values can be modified. For example, if we have a -volume control, the +each mixer control's values can be modified. +For example, if we have a volume control, the .Ar mod function will be responsible for handling volume changes. .It Fa print Function pointer to a control print function. .El .Ss Opening and closing the mixer -.Pp The application must first call the .Fn mixer_open -function to obtain a handle to the device, which is used as an argument -in most other functions and macros. The parameter +function to obtain a handle to the device, which is used as an argument \ +in most other functions and macros. +The parameter .Ar name -specifies the path to the mixer. OSS mixers are stored under +specifies the path to the mixer. +OSS mixers are stored under .Ar /dev/mixerN where .Ar N -is the number of the mixer device. Each device maps to an actual +is the number of the mixer device. +Each device maps to an actual .Ar pcm audio card, so .Ar /dev/mixer0 is the mixer for .Ar pcm0 , -and so on. If +and so on. +If .Ar name is .Ar NULL @@ -305,30 +315,30 @@ .Pp The .Fn mixer_close -function frees resources and closes the mixer device. It's a good practice to -always call it when the application is done using the mixer. +function frees resources and closes the mixer device. +It's a good practice to always call it when the application is done using the mixer. .Ss Manipulating the mixer -.Pp The .Fn mixer_get_dev and .Fn mixer_get_dev_byname -functions select a mixer device, either by its number or by its name -respectively. The mixer structure keeps a list of all the devices, but only -one can be manipulated at a time. Each time a new device is to be manipulated, -one of the two functions has to be called. +functions select a mixer device, either by its number or by its name respectively. +The mixer structure keeps a list of all the devices, but only \ +one can be manipulated at a time. +Each time a new device is to be manipulated, one of the two functions has to be called. .Pp The .Fn mixer_set_vol -function changes the volume of the selected mixer device. The +function changes the volume of the selected mixer device. +The .Ar vol -parameter is a structure that stores the left and right volumes of a given -device. The allowed volume values are between MIX_VOLMIN (0.0) and -MIX_VOLMAX (1.0). +parameter is a structure that stores the left and right volumes of a given device. +The allowed volume values are between MIX_VOLMIN (0.0) and MIX_VOLMAX (1.0). .Pp The .Fn mixer_set_mute -function modifies the mute of a selected device. The +function modifies the mute of a selected device. +The .Ar opt parameter has to be one of the following options: .Bl -tag -width MIX_TOGGLEMUTE -offset indent @@ -342,8 +352,9 @@ .Pp The .Fn mixer_mod_recsrc -function modifies a recording device. The selected device has to be -a recording device, otherwise the function will fail. The +function modifies a recording device. +The selected device has to be a recording device, otherwise the function will fail. +The .Ar opt parameter has to be one of the following options: .Bl -tag -width MIX_REMOVERECSRC -offset indent @@ -361,16 +372,17 @@ .Fn mixer_get_dunit and .Fn mixer_set_dunit -functions get and set the default audio card in the system. Although this is -not really a mixer feature, it's useful to have instead of having to use -the +functions get and set the default audio card in the system. +Although this is not really a mixer feature, it's useful to have instead of \ +having to use the .Xr sysctl 3 controls. .Pp The .Fn mixer_get_mode -function returns the playback/recording mode of the audio device the mixer -belongs to. The available values are the following: +function returns the playback/recording mode of the audio device the mixer \ +belongs to. +The available values are the following: .Bl -tag -width "MIX_STATUS_PLAY | MIX_STATUS_REC" -offset indent .It Dv MIX_STATUS_NONE Neither playback nor recording. @@ -388,9 +400,9 @@ .Pp The .Fn MIX_ISDEV -macro checks if a device is actually a valid device for a given mixer. It's very -unlikely that this macro will ever be needed since the library stores only -valid devices by default. +macro checks if a device is actually a valid device for a given mixer. +It's very unlikely that this macro will ever be needed since the library \ +stores only valid devices by default. .Pp The .Fn MIX_ISMUTE @@ -406,8 +418,8 @@ .Pp The .Fn MIX_VOLNORM -macro normalizes a value to 32-bit floating point number. It's used -to normalize the volumes read from the OSS API. +macro normalizes a value to 32-bit floating point number. +It's used to normalize the volumes read from the OSS API. .Pp The .Fn MIX_VOLDENORM @@ -415,7 +427,6 @@ .Ft mix_dev structure. .Ss Defining and using mixer controls -.Pp The .Fn mix_add_ctl function creates a control and attaches it to the device specified in the @@ -438,7 +449,8 @@ .Fn mixer_get_ctl function searches for a control in the device specified in the .Ar d -argument and returns a pointer to it. The search is done using the control's ID. +argument and returns a pointer to it. +The search is done using the control's ID. .Pp The .Fn mixer_get_ctl_byname @@ -446,7 +458,6 @@ .Fn mixer_get_ctl but the search is done using the control's name. .Sh RETURN VALUES -.Pp The .Fn mixer_open function returns the newly created handle on success and NULL on failure. @@ -530,10 +541,10 @@ (void)mixer_close(m); .Ed .Sh SEE ALSO -.Xr mixer 8 , -.Xr sound 4 , +.Xr queue 3 , .Xr sysctl 3 , -.Xr queue 3 +.Xr sound 4 , +.Xr mixer 8 and .Xr errno 2 .Sh AUTHORS diff --git a/usr.sbin/mixer/mixer.8 b/usr.sbin/mixer/mixer.8 --- a/usr.sbin/mixer/mixer.8 +++ b/usr.sbin/mixer/mixer.8 @@ -21,7 +21,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 13, 2022 +.Dd March 18, 2022 .Dt MIXER 8 .Os .Sh NAME @@ -32,7 +32,7 @@ .Op Fl f Ar device .Op Fl d Ar unit .Op Fl os -.Op Ar dev Ns Op Cm \&. Ns Ar control Ns Op Cm \&= Ns Ar value +.Op Ar dev Ns Op . Ns Ar control Ns Op = Ns Ar value .Ar ... .Nm .Op Fl d Ar unit @@ -48,22 +48,19 @@ The options are as follows: .Bl -tag -width "-f device" .It Fl a -Print the values for all mixer devices available in the system -.Pq see Sx FILES . +Print the values for all mixer devices available in the system (see FILES). .It Fl d Ar unit Change the default audio card to .Ar unit . The unit has to be an integer value. -To see what unit values are available, look -at the number each mixer device has by running +To see what unit values are available, look at the number each mixer device has by running .Nm . .It Fl f Ar device Open .Ar device -as the mixer device -.Pq see Sx FILES . +as the mixer device (see FILES). .It Fl h -Print a help message. +Print a help message to stderr. .It Fl o Print mixer values in a format suitable for use inside scripts. The mixer's header (name, audio card name, ...) will not be printed. @@ -73,14 +70,9 @@ .Pp The list of mixer devices that may be modified are: .Bd -ragged -offset indent -.Cm vol , bass , treble , synth , pcm , speaker , line , mic , cd , mix , -.Cm pcm2 , rec , -.Cm igain , ogain , -.Cm line1 , line2 , line3 , -.Cm dig1 , dig2 , dig3 , -.Cm phin , phout , video , radio , -and -.Cm monitor . +vol, bass, treble, synth, pcm, speaker, line, mic, cd, mix, +pcm2, rec, igain, ogain, line1, line2, line3, dig1, dig2, dig3, +phin, phout, video, radio, and monitor. .Ed .Pp Not all mixer devices are available. @@ -99,43 +91,33 @@ .Pp Commands use the following format: .Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent -.It Sy Name Ta Sy Action -.It Ar dev Ta Display all controls -.It Ar dev Ns Cm \&. Ns Ar control Ta Display only the specified control -.It Ar dev Ns Cm \&. Ns Ar control Ns Cm \&= Ns Ar value Ta Set control value +.It Sy "Name Action" +.It "dev Display all controls" +.It "dev.control Display only the specified control" +.It "dev.control=value Set control value" .El .Pp The available controls are as follows (replace .Ar dev with one of the available devices): -.Sm off .Bl -column xxxxxxxxxxxxxxxxxxxxxxxx -offset indent -.It Sy Name Ta Sy Value -.It Ar dev Cm .volume Ta Xo -.Ar vol | -.Oo Cm \&+ | Cm \&- Oc Ar lvol -.Oo Cm \&: Oo Cm \&+ | Cm \&- Oc Ar rvol Oc -.Xc -.It Ar dev Cm .mute Ta Cm 0 | 1 | ^ -.It Ar dev Cm .recsrc Ta Cm ^ | + | - | = +.It Sy "Name Value" +.It "dev.volume [[+|-]lvol[:[+|-]rvol]]" +.It "dev.mute {0|1|^}" +.It "dev.recsrc {+|-|^|=}" .El -.Sm on .Pp The -.Ar dev Ns Cm .volume +.Ar dev.volume control modifies a device's volume. The optional .Ar lvol and/or .Ar rvol values have to be specified. -The values have to be normalized 32-bit floats, -from 0.0 to 1.0 inclusivly. -If no -.Ql \&. -character is present, the value is treated -like a percentage, for backwards compatibility. -If the left or right volume values are prefixed with +The values have to be normalized 32-bit floats, from 0.0 to 1.0 inclusivly. +If no "." character is present, the value is treated like a percentage, for backwards compatibility. +If the the left or right volume values are prefixed with .Cm + or .Cm - , @@ -143,32 +125,32 @@ current settings by the amount specified. .Pp The -.Ar dev Ns Cm .mute +.Ar dev.mute control (un)mutes a device. The following values are available: .Bl -tag -width = -offset indent .It Cm 0 unmutes -.Ar dev +.Ar dev . .It Cm 1 mutes -.Ar dev +.Ar dev . .It Cm ^ toggles the mute of -.Ar dev +.Ar dev . .El .Pp The -.Ar dev Ns Cm .recsrc +.Ar dev.recsrc control modifies the recording sources of a mixer. .Nm marks devices which can be used as a recording source with -.Sy rec . +.Ar rec . Recording sources are marked with -.Sy src . +.Ar src . To modify the recording source you can use one of the following modifiers on a -.Sy rec +.Ar rec device: .Bl -tag -width = -offset indent .It Cm ^ @@ -195,9 +177,9 @@ is the number of that device, for example .Ar /dev/mixer0 . PCM cards and mixers have a 1:1 relationship, which means that -.Pa /dev/mixer0 +.Ar mixer0 is the mixer for -.Pa /dev/pcm0 +.Ar pcm0 and so on. By default, .Nm @@ -205,8 +187,8 @@ in the form of .Ar pcmN:mixer . The -.Pa /dev/mixer -file, although it does not exist in the filesystem, points to the default +.Ar /dev/mixer +file, although it doesn't exist in the filesystem, points to the default mixer device and is the file .Nm opens when the @@ -215,45 +197,45 @@ .El .Sh EXAMPLES Change the volume for the -.Cm vol +.Ar vol device of the -.Pa /dev/mixer0 +.Ar /dev/mixer0 mixer device to 0.65: -.Bd -literal -offset indent -$ mixer -f /dev/mixer0 vol.volume=0.65 -.Ed +.Bl -tag -width Ds -offset indent +.It $ mixer -f /dev/mixer0 vol.volume=0.65 +.El .Pp Increase the -.Cm mic +.Ar mic device's left volume by 0.10 and decrease the right volume by 0.05: -.Bd -literal -offset indent -$ mixer mic.volume=+0.10:-0.05 -.Ed +.Bl -tag -width Ds -offset indent +.It $ mixer mic.volume=+0.10:-0.05 +.El .Pp Toggle the mute for -.Cm vol : -.Bd -literal -offset indent -$ mixer vol.mute=^ -.Ed +.Ar vol : +.Bl -tag -width Ds -offset indent +.It $ mixer vol.mute=^ +.El .Pp Set -.Cm mic +.Ar mic and toggle -.Cm line +.Ar line recording sources: -.Bd -literal -offset indent -$ mixer mic.recsrc=+ line.recsrc=^ -.Ed +.Bl -tag -width Ds -offset indent +.It $ mixer mic.recsrc=+ line.recsrc=^ +.El .Pp Dump -.Pa /dev/mixer0 -information to a file and retrieve back later: -.Bd -literal -offset indent -$ mixer -f /dev/mixer0 -o > info -\&... -$ mixer -f /dev/mixer0 `cat info` -.Ed +.Ar /dev/mixer0 +information to a file and retrieve back later +.Bl -tag -width Ds -offset indent +.It $ mixer -f /dev/mixer0 -o > info +.It ... +.It $ mixer -f /dev/mixer0 `cat info` +.El .Sh SEE ALSO .Xr mixer 3 , .Xr sound 4 ,