code.delx.au - pulseaudio/blob - doc/cli.html.in

   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">
   4 <head>
   5 <title>polypaudio: Simple Command Line Language</title>
   6 <link rel="stylesheet" type="text/css" href="style.css" />
   7 </head>
   8
   9 <body>
  10 <h1>Simple Command Line Language</h1>
  11
  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>
  17
  18 <h2>Miscellaneous Commands</h2>
  19
  20 <h3><tt>help</tt></h3>
  21
  22 <p>Show a quick help on the commands available.</p>
  23
  24 <h3><tt>exit</tt></h3>
  25
  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>
  28
  29 <h2>Status Commands</h2>
  30
  31 <h3><tt>list-modules</tt></h3>
  32
  33 <p>Show all currently loaded modules with their arguments.</p>
  34
  35 <h3><tt>list-sinks/list-sources</tt></h3>
  36
  37 <p>Show all currently registered sinks (resp. sources).</p>
  38
  39 <h3><tt>list-clients</tt></h3>
  40
  41 <p>Show all currently active clients.</p>
  42
  43 <h3><tt>list-sink-inputs/list-sink-outputs</tt></h3>
  44
  45 <p>Show all currently active inputs to sinks (resp. outputs of sources).</p>
  46
  47 <h3><tt>stat</tt></h3>
  48
  49 <p>Show some simple statistics about the allocated memory blocks and
  50 the space used by them.</p>
  51
  52 <h3><tt>info</tt></h3>
  53
  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>
  56
  57 <h2>Module Management</h2>
  58
  59 <h3><tt>load-module</tt></h3>
  60
  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>
  63
  64 <h3><tt>unload-module</tt></h3>
  65
  66 <p>Unload a module specified by its index in the module list as
  67 returned by <tt>modules</tt>.</p>
  68
  69 <h2>Configuration Commands</h2>
  70
  71 <h3><tt>set-sink-volume</tt>/<tt>set-source-volume</tt></h3>
  72
  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>
  78
  79 <h3><tt>set-sink-mute</tt>/<tt>set-source-mute</tt></h3>
  80
  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
  83 either 0 or 1.</p>
  84
  85 <h3><tt>set-sink-input-volume</tt></h3>
  86
  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>
  89
  90 <h3><tt>set-default-sink</tt>/<tt>set-default-source</tt></h3>
  91
  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
  94 name.</p>
  95
  96 <h2>Sample Cache</h2>
  97
  98 <h3><tt>list-samples</tt></h3>
  99
 100 <p>Lists the contents of the sample cache.</p>
 101
 102 <h3><tt>play-sample</tt></h3>
 103
 104 <p>Play a sample cache entry to a sink. Expects the sample name and the sink name as arguments.</p>
 105
 106 <h3><tt>remove-sample</tt></h3>
 107
 108 <p>Remove an entry from the sample cache. Expects the sample name as argument.</p>
 109
 110 <h3><tt>load-sample</tt></h3>
 111
 112 <p>Load an audio file to the sample cache. Expects the file name to load and the desired sample name as arguments.</p>
 113
 114 <h3><tt>load-sample-lazy</tt></h3>
 115
 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>
 120
 121 <h3><tt>load-sample-dir-lazy</tt></h3>
 122
 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>
 126
 127 <h2>Module Autoloading</h2>
 128
 129 <h3><tt>list-autoload</tt></h3>
 130
 131 <p>Lists all currently defined autoloading entries.</p>
 132
 133 <h3><tt>add-autoload-sink/add-autoload-source</tt></h3>
 134
 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>
 136
 137 <h3><tt>remove-autoload-sink/remove-autoload-source</tt></h3>
 138
 139 <p>Remove an autoloading entry. Expects the sink name (resp. source name) as argument.</p>
 140
 141 <h2>Miscellaneous Commands</h2>
 142
 143 <h3><tt>play-file</tt></h3>
 144
 145 <p>Play an audio file to a sink. Expects the file name and the sink name as argumens.</p>
 146
 147 <h3><tt>dump</tt></h3>
 148
 149 <p>Dump the daemon's current configuration in CLI commands.</p>
 150
 151 <h2>Killing Clients/Streams</h2>
 152
 153 <h3><tt>kill-client</tt></h3>
 154
 155 <p>Remove a client forcibly from the server. There is no protection that
 156 the client reconnects immediately.</p>
 157
 158 <h3><tt>kill-sink-input/kill-source-output</tt></h3>
 159
 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>
 163
 164 <h2>Meta Commands</h2>
 165
 166 <p>In addition the the commands described above there a few meta
 167 directives supported by the command line interpreter:</p>
 168
 169 <h3><tt>.include</tt></h3>
 170
 171 <p>Executes the commands from the specified script file.</p>
 172
 173 <h3><tt>.fail/.nofail</tt></h3>
 174
 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>
 178
 179 <h3><tt>.verbose/.noverbose</tt></h3>
 180 <p>Enable (resp. disable) extra verbosity.</p>
 181
 182 <h2>Example Configuration Script</h2>
 183
 184 <p>Mark the following script as executable (<tt>chmod +x</tt>) and run it for a sensible polypaudio configuration.</p>
 185
 186 <pre>
 187 #!/usr/bin/polaudio -nF
 188
 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
 193
 194 add-autoload-source input module-alsa-source device=hw:1,0 source_name=input
 195
 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
 201
 202 # Make some devices default
 203 set-default-sink combined
 204 set-default-source input
 205
 206 # Don't fail if the audio files referred to below don't exist
 207 .nofail
 208
 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
 212
 213 # Play a welcome sound
 214 play-file /usr/share/sounds/startup3.wav combined
 215 </pre>
 216
 217 <hr/>
 218 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, April 2006</address>
 219 <div class="grey"><i>$Id$</i></div>
 220 </body> </html>