PipeWire Proxies — WirePlumber 0.5.15 documentation

# PipeWire Proxies

## 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_iterate_ports()`

  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:

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

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

  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.

  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 iterator

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

## Permission Manager

The `PermissionManager` object manages per-object permissions for clients. It is created with the global `PermissionManager()` constructor and configured with default permissions, core permissions, and match rules.

PermissionManager()

  Creates a new permission manager.

  Returns:

    a new permission manager

  Return type:

    WpPermissionManager

PermissionManager.set_default_permissions(self, perms)

  Binds `wp_permission_manager_set_default_permissions()`

  Sets the default permissions applied to all objects that don't match any rule.

  Parameters:

    - self -- the permission manager

    - perms -- a permission string (e.g. "rx") or an integer bitmask (e.g. `Perm.RX`)

PermissionManager.get_default_permissions(self)

  Binds `wp_permission_manager_get_default_permissions()`

  Returns the default permissions as an integer bitmask. This can be compared against the `Perm` constants using bitwise operators.

  Example:

      local pm = client:get_permission_manager()
      local perms = pm:get_default_permissions()
      if (perms & Perm.RX) == Perm.RX then
        -- client has at least read + execute
      end

  Parameters:

    self -- the permission manager

  Returns:

    the default permissions bitmask

  Return type:

    integer

PermissionManager.set_core_permissions(self, perms)

  Binds `wp_permission_manager_set_core_permissions()`

  Sets the permissions applied specifically to the PipeWire core object (ID 0). If not set, the core inherits the default permissions.

  Parameters:

    - self -- the permission manager

    - perms -- a permission string or an integer bitmask

PermissionManager.add_rules_match(self, rules)

  Binds `wp_permission_manager_add_rules_match()`

  Adds a set of match rules that grant specific permissions to objects matching the given constraints.

  Parameters:

    - self -- the permission manager

    - rules (WpSpaJson) -- a JSON array of match rules

  Returns:

    the match id (can be used with `remove_match`)

  Return type:

    integer

PermissionManager.add_interest_match(self, callback, interest)

  Binds `wp_permission_manager_add_interest_match_closure()`

  Adds a dynamic match that calls the given callback to determine permissions for objects matching the given interest.

  Parameters:

    - self -- the permission manager

    - callback (function) -- a function that returns the permissions for the matched object

    - interest (WpObjectInterest) -- the interest to match

  Returns:

    the match id

  Return type:

    integer

PermissionManager.add_interest_match_simple(self, perms, interest)

  Binds `wp_permission_manager_add_interest_match_simple()`

  Adds a static match that grants the given permissions to objects matching the given interest.

  Parameters:

    - self -- the permission manager

    - perms (integer) -- the permissions bitmask to grant

    - interest (WpObjectInterest) -- the interest to match

  Returns:

    the match id

  Return type:

    integer

PermissionManager.remove_match(self, match_id)

  Binds `wp_permission_manager_remove_match()`

  Removes a previously added match.

  Parameters:

    - self -- the permission manager

    - match_id (integer) -- the match id returned by an `add_*_match` method

PermissionManager.update_permissions(self)

  Binds `wp_permission_manager_update_permissions()`

  Forces a recalculation and update of permissions on all attached clients.

  Parameters:

    self -- the permission manager