From aa19646d34e57719ee87bb8c619ccc7d4ea4e9aa Mon Sep 17 00:00:00 2001
From: Colin Guthrie
Date: Thu, 5 Apr 2012 11:41:18 +0100
Subject: [PATCH] man: Document the cli inteface a little.
This just documents the cli interface syntax. Mostly a lift from
http://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/CLI
with some minor editing and bringing up to date.
Also document a few undocumented commands.
Shuffle around the order in 'pacmd help' output to match the order
in the new docs for consistency.
https://bugs.freedesktop.org/show_bug.cgi?id=45029
---
configure.ac | 1 +
man/Makefile.am | 3 +
man/default.pa.5.xml.in | 9 +-
man/pacmd.1.xml.in | 11 +-
man/pactl.1.xml.in | 7 +-
man/pulse-cli-syntax.5.xml.in | 335 ++++++++++++++++++++++++++++++++++++++++++
src/pulsecore/cli-command.c | 44 +++---
7 files changed, 379 insertions(+), 31 deletions(-)
create mode 100644 man/pulse-cli-syntax.5.xml.in
diff --git a/configure.ac b/configure.ac
index 7bdd401..efcb753 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1330,6 +1330,7 @@ man/padsp.1.xml
man/pulse-daemon.conf.5.xml
man/pulse-client.conf.5.xml
man/default.pa.5.xml
+man/pulse-cli-syntax.5.xml
man/start-pulseaudio-kde.1.xml
man/start-pulseaudio-x11.1.xml
])
diff --git a/man/Makefile.am b/man/Makefile.am
index b27a9f2..d0cc8e7 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -31,6 +31,7 @@ noinst_DATA = \
pulse-daemon.conf.5.xml \
pulse-client.conf.5.xml \
default.pa.5.xml \
+ pulse-cli-syntax.5.xml \
start-pulseaudio-kde.1.xml \
start-pulseaudio-x11.1.xml
@@ -54,6 +55,7 @@ dist_man_MANS = \
pulse-daemon.conf.5 \
pulse-client.conf.5 \
default.pa.5 \
+ pulse-cli-syntax.5 \
start-pulseaudio-kde.1 \
start-pulseaudio-x11.1
@@ -78,6 +80,7 @@ EXTRA_DIST = \
pulse-daemon.conf.5.xml.in \
pulse-client.conf.5.xml.in \
default.pa.5.xml.in \
+ pulse-cli-syntax.5.xml.in \
start-pulseaudio-kde.1.xml.in \
start-pulseaudio-x11.1.xml.in \
xmltoman \
diff --git a/man/default.pa.5.xml.in b/man/default.pa.5.xml.in
index 1ec618d..fb5b2d2 100644
--- a/man/default.pa.5.xml.in
+++ b/man/default.pa.5.xml.in
@@ -34,7 +34,7 @@ USA.
~/.pulse/default.pa on startup, and when that file
doesn't exist @PA_DEFAULT_CONFIG_DIR@/default.pa . It
should contain directives in the PulseAudio CLI languages, as
- documented on .
+ documented in .
The same commands can also be entered during runtime in the tool, allowing flexible runtime reconfiguration.
@@ -47,9 +47,10 @@ USA.
diff --git a/man/pacmd.1.xml.in b/man/pacmd.1.xml.in
index c20c016..079eb61 100644
--- a/man/pacmd.1.xml.in
+++ b/man/pacmd.1.xml.in
@@ -34,7 +34,11 @@ USA.
the commands also understood in the default.pa
configuration scripts.
- This program takes no command line options.
+ To exit the live shell, use ctrl+d. Note that the 'exit' command
+ inside the shell will tell the PulseAudio daemon itself to shutdown!
+
+ If any arguments are passed on the command line, they will be
+ passed into the live shell which will process the command and exit.
@@ -43,7 +47,10 @@ USA.
diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in
index 688ac38..86e7609 100644
--- a/man/pactl.1.xml.in
+++ b/man/pactl.1.xml.in
@@ -66,7 +66,7 @@ USA.
- stat [short]
+ stat [short ]
Dump a few statistics about the memory usage of the PulseAudio daemon. (Note: for backwards
compatibility, we also show the output of the info command. In order to only show
statistics, use the optional short argument. In a future version of PA we will
@@ -79,7 +79,7 @@ USA.
- list [short] [TYPE ]
+ list [short ] [TYPE ]
Dump all currently loaded modules, available sinks, sources, streams, etc. TYPE must be one of:
modules, sinks, sources, sink-inputs, source-outputs, clients, samples, cards. If not specified, all info is listed. If
short is given, output is in a tabular format, for easy parsing by scripts.
@@ -243,7 +243,8 @@ USA.
- ,
+ ,
+
diff --git a/man/pulse-cli-syntax.5.xml.in b/man/pulse-cli-syntax.5.xml.in
new file mode 100644
index 0000000..4f4e838
--- /dev/null
+++ b/man/pulse-cli-syntax.5.xml.in
@@ -0,0 +1,335 @@
+
+
+
+
+
+
+
+
+
+ ~/.pulse/default.pa
+ @PA_DEFAULT_CONFIG_DIR@/default.pa
+ @PA_DEFAULT_CONFIG_DIR@/system.pa
+
+
+
+
+ PulseAudio provides a simple command line language used by configuration
+ scripts and the pacmd interactive shell, and the modules module-cli and
+ module-cli-protocol-{unix,tcp}. Empty lines and lines beginning with a
+ hashmark (#) are silently ignored. Several commands are supported.
+
+
+
+ Note that any boolean arguments can be given positively as '1', 'on' or any
+ word starting with the letters 't' or 'y'. Likewise, negative values can be
+ given as '0', 'off' or any word starting with the letters 'f' or 'n'.
+ Case is ignored.
+
+
+
+
+
+
+ help
+ Show a quick help on the commands available.
+
+
+
+
+
+ list-modules
+ Show all currently loaded modules with their arguments.
+
+
+
+ list-cards
+ Show all currently registered cards
+
+
+
+ list-sinks or list-sources
+ Show all currently registered sinks (resp. sources).
+
+
+
+ list-clients
+ Show all currently active clients.
+
+
+
+ list-sink-inputs or list-source-outputs
+ Show all currently active inputs to sinks a.k.a. playback
+ streams (resp. outputs of sources a.k.a. recording streams).
+
+
+
+ stat
+ Show some simple statistics about the allocated memory blocks and the space used by them.
+
+
+
+ info or ls or list
+ A combination of all status commands described above (all
+ three commands are synonyms).
+
+
+
+
+
+ load-module name [arguments... ]
+ Load a module specified by its name and arguments. For most
+ modules it is OK to be loaded more than once.
+
+
+
+ unload-module index
+ Unload a module specified by its index in the module list as
+ returned by list-modules.
+
+
+
+ describe-module name
+ Give information about a module specified by its name.
+
+
+
+
+
+ set-sink-volume|set-source-volume index|name volume
+ Set the volume of the specified sink (resp. source). You may
+ specify the sink (resp. source) either by its index in the sink/source list
+ or by its name. The volume should be an integer value greater or equal than
+ 0 (muted). Volume 65536 (0x10000) is 'normal' volume a.k.a. 100%. Values
+ greater than this amplify the audio signal (with clipping).
+
+
+
+ set-sink-mute|set-source-mute index|name boolean
+ Mute or unmute the specified sink (resp. source). You may
+ specify the sink (resp. source) either by its index or by its name.
+ The mute value is either 0 (not muted) or 1 (muted).
+
+
+
+ set-sink-input-volume index volume
+ Set the volume of a sink input specified
+ by its index. The same volume rules apply as with set-sink-volume.
+
+
+
+ set-sink-input-mute index boolean
+ Mute or unmute a sink input specified
+ by its index. The same mute rules apply as with set-sink-mute.
+
+
+
+
+
+ set-default-sink|set-default-source index|name
+ Make a sink (resp. source) the default. You may specify the
+ sink (resp. source) by its index in the sink (resp. source) list or by its
+ name.
Note that defaults may be overridden by various policy modules
+ or by specific stream configurations.
+
+
+
+ set-card-profile index|name profile-name
+ Change the profile of a card.
+
+
+
+ set-sink-port|set-source-port index|name port-name
+ Change the profile of a sink (resp. source).
+
+
+
+ suspend-sink|suspend-source index|name boolean
+ Suspend (i.e. disconnect from the underlying hardware) a sink
+ (resp. source).
+
+
+
+ suspend boolean
+ Suspend all sinks and sources.
+
+
+
+
+
+ move-sink-input|move-source-output index sink-index|sink-name
+ Move sink input (resp. source output) to another sink
+ (resp. source).
+
+
+
+
+
+ update-sink-proplist|update-source-proplist index|name properties
+ Update the properties of a sink (resp. source) specified by
+ name or index. The property is specified as e.g. device.description="My
+ Preferred Name"
+
+
+
+ update-sink-input-proplist|update-source-output-proplist index properties
+ Update the properties of a sink input (resp. source output)
+ specified by index. The properties are specified as above.
+
+
+
+
+
+ list-samples
+ Lists the contents of the sample cache.
+
+
+
+ play-sample name sink-index|sink-name
+ Play a sample cache entry to a sink.
+
+
+
+ remove-sample name
+ Remove an entry from the sample cache.
+
+
+
+ load-sample name filename
+ Load an audio file to the sample cache.
+
+
+
+ load-sample-lazy name filename
+ Create a new entry in the sample cache, but don't load the
+ sample immediately. The sample is loaded only when it is first used.
+ After a certain idle time it is freed again.
+
+
+
+ load-sample-dir-lazy path
+ Load all entries in the specified directory into the sample
+ cache as lazy entries. A shell globbing expression (e.g. *.wav) may be
+ appended to the path of the directory to add.
+
+
+
+
+
+ kill-client index
+ Remove a client forcibly from the server. There is no protection
+ against the client reconnecting immediately.
+
+
+
+ kill-sink-input|kill-source-output index
+ Remove a sink input (resp. source output) forcibly from the
+ server. This will not remove the owning client or any other streams opened
+ by the same client from the server.
+
+
+
+
+
+ set-log-level numeric-level
+ Change the log level.
+
+
+
+ set-log-meta boolean
+ Show source code location in log messages.
+
+
+
+ set-log-time boolean
+ Show timestamps in log messages.
+
+
+
+ set-log-backtrace num-frames
+ Show backtrace in log messages.
+
+
+
+
+
+ play-file filename sink-index|sink-name
+ Play an audio file to a sink.
+
+
+
+ dump
+ Dump the daemon's current configuration in CLI commands.
+
+
+
+ dump-volumes
+ Debug: Shows the current state of all volumes.
+
+
+
+ shared
+ Debug: Show shared properties.
+
+
+
+ exit
+ Terminate the daemon. If you want to terminate a CLI
+ connection ("log out") you might want to use ctrl+d
+
+
+
+
+
+ In addition the the commands described above there a few meta directives
+ supported by the command line interpreter.
+
+
+ .include filename|folder
+ Executes the commands from the specified script file or in all
+ of the *.pa file within the folder.
+
+
+ .fail and .nofail
+ Enable (resp. disable) that following failing commands will
+ cancel the execution of the current script file. This is a ignored when
+ used on the interactive command line.
+
+
+
+ .verbose and .noverbose
+ Enable (resp. disable) extra verbosity.
+
+
+
+
+ The PulseAudio Developers <@PACKAGE_BUGREPORT@>;
+ PulseAudio is available from
+
+
+
+
+
diff --git a/src/pulsecore/cli-command.c b/src/pulsecore/cli-command.c
index a43b7ca..fd265d5 100644
--- a/src/pulsecore/cli-command.c
+++ b/src/pulsecore/cli-command.c
@@ -135,15 +135,14 @@ static int pa_cli_command_dump_volumes(pa_core *c, pa_tokenizer *t, pa_strbuf *b
/* A method table for all available commands */
static const struct command commands[] = {
- { "exit", pa_cli_command_exit, "Terminate the daemon", 1 },
{ "help", pa_cli_command_help, "Show this help", 1 },
{ "list-modules", pa_cli_command_modules, "List loaded modules", 1 },
+ { "list-cards", pa_cli_command_cards, "List cards", 1 },
{ "list-sinks", pa_cli_command_sinks, "List loaded sinks", 1 },
{ "list-sources", pa_cli_command_sources, "List loaded sources", 1 },
{ "list-clients", pa_cli_command_clients, "List loaded clients", 1 },
{ "list-sink-inputs", pa_cli_command_sink_inputs, "List sink inputs", 1 },
{ "list-source-outputs", pa_cli_command_source_outputs, "List source outputs", 1 },
- { "list-cards", pa_cli_command_cards, "List cards", 1 },
{ "stat", pa_cli_command_stat, "Show memory block statistics", 1 },
{ "info", pa_cli_command_info, "Show comprehensive status", 1 },
{ "ls", pa_cli_command_info, NULL, 1 },
@@ -152,43 +151,44 @@ static const struct command commands[] = {
{ "unload-module", pa_cli_command_unload, "Unload a module (args: index)", 2},
{ "describe-module", pa_cli_command_describe, "Describe a module (arg: name)", 2},
{ "set-sink-volume", pa_cli_command_sink_volume, "Set the volume of a sink (args: index|name, volume)", 3},
- { "set-sink-input-volume", pa_cli_command_sink_input_volume, "Set the volume of a sink input (args: index, volume)", 3},
{ "set-source-volume", pa_cli_command_source_volume, "Set the volume of a source (args: index|name, volume)", 3},
{ "set-sink-mute", pa_cli_command_sink_mute, "Set the mute switch of a sink (args: index|name, bool)", 3},
- { "set-sink-input-mute", pa_cli_command_sink_input_mute, "Set the mute switch of a sink input (args: index, bool)", 3},
{ "set-source-mute", pa_cli_command_source_mute, "Set the mute switch of a source (args: index|name, bool)", 3},
+ { "set-sink-input-volume", pa_cli_command_sink_input_volume, "Set the volume of a sink input (args: index, volume)", 3},
+ { "set-sink-input-mute", pa_cli_command_sink_input_mute, "Set the mute switch of a sink input (args: index, bool)", 3},
+ { "set-default-sink", pa_cli_command_sink_default, "Set the default sink (args: index|name)", 2},
+ { "set-default-source", pa_cli_command_source_default, "Set the default source (args: index|name)", 2},
+ { "set-card-profile", pa_cli_command_card_profile, "Change the profile of a card (args: index|name, profile-name)", 3},
+ { "set-sink-port", pa_cli_command_sink_port, "Change the port of a sink (args: index|name, port-name)", 3},
+ { "set-source-port", pa_cli_command_source_port, "Change the port of a source (args: index|name, port-name)", 3},
+ { "suspend-sink", pa_cli_command_suspend_sink, "Suspend sink (args: index|name, bool)", 3},
+ { "suspend-source", pa_cli_command_suspend_source, "Suspend source (args: index|name, bool)", 3},
+ { "suspend", pa_cli_command_suspend, "Suspend all sinks and all sources (args: bool)", 2},
+ { "move-sink-input", pa_cli_command_move_sink_input, "Move sink input to another sink (args: index, sink)", 3},
+ { "move-source-output", pa_cli_command_move_source_output, "Move source output to another source (args: index, source)", 3},
{ "update-sink-proplist", pa_cli_command_update_sink_proplist, "Update the properties of a sink (args: index|name, properties)", 3},
{ "update-source-proplist", pa_cli_command_update_source_proplist, "Update the properties of a source (args: index|name, properties)", 3},
{ "update-sink-input-proplist", pa_cli_command_update_sink_input_proplist, "Update the properties of a sink input (args: index, properties)", 3},
{ "update-source-output-proplist", pa_cli_command_update_source_output_proplist, "Update the properties of a source_output (args: index, properties)", 3},
- { "set-default-sink", pa_cli_command_sink_default, "Set the default sink (args: index|name)", 2},
- { "set-default-source", pa_cli_command_source_default, "Set the default source (args: index|name)", 2},
- { "kill-client", pa_cli_command_kill_client, "Kill a client (args: index)", 2},
- { "kill-sink-input", pa_cli_command_kill_sink_input, "Kill a sink input (args: index)", 2},
- { "kill-source-output", pa_cli_command_kill_source_output, "Kill a source output (args: index)", 2},
{ "list-samples", pa_cli_command_scache_list, "List all entries in the sample cache", 1},
{ "play-sample", pa_cli_command_scache_play, "Play a sample from the sample cache (args: name, sink|index)", 3},
{ "remove-sample", pa_cli_command_scache_remove, "Remove a sample from the sample cache (args: name)", 2},
{ "load-sample", pa_cli_command_scache_load, "Load a sound file into the sample cache (args: name, filename)", 3},
{ "load-sample-lazy", pa_cli_command_scache_load, "Lazily load a sound file into the sample cache (args: name, filename)", 3},
{ "load-sample-dir-lazy", pa_cli_command_scache_load_dir, "Lazily load all files in a directory into the sample cache (args: pathname)", 2},
- { "play-file", pa_cli_command_play_file, "Play a sound file (args: filename, sink|index)", 3},
- { "dump", pa_cli_command_dump, "Dump daemon configuration", 1},
- { "shared", pa_cli_command_list_shared_props, NULL, 1},
- { "move-sink-input", pa_cli_command_move_sink_input, "Move sink input to another sink (args: index, sink)", 3},
- { "move-source-output", pa_cli_command_move_source_output, "Move source output to another source (args: index, source)", 3},
- { "vacuum", pa_cli_command_vacuum, NULL, 1},
- { "suspend-sink", pa_cli_command_suspend_sink, "Suspend sink (args: index|name, bool)", 3},
- { "suspend-source", pa_cli_command_suspend_source, "Suspend source (args: index|name, bool)", 3},
- { "suspend", pa_cli_command_suspend, "Suspend all sinks and all sources (args: bool)", 2},
- { "set-card-profile", pa_cli_command_card_profile, "Change the profile of a card (args: index, name)", 3},
- { "set-sink-port", pa_cli_command_sink_port, "Change the port of a sink (args: index, name)", 3},
- { "set-source-port", pa_cli_command_source_port, "Change the port of a source (args: index, name)", 3},
+ { "kill-client", pa_cli_command_kill_client, "Kill a client (args: index)", 2},
+ { "kill-sink-input", pa_cli_command_kill_sink_input, "Kill a sink input (args: index)", 2},
+ { "kill-source-output", pa_cli_command_kill_source_output, "Kill a source output (args: index)", 2},
{ "set-log-level", pa_cli_command_log_level, "Change the log level (args: numeric level)", 2},
{ "set-log-meta", pa_cli_command_log_meta, "Show source code location in log messages (args: bool)", 2},
{ "set-log-time", pa_cli_command_log_time, "Show timestamps in log messages (args: bool)", 2},
{ "set-log-backtrace", pa_cli_command_log_backtrace, "Show backtrace in log messages (args: frames)", 2},
- { "dump-volumes", pa_cli_command_dump_volumes, NULL, 1 },
+ { "play-file", pa_cli_command_play_file, "Play a sound file (args: filename, sink|index)", 3},
+ { "dump", pa_cli_command_dump, "Dump daemon configuration", 1},
+ { "dump-volumes", pa_cli_command_dump_volumes, "Debug: Show the state of all volumes", 1 },
+ { "shared", pa_cli_command_list_shared_props, "Debug: Show shared properties", 1},
+ { "exit", pa_cli_command_exit, "Terminate the daemon", 1 },
+ { "vacuum", pa_cli_command_vacuum, NULL, 1},
{ NULL, NULL, NULL, 0 }
};
--
2.7.4