Okay, so I've done the work on this, and I've decided that given
"mixerctl" was formerly Evolving (and unfortunately has name conflicts
with similar, yet different, programs from other FOSS), and that it
offers zero useful functionality in the Boomer era, that its best to
just EOF.
So, here is the new spec:
1) EOF mixerctl.
2) Deliver "audioctl" which provides full capabilities, as
/usr/bin/audioctl. The following man page has all the latest updates,
and accurately reflects the code (other than an undocumented "help"
command which only outputs a simple usage summary). Note that the
design of the interface is modeled somewhat loosely on dladm, zpool,
zoneadm, and other newer commands-that-have-subcommands:
User Commands audioctl(1)
NAME
audioctl - audio mixer control command line application
SYNOPSIS
audioctl list-devices
audioctl show-device [-v] [-d device ]
audioctl show-control [-v] [-d device] [control ...]
audioctl set-control [-v] [-d device] control value
audioctl save-controls [-d device] [-f] file
audioctl load-controls [-d device] file
DESCRIPTION
The audioctl command is used to control various features of
the audio mixer and to get information about the audio mixer
and the audio device.
The audioctl command operates on the following data types:
device
An audio device, such as "audiohd#0". The subcommands
that accept this do so as an argument to an option -d.
If not supplied, then the default audio device is assumed.
Any device node associated with an audio device will work
as well, such as /dev/sound/0, /dev/dsp1, or /dev/audio.
control
A mixer control name, such as "volume".
value
The value of a control. The specific format depends on
the type of control. Monophonic values usually use a single
whole number between 0 and 100, inclusive. Stereo values
use a pair of such numbers (representing right and left
channels.) Boolean values indicate either "on" or "off".
Enumerations take a single value of one or more names.
file
An ASCII text file of control settings.
Options:
Each subcommand has its own set of options that it takes.
However, some subcommands support the special flag -v, which
indicates a request for more verbose output.
SUBCOMMANDS
The following subcommands are supported:
audioctl list-devices
List all the audio devices on the system.
audioctl show-device [-v] [-d device]
Display general information about a device.
audioctl show-control [-v] [-d device] [control ...]
Display the control setting values for the device. The named
controls are displayed. If no control names are provided, then
all control values are displayed.
audioctl set-control [-v] [-d device] control value
Changes the value of a control to the supplied value.
audioctl save-controls [-f] [-d device] file
Saves the current state of all mixer control values to the named
file. The command will abort safely if the file already exists,
unless -f is supplied.
audioctl load-controls [-d device] file
Restores previously saved state in the named file for all mixer
controls.
ENVIRONMENT VARIABLES
AUDIODEV If the -d and -a options are not specified, the
AUDIODEV environment variable is consulted. If
set, AUDIODEV contains the full path name of the
user's default audio device.
FILES
/dev/audioctl /dev/sound/{0...n}ctl
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | SPARC, x86 |
|_____________________________|_____________________________|
| Availability | SUNWauda |
|_____________________________|_____________________________|
| Stability Level | See notes |
|_____________________________|_____________________________|
NOTES
The audioctl command and its subcommands are Committed.
The human readable output from this command is Not An Interface.
The device names, control names, and values are Uncommitted.
The format of the state files used by the save-controls and load-controls
subcommands is Committed Private.
SEE ALSO
audioconvert(1), audioplay(1), audiorecord(1), open(2),
attributes(5)
Garrett D'Amore wrote:
> Edward Pilatowicz wrote:
>> On Mon, Nov 16, 2009 at 11:02:34AM -0800, Garrett D'Amore wrote:
>>
>>> Edward Pilatowicz wrote:
>>>
>>>> so i assume that in the man page below you'll be doing
>>>> s/mixerctl/audioctl/. if that's the case then i wonder about the need
>>>> for AUDIODEV support. AUDIODEV normally points to SADA style audio
>>>> devices, right? but since your introducting a new audioctl tool,
>>>> shouldn't it be designed to work on boomer audio devices, not SADA
>>>> devices?
>>>>
>>> Yes, it should have the "s/mixerctl/audioctl/". I am going to have
>>> another set of updates, as since I've made changes to the code I've
>>> altered a few more things.
>>>
>>> As far as $AUDIODEV goes, the code actually will work with either a
>>> SADA device node or a Boomer node. The underlying code only
>>> operates on Boomer nodes, but it operates by finding the associated
>>> "mixer" device node for the device file you supply.
>>>
>>> So it will work to supply any of:
>>>
>>> /dev/audio
>>> /dev/audioctl
>>> /dev/sound/0
>>> /dev/dsp
>>> /dev/dsp1
>>> /dev/sound/audiohd:0
>>> /dev/sound/audiohd:0dsp
>>> /dev/sound/audiohd:0mixer
>>>
>>> The goal here is that end-users should not need to be aware of SADA
>>> vs. Boomer. Those are API details.
>>>
>>>
>>
>> ok. but for familiarity sake (since those are common to all OSS based
>> systems), and to facilitate any possible future removal of SADA
>> compatibility, shouldn't we only document the new boomer interfaces? in
>> this case the device path doesn't seem like an API detail. the user as
>> to set AUDIODEV to something.
>>
>> since mixerctl(1) is SADA specific and legacy, it's ok for it to talk
>> about /dev/audio* paths, but shouldn't any newish, non-legacy
>> documentation (say audioctl(1)) and apis always refer to boomer/oss
>> device paths? (note that i'm not talking about the implementation here,
>> just the documentation that end users see.)
>>
>> ed
>>
> One more thought: legacy Sun audio(7I) isn't going away. Its a
> committed interface. I'm not worried about keeping it around forever.
>
> SADA != Sun audio(7I).
>
> - Garrett
