1 <?xml version=
"1.0" encoding=
"iso-8859-1"?> <!-- -*-html-helper-*- -->
2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns=
"http://www.w3.org/1999/xhtml">
5 <title>polypaudio: Simple Command Line Language
</title>
6 <link rel=
"stylesheet" type=
"text/css" href=
"style.css" />
10 <h1>Simple Command Line Language
</h1>
12 <p><tt>polypaudio
</tt> provides a simple command line language used by
13 configuration scripts as well as the modules
<tt>module-cli
</tt>
14 and
<tt>module-cli-protocol-{unix,tcp}
</tt>. Empty lines and lines
15 beginning with a hashmark (
<tt>#
</tt>) are silently ignored. Several
16 commands are supported:
</p>
18 <h2>Miscellaneous Commands
</h2>
20 <h3><tt>help
</tt></h3>
22 <p>Show a quick help on the commands available.
</p>
24 <h3><tt>exit
</tt></h3>
26 <p>Terminate the daemon. If you want to terminate a CLI connection
27 (
"log out") you might want to use
<tt>C-d
</tt>.
</p>
29 <h2>Status Commands
</h2>
31 <h3><tt>list-modules
</tt></h3>
33 <p>Show all currently loaded modules with their arguments.
</p>
35 <h3><tt>list-sinks/list-sources
</tt></h3>
37 <p>Show all currently registered sinks (resp. sources).
</p>
39 <h3><tt>list-clients
</tt></h3>
41 <p>Show all currently active clients.
</p>
43 <h3><tt>list-sink-inputs/list-sink-outputs
</tt></h3>
45 <p>Show all currently active inputs to sinks (resp. outputs of sources).
</p>
47 <h3><tt>stat
</tt></h3>
49 <p>Show some simple statistics about the allocated memory blocks and
50 the space used by them.
</p>
52 <h3><tt>info
</tt></h3>
54 <p>A combination of all status commands described above.
<tt>ls
</tt>
55 and
<tt>list
</tt> are synonyms for
<tt>info
</tt>.
</p>
57 <h2>Module Management
</h2>
59 <h3><tt>load-module
</tt></h3>
61 <p>Load a module specified by its name and arguments. For most modules
62 it is OK to be loaded more than once.
</p>
64 <h3><tt>unload-module
</tt></h3>
66 <p>Unload a module specified by its index in the module list as
67 returned by
<tt>modules
</tt>.
</p>
69 <h2>Configuration Commands
</h2>
71 <h3><tt>set-sink-volume
</tt>/
<tt>set-source-volume
</tt></h3>
73 <p>Set the volume of the specified sink or source. You may specify the sink/source either
74 by its index in the sink/source list or by its name. The volume should be an
75 integer value greater or equal than
0 (= muted). Volume
65536
76 (
<tt>0x10000</tt>) is normal volume, values greater than this amplify
77 the audio signal (with clipping).
</p>
79 <h3><tt>set-sink-mute
</tt>/
<tt>set-source-mute
</tt></h3>
81 <p>Mute or unmute the specified sink our source. You may specify the
82 sink/source either by its index or by its name. The mute value is
85 <h3><tt>set-sink-input-volume
</tt></h3>
87 <p>Set the volume of a sink input specified by its index the the sink
88 input list. The same volume rules apply as with
<tt>sink_volume
</tt>.
</p>
90 <h3><tt>set-default-sink
</tt>/
<tt>set-default-source
</tt></h3>
92 <p>Make a sink (resp. source) the default. You may specify the sink
93 (resp. ssource) by its index in the sink (resp. source) list or by its
98 <h3><tt>list-samples
</tt></h3>
100 <p>Lists the contents of the sample cache.
</p>
102 <h3><tt>play-sample
</tt></h3>
104 <p>Play a sample cache entry to a sink. Expects the sample name and the sink name as arguments.
</p>
106 <h3><tt>remove-sample
</tt></h3>
108 <p>Remove an entry from the sample cache. Expects the sample name as argument.
</p>
110 <h3><tt>load-sample
</tt></h3>
112 <p>Load an audio file to the sample cache. Expects the file name to load and the desired sample name as arguments.
</p>
114 <h3><tt>load-sample-lazy
</tt></h3>
116 <p>Create a new entry in the sample cache, but don't load the sample
117 immediately. The sample is loaded only when it is first used. After a
118 certain idle time it is freed again. Expects the the desired sample
119 name and file name to load as arguments.
</p>
121 <h3><tt>load-sample-dir-lazy
</tt></h3>
123 <p>Load all entries in the specified directory into the sample cache
124 as lazy entries. A shell globbing expression (e.g.
<tt>*.wav
</tt>) may
125 be appended to the path of the directory to add.
</p>
127 <h2>Module Autoloading
</h2>
129 <h3><tt>list-autoload
</tt></h3>
131 <p>Lists all currently defined autoloading entries.
</p>
133 <h3><tt>add-autoload-sink/add-autoload-source
</tt></h3>
135 <p>Adds an autoloading entry for a sink (resp. source). Expects the sink name (resp. source name), the module name and the module arguments as arguments.
</p>
137 <h3><tt>remove-autoload-sink/remove-autoload-source
</tt></h3>
139 <p>Remove an autoloading entry. Expects the sink name (resp. source name) as argument.
</p>
141 <h2>Miscellaneous Commands
</h2>
143 <h3><tt>play-file
</tt></h3>
145 <p>Play an audio file to a sink. Expects the file name and the sink name as argumens.
</p>
147 <h3><tt>dump
</tt></h3>
149 <p>Dump the daemon's current configuration in CLI commands.
</p>
151 <h2>Killing Clients/Streams
</h2>
153 <h3><tt>kill-client
</tt></h3>
155 <p>Remove a client forcibly from the server. There is no protection that
156 the client reconnects immediately.
</p>
158 <h3><tt>kill-sink-input/kill-source-output
</tt></h3>
160 <p>Remove a sink input (resp. source output) forcibly from the
161 server. This will not remove the owning client or any other streams
162 opened by the client from the server.
</p>
164 <h2>Meta Commands
</h2>
166 <p>In addition the the commands described above there a few meta
167 directives supported by the command line interpreter:
</p>
169 <h3><tt>.include
</tt></h3>
171 <p>Executes the commands from the specified script file.
</p>
173 <h3><tt>.fail/.nofail
</tt></h3>
175 <p>Enable (resp. disable) that following failing commands will cancel
176 the execution of the current script file. This is a ignored when used
177 on the interactive command line.
</p>
179 <h3><tt>.verbose/.noverbose
</tt></h3>
180 <p>Enable (resp. disable) extra verbosity.
</p>
182 <h2>Example Configuration Script
</h2>
184 <p>Mark the following script as executable (
<tt>chmod +x
</tt>) and run it for a sensible polypaudio configuration.
</p>
187 #!/usr/bin/polaudio -nF
189 # Create autoload entries for the device drivers
190 add-autoload-sink output module-alsa-sink device=plughw:
0,
0 rate=
48000 sink_name=output
191 add-autoload-sink output2 module-oss device=/dev/dsp1 record=
0 sink_name=output2
192 add-autoload-sink combined module-combine master=output slaves=output2 sink_name=combined
194 add-autoload-source input module-alsa-source device=hw:
1,
0 source_name=input
196 # Load several protocols
197 load-module module-esound-protocol-unix
198 load-module module-simple-protocol-tcp
199 load-module module-native-protocol-unix
200 load-module module-cli-protocol-unix
202 # Make some devices default
203 set-default-sink combined
204 set-default-source input
206 # Don't fail if the audio files referred to below don't exist
209 # Load an audio to the sample cache for usage with module-x11-bell
210 load-sample-lazy /usr/share/sounds/KDE_Notify.wav x11-bell
211 load-module module-x11-bell sample=x11-bell
213 # Play a welcome sound
214 play-file /usr/share/sounds/startup3.wav combined
218 <address class=
"grey">Lennart Poettering
<@PACKAGE_BUGREPORT@
>, April
2006</address>
219 <div class=
"grey"><i>$Id$
</i></div>