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 <h2>Module Autoloading</h2>
 116
 117 <h3><tt>list-autoload</tt></h3>
 118
 119 <p>Lists all currently defined autoloading entries.</p>
 120
 121 <h3><tt>add-autoload-sink/add-autoload-source</tt></h3>
 122
 123 <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>
 124
 125 <h3><tt>remove-autoload-sink/remove-autoload-source</tt></h3>
 126
 127 <p>Remove an autoloading entry. Expects the sink name (resp. source name) as argument.</p>
 128
 129 <h2>Miscellaneous Commands</h2>
 130
 131 <h3><tt>play-file</tt></h3>
 132
 133 <p>Play an audio file to a sink. Expects the file name and the sink name as argumens.</p>
 134
 135 <h3><tt>dump</tt></h3>
 136
 137 <p>Dump the daemon's current configuration in CLI commands.</p>
 138
 139 <h2>Killing Clients/Streams</h2>
 140
 141 <h3><tt>kill-client</tt></h3>
 142
 143 <p>Remove a client forcibly from the server. There is no protection that
 144 the client reconnects immediately.</p>
 145
 146 <h3><tt>kill-sink-input/kill-source-output</tt></h3>
 147
 148 <p>Remove a sink input (resp. source output) forcibly from the
 149 server. This will not remove the owning client or any other streams
 150 opened by the client from the server.</p>
 151
 152 <h2>Meta Commands</h2>
 153
 154 <p>In addition the the commands described above there a few meta
 155 directives supported by the command line interpreter:</p>
 156
 157 <h3><tt>.include</tt></h3>
 158
 159 <p>Executes the commands from the specified script file.</p>
 160
 161 <h3><tt>.fail/.nofail</tt></h3>
 162
 163 <p>Enable (resp. disable) that following failing commands will cancel
 164 the execution of the current script file. This is a ignored when used
 165 on the interactive command line.</p>
 166
 167 <h3><tt>.verbose/.noverbose</tt></h3>
 168 <p>Enable (resp. disable) extra verbosity.</p>
 169
 170 <h2>Example Configuration Script</h2>
 171
 172 <p>Mark the following script as executable (<tt>chmod +x</tt>) and run it for a sensible polypaudio configuration.</p>
 173
 174 <pre>
 175 #!/usr/bin/polaudio -nF
 176
 177 # Create autoload entries for the device drivers
 178 add-autoload-sink output module-alsa-sink device=plughw:0,0 rate=48000 sink_name=output
 179 add-autoload-sink output2 module-oss device=/dev/dsp1 record=0 sink_name=output2
 180 add-autoload-sink combined module-combine master=output slaves=output2 sink_name=combined
 181
 182 add-autoload-source input module-alsa-source device=hw:1,0 source_name=input
 183
 184 # Load several protocols
 185 load-module module-esound-protocol-unix
 186 load-module module-simple-protocol-tcp
 187 load-module module-native-protocol-unix
 188 load-module module-cli-protocol-unix
 189
 190 # Make some devices default
 191 set-default-sink combined
 192 set-default-source input
 193
 194 # Don't fail if the audio files referred to below don't exist
 195 .nofail
 196
 197 # Load an audio to the sample cache for usage with module-x11-bell
 198 load-sample-lazy  /usr/share/sounds/KDE_Notify.wav x11-bell
 199 load-module module-x11-bell sample=x11-bell
 200
 201 # Play a welcome sound
 202 play-file /usr/share/sounds/startup3.wav combined
 203 </pre>
 204
 205 <hr/>
 206 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
 207 <div class="grey"><i>$Id$</i></div>
 208 </body> </html>