Provided by: gom_0.30.2-6build1_amd64 bug

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.