NAME
wpexec - WirePlumber Script Interpreter
SYNOPSIS
wpexec SCRIPT [ARGUMENTS]
DESCRIPTION
wpexec is the WirePlumber script interpreter. It runs a single Lua script against a running PipeWire daemon, without starting a full session manager.
This makes it the tool of choice for developing and testing scripts, for one-off queries and for small standalone policy scripts that run alongside the main WirePlumber instance.
When invoked, wpexec connects to PipeWire, activates the plugins that the script requires through Core.require_api() <#Core.require_api>, and then runs the script. It keeps running until the script calls Core.quit() <#Core.quit>, the connection to PipeWire is lost, or it is interrupted with SIGINT, SIGTERM or SIGHUP.
Scripts run under wpexec have access to the same Lua API <#scripting-lua-api> as scripts loaded by the daemon, with the exception of a few functions that only make sense inside the daemon.
ARGUMENTS
- SCRIPT
-
The path to the Lua script to execute.
- ARGUMENTS
-
An optional SPA-JSON object that is passed to the script as its argument (...). Passing anything that is not a JSON object is an error.
EXAMPLES
Run a script:
$ wpexec ./get-default-sink-volume.lua
Run a script with arguments:
$ wpexec ./interactive.lua '{ option1 = "value1", option2 = "value2" }'
Run a script from a build tree, without installing:
$ ./wp-uninstalled.sh wpexec tests/examples/interactive.lua
A script may also be made directly executable by giving it the appropriate shebang line, as the examples in tests/examples do:
#!/usr/bin/wpexec
ENVIRONMENT
wpexec honours the same environment variables as wireplumber(1), most usefully WIREPLUMBER_DEBUG; see Debug Logging <#daemon-logging>.
EXIT STATUS
Exit codes follow the conventions of sysexits.h(3head):
- 0 (EX_OK)
-
Success.
- 64 (EX_USAGE)
-
Command line usage error, including a malformed ARGUMENTS object.
- 69 (EX_UNAVAILABLE)
-
Could not connect to PipeWire.
- 70 (EX_SOFTWARE)
-
Internal software error, including an error raised by the script.
SEE ALSO
wireplumber(1), wpctl(1), pipewire(1), sysexits.h(3head)
WirePlumber Documentation: <https://pipewire.pages.freedesktop.org/wireplumber/>
Author
The WirePlumber Developers
Copyright
2020-2025, Collabora & contributors