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></h3>
  72
  73 <p>Set the volume of the specified sink. You may specify the sink either
  74 by its index in the sink list or by its name. The volume should be an
  75 integer value greater or equal than 0 (= muted). Volume 256
  76 (<tt>0x100</tt>) is normal volume, values greater than this amplify
  77 the audio signal with clipping.</p>
  78
  79 <h3><tt>set-sink-input-volume</tt></h3>
  80
  81 <p>Set the volume of a sink input specified by its index the the sink
  82 input list. The same volume rules apply as with <tt>sink_volume</tt>.</p>
  83
  84 <h3><tt>set-default-sink</tt>/<tt>set-default-source</tt></h3>
  85
  86 <p>Make a sink (resp. source) the default. You may specify the sink
  87 (resp. ssource) by its index in the sink (resp. source) list or by its
  88 name.</p>
  89
  90 <h2>Sample Cache</h2>
  91
  92 <h3><tt>list-samples</tt></h3>
  93
  94 <p>Lists the contents of the sample cache.</p>
  95
  96 <h3><tt>play-sample</tt></h3>
  97
  98 <p>Play a sample cache entry to a sink. Expects the sample name and the sink name as arguments.</p>
  99
 100 <h3><tt>remove-sample</tt></h3>
 101
 102 <p>Remove an entry from the sample cache. Expects the sample name as argument.</p>
 103
 104 <h3><tt>load-sample</tt></h3>
 105
 106 <p>Load an audio file to the sample cache. Expects the file name to load and the desired sample name as arguments.</p>
 107
 108 <h3><tt>load-sample-lazy</tt></h3>
 109
 110 <p>Create a new entry in the sample cache, but don't load the sample
 111 immediately. The sample is loaded only when it is first used. After a
 112 certain idle time it is freed again. Expects the the desired sample
 113 name and file name to load as arguments.</p>
 114
 115 <h3><tt>load-sample-dir-lazy</tt></h3>
 116
 117 <p>Load all entries in the specified directory into the sample cache
 118 as lazy entries. A shell globbing expression (e.g. <tt>*.wav</tt>) may
 119 be appended to the path of the directory to add.</p>
 120
 121 <h2>Module Autoloading</h2>
 122
 123 <h3><tt>list-autoload</tt></h3>
 124
 125 <p>Lists all currently defined autoloading entries.</p>
 126
 127 <h3><tt>add-autoload-sink/add-autoload-source</tt></h3>
 128
 129 <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>
 130
 131 <h3><tt>remove-autoload-sink/remove-autoload-source</tt></h3>
 132
 133 <p>Remove an autoloading entry. Expects the sink name (resp. source name) as argument.</p>
 134
 135 <h2>Miscellaneous Commands</h2>
 136
 137 <h3><tt>play-file</tt></h3>
 138
 139 <p>Play an audio file to a sink. Expects the file name and the sink name as argumens.</p>
 140
 141 <h3><tt>dump</tt></h3>
 142
 143 <p>Dump the daemon's current configuration in CLI commands.</p>
 144
 145 <h2>Killing Clients/Streams</h2>
 146
 147 <h3><tt>kill-client</tt></h3>
 148
 149 <p>Remove a client forcibly from the server. There is no protection that
 150 the client reconnects immediately.</p>
 151
 152 <h3><tt>kill-sink-input/kill-source-output</tt></h3>
 153
 154 <p>Remove a sink input (resp. source output) forcibly from the
 155 server. This will not remove the owning client or any other streams
 156 opened by the client from the server.</p>
 157
 158 <h2>Meta Commands</h2>
 159
 160 <p>In addition the the commands described above there a few meta
 161 directives supported by the command line interpreter:</p>
 162
 163 <h3><tt>.include</tt></h3>
 164
 165 <p>Executes the commands from the specified script file.</p>
 166
 167 <h3><tt>.fail/.nofail</tt></h3>
 168
 169 <p>Enable (resp. disable) that following failing commands will cancel
 170 the execution of the current script file. This is a ignored when used
 171 on the interactive command line.</p>
 172
 173 <h3><tt>.verbose/.noverbose</tt></h3>
 174 <p>Enable (resp. disable) extra verbosity.</p>
 175
 176 <h2>Example Configuration Script</h2>
 177
 178 <p>Mark the following script as executable (<tt>chmod +x</tt>) and run it for a sensible polypaudio configuration.</p>
 179
 180 <pre>
 181 #!/usr/bin/polaudio -nF
 182
 183 # Create autoload entries for the device drivers
 184 add-autoload-sink output module-alsa-sink device=plughw:0,0 rate=48000 sink_name=output
 185 add-autoload-sink output2 module-oss device=/dev/dsp1 record=0 sink_name=output2
 186 add-autoload-sink combined module-combine master=output slaves=output2 sink_name=combined
 187
 188 add-autoload-source input module-alsa-source device=hw:1,0 source_name=input
 189
 190 # Load several protocols
 191 load-module module-esound-protocol-unix
 192 load-module module-simple-protocol-tcp
 193 load-module module-native-protocol-unix
 194 load-module module-cli-protocol-unix
 195
 196 # Make some devices default
 197 set-default-sink combined
 198 set-default-source input
 199
 200 # Don't fail if the audio files referred to below don't exist
 201 .nofail
 202
 203 # Load an audio to the sample cache for usage with module-x11-bell
 204 load-sample-lazy  /usr/share/sounds/KDE_Notify.wav x11-bell
 205 load-module module-x11-bell sample=x11-bell
 206
 207 # Play a welcome sound
 208 play-file /usr/share/sounds/startup3.wav combined
 209 </pre>
 210
 211 <hr/>
 212 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, November 2004</address>
 213 <div class="grey"><i>$Id$</i></div>
 214 </body> </html>