1<?xml version="1.0"?><!--*-nxml-*--> 2<!DOCTYPE manpage SYSTEM "xmltoman.dtd"> 3<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?> 4 5<!-- 6This file is part of PulseAudio. 7 8PulseAudio is free software; you can redistribute it and/or modify it 9under the terms of the GNU Lesser General Public License as 10published by the Free Software Foundation; either version 2.1 of the 11License, or (at your option) any later version. 12 13PulseAudio is distributed in the hope that it will be useful, but WITHOUT 14ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 15or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General 16Public License for more details. 17 18You should have received a copy of the GNU Lesser General Public 19License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>. 20--> 21 22<manpage name="pulse-cli-syntax" section="5" desc="PulseAudio Command Line Interface Syntax"> 23 24 <synopsis> 25 <p><file>~/.config/pulse/default.pa</file></p> 26 <p><file>@PA_DEFAULT_CONFIG_DIR@/default.pa</file></p> 27 <p><file>@PA_DEFAULT_CONFIG_DIR@/system.pa</file></p> 28 </synopsis> 29 30 <description> 31 <p> 32 PulseAudio provides a simple command line language used by configuration 33 scripts, the pacmd interactive shell, and the modules module-cli and 34 module-cli-protocol-{unix,tcp}. Empty lines and lines beginning with a 35 hashmark (#) are silently ignored. Several commands are supported. 36 </p> 37 38 <p> 39 Note that any boolean arguments can be given positively as '1', 't', 'y', 40 'true', 'yes' or 'on'. Likewise, negative values can be given as '0', 41 'f', 'n', 'false', 'no' or 'off'. Case is ignored. 42 </p> 43 </description> 44 45 <section name="General Commands"> 46 47 <option> 48 <p><opt>help</opt></p> 49 <optdesc><p>Show a quick help on the commands available.</p></optdesc> 50 </option> 51 </section> 52 53 <section name="Status Commands"> 54 <option> 55 <p><opt>list-modules</opt></p> 56 <optdesc><p>Show all currently loaded modules with their arguments.</p></optdesc> 57 </option> 58 59 <option> 60 <p><opt>list-cards</opt></p> 61 <optdesc><p>Show all currently registered cards</p></optdesc> 62 </option> 63 64 <option> 65 <p><opt>list-sinks</opt> or <opt>list-sources</opt></p> 66 <optdesc><p>Show all currently registered sinks (resp. sources).</p></optdesc> 67 </option> 68 69 <option> 70 <p><opt>list-clients</opt></p> 71 <optdesc><p>Show all currently active clients.</p></optdesc> 72 </option> 73 74 <option> 75 <p><opt>list-sink-inputs</opt> or <opt>list-source-outputs</opt></p> 76 <optdesc><p>Show all currently active inputs to sinks a.k.a. playback 77 streams (resp. outputs of sources a.k.a. recording streams).</p></optdesc> 78 </option> 79 80 <option> 81 <p><opt>stat</opt></p> 82 <optdesc><p>Show some simple statistics about the allocated memory blocks and the space used by them.</p></optdesc> 83 </option> 84 85 <option> 86 <p><opt>info</opt> or <opt>ls</opt> or <opt>list</opt></p> 87 <optdesc><p>A combination of all status commands described above (all 88 three commands are synonyms).</p></optdesc> 89 </option> 90 </section> 91 92 <section name="Module Management"> 93 <option> 94 <p><opt>load-module</opt> <arg>name</arg> [<arg>arguments...</arg>]</p> 95 <optdesc><p>Load a module specified by its name and arguments. For most 96 modules it is OK to be loaded more than once.</p></optdesc> 97 </option> 98 99 <option> 100 <p><opt>unload-module</opt> <arg>index|name</arg></p> 101 <optdesc><p>Unload a module, specified either by its index in the module 102 list or its name.</p></optdesc> 103 </option> 104 105 <option> 106 <p><opt>describe-module</opt> <arg>name</arg></p> 107 <optdesc><p>Give information about a module specified by its name.</p></optdesc> 108 </option> 109 </section> 110 111 <section name="Volume Commands"> 112 <option> 113 <p><opt>set-sink-volume|set-source-volume</opt> <arg>index|name</arg> <arg>volume</arg></p> 114 <optdesc><p>Set the volume of the specified sink (resp. source). You may 115 specify the sink (resp. source) either by its index in the sink/source list 116 or by its name. The volume should be an integer value greater or equal than 117 0 (muted). Volume 65536 (0x10000) is 'normal' volume a.k.a. 100%. Values 118 greater than this amplify the audio signal (with clipping).</p></optdesc> 119 </option> 120 121 <option> 122 <p><opt>set-sink-mute|set-source-mute</opt> <arg>index|name</arg> <arg>boolean</arg></p> 123 <optdesc><p>Mute or unmute the specified sink (resp. source). You may 124 specify the sink (resp. source) either by its index or by its name. 125 The mute value is either 0 (not muted) or 1 (muted).</p></optdesc> 126 </option> 127 128 <option> 129 <p><opt>set-sink-input-volume|set-source-output-volume</opt> <arg>index</arg> <arg>volume</arg></p> 130 <optdesc><p>Set the volume of a sink input (resp. source output) specified 131 by its index. The same volume rules apply as with set-sink-volume.</p></optdesc> 132 </option> 133 134 <option> 135 <p><opt>set-sink-input-mute|set-source-output-mute</opt> <arg>index</arg> <arg>boolean</arg></p> 136 <optdesc><p>Mute or unmute a sink input (resp. source output) specified 137 by its index. The same mute rules apply as with set-sink-mute.</p></optdesc> 138 </option> 139 </section> 140 141 <section name="Configuration Commands"> 142 <option> 143 <p><opt>set-default-sink|set-default-source</opt> <arg>index|name</arg></p> 144 <optdesc><p>Make a sink (resp. source) the default. You may specify the 145 sink (resp. source) by its index in the sink (resp. source) list or by its 146 name.</p><p>Note that defaults may be overridden by various policy modules 147 or by specific stream configurations.</p></optdesc> 148 </option> 149 150 <option> 151 <p><opt>set-card-profile</opt> <arg>index|name</arg> <arg>profile-name</arg></p> 152 <optdesc><p>Change the profile of a card.</p></optdesc> 153 </option> 154 155 <option> 156 <p><opt>set-sink-port|set-source-port</opt> <arg>index|name</arg> <arg>port-name</arg></p> 157 <optdesc><p>Change the profile of a sink (resp. source).</p></optdesc> 158 </option> 159 160 <option> 161 <p><opt>set-port-latency-offset</opt> <arg>card-index|card-name</arg> <arg>port-name</arg> <arg>offset</arg> </p> 162 <optdesc><p>Change the latency offset of a port belonging to the specified card</p></optdesc> 163 </option> 164 165 <option> 166 <p><opt>suspend-sink|suspend-source</opt> <arg>name|index</arg> 167 <arg>true|false</arg> 168 </p> 169 <optdesc><p>Suspend or resume the specified sink or source (which may be 170 specified either by its name or index), depending whether true 171 (suspend) or false (resume) is passed as last argument. Suspending 172 a sink will pause all playback and suspending a source will pause all 173 capturing. Depending on the module implementing the sink or source this 174 might have the effect that the underlying device is closed, making it 175 available for other applications to use. The exact behaviour depends on 176 the module. 177 </p></optdesc> 178 </option> 179 180 <option> 181 <p><opt>suspend</opt> <arg>boolean</arg></p> 182 <optdesc><p>Suspend all sinks and sources.</p></optdesc> 183 </option> 184 </section> 185 186 <section name="Moving streams"> 187 <option> 188 <p><opt>move-sink-input|move-source-output</opt> <arg>index</arg> <arg>sink-index|sink-name</arg></p> 189 <optdesc><p>Move sink input (resp. source output) to another sink 190 (resp. source).</p></optdesc> 191 </option> 192 </section> 193 194 <section name="Property lists"> 195 <option> 196 <p><opt>update-sink-proplist|update-source-proplist</opt> <arg>index|name</arg> <arg>properties</arg></p> 197 <optdesc><p>Update the properties of a sink (resp. source) specified by 198 name or index. The property is specified as e.g. device.description="My 199 Preferred Name"</p></optdesc> 200 </option> 201 202 <option> 203 <p><opt>update-sink-input-proplist|update-source-output-proplist</opt> <arg>index</arg> <arg>properties</arg></p> 204 <optdesc><p>Update the properties of a sink input (resp. source output) 205 specified by index. The properties are specified as above.</p></optdesc> 206 </option> 207 </section> 208 209 <section name="Sample Cache"> 210 <option> 211 <p><opt>list-samples</opt></p> 212 <optdesc><p>Lists the contents of the sample cache.</p></optdesc> 213 </option> 214 215 <option> 216 <p><opt>play-sample</opt> <arg>name</arg> <arg>sink-index|sink-name</arg></p> 217 <optdesc><p>Play a sample cache entry to a sink.</p></optdesc> 218 </option> 219 220 <option> 221 <p><opt>remove-sample</opt> <arg>name</arg></p> 222 <optdesc><p>Remove an entry from the sample cache.</p></optdesc> 223 </option> 224 225 <option> 226 <p><opt>load-sample</opt> <arg>name</arg> <arg>filename</arg></p> 227 <optdesc><p>Load an audio file to the sample cache.</p></optdesc> 228 </option> 229 230 <option> 231 <p><opt>load-sample-lazy</opt> <arg>name</arg> <arg>filename</arg></p> 232 <optdesc><p>Create a new entry in the sample cache, but don't load the 233 sample immediately. The sample is loaded only when it is first used. 234 After a certain idle time it is freed again.</p></optdesc> 235 </option> 236 237 <option> 238 <p><opt>load-sample-dir-lazy</opt> <arg>path</arg></p> 239 <optdesc><p>Load all entries in the specified directory into the sample 240 cache as lazy entries. A shell globbing expression (e.g. *.wav) may be 241 appended to the path of the directory to add.</p></optdesc> 242 </option> 243 </section> 244 245 <section name="Killing Clients/Streams"> 246 <option> 247 <p><opt>kill-client</opt> <arg>index</arg></p> 248 <optdesc><p>Remove a client forcibly from the server. There is no protection 249 against the client reconnecting immediately.</p></optdesc> 250 </option> 251 252 <option> 253 <p><opt>kill-sink-input|kill-source-output</opt> <arg>index</arg></p> 254 <optdesc><p>Remove a sink input (resp. source output) forcibly from the 255 server. This will not remove the owning client or any other streams opened 256 by the same client from the server.</p></optdesc> 257 </option> 258 </section> 259 260 <section name="Log Commands"> 261 <option> 262 <p><opt>set-log-level</opt> <arg>numeric-level</arg></p> 263 <optdesc><p>Change the log level.</p></optdesc> 264 </option> 265 266 <option> 267 <p><opt>set-log-meta</opt> <arg>boolean</arg></p> 268 <optdesc><p>Show source code location in log messages.</p></optdesc> 269 </option> 270 271 <option> 272 <p><opt>set-log-target</opt> <arg>target</arg></p> 273 <optdesc><p>Change the log target (null, auto, journal, syslog, stderr, 274 file:PATH, newfile:PATH).</p></optdesc> 275 </option> 276 277 <option> 278 <p><opt>set-log-time</opt> <arg>boolean</arg></p> 279 <optdesc><p>Show timestamps in log messages.</p></optdesc> 280 </option> 281 282 <option> 283 <p><opt>set-log-backtrace</opt> <arg>num-frames</arg></p> 284 <optdesc><p>Show backtrace in log messages.</p></optdesc> 285 </option> 286 </section> 287 288 <section name="Miscellaneous Commands"> 289 <option> 290 <p><opt>play-file</opt> <arg>filename</arg> <arg>sink-index|sink-name</arg></p> 291 <optdesc><p>Play an audio file to a sink.</p></optdesc> 292 </option> 293 294 <option> 295 <p><opt>dump</opt></p> 296 <optdesc><p>Dump the daemon's current configuration in CLI commands.</p></optdesc> 297 </option> 298 299 <option> 300 <p><opt>dump-volumes</opt></p> 301 <optdesc><p>Debug: Shows the current state of all volumes.</p></optdesc> 302 </option> 303 304 <option> 305 <p><opt>shared</opt></p> 306 <optdesc><p>Debug: Show shared properties.</p></optdesc> 307 </option> 308 309 <option> 310 <p><opt>exit</opt></p> 311 <optdesc><p>Terminate the daemon. If you want to terminate a CLI 312 connection ("log out") you might want to use ctrl+d</p></optdesc> 313 </option> 314 </section> 315 316 <section name="Meta Commands"> 317 <p> 318 In addition to the commands described above there are a few meta directives 319 supported by the command line interpreter. 320 </p> 321 <option> 322 <p><opt>.include</opt> <arg>filename|folder</arg></p> 323 <optdesc><p>Executes the commands from the specified script file or in all 324 of the *.pa files within the folder.</p></optdesc> 325 </option> 326 <option> 327 <p><opt>.fail</opt> and <opt>.nofail</opt></p> 328 <optdesc><p>Enable (resp. disable) that following failing commands will 329 cancel the execution of the current script file. This is ignored when 330 used on the interactive command line.</p></optdesc> 331 </option> 332 <option> 333 <p><opt>.ifexists</opt> <arg>filename</arg></p> 334 <optdesc><p>Execute the subsequent block of commands only if the specified 335 file exists. Typically <arg>filename</arg> indicates a module. Relative 336 paths are resolved using the module directory as the base. By using an 337 absolute path, the existence of other files can be checked as well.</p></optdesc> 338 </option> 339 <option> 340 <p><opt>.else</opt> and <opt>.endif</opt></p> 341 <optdesc><p>A block of commands is delimited by an <opt>.else</opt> or 342 <opt>.endif</opt> meta command. Nesting conditional commands is not 343 supported.</p></optdesc> 344 </option> 345 </section> 346 347 <section name="Authors"> 348 <p>The PulseAudio Developers <@PACKAGE_BUGREPORT@>; 349 PulseAudio is available from <url href="@PACKAGE_URL@"/></p> 350 </section> 351 352 <section name="See also"> 353 <p> 354 <manref name="default.pa" section="5"/>, 355 <manref name="pacmd" section="1"/>, 356 <manref name="pulseaudio" section="1"/> 357 </p> 358 </section> 359 360</manpage> 361