=pod

=head1 NAME

 icesound - play audio files when interesting GUI events happen

=head1 SYNOPSIS

B<icesound> [I<OPTIONS>]

=head1 DESCRIPTION

The L<icewm(1)> window manager generates so-called GUI events in
response to interesting actions, like opening or closing of application
windows, switching of work space, etc.  GUI events are a property of the
X root window.  L<icewm(1)> changes this property whenever a new GUI
event occurs.  Interested applications can listen for changes to this
property.  There are nearly twenty GUI events defined.

B<icesound> is an application, which is one of the L<icewm(1)>
applications, which responds to these GUI events by playing audio files.
These sound files are F<.wav> files located in a F<sounds> sub-directory
in one of the L<icewm(1)> configuration directories.

B<icesound> supports several common audio interfaces.  These are: ALSA,
OSS and libAO.  These must be enabled during configuration.
ALSA, OSS and libAO all require support for L<libsndfile>, which is a
very common library to read audio files.

=over

=item B<ALSA>

B<ALSA> is rather involved to program and it works, but this could use
more testing.  It plays at most one sound at a time.

=item B<LibAO>

B<LibAO> is a cross-platform audio output library which is a convenient
wrapper around a significant number of common audio interfaces.  It has
a simple configuration file which is documented in the L<libao.conf(5)>
manual page.

=item B<OSS>

The I<Open Sound System (OSS)> is a cross-platform sound interface,
which is fully supported by B<icesound>.

=back

When multiple audio interfaces are available B<icesound> will examine
them all until it finds one which it can connect to and then use that
one. By default it prefers them in the order of: B<AO>, B<ALSA>, B<OSS>.

=head1 OPTIONS

=head2 SPECIFIC OPTIONS

=over

=item B<-d>, B<--display>=I<DISPLAY>

X11 display used by L<icewm(1)> (default: $DISPLAY).

=item B<-s>, B<--sample-dir>=I<DIRECTORY>

Specifies a directory with sound files.  The default is:
F<$HOME/.config/icewm/sounds>, F<$HOME/.icewm/sounds>, F<CFGDIR/sounds>
and F<LIBDIR/sounds>.  See the output of C<icewm --directories>.

=item B<-i>, B<--interface>={B<AO>|B<ALSA>|B<OSS>}[,{B<AO>|B<ALSA>|B<OSS>}]*

Specifies the audio output interfaces. One or more of: B<AO>,
B<ALSA>, B<OSS> separated by commas (C<,>).

=item B<-D>, B<--device>=I<DEVICE>

Backwards compatibility only: the default device.
Please prefer one of the B<-A>, B<-O> or B<-S> options.

=item B<-O>, B<--oss>=I<DEVICE>

Specifies the OSS device (default: F</dev/dsp>).

=item B<-A>, B<--alsa>=I<DEVICE>

Specifies the ALSA device (default: C<default>).

=item B<-z>, B<--snooze>=I<MILLISECONDS>

Specifies the snooze interval between sound events
in milliseconds.  Default is 500 milliseconds.

=item B<-p>, B<--play>=I<SOUND>

Plays the given sound (name or number) and exits.

=item B<-l>, B<--list-files>

Lists the available sound file paths and exits.

=item B<--list-sounds>

Lists the supported sound file names and exits.

=item B<--list-interfaces>

Lists the supported audio interfaces and exits.

=item B<-v>, B<--verbose>

Be verbose and print some information when sound events occur.

=back

=head2 GENERAL OPTIONS

=over

=item B<-h>, B<--help>

Print a brief usage statement to F<stdout> and exit.

=item B<-V>, B<--version>

Print the program version to F<stdout> and exit.

=item B<-C>, B<--copying>

Print copying permissions to F<stdout> for the program and exit.

=back

=head1 EXIT STATUS

=over

=item B<0>

Success.

=item B<1>

General error.

=item B<2>

Command line error.

=item B<3>

Subsystems error (i.e cannot connect to server).

=back

=head1 SEE ALSO

L<icewm(1)>,
L<libao.conf(5)>,
L<padsp(1)>,
L<aplay(1)>,
L<alsamixer(1)>.

=head1 BUGS

Please report bugs at L<https://github.com/bbidulock/icewm/issues>.

=head1 AUTHOR

Brian Bidulock L<mailto:bidulock@openss7.org>.

See B<--copying> for full copyright notice and copying permissions.

=head1 LICENSE

B<IceWM> is licensed under the GNU Library General Public License.
See the F<COPYING> file in the distribution or use the B<--copying> flag
to display copying permissions.

=cut

# vim: set sw=4 tw=72 nocin spell spelllang=en_ca: