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>