PipeWire Proxies

Constructors

Most proxies are obtained from an ObjectManager rather than constructed. The following globals create new objects, each by asking a PipeWire factory to make one.

Node(factory, properties)

Binds wp_node_new_from_factory()

Creates a node using the given PipeWire factory. The node lives in the PipeWire daemon.

Parameters:

  • factory (string) -- the name of the PipeWire factory

  • properties -- (optional) a table or Properties object with the node properties

Returns:

the new node, or nil if the factory could not create it

Return type:

Node

LocalNode(factory, properties)

Binds wp_impl_node_new_from_pw_factory()

Creates a node that runs inside the WirePlumber process and is exported to the PipeWire graph, rather than living in the PipeWire daemon. This is what the MIDI bridge and the Bluetooth nodes use.

The returned object must be activated before it appears in the graph; see WpObject.

Parameters:

  • factory (string) -- the name of the PipeWire factory

  • properties -- (optional) a table or Properties object with the node properties

Returns:

the new node, or nil if the factory could not create it

Return type:

LocalNode

Binds wp_link_new_from_factory()

Creates a link. The endpoints are given as properties: link.output.node, link.output.port, link.input.node and link.input.port.

Note that the linking policy does not use this directly; it creates si-standard-link session items instead, which manage the underlying links themselves.

Parameters:

  • factory (string) -- the name of the PipeWire factory, normally "link-factory"

  • properties -- (optional) a table or Properties object describing the link

Returns:

the new link, or nil if the factory could not create it

Return type:

Link

ImplMetadata(name, properties)

Binds wp_impl_metadata_new_full()

Creates a metadata object that WirePlumber itself exports to the PipeWire graph, as opposed to a proxy to one exported by somebody else. This is how the default, filters and sm-settings metadata objects come into existence.

The returned object must be activated before it appears in the graph; see WpObject. It supports the same methods as a metadata proxy; see PipeWire Metadata below.

Parameters:

  • name (string) -- the name of the metadata object

  • properties -- (optional) a table or Properties object with additional properties

Returns:

the new metadata object

Return type:

ImplMetadata

See also Device and SpaDevice in Spa Device.

Proxy

Lua objects that bind a WpProxy contain the following methods:

Proxy.get_interface_type(self)

Binds wp_proxy_get_interface_type()

Parameters:

self -- the proxy

Returns:

the proxy type, the proxy type version

Return type:

string, integer

PipeWire Object

Lua objects that bind a WpPipewireObject contain the following methods:

PipewireObject.iterate_params(self, param_name)

Binds wp_pipewire_object_enum_params_sync()

Parameters:

  • self -- the proxy

  • param_name (string) -- the PipeWire param name to enumerate, ex "Props", "Route"

Returns:

the available parameters

Return type:

Iterator; the iteration items are Spa Pod objects

PipewireObject.set_param(self, param_name, pod)

Binds wp_pipewire_object_set_param()

Parameters:

  • self -- the proxy

  • param_name (string) -- The PipeWire param name to set, ex "Props", "Route"

  • pod (Pod) -- A Spa Pod object containing the new params

Global Proxy

Lua objects that bind a WpGlobalProxy contain the following methods:

GlobalProxy.request_destroy(self)

Binds wp_global_proxy_request_destroy()

Parameters:

self -- the proxy

PipeWire Node

Lua objects that bind a WpNode contain the following methods:

Node.get_state(self)

Binds wp_node_get_state()

Parameters:

self -- the proxy

Returns:

the current state of the node and an error message, if any

Return type:

string (WpNodeState), string (error message)

Since:

0.4.2

Node.get_n_input_ports(self)

Binds wp_node_get_n_input_ports()

Parameters:

self -- the proxy

Returns:

the current and max numbers of input ports on the node

Return type:

integer (current), integer (max)

Since:

0.4.2

Node.get_n_output_ports(self)

Binds wp_node_get_n_output_ports()

Parameters:

self -- the proxy

Returns:

the current and max numbers of output ports on the node

Return type:

integer (current), integer (max)

Since:

0.4.2

Node.get_n_ports(self)

Binds wp_node_get_n_ports()

Parameters:

self -- the proxy

Returns:

the number of ports on the node

Since:

