WpObject

WpObject is the base class of most WirePlumber objects — nodes, devices, links, metadata, session items and so on. It binds the WpObject C API.

Its distinguishing feature is the features mechanism. A newly created object is not immediately usable in full: proxies to PipeWire objects, for example, start out knowing only their id, and additional information has to be requested and awaited. Features name the pieces of functionality that can be activated, and activation is asynchronous.

Scripts do not normally construct WpObject directly; they receive objects from an ObjectManager (already activated, as requested by the object manager) or create a specific subclass such as Node() or SpaDevice().

Activation

Object.activate(self, features, callback)

Binds wp_object_activate()

Requests activation of the given features. This is asynchronous: the object is only usable for those features once callback has been called successfully.

device:activate (Feature.SpaDevice.ENABLED, function (dev, err)
  if err then
    log:warning (dev, "failed to activate: " .. err)
    return
  end
  -- the device is now enabled
end)

Parameters:

features (integer) -- a bitmask of the features to activate; see the constants below
callback (function) -- (optional) called when activation completes, as callback(object, error); error is nil on success and an error message string on failure

Object.deactivate(self, features)

Binds wp_object_deactivate()

Deactivates the given features, releasing whatever resources they hold.

Parameters:: features (integer) -- a bitmask of the features to deactivate

Object.get_active_features(self)

Binds wp_object_get_active_features()

Returns:: a bitmask of the features that are currently active
Return type:: integer

Object.get_supported_features(self)

Binds wp_object_get_supported_features()

Returns:: a bitmask of the features that this object is able to activate
Return type:: integer

Feature constants

Individual features are named by the Feature table, grouped by the object type that supports them:

Constant	Applies to
`Feature.Proxy.BOUND`	any proxy
`Feature.PipewireObject.INFO`	any PipeWire object
`Feature.PipewireObject.PARAM_PROPS`	objects with a Props param
`Feature.PipewireObject.PARAM_FORMAT`	objects with a Format param
`Feature.PipewireObject.PARAM_PROFILE`	devices
`Feature.PipewireObject.PARAM_PORT_CONFIG`	nodes
`Feature.PipewireObject.PARAM_ROUTE`	devices
`Feature.SpaDevice.ENABLED`	SpaDevice
`Feature.Node.PORTS`	Node
`Feature.Metadata.DATA`	Metadata
`Feature.SessionItem.ACTIVE`	SessionItem
`Feature.SessionItem.EXPORTED`	SessionItem

The Features table provides convenient combinations:

Constant	Meaning
`Features.ALL`	all features the object supports
`Features.PipewireObject.MINIMAL`	`Proxy.BOUND` plus `PipewireObject.INFO`

Since features are a bitmask, they are combined with the bitwise or operator:

node:activate (Features.PipewireObject.MINIMAL | Feature.Node.PORTS,
    function (n, err) --[[ ... ]] end)