WPEXEC(1)

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