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>modules</tt></h3>
  32
  33 <p>Show all currently loaded modules with their arguments.</p>
  34
  35 <h3><tt>sinks/sources</tt></h3>
  36
  37 <p>Show all currently registered sinks (resp. sources).</p>
  38
  39 <h3><tt>clients</tt></h3>
  40
  41 <p>Show all currently active clients.</p>
  42
  43 <h3><tt>sink_inputs/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</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</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>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>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>sink_default/source_default</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>scache_list</tt></h3>
  93
  94 <p>Lists the contents of the sample cache.</p>
  95
  96 <h3><tt>scache_play</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>sache_remove</tt></h3>
 101
 102 <p>Remove an entry from the sample cache. Expects the sample name as argument.</p>
 103
 104 <h3><tt>sache_load</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 <h2>Module Autoloading</h2>
 109
 110 <h3><tt>autoload_list</tt></h3>
 111
 112 <p>Lists all currently defined autoloading entries.</p>
 113
 114 <h3><tt>autoload_sink_add/autoload_source_add</tt></h3>
 115
 116 <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>
 117
 118 <h3><tt>autoload_sink_remove/autoload_source_remove</tt></h3>
 119
 120 <p>Remove an autoloading entry. Expects the sink name (resp. source name) as argument.</p>
 121
 122 <h2>Miscellaneous Commands</h2>
 123
 124 <h3><tt>play_file</tt></h3>
 125
 126 <p>Play an audio file to a sink. Expects the file name and the sink name as argumens.</p>
 127
 128 <h3><tt>dump</tt></h3>
 129
 130 <p>Dump the daemon's current configuration in CLI commands.</p>
 131
 132 <h2>Killing Clients/Streams</h2>
 133
 134 <h3><tt>kill_client</tt></h3>
 135
 136 <p>Remove a client forcibly from the server. There is no protection that
 137 the client reconnects immediately.</p>
 138
 139 <h3><tt>kill_sink_input/kill_source_output</tt></h3>
 140
 141 <p>Remove a sink input (resp. source output) forcibly from the
 142 server. This will not remove the owning client or any other streams
 143 opened by the client from the server.</p>
 144
 145 <h2>Meta Commands</h2>
 146
 147 <p>In addition the the commands described above there a few meta
 148 directives supported by the command line interpreter:</p>
 149
 150 <h3><tt>.include</tt></h3>
 151
 152 <p>Executes the commands from the specified script file.</p>
 153
 154 <h3><tt>.fail/.nofail</tt></h3>
 155
 156 <p>Enable (resp. disable) that following failing commands will cancel
 157 the execution of the current script file. This is a ignored when used
 158 on the interactive command line.</p>
 159
 160 <h3><tt>.verbose/.noverbose</tt></h3>
 161 <p>Enable (resp. disable) extra verbosity.</p>
 162
 163 <h2>Example Configuration Script</h2>
 164
 165 <p>Mark the following script as executable (<tt>chmod +x</tt>) and run it for a sensible polypaudio configuration.</p>
 166
 167 <pre>
 168 #!/usr/bin/polaudio -F
 169
 170 # Create autoload entries for the device drivers
 171 autoload_sink_add output module-alsa-sink device=plughw:0,0 rate=48000 sink_name=output
 172 autoload_source_add input load module-alsa-source device=hw:1,0 source_name=input
 173
 174 # Load several protocols
 175 load module-esound-protocol-tcp
 176 load module-simple-protocol-tcp
 177 load module-native-protocol-unix
 178 load module-cli-protocol-unix
 179
 180 # Load the CLI module (This is similar to passing "-C" on the command line of polypaudio)
 181 load module-cli
 182
 183 # Make some devices default
 184 sink_default output
 185 source_default input
 186
 187 # Don't fail if the audio files referred to below don't exist
 188 .nofail
 189
 190 # Load an audio to the sample cache for usage with module-x11-bell
 191 scache_load /usr/share/sounds/KDE_Notify.wav x11-bell
 192 load module-x11-bell
 193
 194 # Play a welcome sound
 195 play_file /usr/share/sounds/startup3.wav output
 196 </pre>
 197
 198 <hr/>
 199 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, September 2004</address>
 200 <div class="grey"><i>$Id$</i></div>
 201 </body> </html>