0.4.2

Node.iterate_ports(self, interest)

Binds wp_node_new_ports_iterator()

Parameters:

  • self -- the proxy

  • interest (Interest or nil or none) -- an interest to filter objects

Returns:

all the ports of this node that that match the interest

Return type:

Iterator; the iteration items are of type WpPort

Since:

0.4.2

Node.lookup_port(self, interest)

Binds wp_node_lookup_port()

Parameters:

  • self -- the proxy

  • interest (Interest or nil or none) -- the interest to use for the lookup

Returns:

the first port of this node that matches the interest

Return type:

WpPort

Since:

0.4.2

Node.send_command(self, command)

Binds wp_node_send_command()

Parameters:

  • self -- the proxy

  • command (string) -- the command to send to the node (ex "Suspend")

PipeWire Port

Lua objects that bind a WpPort contain the following methods:

Port.get_direction(self)

Binds wp_port_get_direction()

Parameters:

self -- the port

Returns:

the direction of the Port

Return type:

string (WpDirection)

Since:

0.4.2

PipeWire Client

Lua objects that bind a WpClient contain the following methods. See Permissions API for the Perm constants and the PermissionManager object that these methods work with.

Client.update_permissions(self, perms)

Binds wp_client_update_permissions()

Takes a table where the keys are object identifiers and the values are permission strings.

Valid object identifiers are:

  • A number, meaning the bound ID of a proxy

  • The string "any" or the string "all", which sets the default permissions for this client

The permission strings have a chmod-like syntax (ex. "rwx" or "r-xm"), where:

  • "r" means permission to read the object

  • "w" means permission to write data to the object

  • "x" means permission to call methods on the object

  • "m" means permission to set metadata for the object

  • "l" means permission to link to the object without being able to see it

  • "-" is ignored and can be used to make the string more readable when a permission flag is omitted

The string "all" is also accepted and is a synonym for "rwxm".

Example:

client:update_permissions {
  ["all"] = "r-x",
  [35] = "rwxm",
}
Parameters:

  • self -- the proxy

  • perms (table) -- the permissions to update for this client

Client.attach_permission_manager(self, pm)

Binds wp_client_attach_permission_manager()

Attaches a permission manager to handle permissions for this client automatically. The permission manager will manage per-object permissions based on its configured rules and default permissions; see Permissions API. It must have been activated with Features.ALL before it is attached.

Parameters:

  • self -- the client

  • pm (WpPermissionManager) -- the permission manager to attach

Client.get_permission_manager(self)

Binds wp_client_get_permission_manager()

Returns the permission manager currently attached to this client, or nil if no permission manager is attached.

Example:

local pm = client:get_permission_manager()
if pm then
  local perms = pm:get_default_permissions()
  -- check permission bits
end
Parameters:

self -- the client

Returns:

the attached permission manager, or nil

Return type:

WpPermissionManager or nil

PipeWire Metadata

Lua objects that bind a WpMetadata contain the following methods:

Metadata.iterate(self, subject)

Binds wp_metadata_new_iterator()

Parameters:

  • self -- the proxy

  • subject (integer) -- the subject id

Returns:

an iteration over the metadata entries of this subject, to be used in a for loop; each step yields the subject id, the key, the value type and the value

Example:

for subject, key, type, value in metadata:iterate (-1) do
  log:info (tostring (subject) .. " " .. key .. " = " .. value)
end
Metadata.find(self, subject, key)

Binds wp_metadata_find()

Parameters:

  • self -- the proxy

  • subject (string) -- the subject id

  • key (string) -- the metadata key to find

Returns:

the value for this metadata key, the type of the value

Return type:

string, string

Metadata.set(self, subject, key, type, value)

Binds wp_metadata_set()

Stores a value. Passing no value removes the key; passing no key either removes all the metadata associated with subject.

Note that this only takes effect if the client has the "m" permission on subject; see Client.update_permissions(). On a metadata proxy, the change is also not visible to Metadata.find() until the next round-trip with the PipeWire server.

Parameters:

  • self -- the proxy

  • subject (integer) -- the subject id

  • key (string) -- (optional) the key to set

  • type (string) -- (optional) the type of the value; nil means "string"

  • value (string) -- (optional) the value to set