1=pod
2
3=head1 NAME
4
5 icesound - play audio files when interesting GUI events happen
6
7=head1 SYNOPSIS
8
9B<icesound> [I<OPTIONS>]
10
11=head1 DESCRIPTION
12
13The L<icewm(1)> window manager generates so-called GUI events in
14response to interesting actions, like opening or closing of application
15windows, switching of work space, etc.  GUI events are a property of the
16X root window.  L<icewm(1)> changes this property whenever a new GUI
17event occurs.  Interested applications can listen for changes to this
18property.  There are nearly twenty GUI events defined.
19
20B<icesound> is an application, which is one of the L<icewm(1)>
21applications, which responds to these GUI events by playing audio files.
22These sound files are F<.wav> files located in a F<sounds> sub-directory
23in one of the L<icewm(1)> configuration directories.
24
25B<icesound> supports several common audio interfaces.  These are: ALSA,
26OSS and libAO.  These must be enabled during configuration.
27ALSA, OSS and libAO all require support for L<libsndfile>, which is a
28very common library to read audio files.
29
30=over
31
32=item B<ALSA>
33
34B<ALSA> is rather involved to program and it works, but this could use
35more testing.  It plays at most one sound at a time.
36
37=item B<LibAO>
38
39B<LibAO> is a cross-platform audio output library which is a convenient
40wrapper around a significant number of common audio interfaces.  It has
41a simple configuration file which is documented in the L<libao.conf(5)>
42manual page.
43
44=item B<OSS>
45
46The I<Open Sound System (OSS)> is a cross-platform sound interface,
47which is fully supported by B<icesound>.
48
49=back
50
51When multiple audio interfaces are available B<icesound> will examine
52them all until it finds one which it can connect to and then use that
53one. By default it prefers them in the order of: B<AO>, B<ALSA>, B<OSS>.
54
55=head1 OPTIONS
56
57=head2 SPECIFIC OPTIONS
58
59=over
60
61=item B<-d>, B<--display>=I<DISPLAY>
62
63X11 display used by L<icewm(1)> (default: $DISPLAY).
64
65=item B<-s>, B<--sample-dir>=I<DIRECTORY>
66
67Specifies a directory with sound files.  The default is:
68F<$HOME/.config/icewm/sounds>, F<$HOME/.icewm/sounds>, F<CFGDIR/sounds>
69and F<LIBDIR/sounds>.  See the output of C<icewm --directories>.
70
71=item B<-i>, B<--interface>={B<AO>|B<ALSA>|B<OSS>}[,{B<AO>|B<ALSA>|B<OSS>}]*
72
73Specifies the audio output interfaces. One or more of: B<AO>,
74B<ALSA>, B<OSS> separated by commas (C<,>).
75
76=item B<-D>, B<--device>=I<DEVICE>
77
78Backwards compatibility only: the default device.
79Please prefer one of the B<-A>, B<-O> or B<-S> options.
80
81=item B<-O>, B<--oss>=I<DEVICE>
82
83Specifies the OSS device (default: F</dev/dsp>).
84
85=item B<-A>, B<--alsa>=I<DEVICE>
86
87Specifies the ALSA device (default: C<default>).
88
89=item B<-z>, B<--snooze>=I<MILLISECONDS>
90
91Specifies the snooze interval between sound events
92in milliseconds.  Default is 500 milliseconds.
93
94=item B<-p>, B<--play>=I<SOUND>
95
96Plays the given sound (name or number) and exits.
97
98=item B<-l>, B<--list-files>
99
100Lists the available sound file paths and exits.
101
102=item B<--list-sounds>
103
104Lists the supported sound file names and exits.
105
106=item B<--list-interfaces>
107
108Lists the supported audio interfaces and exits.
109
110=item B<-v>, B<--verbose>
111
112Be verbose and print some information when sound events occur.
113
114=back
115
116=head2 GENERAL OPTIONS
117
118=over
119
120=item B<-h>, B<--help>
121
122Print a brief usage statement to F<stdout> and exit.
123
124=item B<-V>, B<--version>
125
126Print the program version to F<stdout> and exit.
127
128=item B<-C>, B<--copying>
129
130Print copying permissions to F<stdout> for the program and exit.
131
132=back
133
134=head1 EXIT STATUS
135
136=over
137
138=item B<0>
139
140Success.
141
142=item B<1>
143
144General error.
145
146=item B<2>
147
148Command line error.
149
150=item B<3>
151
152Subsystems error (i.e cannot connect to server).
153
154=back
155
156=head1 SEE ALSO
157
158L<icewm(1)>,
159L<libao.conf(5)>,
160L<padsp(1)>,
161L<aplay(1)>,
162L<alsamixer(1)>.
163
164=head1 BUGS
165
166Please report bugs at L<https://github.com/bbidulock/icewm/issues>.
167
168=head1 AUTHOR
169
170Brian Bidulock L<mailto:bidulock@openss7.org>.
171
172See B<--copying> for full copyright notice and copying permissions.
173
174=head1 LICENSE
175
176B<IceWM> is licensed under the GNU Library General Public License.
177See the F<COPYING> file in the distribution or use the B<--copying> flag
178to display copying permissions.
179
180=cut
181
182# vim: set sw=4 tw=72 nocin spell spelllang=en_ca:
183