<commit_before>=pod

=head1 NAME

 icesound - 

=head1 SYNOPSIS

B<icesound> [I<OPTIONS>]

=head1 DESCRIPTION

=head1 OPTIONS

=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 BUGS

B<icesound> had no known bugs at the time of release.  Please report bugs
for current versions to the source code repository at
L<https://github.com/bbidulock/icewm/issues>.

=head1 AUTHOR

<NAME> L<mailto:<EMAIL>>.

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
<commit_msg>comaplete icesound manual page<commit_after>=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 can be configured to generate 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 root window.  L<icewm(1)> changes this property when a
new GUI event occurs.  Interested applications can listen for changes to
this property.  GUI events are an optional feature of L<icewm(1)>.  It
must be explicitly enabled by giving the B<--enable-guievents> option
during configuration.  There are nearly twenty GUI events defined.  The
B<--list-sounds> option will show them.

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,
ESounD, 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<ESounD>

The B<ESounD> interface is much simpler to implement and this works very
well, because the difficult details are handled by the B<ESounD> Sound
Daemon.  It supports mixing of sounds when multiple GUI events occur
within a second.  This may be the best option currently.  It requires
that L<esd(1)> is running and that B<icesound> can connect to it.

=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<ESD>,
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<ESD>|B<ALSA>|B<OSS>}[,{B<AO>|B<ESD>|B<ALSA>|B<OSS>}]*

Specifies the audio output interfaces. One or more of: B<AO>, B<ESD>,
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: C<default>).

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

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

=item B<-S>, B<--server>=I<ADDR>[B<:>I<PORT>]

Specifies the ESD server address and port number.
For ESD the default is C<localhost:16001>.

=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 0

Success.

=item 1

General error.

=item 2

Command line error.

=item 3

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

=back

=head1 SEE ALSO

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

=head1 BUGS

B<icesound> had no known bugs at the time of release.  Please report bugs
for current versions to the source code repository at
L<https://github.com/bbidulock/icewm/issues>.

=head1 AUTHOR

<NAME> L<mailto:<EMAIL>>.

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

{'fraction_non_alphanumeric': 0.10790045097711709, 'fraction_numerical': 0.007850342408551862, 'mean_word_length': 4.3416592328278325, 'pattern_counts': {'":': 0, '<': 138, '<?xml version=': 0, '>': 138, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7413771', 'n_tokens_mistral': 2099, 'n_tokens_neox': 1983, 'n_words': 816}