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. Use the special name \@NONE@ to unset the user defined default sink or 147 source. In this case, pulseaudio will return to the default sink or source 148 selection based on priority.</p><p>Note that defaults may be overridden by 149 various policy modules or by specific stream configurations.</p></optdesc> 150 </option> 151 152 <option> 153 <p><opt>set-card-profile</opt> <arg>index|name</arg> <arg>profile-name</arg></p> 154 <optdesc><p>Change the profile of a card.</p></optdesc> 155 </option> 156 157 <option> 158 <p><opt>set-sink-port|set-source-port</opt> <arg>index|name</arg> <arg>port-name</arg></p> 159 <optdesc><p>Change the profile of a sink (resp. source).</p></optdesc> 160 </option> 161 162 <option> 163 <p><opt>set-port-latency-offset</opt> <arg>card-index|card-name</arg> <arg>port-name</arg> <arg>offset</arg> </p> 164 <optdesc><p>Change the latency offset of a port belonging to the specified card</p></optdesc> 165 </option> 166 167 <option> 168 <p><opt>suspend-sink|suspend-source</opt> <arg>name|index</arg> 169 <arg>true|false</arg> 170 </p> 171 <optdesc><p>Suspend or resume the specified sink or source (which may be 172 specified either by its name or index), depending whether true 173 (suspend) or false (resume) is passed as last argument. Suspending 174 a sink will pause all playback and suspending a source will pause all 175 capturing. Depending on the module implementing the sink or source this 176 might have the effect that the underlying device is closed, making it 177 available for other applications to use. The exact behaviour depends on 178 the module. 179 </p></optdesc> 180 </option> 181 182 <option> 183 <p><opt>suspend</opt> <arg>boolean</arg></p> 184 <optdesc><p>Suspend all sinks and sources.</p></optdesc> 185 </option> 186 </section> 187 188 <section name="Moving streams"> 189 <option> 190 <p><opt>move-sink-input|move-source-output</opt> <arg>index</arg> <arg>sink-index|sink-name</arg></p> 191 <optdesc><p>Move sink input (resp. source output) to another sink 192 (resp. source).</p></optdesc> 193 </option> 194 </section> 195 196 <section name="Property lists"> 197 <option> 198 <p><opt>update-sink-proplist|update-source-proplist</opt> <arg>index|name</arg> <arg>properties</arg></p> 199 <optdesc><p>Update the properties of a sink (resp. source) specified by 200 name or index. The property is specified as e.g. device.description="My 201 Preferred Name"</p></optdesc> 202 </option> 203 204 <option> 205 <p><opt>update-sink-input-proplist|update-source-output-proplist</opt> <arg>index</arg> <arg>properties</arg></p> 206 <optdesc><p>Update the properties of a sink input (resp. source output) 207 specified by index. The properties are specified as above.</p></optdesc> 208 </option> 209 </section> 210 211 <section name="Sample Cache"> 212 <option> 213 <p><opt>list-samples</opt></p> 214 <optdesc><p>Lists the contents of the sample cache.</p></optdesc> 215 </option> 216 217 <option> 218 <p><opt>play-sample</opt> <arg>name</arg> <arg>sink-index|sink-name</arg></p> 219 <optdesc><p>Play a sample cache entry to a sink.</p></optdesc> 220 </option> 221 222 <option> 223 <p><opt>remove-sample</opt> <arg>name</arg></p> 224 <optdesc><p>Remove an entry from the sample cache.</p></optdesc> 225 </option> 226 227 <option> 228 <p><opt>load-sample</opt> <arg>name</arg> <arg>filename</arg></p> 229 <optdesc><p>Load an audio file to the sample cache.</p></optdesc> 230 </option> 231 232 <option> 233 <p><opt>load-sample-lazy</opt> <arg>name</arg> <arg>filename</arg></p> 234 <optdesc><p>Create a new entry in the sample cache, but don't load the 235 sample immediately. The sample is loaded only when it is first used. 236 After a certain idle time it is freed again.</p></optdesc> 237 </option> 238 239 <option> 240 <p><opt>load-sample-dir-lazy</opt> <arg>path</arg></p> 241 <optdesc><p>Load all entries in the specified directory into the sample 242 cache as lazy entries. A shell globbing expression (e.g. *.wav) may be 243 appended to the path of the directory to add.</p></optdesc> 244 </option> 245 </section> 246 247 <section name="Killing Clients/Streams"> 248 <option> 249 <p><opt>kill-client</opt> <arg>index</arg></p> 250 <optdesc><p>Remove a client forcibly from the server. There is no protection 251 against the client reconnecting immediately.</p></optdesc> 252 </option> 253 254 <option> 255 <p><opt>kill-sink-input|kill-source-output</opt> <arg>index</arg></p> 256 <optdesc><p>Remove a sink input (resp. source output) forcibly from the 257 server. This will not remove the owning client or any other streams opened 258 by the same client from the server.</p></optdesc> 259 </option> 260 </section> 261 262 <section name="Log Commands"> 263 <option> 264 <p><opt>set-log-level</opt> <arg>numeric-level</arg></p> 265 <optdesc><p>Change the log level.</p></optdesc> 266 </option> 267 268 <option> 269 <p><opt>set-log-meta</opt> <arg>boolean</arg></p> 270 <optdesc><p>Show source code location in log messages.</p></optdesc> 271 </option> 272 273 <option> 274 <p><opt>set-log-target</opt> <arg>target</arg></p> 275 <optdesc><p>Change the log target (null, auto, journal, syslog, stderr, 276 file:PATH, newfile:PATH).</p></optdesc> 277 </option> 278 279 <option> 280 <p><opt>set-log-time</opt> <arg>boolean</arg></p> 281 <optdesc><p>Show timestamps in log messages.</p></optdesc> 282 </option> 283 284 <option> 285 <p><opt>set-log-backtrace</opt> <arg>num-frames</arg></p> 286 <optdesc><p>Show backtrace in log messages.</p></optdesc> 287 </option> 288 </section> 289 290 <section name="Miscellaneous Commands"> 291 <option> 292 <p><opt>play-file</opt> <arg>filename</arg> <arg>sink-index|sink-name</arg></p> 293 <optdesc><p>Play an audio file to a sink.</p></optdesc> 294 </option> 295 296 <option> 297 <p><opt>dump</opt></p> 298 <optdesc><p>Dump the daemon's current configuration in CLI commands.</p></optdesc> 299 </option> 300 301 <option> 302 <p><opt>dump-volumes</opt></p> 303 <optdesc><p>Debug: Shows the current state of all volumes.</p></optdesc> 304 </option> 305 306 <option> 307 <p><opt>shared</opt></p> 308 <optdesc><p>Debug: Show shared properties.</p></optdesc> 309 </option> 310 311 <option> 312 <p><opt>send-message</opt> <arg>recipient</arg> <arg>message</arg> <arg>message_parameters</arg></p> 313 <optdesc><p>Send a message to the specified recipient object. If applicable an additional string containing 314 message parameters can be specified. A string is returned as a response to the message. For available messages 315 see https://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/messaging_api.txt.</p></optdesc> 316 </option> 317 318 <option> 319 <p><opt>exit</opt></p> 320 <optdesc><p>Terminate the daemon. If you want to terminate a CLI 321 connection ("log out") you might want to use ctrl+d</p></optdesc> 322 </option> 323 </section> 324 325 <section name="Meta Commands"> 326 <p> 327 In addition to the commands described above there are a few meta directives 328 supported by the command line interpreter. 329 </p> 330 <option> 331 <p><opt>.include</opt> <arg>filename|folder</arg></p> 332 <optdesc><p>Executes the commands from the specified script file or in all 333 of the *.pa files within the folder.</p></optdesc> 334 </option> 335 <option> 336 <p><opt>.fail</opt> and <opt>.nofail</opt></p> 337 <optdesc><p>Enable (resp. disable) that following failing commands will 338 cancel the execution of the current script file. This is ignored when 339 used on the interactive command line.</p></optdesc> 340 </option> 341 <option> 342 <p><opt>.ifexists</opt> <arg>filename</arg></p> 343 <optdesc><p>Execute the subsequent block of commands only if the specified 344 file exists. Typically <arg>filename</arg> indicates a module. Relative 345 paths are resolved using the module directory as the base. By using an 346 absolute path, the existence of other files can be checked as well.</p></optdesc> 347 </option> 348 <option> 349 <p><opt>.else</opt> and <opt>.endif</opt></p> 350 <optdesc><p>A block of commands is delimited by an <opt>.else</opt> or 351 <opt>.endif</opt> meta command. Nesting conditional commands is not 352 supported.</p></optdesc> 353 </option> 354 </section> 355 356 <section name="Authors"> 357 <p>The PulseAudio Developers <@PACKAGE_BUGREPORT@>; 358 PulseAudio is available from <url href="@PACKAGE_URL@"/></p> 359 </section> 360 361 <section name="See also"> 362 <p> 363 <manref name="default.pa" section="5"/>, 364 <manref name="pacmd" section="1"/>, 365 <manref name="pulseaudio" section="1"/> 366 </p> 367 </section> 368 369</manpage> 370