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 <h2>Killing Clients/Streams</h2>
 129
 130 <h3><tt>kill_client</tt></h3>
 131
 132 <p>Remove a client forcibly from the server. There is no protection that
 133 the client reconnects immediately.</p>
 134
 135 <h3><tt>kill_sink_input/kill_source_output</tt></h3>
 136
 137 <p>Remove a sink input (resp. source output) forcibly from the
 138 server. This will not remove the owning client or any other streams
 139 opened by the client from the server.</p>
 140
 141 <h2>Meta Commands</h2>
 142
 143 <p>In addition the the commands described above there a few meta
 144 directives supported by the command line interpreter:</p>
 145
 146 <h3><tt>.include</tt></h3>
 147
 148 <p>Executes the commands from the specified script file.</p>
 149
 150 <h3><tt>.fail/.nofail</tt></h3>
 151
 152 <p>Enable (resp. disable) that following failing commands will cancel
 153 the execution of the current script file. This is a ignored when used
 154 on the interactive command line.</p>
 155
 156 <h3><tt>.verbose/.noverbose</tt></h3>
 157 <p>Enable (resp. disable) extra verbosity.</p>
 158
 159 <h2>Example Configuration Script</h2>
 160
 161 <p>Mark the following script as executable (<tt>chmod +x</tt>) and run it for a sensible polypaudio configuration.</p>
 162
 163 <pre>
 164 #!/usr/bin/polaudio -F
 165
 166 # Create autoload entries for the device drivers
 167 autoload_sink_add output module-alsa-sink device=plughw:0,0 rate=48000 sink_name=output
 168 autoload_source_add input load module-alsa-source device=hw:1,0 source_name=input
 169
 170 # Load several protocols
 171 load module-esound-protocol-tcp
 172 load module-simple-protocol-tcp
 173 load module-native-protocol-unix
 174 load module-cli-protocol-unix
 175
 176 # Load the CLI module (This is similar to passing "-C" on the command line of polypaudio)
 177 load module-cli
 178
 179 # Make some devices default
 180 sink_default output
 181 source_default input
 182
 183 # Don't fail if the audio files referred to below don't exist
 184 .nofail
 185
 186 # Load an audio to the sample cache for usage with module-x11-bell
 187 scache_load /usr/share/sounds/KDE_Notify.wav x11-bell
 188 load module-x11-bell
 189
 190 # Play a welcome sound
 191 play_file /usr/share/sounds/startup3.wav output
 192 </pre>
 193
 194 <hr/>
 195 <address class="grey">Lennart Poettering &lt;@PACKAGE_BUGREPORT@&gt;, August 2004</address>
 196 <div class="grey"><i>$Id$</i></div>
 197 </body> </html>