# 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

Link(factory, properties)

  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