.\"
.\" Copyright (c) 1996, 1997 Stephan Alexander Suerken <absurd@debian.org>
.\"
.TH GOM 1 "1997 Sep 23" "3rd party" "Contributed tool"
.SH NAME
gom \- a generic audio mixer (supports: OSS)
.br
.SH SYNOPSIS
.BI "gom {OPTION}"
.br
.SH DESCRIPTION
.LP

.BR "" "This manual page describes " "gom 0.29.10" " (1997 Sep 23), "
a generic audio mixer program; it 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.

At the moment, gom only supports the Open Sound System (OSS) sound
driver. OSS comes with the Linux kernel as free software called
OSS/Free, and is available for a number of other platforms.

Apart from the exhaustive command line interface described here, gom
optionally has two built-in interactive interfaces (that I call
gomiis, gom interactive interfaces;): a terminal gomii using ncurses,
and a X gomii using the xview toolkit.  All gomiis support adjustable
(this includes disabling) real time updating. The gomiis are not
explained in this manual page; please refer to the specific online
help when using one of these gomiis. However, the gomiis handling
should be obvious, and actually they "try to resemble" the command
line options. Furthermore,
.B gom
might be compiled leaving out some or all gomiis.

And remember: gom is spelled g-o-m, but pronounced backwards for
compatibility reasons. Its real, actual and recursive title is
.B gom, GOM is nOt yet another Mixer
(for reasons beyond the scope of this manual).

.br
.SH CONFIGURING GOM

There is
.B 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, whenever gom is started up, it will try to "configure" itself
thusly: gom loads _either_ the user's (~/.gom/gomrc) or the system's
configuration file (/etc/gom/gomrc). The latter is used only if the
user config does not exist; if both do not exist, then there is no
configuration for gom -- which is perfectly normal. To correct
errors, please create and/or change your user's config file.

"gomrc-Files" are simply gatherings of command line options to gom.
Please see "--get-options" below.

For a normal user, I would recommend the following steps:

1. Create a directory ".gom" in your $HOME. Without it, you can't
create a user configuration file, and you can't easily save and load
mixer settings.

2. Create a user configuration file. The configuration file -- as well
as the settings files that you can automatically save with gom -- are
"free-form" files; all lines starting with '-' are treated as if they
were command line options to gom, other lines are ignored.  The
options in this file are simply read on every startup of gom.

Thus, a recommended, minimal "user installation" would be:

.br 
$ mkdir ~/.gom
.br
$ echo "-d<your_mixer_device>" >~/.gom/gomrc"
.br

As of version 0.29.10, configuration will be checked if gom
is called without arguments.

.SH 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 availabel, 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.
.B 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). This driver exists for a variety of
platforms (especially, it is part of the Linux kernel as free
software called OSS/Free). (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
(and can't be) covered by this man page;) is a necessity for
using gom.

.br
.SH OPTIONS

Options can be given in arbitrary order or amount; they are compu
ted in sequence from left to right. Default values (if any), are 
given in []. It might be sane to restrict the options in the conf
iguration file to those marked here as "configuration options". F
or 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;).

If no options are given, gom will perform a configuration test.

.TP
Configuring options:
.TP
.B -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 wil l be resetted to
defaults. If this is the _very_first_ given option, gom has a
_special_ startup behaviour: when loading t he configuration file,
this option -- if given there -- is _i gnored_ (for the user, this
normally has no visual effect, bu t this avoids loading the device
twice, or may avoid trying a bogus device from the config if you
somehow can't change it).
.TP
.B -c, --channel <argument>
[first available channel] Set current mixer channel to <argum
ent>. The channel may be given as number or as name.
.TP
.B -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).
.TP
.B -k, --lock <argument>
.TP
.B -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.
.TP
.B -F, --fade-interval <argument>
[5] Set fade interval to <argument> seconds. See --fade-to-lo
udness.
.TP
.B -U, --refresh-interval <argument>
[30] Set gomii refresh (update) interval to <argument> second
s (zero disables).
.TP
.B -W, --write-config, --save-config
This option is obsolete since version 0.29.10.

.TP
Setting mixer options:
.TP
.B -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.
.TP
.B -r, --record <argument>
Set recording for current channel on or off.
.TP
.B -R, --record-single
Set recording for current channel on and disable all other re
cording sources.
.TP
.B -L, --fade-to-loudness, --fade-to-volume <argument>
Like --loudness, but fade to the new volume within a time giv
en with --fade-interval.
.TP
.B -m, --mute
.TP
.B -M, --mute-all
Mute current or all channels. Muting means setting all channe
l volumes to 0.

.TP
Mixer settings options:
.TP
.B -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 "$HOME/.gom/<argument>". Any fr
ee-form files with gom one-character command line options in 
any lines starting with a dash (in column zero) will make sen
se to this option.
.TP
.B -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. 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 ap
art from the pure mixer settings (e.g. channel locking, curre
nt channel)). The bottom line to these load/save options is t
hat you can easily save new and load predefined mixer setting
s from anywhere.
.TP
.B -z, --snapshot-settings
.TP
.B -Z, --unsnapshot-settings, --restore-settings
[mixer settings after opening a new mixer] Snap- or unsnapsho
t to/from current mixer settings.

