mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-11-02 09:01:50 -05:00
man: update man pages
Add man page for pipewire-cli
This commit is contained in:
Wim Taymans
parent
6af4f08c6e
commit
807af5b983
5 changed files with 220 additions and 33 deletions
|
|
@ -7,6 +7,7 @@ manpage_conf.set('top_srcdir', meson.source_root())
|
|||
manpage_conf.set('top_builddir', meson.build_root())
|
||||
|
||||
manpages = ['pipewire.1',
|
||||
'pipewire-cli.1',
|
||||
'pipewire-monitor.1' ]
|
||||
|
||||
foreach m : manpages
|
||||
|
|
|
|||
165
man/pipewire-cli.1.xml.in
Normal file
165
man/pipewire-cli.1.xml.in
Normal file
|
|
@ -0,0 +1,165 @@
|
|||
<?xml version="1.0"?><!--*-nxml-*-->
|
||||
<!DOCTYPE manpage SYSTEM "xmltoman.dtd">
|
||||
<?xml-stylesheet type="text/xsl" href="xmltoman.xsl" ?>
|
||||
|
||||
<!--
|
||||
This file is part of PipeWire.
|
||||
|
||||
PipeWire is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU Lesser General Public License as
|
||||
published by the Free Software Foundation; either version 2.1 of the
|
||||
License, or (at your option) any later version.
|
||||
|
||||
PipeWire is distributed in the hope that it will be useful, but WITHOUT
|
||||
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
|
||||
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
|
||||
Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public
|
||||
License along with PipeWire; if not, see <http://www.gnu.org/licenses/>.
|
||||
-->
|
||||
|
||||
<manpage name="pipewire-cli" section="1" desc="The PipeWire Command Line Interface">
|
||||
|
||||
<synopsis>
|
||||
<cmd>pipewire-cli</cmd>
|
||||
</synopsis>
|
||||
|
||||
<description>
|
||||
<p>Interact with a PipeWire instance.</p>
|
||||
|
||||
<p><manref name="pipewire-cli" section="1"/> starts an interactive session
|
||||
with a pipewire instance. By default, a connection is made with the local
|
||||
PipeWire instance, that of the pipewire-cli command itself.</p>
|
||||
|
||||
<p>Connections to other, remote instances can be made. The current instance
|
||||
name is displayed at the prompt. Some commands operate on the current
|
||||
instance and some on the local instance.</p>
|
||||
|
||||
<p>Use the 'help' command to list the available commands.</p>
|
||||
|
||||
</description>
|
||||
|
||||
<section name="General commands">
|
||||
<option>
|
||||
<p><opt>help</opt></p>
|
||||
<optdesc><p>Show a quick help on the commands available.</p></optdesc>
|
||||
</option>
|
||||
</section>
|
||||
|
||||
<section name="Module Management">
|
||||
<p>Modules are loaded and unloaded in the local instance and can add
|
||||
functionality or objects to the local instance.</p>
|
||||
<option>
|
||||
<p><opt>load-module</opt> <arg>name</arg> [<arg>arguments...</arg>]</p>
|
||||
<optdesc><p>Load a module specified by its name and arguments. For most
|
||||
modules it is OK to be loaded more than once.</p>
|
||||
<p>This command returns a module variable that can be used
|
||||
to unload the module.</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>unload-module</opt> <arg>module-var</arg></p>
|
||||
<optdesc><p>Unload a module, specified either by its variable.</p></optdesc>
|
||||
</option>
|
||||
</section>
|
||||
|
||||
<section name="Object Introspection">
|
||||
<option>
|
||||
<p><opt>list-objects</opt></p>
|
||||
<optdesc><p>List the objects of the current instance.</p>
|
||||
<p>Objects are listed with their id, type and version.</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>info</opt> <arg>id|all</arg></p>
|
||||
<optdesc><p>Get information about a specific object or all objects.</p>
|
||||
<p>Requesting info about an object will also notify you of changes.</p>
|
||||
</optdesc>
|
||||
</option>
|
||||
</section>
|
||||
|
||||
<section name="Working with remotes">
|
||||
<option>
|
||||
<p><opt>connect</opt> [<arg>remote-name</arg>]</p>
|
||||
<optdesc><p>Connect to a remote instance and make this the new current
|
||||
instance.</p><p>If no remote name is specified, a connection is made to
|
||||
the default remote instance, usually pipewire-0</p>
|
||||
<p>This command returns a remote var that can be used to disconnect or
|
||||
switch remotes</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>disconnect</opt> [<arg>remote-var</arg>]</p>
|
||||
<optdesc><p>Disconnect from a remote instance.</p>
|
||||
<p>If no remote name is specified, the current instance is disconnected.
|
||||
</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>list-remotes</opt></p>
|
||||
<optdesc><p>List all remote instances.</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>switch-remote</opt> [<arg>remote-var</arg>]</p>
|
||||
<optdesc><p>Make the specified remote the current instance.</p>
|
||||
<p>If no remote name is specified, the local instance is made current.
|
||||
</p></optdesc>
|
||||
</option>
|
||||
</section>
|
||||
|
||||
<section name="Node management">
|
||||
<option>
|
||||
<p><opt>create-node</opt> <arg>factory-name</arg> [<arg>properties...</arg>]</p>
|
||||
<optdesc><p>Create a node from a factory in the current instance.</p>
|
||||
<p>Properties are key=value pairs separated by whitespace</p>
|
||||
<p>This command returns a node variable.</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>destroy-node</opt> <arg>node-var</arg></p>
|
||||
<optdesc><p>Destroy a node</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>export-node</opt> <arg>node-id</arg> [<arg>remote-var</arg>]</p>
|
||||
<optdesc><p>Export a node from the local instance to the specified instance.
|
||||
When no instance is specified, the node will be exported to the current
|
||||
instance.</p></optdesc>
|
||||
</option>
|
||||
</section>
|
||||
|
||||
<section name="Link management">
|
||||
<option>
|
||||
<p><opt>create-link</opt>
|
||||
<arg>node-id</arg> <arg>port-id</arg>
|
||||
<arg>node-id</arg> <arg>port-id</arg> [<arg>properties...</arg>]</p>
|
||||
<optdesc><p>Create a link between 2 nodes and ports.</p>
|
||||
<p>Port ids can be -1 to automatically select an available port.</p>
|
||||
<p>Properties are key=value pairs separated by whitespace</p>
|
||||
<p>This command returns a link variable.</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>destroy-link</opt> <arg>link-var</arg></p>
|
||||
<optdesc><p>Destroy a link</p></optdesc>
|
||||
</option>
|
||||
</section>
|
||||
|
||||
<section name="Examples">
|
||||
<p></p>
|
||||
</section>
|
||||
|
||||
<section name="Authors">
|
||||
<p>The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from <url href="@PACKAGE_URL@"/></p>
|
||||
</section>
|
||||
|
||||
<section name="See also">
|
||||
<p>
|
||||
<manref name="pipewire" section="1"/>,
|
||||
<manref name="pipewire-monitor" section="1"/>,
|
||||
</p>
|
||||
</section>
|
||||
|
||||
</manpage>
|
||||
|
|
@ -22,15 +22,21 @@ License along with PipeWire; if not, see <http://www.gnu.org/licenses/>.
|
|||
<manpage name="pipewire-monitor" section="1" desc="The PipeWire monitor">
|
||||
|
||||
<synopsis>
|
||||
<cmd>pipewire</cmd>
|
||||
<cmd>pipewire-monitor [<arg>remote-name</arg>]</cmd>
|
||||
</synopsis>
|
||||
|
||||
<description>
|
||||
<p>Monitor objects on the PipeWire service.</p>
|
||||
<p>Monitor objects on the PipeWire instance.</p>
|
||||
</description>
|
||||
|
||||
<options>
|
||||
|
||||
<option>
|
||||
<p><opt>remote-name</opt></p>
|
||||
<optdesc><p>The name the remote instance to monitor. If left unspecified,
|
||||
a connection is made to the default PipeWire instance.</p></optdesc>
|
||||
</option>
|
||||
|
||||
<option>
|
||||
<p><opt>-h | --help</opt></p>
|
||||
|
||||
|
|
|
|||
|
|
@ -162,18 +162,18 @@ static bool do_export_node(struct data *data, const char *cmd, char *args, char
|
|||
static struct command command_list[] = {
|
||||
{ "help", "Show this help", do_help },
|
||||
{ "load-module", "Load a module. <module-name> [<module-arguments>]", do_load_module },
|
||||
{ "unload-module", "Unload a module. $<module-var>", do_not_implemented },
|
||||
{ "unload-module", "Unload a module. <module-var>", do_not_implemented },
|
||||
{ "connect", "Connect to a remote. [<remote-name>]", do_connect },
|
||||
{ "disconnect", "Disconnect from a remote. [$<remote-var>]", do_disconnect },
|
||||
{ "disconnect", "Disconnect from a remote. [<remote-var>]", do_disconnect },
|
||||
{ "list-remotes", "List connected remotes.", do_list_remotes },
|
||||
{ "switch-remote", "Switch between current remotes. [$<remote-var>]", do_switch_remote },
|
||||
{ "switch-remote", "Switch between current remotes. [<remote-var>]", do_switch_remote },
|
||||
{ "list-objects", "List objects or current remote.", do_list_objects },
|
||||
{ "info", "Get info about an object. <object-id>|all", do_info },
|
||||
{ "create-node", "Create a node from a factory. <factory-name> <name> [<properties>]", do_create_node },
|
||||
{ "destroy-node", "Destroy a node. $<node-var>", do_destroy_node },
|
||||
{ "create-node", "Create a node from a factory. <factory-name> [<properties>]", do_create_node },
|
||||
{ "destroy-node", "Destroy a node. <node-var>", do_destroy_node },
|
||||
{ "create-link", "Create a link between nodes. <node-id> <port-id> <node-id> <port-id> [<properties>]", do_create_link },
|
||||
{ "destroy-link", "Destroy a link. $<link-var>", do_destroy_link },
|
||||
{ "export-node", "Export a local node to the current remote. <node-id>", do_export_node },
|
||||
{ "destroy-link", "Destroy a link. <link-var>", do_destroy_link },
|
||||
{ "export-node", "Export a local node to the current remote. <node-id> [remote-var]", do_export_node },
|
||||
};
|
||||
|
||||
static bool do_help(struct data *data, const char *cmd, char *args, char **error)
|
||||
|
|
@ -207,7 +207,7 @@ static bool do_load_module(struct data *data, const char *cmd, char *args, char
|
|||
}
|
||||
|
||||
id = pw_map_insert_new(&data->vars, module);
|
||||
fprintf(stdout, "$%d = @module:%d\n", id, pw_global_get_id(pw_module_get_global(module)));
|
||||
fprintf(stdout, "%d = @module:%d\n", id, pw_global_get_id(pw_module_get_global(module)));
|
||||
|
||||
return true;
|
||||
}
|
||||
|
|
@ -216,7 +216,7 @@ static void on_info_changed(void *_data, const struct pw_core_info *info)
|
|||
{
|
||||
struct remote_data *rd = _data;
|
||||
rd->name = info->name;
|
||||
fprintf(stdout, "remote $%d is named '%s'\n", rd->id, rd->name);
|
||||
fprintf(stdout, "remote %d is named '%s'\n", rd->id, rd->name);
|
||||
}
|
||||
|
||||
static void show_prompt(struct remote_data *rd)
|
||||
|
|
@ -268,7 +268,7 @@ static void registry_event_global(void *data, uint32_t id, uint32_t parent_id,
|
|||
global->type = type;
|
||||
global->version = version;
|
||||
|
||||
fprintf(stdout, "remote $%d added global: ", rd->id);
|
||||
fprintf(stdout, "remote %d added global: ", rd->id);
|
||||
print_global(global, NULL);
|
||||
|
||||
size = pw_map_get_size(&rd->globals);
|
||||
|
|
@ -294,11 +294,11 @@ static void registry_event_global_remove(void *data, uint32_t id)
|
|||
|
||||
global = pw_map_lookup(&rd->globals, id);
|
||||
if (global == NULL) {
|
||||
fprintf(stdout, "remote $%d removed unknown global %d\n", rd->id, id);
|
||||
fprintf(stdout, "remote %d removed unknown global %d\n", rd->id, id);
|
||||
return;
|
||||
}
|
||||
|
||||
fprintf(stdout, "remote $%d removed global: ", rd->id);
|
||||
fprintf(stdout, "remote %d removed global: ", rd->id);
|
||||
print_global(global, NULL);
|
||||
destroy_global(global, rd);
|
||||
}
|
||||
|
|
@ -333,12 +333,12 @@ static void on_state_changed(void *_data, enum pw_remote_state old,
|
|||
|
||||
switch (state) {
|
||||
case PW_REMOTE_STATE_ERROR:
|
||||
fprintf(stderr, "remote $%d error: %s\n", rd->id, error);
|
||||
fprintf(stderr, "remote %d error: %s\n", rd->id, error);
|
||||
pw_main_loop_quit(data->loop);
|
||||
break;
|
||||
|
||||
case PW_REMOTE_STATE_CONNECTED:
|
||||
fprintf(stdout, "remote $%d state: \"%s\"\n", rd->id, pw_remote_state_as_string(state));
|
||||
fprintf(stdout, "remote %d state: \"%s\"\n", rd->id, pw_remote_state_as_string(state));
|
||||
rd->core_proxy = pw_remote_get_core_proxy(rd->remote);
|
||||
rd->registry_proxy = pw_core_proxy_get_registry(rd->core_proxy,
|
||||
t->registry,
|
||||
|
|
@ -350,7 +350,7 @@ static void on_state_changed(void *_data, enum pw_remote_state old,
|
|||
break;
|
||||
|
||||
default:
|
||||
fprintf(stdout, "remote $%d state: \"%s\"\n", rd->id, pw_remote_state_as_string(state));
|
||||
fprintf(stdout, "remote %d state: \"%s\"\n", rd->id, pw_remote_state_as_string(state));
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
|
@ -385,7 +385,7 @@ static bool do_connect(struct data *data, const char *cmd, char *args, char **er
|
|||
rd->id = pw_map_insert_new(&data->vars, rd);
|
||||
spa_list_append(&data->remotes, &rd->link);
|
||||
|
||||
fprintf(stdout, "$%d = @remote:%p\n", rd->id, remote);
|
||||
fprintf(stdout, "%d = @remote:%p\n", rd->id, remote);
|
||||
data->current = rd;
|
||||
|
||||
pw_remote_add_listener(remote, &rd->remote_listener, &remote_events, rd);
|
||||
|
|
@ -431,7 +431,7 @@ static bool do_list_remotes(struct data *data, const char *cmd, char *args, char
|
|||
struct remote_data *rd;
|
||||
|
||||
spa_list_for_each(rd, &data->remotes, link)
|
||||
fprintf(stdout, "\t$%d = @remote:%p '%s'\n", rd->id, rd->remote, rd->name);
|
||||
fprintf(stdout, "\t%d = @remote:%p '%s'\n", rd->id, rd->remote, rd->name);
|
||||
|
||||
return true;
|
||||
}
|
||||
|
|
@ -591,7 +591,7 @@ static void core_event_info(void *object, struct pw_core_info *info)
|
|||
struct proxy_data *pd = object;
|
||||
struct remote_data *rd = pd->rd;
|
||||
if (pd->info)
|
||||
fprintf(stdout, "remote $%d core %d changed\n", rd->id, info->id);
|
||||
fprintf(stdout, "remote %d core %d changed\n", rd->id, info->id);
|
||||
pd->info = pw_core_info_update(pd->info, info);
|
||||
if (pd->global == NULL)
|
||||
pd->global = pw_map_lookup(&rd->globals, info->id);
|
||||
|
|
@ -612,7 +612,7 @@ static void module_event_info(void *object, struct pw_module_info *info)
|
|||
struct proxy_data *pd = object;
|
||||
struct remote_data *rd = pd->rd;
|
||||
if (pd->info)
|
||||
fprintf(stdout, "remote $%d module %d changed\n", rd->id, info->id);
|
||||
fprintf(stdout, "remote %d module %d changed\n", rd->id, info->id);
|
||||
pd->info = pw_module_info_update(pd->info, info);
|
||||
if (pd->global == NULL)
|
||||
pd->global = pw_map_lookup(&rd->globals, info->id);
|
||||
|
|
@ -632,7 +632,7 @@ static void node_event_info(void *object, struct pw_node_info *info)
|
|||
struct proxy_data *pd = object;
|
||||
struct remote_data *rd = pd->rd;
|
||||
if (pd->info)
|
||||
fprintf(stdout, "remote $%d node %d changed\n", rd->id, info->id);
|
||||
fprintf(stdout, "remote %d node %d changed\n", rd->id, info->id);
|
||||
pd->info = pw_node_info_update(pd->info, info);
|
||||
if (pd->global == NULL)
|
||||
pd->global = pw_map_lookup(&rd->globals, info->id);
|
||||
|
|
@ -652,7 +652,7 @@ static void factory_event_info(void *object, struct pw_factory_info *info)
|
|||
struct proxy_data *pd = object;
|
||||
struct remote_data *rd = pd->rd;
|
||||
if (pd->info)
|
||||
fprintf(stdout, "remote $%d factory %d changed\n", rd->id, info->id);
|
||||
fprintf(stdout, "remote %d factory %d changed\n", rd->id, info->id);
|
||||
pd->info = pw_factory_info_update(pd->info, info);
|
||||
if (pd->global == NULL)
|
||||
pd->global = pw_map_lookup(&rd->globals, info->id);
|
||||
|
|
@ -672,7 +672,7 @@ static void client_event_info(void *object, struct pw_client_info *info)
|
|||
struct proxy_data *pd = object;
|
||||
struct remote_data *rd = pd->rd;
|
||||
if (pd->info)
|
||||
fprintf(stdout, "remote $%d client %d changed\n", rd->id, info->id);
|
||||
fprintf(stdout, "remote %d client %d changed\n", rd->id, info->id);
|
||||
pd->info = pw_client_info_update(pd->info, info);
|
||||
if (pd->global == NULL)
|
||||
pd->global = pw_map_lookup(&rd->globals, info->id);
|
||||
|
|
@ -692,7 +692,7 @@ static void link_event_info(void *object, struct pw_link_info *info)
|
|||
struct proxy_data *pd = object;
|
||||
struct remote_data *rd = pd->rd;
|
||||
if (pd->info)
|
||||
fprintf(stdout, "remote $%d link %d changed\n", rd->id, info->id);
|
||||
fprintf(stdout, "remote %d link %d changed\n", rd->id, info->id);
|
||||
pd->info = pw_link_info_update(pd->info, info);
|
||||
if (pd->global == NULL)
|
||||
pd->global = pw_map_lookup(&rd->globals, info->id);
|
||||
|
|
@ -893,7 +893,7 @@ static bool do_create_node(struct data *data, const char *cmd, char *args, char
|
|||
pw_proxy_add_listener(proxy, &pd->proxy_listener, &proxy_events, pd);
|
||||
|
||||
id = pw_map_insert_new(&data->vars, proxy);
|
||||
fprintf(stdout, "$%d = @proxy:%d\n", id, pw_proxy_get_id(proxy));
|
||||
fprintf(stdout, "%d = @proxy:%d\n", id, pw_proxy_get_id(proxy));
|
||||
|
||||
return true;
|
||||
}
|
||||
|
|
@ -938,7 +938,7 @@ static bool do_create_link(struct data *data, const char *cmd, char *args, char
|
|||
pw_proxy_add_listener(proxy, &pd->proxy_listener, &proxy_events, pd);
|
||||
|
||||
id = pw_map_insert_new(&data->vars, proxy);
|
||||
fprintf(stdout, "$%d = @proxy:%d\n", id, pw_proxy_get_id((struct pw_proxy*)proxy));
|
||||
fprintf(stdout, "%d = @proxy:%d\n", id, pw_proxy_get_id((struct pw_proxy*)proxy));
|
||||
|
||||
return true;
|
||||
}
|
||||
|
|
@ -956,15 +956,22 @@ static bool do_export_node(struct data *data, const char *cmd, char *args, char
|
|||
struct pw_global *global;
|
||||
struct pw_node *node;
|
||||
struct pw_proxy *proxy;
|
||||
char *a[1];
|
||||
int n;
|
||||
char *a[2];
|
||||
int n, idx;
|
||||
uint32_t id;
|
||||
|
||||
n = pw_split_ip(args, WHITESPACE, 1, a);
|
||||
n = pw_split_ip(args, WHITESPACE, 2, a);
|
||||
if (n < 1) {
|
||||
asprintf(error, "%s <node-id>", cmd);
|
||||
asprintf(error, "%s <node-id> [<remote-var>]", cmd);
|
||||
return false;
|
||||
}
|
||||
if (n == 2) {
|
||||
idx = atoi(a[1]);
|
||||
rd = pw_map_lookup(&data->vars, idx);
|
||||
if (rd == NULL)
|
||||
goto no_remote;
|
||||
}
|
||||
|
||||
global = pw_core_find_global(data->core, atoi(a[0]));
|
||||
if (global == NULL) {
|
||||
asprintf(error, "object %d does not exist", atoi(a[0]));
|
||||
|
|
@ -978,9 +985,13 @@ static bool do_export_node(struct data *data, const char *cmd, char *args, char
|
|||
proxy = pw_remote_export(rd->remote, node);
|
||||
|
||||
id = pw_map_insert_new(&data->vars, proxy);
|
||||
fprintf(stdout, "$%d = @proxy:%d\n", id, pw_proxy_get_id((struct pw_proxy*)proxy));
|
||||
fprintf(stdout, "%d = @proxy:%d\n", id, pw_proxy_get_id((struct pw_proxy*)proxy));
|
||||
|
||||
return true;
|
||||
|
||||
no_remote:
|
||||
asprintf(error, "Remote %d does not exist", idx);
|
||||
return false;
|
||||
}
|
||||
|
||||
static bool parse(struct data *data, char *buf, size_t size, char **error)
|
||||
|
|
|
|||
|
|
@ -431,6 +431,7 @@ int main(int argc, char *argv[])
|
|||
{
|
||||
struct data data = { 0 };
|
||||
struct pw_loop *l;
|
||||
struct pw_properties *props = NULL;
|
||||
|
||||
pw_init(&argc, &argv);
|
||||
|
||||
|
|
@ -446,7 +447,10 @@ int main(int argc, char *argv[])
|
|||
if (data.core == NULL)
|
||||
return -1;
|
||||
|
||||
data.remote = pw_remote_new(data.core, NULL, 0);
|
||||
if (argc > 1)
|
||||
props = pw_properties_new(PW_REMOTE_PROP_REMOTE_NAME, argv[1], NULL);
|
||||
|
||||
data.remote = pw_remote_new(data.core, props, 0);
|
||||
if (data.remote == NULL)
|
||||
return -1;
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue