doc: document module-link-factory

src/daemon/pipewire.conf.in

@@ -200,7 +200,11 @@ context.modules = [
     }
 
     # Makes a factory for creating links between ports.
+    # use module.link-factory.args = { ... } to override the arguments.
     { name = libpipewire-module-link-factory
+        args = {
+            #allow.link.passive = false
+	}
         condition = [ { module.link-factory = !false } ]
     }
 

src/modules/module-link-factory.c

@@ -15,10 +15,84 @@
 #include <pipewire/impl.h>
 
 /** \page page_module_link_factory Link Factory
+ *
+ * Allows clients to create links between ports.
+ *
+ * This module creates a new factory. Clients that can see the factory
+ * can use the factory name (`link-factory`) to create new link
+ * objects with \ref pw_core_create_object().
+ *
+ * Object of the \ref PW_TYPE_INTERFACE_Link will be created and a proxy
+ * to it will be returned.
+ *
+ * As an argument to the create_object call, a set of properties will
+ * control what ports will be linked.
  *
  * ## Module Name
  *
  * `libpipewire-module-link-factory`
+ *
+ * ## Module Options
+ *
+ * - `allow.link.passive`: if the `link.passive` property is allowed. Default false.
+ *                        By default, the core will decide when a link is passive
+ *                        based on the properties of the node and ports.
+ *
+ * ## Properties for the create_object call
+ *
+ * `link.output.node`: The output node to use. This can be the node id, node.name,
+ *                     node.nick, node.description or object.path of a node. When the
+ *                     property is not given or NULL, the output port should be
+ *                     specified.
+ * `link.output.port`: The output port to link. This can be a port id, port.name,
+ *                     port.alias or object.path. If an output node is specified, the
+ *                     port must belong to the node. If no output port is given, an
+ *                     output node must be specified and a random (unlinked) port will
+ *                     be used from the node.
+ * `link.input.node`: The input node to use. This can be the node id, node.name,
+ *                     node.nick, node.description or object.path of a node. When the
+ *                     property is not given or NULL, the input port should be
+ *                     specified.
+ * `link.input.port`: The input port to link. This can be a port id, port.name,
+ *                     port.alias or object.path. If an input node is specified, the
+ *                     port must belong to the node. If no input port is given, an
+ *                     input node must be specified and a random (unlinked) port will
+ *                     be used from the node.
+ * `object.linger`: Keep the link around even when the client that created it is gone.
+ * `link.passive`: The link is passive, meaning that it will not keep nodes busy.
+ *                 By default this property is ignored and the node and port properties
+ *                 are used to determine the passive state of the link.
+ *
+ * ## Example configuration
+ *
+ * The module is usually added to the config file of the main pipewire daemon.
+ *
+ *\code{.unparsed}
+ * context.modules = [
+ * { name = libpipewire-link-factory
+ *   args = {
+ *       #allow.link.passive = false
+ *   }
+ * }
+ * ]
+ *\endcode
+
+ * ## Config override
+ *
+ * A `module.link-factory.args` config section can be added
+ * to override the module arguments.
+ *
+ *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-link-factory-args.conf
+ *
+ * module.link-factory.args = {
+ *     #allow.link.passive = false
+ * }
+ *\endcode
+ *
+ * ## See also
+ *
+ * - `pw-link`: a tool to manage port links
  */
 
 #define NAME "link-factory"
@@ -543,6 +617,8 @@ int pipewire__module_init(struct pw_impl_module *module, const char *args)
 	data->props = args ? pw_properties_new_string(args) : NULL;
 
 	if (data->props) {
+		pw_context_conf_update_props(context, "module."NAME".args", data->props);
+
 		data->allow_passive = pw_properties_get_bool(data->props,
 				"allow.link.passive", false);
 	}