.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "WPEXEC" "1" "Sep 03, 2026" "0.5.17" "WirePlumber"
.SH NAME
wpexec \- WirePlumber Script Interpreter
.SH SYNOPSIS
.sp
\fBwpexec\fP \fISCRIPT\fP [\fIARGUMENTS\fP]
.SH DESCRIPTION
.sp
\fBwpexec\fP is the WirePlumber script interpreter. It runs a single Lua script
against a running PipeWire daemon, without starting a full session manager.
.sp
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.
.sp
When invoked, \fBwpexec\fP connects to PipeWire, activates the plugins that the
script requires through \fBCore.require_api()\fP \%<#\:Core\:.require_api>, and then runs the script. It
keeps running until the script calls \fBCore.quit()\fP \%<#\:Core\:.quit>, the connection to
PipeWire is lost, or it is interrupted with SIGINT, SIGTERM or SIGHUP.
.sp
Scripts run under \fBwpexec\fP 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.
.SH ARGUMENTS
.INDENT 0.0
.TP
.B \fISCRIPT\fP
The path to the Lua script to execute.
.TP
.B \fIARGUMENTS\fP
An optional SPA\-JSON \fBobject\fP that is passed to the script as its argument
(\fB\&...\fP). Passing anything that is not a JSON object is an error.
.UNINDENT
.SH EXAMPLES
.sp
Run a script:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ wpexec ./get\-default\-sink\-volume.lua
.EE
.UNINDENT
.UNINDENT
.sp
Run a script with arguments:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ wpexec ./interactive.lua \(aq{ option1 = \(dqvalue1\(dq, option2 = \(dqvalue2\(dq }\(aq
.EE
.UNINDENT
.UNINDENT
.sp
Run a script from a build tree, without installing:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
$ ./wp\-uninstalled.sh wpexec tests/examples/interactive.lua
.EE
.UNINDENT
.UNINDENT
.sp
A script may also be made directly executable by giving it the appropriate
shebang line, as the examples in \fBtests/examples\fP do:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#!/usr/bin/wpexec
.EE
.UNINDENT
.UNINDENT
.SH ENVIRONMENT
.sp
\fBwpexec\fP honours the same environment variables as \fBwireplumber\fP(1),
most usefully \fBWIREPLUMBER_DEBUG\fP; see Debug Logging \%<#\:daemon-logging>\&.
.SH EXIT STATUS
.sp
Exit codes follow the conventions of \fBsysexits.h\fP(3head):
.INDENT 0.0
.TP
\fB0\fP (\fIEX_OK\fP)
Success.
.TP
\fB64\fP (\fIEX_USAGE\fP)
Command line usage error, including a malformed \fIARGUMENTS\fP object.
.TP
\fB69\fP (\fIEX_UNAVAILABLE\fP)
Could not connect to PipeWire.
.TP
\fB70\fP (\fIEX_SOFTWARE\fP)
Internal software error, including an error raised by the script.
.UNINDENT
.SH SEE ALSO
.sp
\fBwireplumber\fP(1), \fBwpctl\fP(1), \fBpipewire\fP(1), \fBsysexits.h\fP(3head)
.sp
WirePlumber Documentation: \%<https://\:pipewire\:.pages\:.freedesktop\:.org/\:wireplumber/>
.SH Author
The WirePlumber Developers
.SH Copyright
2020-2025, Collabora & contributors
.\" End of generated man page.