NAME
gom - a generic audio mixer (supports: OSS and derivatives)
SYNOPSIS
gom {OPTION}
VERSION
This manual page was distributed with gom 0.30.2 (31 May 2004).
DESCRIPTION
gom is a command line mixer manipulation program including a minimal,
yet fully functional internal ineractive text based interface.
Currently, there is also an internal X (xview) interface, but it’s not
well maintained and will eventually be removed when a proper
alternative is available.
At the moment, gom only supports the Open Sound System (OSS) and its
derivatives (OSS/Lite, OSS/Free (these two are obviously obsolete), the
new Linux Sounddriver, ...).
gom tries to provide a complete and convenient interface for all kind
of audio mixer manipulation. gom’s facilities include sound driver
(compile time) and sound card (run time) independence, arbitrary mixer
selection, loading and saving of mixer settings, volume fading,
verbosity-level driven output, "Un*x-like scripting support", etc.
Apart from the exhaustive command line interface described here, gom
has a built-in interactive terminal interface (that I call gomii, gom
interactive interface) using ncurses. It supports adjustable (this
includes disabling) real time updating. The gomii is not explained in
this manual page; please refer to the specific online help when using
it. However, the gomii’s handling should be obvious, and actually it
"tries to resemble" the command line options.
There is also one more gomii for X using the xview toolkit. However,
gom needs to be especially compiled to include this, and it is intended
to be replaced eventually by some frontend for X using the gom binary.
And remember: gom is spelled g-o-m, but pronounced backwards for
compatibility reasons. Its real, actual and recursive title is gom, GOM
is nOt yet another Mixer (for reasons beyond the scope of this manual).
CONFIGURING GOM
There is no mandatory configuration for gom; it runs fine just as it
is, without any configuration. I.e., for senseful use without
configuration, one always needs to (at least) specify the mixer to use.
For example:
gom --device=/dev/mixer2 --mute-all
However, you can configure gom a) for the system and b) for an
individual user; each user configuration is preferred in favor of the
corresponding system configuration. In fact, the routine for loading
_any_ option file is to 1st try the user file, then the system file,
and else fail.
To configure, you should use the script gomconfig(8) (or most likely
gomconfig --force ) that comes with the distribution -- using it as
root will change the system configuration, normal users will change
their own configuration. You may well skip the rest of this chapter if
you do so.
All configuration files for gom are simply gatherings of command line
options to gom (where some files are restricted to certain options).
Please see "--get-options" below.
The configuration files are (replace the "~/.gom" with "/etc/gom" for
the system configuration):
~/.gom/conf.default_mixer
Loaded on every startup of gom. Restricted to: "-d". Provides
implicit opening of a mixer device.
~/.gom/conf.initialize
Loaded with the option ’-O, --originate, --initialize’.
Unrestricted. Provides creation of an initialization routine,
even for multiple mixers.
~/.gom/conf.gom
Loaded on every startup of gom. Restricted to ’-v, -q, -F, -U’.
Provides implicit creation of certain bevaviours. Discouraged.
~/.gom/<mixer-device>.<name>
These file are accessed simply by their <name> when <mixer-
device> is opened. See --get-options below.
TERMINOLOGY, PHILOSOPHY
A mixer is a set of channels (e.g. vol, line, cd). Each channel has a
set of volume channels (e.g. left, right), and optionally a recording
source flag.
The evaluation which channels are available, and, for an available
channel, which volume channels and which flags are available on that
specific channel, is being done at runtime; this is sound card, and
possibly sound driver dependent.
Thus, there are sound driver supported channels and specific sound card
supported channels. gom --info-all shows all sound driver supported
channels, plus indicating their specific availability.
Up to the time of this writing, the only sound driver supported is OSS
(Open Sound System) and its derivatives. This driver exists for a
variety of platforms and in various flavours (especially, the new
Sounddriver of Linux is a derivative of OSS). (Remark: Gom’s point of
view on how a "generic" mixer should look like may be strongly
influenced by the OSS API; however, the author feels that this view
might not (yet) be absolutely generic). At the time of this writing,
OSS supports 17 channels, and a maximum of two volume channels per
channel (i.e., only "mono" or "stereo").
Of course, as gom depends on the sound driver installed on the system,
its proper installation (which is naturally not covered here) is
mandatory for gom (as for any other sound-using program).
OPTIONS
Options can be given in arbitrary order or amount; they are computed in
sequence from left to right. Default values (if any), are given in [].
For boolean arguments, "1" means on, "0" means off.
Note that for options with _optional_ arguments, these must be gi ven
like "gom -G<file>" (or "gom --get-settings=<file>" resp.) ra ther than
"gom -G <file>" (or "gom --get-settings <file>" resp.). Otherwise,
they will be ignored (or, at least with my implementat ion of getopt;).
Configuring options:
-d, --device, --mixer <argument>
[ **no mixer** ] Set mixer special device file to <argument>.
If the new mixer is valid, the current mixer --if any-- will be
closed and the new mixer opened. Current channel, current
channel volume, the channel lock setting and the snapshot will
be resetted to defaults.
-c, --channel <argument>
[first available channel] Set current mixer channel to <argum
ent>. The channel may be given as number or as name.
-C, --volume-channel <argument>
[first available volume channel on current channel] Set volum e
channel on current mixer channel to <argument> (e.g., for s
tereo, 0 means left, 1 means right volume).
-k, --lock <argument>
-K, --lock-all <argument>
[1] Lock or unlock current or all channel(s). Locking means s
yncing of the stereo volumes (balance) for all volume setting s
gom might do -- this doesn’t change any volume settings by
itself (i.e., it doesn’t auto-balance). Thus, a locked channe l
might have unbalanced volumes.
-F, --fade-interval <argument>
[5] Set fade interval to <argument> seconds. See --fade-to-lo
udness.
-U, --refresh-interval <argument>
[30] Set gomii refresh (update) interval to <argument> second s
(zero disables).
-W, --write-config, --save-config
This option is obsolete since version 0.29.10.
Setting mixer options:
-l, --loudness, --volume <argument>
Set current volume channel on current channel to <argument>. If
the argument is being given with a leading "+" or "-", the given
value will be added or substracted, respectively, from the
current value. The allowed range is from zero up to a sou ndcard
driver dependent maximum.
-r, --record <argument>
Set recording for current channel on or off.
-R, --record-single
Set recording for current channel on and disable all other re
cording sources.
-L, --fade-to-loudness, --fade-to-volume <argument>
Like --loudness, but fade to the new volume within a time giv en
with --fade-interval.
-m, --mute
-M, --mute-all
Mute current or all channels. Muting means setting all channe l
volumes to 0.
Mixer settings options:
-G, --get-options, --load-options, --get-settings, --load-setting
Get options from/to file <argument>. If no argument is given,
the default file (named "default") is used. Non-absolut given
filenames will be expanded to "<mixer-device>.<argument>", and
then first searched for in the user and -- if this fails -- in
the system configuration directory. Any free-form files with gom
one-character command line options in any lines starting with a
dash (in column zero) will make sense to this option.
-S, --save-settings [<argument>]
Save mixer settings to a free-form option file; for the file
name, the same rules as for loading option files apply, except
that only the user configuration dir will be used. Files with
thusly expanded filenames will be silently overwritten; other
files never. When saving, care is being taken that the "last
recording source error" can’t occur when loading these options
(and maybe there are other reasonable side effects apart from
the pure mixer settings (e.g. channel locking, current
channel)). The bottom line to these load/save options is that
you can easily save new and load predefined mixer settings from
anywhere.
-z, --snapshot-settings
-Z, --unsnapshot-settings, --restore-settings
[mixer settings after opening a new mixer] Snap- or unsnapsho t
to/from current mixer settings.
-O, --originate, --initialize
Load the options file "initialize"; all options are allowed in
this file. This is meant to initialize mixers. For example:
"-d/dev/mixer0 -G -d/dev/mixer1 -G". This would load the default
settings file for both the mixer0 and the mixer1 device.
Informational options:
-t, --info
Display current channel information.
-T, --info-all
Display overall information.
-V, --version
Display version information.
-w, --copyright, --copyleft, --license, --warranty
Display copyright/license/warranty information.
-h, --help
-H, --help-verbose
Display this help normally or verbose; both helps are still d
ependent on the current verbosity level (i.e., higher verbosi ty
levels might still show more; "gom -v0 -H" and "gom -h" pr oduce
the same output). For the normal verbosity level, these are
reasonable macros.
Special options:
-e, --execute <argument>
Execute the shell command <argument>.
Command line only options:
-Y, --ignore-config
Skip all automatically loaded configurations files; this must be
given before any other option (except q (quiet) or v (verbose)).
-i, --interface, --gomii <argument>
Explicitly start up a build-in gomii (<argument>=t: terminal
gomii, <argument>=x: X gomii).
-v, --verbose [<argument>]
[NORMAL] Set output verbosity to <argument> (number, the high
er, the more verbose). If no argument is given, the level will
be increased by 1.
-q, --quiet, --silent
Set output verbosity to QUIET (only error / error help messag
es).
-p, --pure, --print <argument>
Pure-print the current channels value given by <argument> to
stdout (<argument>=l|r, according to one character options).
Useful for getting values "into" scripts together with the --
quiet option.
-x, --extract-settings
Extract all mixer settings as a gom option line to stdout (e.
g. for "setting=‘gom --quiet --extract-settings‘" and "gom --
quiet $settings" later in a bash script).
-I, --read-stdin
Read options from stdin (until EOF).
ENVIRONMENT
HOME used as prefix for the configuration directory .gom/ for a non-
root user.
FILES
/etc/gom/ system configuration directory (user root).
$HOME/.gom/ user configuration dir (all non-root users).
Files inside the configuration directory:
conf.default_mixer option file for default mixer (loaded on startup).
conf.gom option file (loaded on startup).
conf.initialize option file for initialization (loaded via
--initialize).
<mixer-device>.default default options file for <mixer-device> (loaded
with --get-options).
<mixer-device>.<name> mixer settings that can be easily accessed just
by <name>
with --get-options=<name> when <mixer-device> is open."
DIAGNOSTICS
Exit status is 0 if no errors were detected while running gom; it is
greater than 0 if one or more errors were detected. This should be
interpreted as warning, not necessarily as failure.
(The amount of detected errors will be printed out if the verbosity
level is VERBOSE or higher; the warning exit status is currently always
2, but this may change).
EXAMPLES
(This section is incomplete and most likely confusing ;).
1. gom as system startup
2. gom as user startup
3. gom in a running session
4. gom in scripts
5. Some more detailed examples
gom --interface=t, gom -it
Interactively manipulate mixer settings with the terminal gomii.
gom --get-settings, gom -G
(e.g. when you log in as user). Loads user’s default options
file.
gom --get-settings=cd, gom -Gcd
Loads options file "cd" (most likely a setting for playing cds).
gom -d/dev/mixer0 -M -d/dev/mixer1 -l100
First, mute mixer 0, then set the volume of the first channel on
mixer 1 to 100.
gom -M -c vol -l 90 -c pcm -l 90 -e bplay super.voc -Z
Plays the sample super.voc on channel 4=pcm with all other
channels muted, restoring original mixer settings afterwards.
gom -ix -e <any_sound_player> -Z
Plays any sound, interactively setting the mixer before with the
X gomii and restoring settings afterwards.
AUTHOR
Copyright (c) 1996-2004 Stephan Alexander Sürken <absurd@olurdix.de>
GPL.
The X gomii of the gom package is also Copyright (c) Hannu Savolainen
1993 (as it is originally based on "xvmixer" by Hannu Savolainen).
The gom package is licensed under the GPL (GNU General Public License).
The files "README" and "COPYING" in the original distribution contain
the exact terms.
SEE ALSO
gomconfig(8)
Information about OSS can currently (1999 August 18) be found at
"http://www.opensound.com/".
KNOWN BUGS
Gom does not detect recursion in option files (e.g. by adding a "-Gcd"
to an options file named "cd").
There must always be at least one recording source, so when writing
option files for gom "by hand", first put all to-be-active recording
sources on, then all to-be-inactive recording sources off, else one
recording source might not become inactive in unfortunate
circumstances. Mixer settings automatically written by gom are saved in
this manner.
The mixer settings files may be inconsistent between different sound
drivers (i.e., if the channel numbering is different).
Loading settings from a options file that was saved from a different
mixer may lead to errors (if some option is not available on the
current mixer), or to silently not-setting of newly available options
of the current mixer; saving mixer settings with the mixer name as
prefix since 0.29.99 avoids this at least for not explicitly given
mixer settings file names.
The "text blocking output" cuts words (true, too, for the OPTIONS
section of this manual page).
X gomii bugs:
The X gomii has some "bugs" due to xview and/or the lack of
documentation available for the author (all the rest of this section):
The X gomii creates its display objects with xview, but doesn’t check
for allocation errors. I guess xview somehow handles this ;).
The X gomii’s scroll window displays in a non-fixed font.
Some placements in the X gomii are still static; it could imagine that
the display might look a little bit screwed up if you use a different
configuration than mine (e.g. a different font).
Xview, in general, "seems to be a little bit unstable" (the author
itself locked all his major input devices (i.e., mouse & keyboard (you
should be so clever to have some other means to access your computer
when programming xview ;)) several times by using xview applications
under X (not necessarily the X gomii) for whatever unknown reasons (and
without being able to reproduce the bug properly). (()())
KNOWINGLY NO BUGS
If starting gom results in loading and initializing the kernel sound
driver (e.g. if the sound driver gets kerneld-autoloaded under Linux),
the sound card’s settings are set to the driver’s default by the driver
itself. gom has nothing to do with these defaults and doesn’t change
any settings -- any program using the sound driver in that situation
would have the same effect.