.TP
Informational options:
.TP
.B -t, --info
Display current channel information.
.TP
.B -T, --info-all
Display overall information.
.TP
.B -V, --version
Display version information.
.TP
.B -w, --copyright, --copyleft, --license, --warranty
Display copyright/license/warranty information.
.TP
.B -h, --help
.TP
.B -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.

.TP
Special options:
.TP
.B -e, --execute <argument>
Execute the shell command <argument>.

.TP
Command line only options:
.TP
.B -i, --interface, --gomii <argument>
Explicitly start up a build-in gomii (<argument>=t: terminal 
gomii, <argument>=x: X gomii).
.TP
.B -v, --verbose [<argument>]
[NORMAL] Set output verbosity to <argument> (number, the high
er, the more verbose). If no argument is given, verbosity wil
l be set to VERBOSE.
.TP
.B -q, --quiet, --silent
Set output verbosity to QUIET (only error / error help messag
es).
.TP
.B -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.
.TP
.B -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).
.TP
.B -I, --read-stdin
Read options from stdin (until EOF).


.SH ENVIRONMENT
.TP
.IR "HOME" " used as prefix for the configuration directory " ".gom/" " for a non-root user."
.br

.SH FILES
.TP
.IR "/etc/gom/" " system configuration directory (user root)."
.TP
.IR "$HOME/.gom/" " user configuration dir (all non-root users)."

.TP
Files inside the configuration directory:
.TP
.IR "gomrc" " configuration file (quietly loaded on startup).
.TP
.IR "default" " default options file (loaded with --get-options)."
.TP
.IR "*" " other files (most likely mixer settings) that can be easily accessed just by their names with gom."


.SH DIAGNOSTICS
.br
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).

.SH EXAMPLES

(This section is incomplete and most likely confusing ;).

.TP
.B "1. gom as system startup"
On my soundcard, one chip gets very hot when there is some
throughput. So, to be gentle to the card, I'd like to mute all
channels to be the default when the system starts. So I created
/etc/gom/gomrc with a line "-d/dev/mixer", and then, as root, i did
"gom --verbose --mute-all --save-settings".  Thusly prepared, all you
have to do is adding "gom --get-options" in some system startup file.

.TP
.B "2. gom as user startup"

Of course, the same as for the system applies for normal users of gom,
with your own configuration dir, and the calling line for gom must go
somewhere that is executed on login.

.TP
.B "3. gom in a running session"

%

.TP
.B "4. gom in scripts"

%

.TP
.B "5. Some more detailed examples"

.TP
.B gom --interface=t, gom -it
Interactively manipulate mixer settings with the terminal gomii.
.TP 
.B gom --get-settings, gom -G
(e.g. when you log in as user). Loads user's default options file.
.TP 
.B gom --get-settings=cd, gom -Gcd
Loads options file "cd" (most likely a setting for playing cds).
.TP 
.B 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.
.TP
.B gom -M -c vol -l 90 -c pcm -l 90 -e "bplay super.voc" -Z
Plays the sample
.IR "super.voc" " on channel 4=pcm with all other channels muted,"
restoring original mixer settings afterwards.
.TP 
.B gom -ix -e <any_sound_player> -Z
Plays any sound, interactively setting the mixer before with the
X gomii and restoring settings afterwards.

.SH AUTHOR
The gom package is Copyright (c) Stephan Suerken <suerken@fh-worms.de> 1996, 1997.

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.

The GOM Home Page on the web can currently (1997 Mar 18) be found at
"http://www.fh-worms.de/~suerken/gom.html".
.br
.SH SEE ALSO
.br
Information about OSS can currently (1997 Mar 18) be found at
"http://www.4front-tech.com/".
.br
.SH KNOWN BUGS
At the moment (0.29.10), it is not possible to load another file from
an options file (frankly, gom crashes). When this bug is fixed, it
might be possible to throw gom into infinite loops and such when
loading option files -- e.g. by adding a "-Gcd" to an options file
named "cd".

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.

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). (()())

.SH 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.
.B 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.