diff options
Diffstat (limited to 'lib/libmixer/mixer.3')
| -rw-r--r-- | lib/libmixer/mixer.3 | 98 |
1 files changed, 68 insertions, 30 deletions
diff --git a/lib/libmixer/mixer.3 b/lib/libmixer/mixer.3 index e1969dfd3a7c..04aa3bd1dca7 100644 --- a/lib/libmixer/mixer.3 +++ b/lib/libmixer/mixer.3 @@ -19,10 +19,7 @@ .\" OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN .\" THE SOFTWARE. .\" -.\" $FreeBSD$ -.\" - -.Dd March 19, 2022 +.Dd August 4, 2024 .Dt MIXER 3 .Os .Sh NAME @@ -42,6 +39,7 @@ .Nm mixer_set_dunit , .Nm mixer_get_mode , .Nm mixer_get_nmixers , +.Nm mixer_get_path , .Nm MIX_ISDEV , .Nm MIX_ISMUTE , .Nm MIX_ISREC , @@ -88,6 +86,8 @@ Mixer library (libmixer, -lmixer) .Ft int .Fn mixer_get_nmixers "void" .Ft int +.Fn mixer_get_path "char * buf" "size_t size" "int unit" +.Ft int .Fn MIX_ISDEV "struct mixer *m" "int devno" .Ft int .Fn MIX_ISMUTE "struct mixer *m" "int devno" @@ -108,7 +108,7 @@ a simple way. A mixer is described by the following structure: .Bd -literal struct mixer { - TAILQ_HEAD(, mix_dev) devs; /* device list */ + TAILQ_HEAD(mix_devhead, mix_dev) devs; /* device list */ struct mix_dev *dev; /* selected device */ oss_mixerinfo mi; /* mixer info */ oss_card_info ci; /* audio card info */ @@ -167,13 +167,15 @@ 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. +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. +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 is very unlikely this mask will @@ -212,7 +214,7 @@ struct mix_dev { float right; /* right volume */ } vol; int nctl; /* number of controls */ - TAILQ_HEAD(, mix_ctl) ctls; /* control list */ + TAILQ_HEAD(mix_ctlhead, mix_ctl) ctls; /* control list */ TAILQ_ENTRY(mix_dev) devs; }; .Ed @@ -317,23 +319,27 @@ opens the default mixer (hw.snd.default_unit). The .Fn mixer_close function frees resources and closes the mixer device. -It is a good practice to always call it when the application is done using the mixer. +It is a good practice to always call it when the application is done using the +mixer. .Ss Manipulating the mixer 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 .Ar vol -parameter is a structure that stores the left and right volumes of a given device. +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 @@ -354,7 +360,8 @@ Toggle the device's mute (e.g mute if unmuted and unmute if muted). 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 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: @@ -381,23 +388,37 @@ 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: -.Bl -tag -width "MIX_STATUS_PLAY | MIX_STATUS_REC" -offset indent -.It Dv MIX_STATUS_NONE -Neither playback nor recording. -.It Dv MIX_STATUS_PLAY -Playback. -.It Dv MIX_STATUS_REC -Recording. -.It Dv MIX_STATUS_PLAY | MIX_STATUS_REC -Playback and recording. +function returns the operating mode of the audio device the mixer belongs to. +The following values can be OR'ed in case more than one mode is supported: +.Bl -tag -width "MIX_MODE_MIXER" -offset indent +.It Dv MIX_MODE_MIXER +The audio device has a mixer. +.It Dv MIX_MODE_PLAY +The audio device supports playback. +.It Dv MIX_MODE_REC +The audio device supports recording. .El .Pp The .Fn mixer_get_nmixers -function returns the total number of mixer devices in the system. +function returns the maximum mixer unit number. +Although this might sound as incorrect behavior, given that one would expect +"nmixers" to refer to the total number of active mixers, it is more intuitive +for applications that want to loop through all mixer devices (see the +.Sx EXAMPLES +section). +.Pp +The +.Fn mixer_get_path +function writes the path of the mixer device specified in the +.Ar unit +argument to the buffer specified in +.Ar buf . +.Ar unit +can be either -1, in which case +.Fn mixer_get_path +will fetch the path of the default mixer, or between 0 and the maximum mixer +unit. .Pp The .Fn MIX_ISDEV @@ -469,9 +490,10 @@ The .Fn mixer_set_mute , .Fn mixer_mod_recsrc , .Fn mixer_get_dunut , -.Fn mixer_set_dunit +.Fn mixer_set_dunit , +.Fn mixer_get_nmixers , and -.Fn mixer_get_nmixers +.Fn mixer_get_path functions return 0 or positive values on success and -1 on failure. .Pp The @@ -541,6 +563,22 @@ TAILQ_FOREACH(dp, &m->devs, devs) { (void)mixer_close(m); .Ed +.Ss Loop through all mixer devices in the system +.Bd -literal +struct mixer *m; +char buf[NAME_MAX]; +int n; + +if ((n = mixer_get_nmixers()) < 0) + errx(1, "no mixers present in the system"); +for (i = 0; i < n; i++) { + (void)mixer_get_path(buf, sizeof(buf), i); + if ((m = mixer_open(buf)) == NULL) + continue; + ... + (void)mixer_close(m); +} +.Ed .Sh SEE ALSO .Xr queue 3 , .Xr sysctl 3 , |