MXWendler Wiki - User contributions [en]

Stage Recorder Deployment

2026-09-29T21:21:19Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Deployment: Recorder and Video Portal =

'''Covers:''' Windows and Linux · recorder and portal on one machine or on two · MQTT broker · reminder mails

== Components ==

A complete installation has up to four parts. Only the recorder is mandatory.

{| class="wikitable"
! Part !! What it is !! Runs on
|-
| '''Recorder''' || the application: capture, playback, scheduling, file browser, OSC/MQTT/VNC || the machine with the capture hardware and the license dongle
|-
| '''Video portal''' || an unmodified PeerTube instance with the Stage Recorder plugin and theme, as three Docker containers (PeerTube, PostgreSQL, Redis) || the same machine, or any Linux machine, NAS or VM that runs Docker
|-
| '''MQTT broker''' || optional; needed only for MQTT remote control and status publishing || anywhere on the LAN, often the portal host
|-
| '''Mail server''' || optional; an existing SMTP account for the reminder digest || not deployed, only configured
|}

The recorder does not have to be reachable from the portal. Every transfer, including the portal's '''Bring back to recorder''' button, is initiated by the recorder: it uploads, it downloads, and it polls the portal every 30 s for fetch requests. The portal may therefore sit behind a firewall or a NAT the recorder cannot be reached through, and the recorder may sit behind one as well.

== Choosing a topology ==

{| class="wikitable"
! Topology !! When !! Trade-offs
|-
| '''A. One machine''' — recorder and portal on the recording PC || one venue, a few viewers on the same LAN, no spare hardware || simplest to set up; transcoding competes with real-time capture, so limit it (see below); Windows needs Docker Desktop with WSL 2
|-
| '''B. Two machines on the LAN''' — recorder plus a Linux portal host (NUC, NAS, VM) || the recommended configuration for a venue || the recording machine is not affected; the portal host performs the transcoding; each side needs only a host name and a port
|-
| '''C. Portal off site''' — a VPS or a server in the company network, reached over the internet || several venues share one portal, or viewers watch from outside the venue || put a TLS reverse proxy in front; uploads take the venue's upstream bandwidth, so use the transfer window; the recorder still needs no inbound port
|}

Rules that hold for every topology:

* The portal is addressed by '''exactly one name''' — <code>PEERTUBE_WEBSERVER_HOSTNAME</code> in its <code>.env</code>. PeerTube answers the login endpoint only when the <code>Host</code> header matches it; an IP address or a second alias gets <code>http 403</code>. Pick a name that every browser and the recorder can resolve (DNS, mDNS or a <code>hosts</code> entry), and use that same name in the recorder's <code>/Portal/URL</code>.
* <code>PEERTUBE_SECRET</code> is generated once and never changed after the instance has data.
* Keep the portal on plain HTTP only inside a trusted LAN. Any instance reachable from outside the LAN is placed behind a reverse proxy with TLS (topology C).

'''Recommendation:''' B for a venue, C when the portal serves more than one venue. A is adequate as a starting point and can be separated later: the recorder only knows the portal as a URL, so moving the stack means copying the <code>docker/</code> directory with its <code>volumes/</code> to the new host and changing <code>/Portal/URL</code>.

== Network reference ==

Inbound ports the recorder opens (all configurable in the settings tree):

{| class="wikitable"
! Port !! Protocol !! Purpose !! Key
|-
| 7000 || UDP || OSC commands || <code>/System/IO/OSC/Receive Port</code>
|-
| 5900 || TCP || VNC remote UI, only with VNC on || <code>/System/IO/VNC/Port</code>, <code>/System/IO/VNC/Use VNC</code>
|-
| 5800 || TCP || browser viewer and the links in the reminder mails, only with VNC on; <code>0</code> switches it off || <code>/System/IO/VNC/Web Port</code>
|}

Outbound connections the recorder makes:

{| class="wikitable"
! Target !! Port !! Purpose !! Key
|-
| MQTT broker || 1883 TCP || commands in, status out || <code>/System/IO/MQTT/Broker Address</code>, <code>/System/IO/MQTT/Use MQTT</code>
|-
| portal || 9000 TCP (443 behind a proxy) || uploads, downloads, fetch-request polling || <code>/Portal/URL</code>
|-
| SMTP server || 587 TCP || reminder digest || <code>/Mail/Server</code>, <code>/Mail/Port</code>
|}

Inbound port the portal opens: '''9000 TCP''' (<code>PEERTUBE_WEBSERVER_PORT</code>), or 80/443 on the reverse proxy in topology C.

The MQTT default <code>broker.hivemq.com</code> is a '''public''' broker. Either switch MQTT off or point it at a broker of your own (section "MQTT broker") before the system goes live.

== Part 1 — The recorder on Windows ==

'''1. Install.''' Run <code>Tourette_Stage_Recorder_5.0.<build>.exe</code> from <code>tools/installer/</code>. It installs the application to <code>C:\Program Files\Tourette Stage Recorder 5.0\</code> with the FFmpeg libraries, <code>ffmpeg.exe</code> (used to render H.264 proxies for the portal), the dongle library, the <code>files\</code> tree, the video portal deployment under <code>portal\</code> (Part 3) and this guide as <code>deployment.pdf</code>, and registers the <code>.mxr</code> / <code>.mxr_syncset</code> file types. A desktop and a start-menu shortcut are created.

'''2. Dongle.''' Plug in the Rockey4ND license dongle before the first start. Without it the application starts with no channels and a warning.

'''3. First start.''' Start from the shortcut. The settings file is created at <code>%APPDATA%\mxw_recorder\mxr_recorder.ini</code>; recordings go to <code>Documents\TouretteStageRecorder</code> until <code>/Recording/Root</code> says otherwise. Every key mentioned in this document appears in the configuration tree of the Settings tab after the first run.

'''4. Recording root.''' Set <code>/Recording/Root</code> to the recording disk. If that path is a mount that may be absent, note that a missing root at record start does not prevent the recording: the default root is used instead and the main tab shows a red banner.

'''5. Firewall.''' Windows asks on the first start; allow the application on the '''Private''' profile. If the rig's network is classified '''Public''', either reclassify it or add inbound rules by hand for UDP 7000 and, with VNC on, TCP 5900 and 5800:

<pre>
netsh advfirewall firewall add rule name="MXW Recorder OSC" dir=in action=allow protocol=UDP localport=7000
netsh advfirewall firewall add rule name="MXW Recorder VNC" dir=in action=allow protocol=TCP localport=5900,5800
</pre>

'''6. Proxies for the portal.''' With <code>/Portal/Use Upload Original</code> off (the default) every take that is not H.264 is encoded to an H.264 proxy with <code>h264_nvenc</code> before the upload; that needs an NVIDIA GPU. Without one the proxy step fails with <code>T003</code>/<code>T004</code> and the original goes up instead. <code>/System/FFmpeg Path</code> overrides the lookup (<code>ffmpeg.exe</code> next to the executable is found on its own).

'''7. Restart policy.''' Settings under <code>/System</code> are read once at startup. After changing any of them use the red '''Save & Restart''' button.

== Part 2 — The recorder on Linux ==

The recorder is installed from a Debian package built for Ubuntu 24.04 (amd64), <code>tourette-stage-recorder_<version>_amd64.deb</code> (<code>tools/installer/linux/build_deb.py</code> in the source tree builds it from a Linux build of the application).

'''1. Install.'''

<pre>
sudo apt install ./tourette-stage-recorder_<version>_amd64.deb
</pre>

<code>apt</code> resolves the dependencies (wxWidgets 3.2, GTK 3, ALSA, libcurl) and installs <code>ffmpeg</code> as a recommendation; it renders the H.264 proxies for the portal. The package places:

{| class="wikitable"
! Path !! Content
|-
| <code>/opt/TouretteStageRecorder/</code> || the application <code>mxw_recorder</code>, the <code>files/</code> tree, the video portal deployment under <code>portal/</code> (Part 3)
|-
| <code>/usr/bin/tourette-stage-recorder</code> || the launcher; it sets the working directory and starts the application
|-
| <code>/usr/share/applications/tourette-stage-recorder.desktop</code> || the entry in the applications menu
|-
| <code>/usr/share/doc/tourette-stage-recorder/deployment.pdf</code> || this guide
|}

'''2. License.''' The Linux build has no dongle support; it reads the license file. Copy <code>mxr_license.lic</code> to <code>/opt/TouretteStageRecorder/</code> before the first start:

<pre>
sudo cp mxr_license.lic /opt/TouretteStageRecorder/
</pre>

'''3. First start.''' Start ''Tourette Stage Recorder'' from the applications menu, or <code>tourette-stage-recorder</code> from a terminal. The settings file is created at <code>~/.mxw_recorder/mxr_recorder.ini</code> of the user who runs it; recordings go to <code>~/Documents/TouretteStageRecorder</code> until <code>/Recording/Root</code> says otherwise. Every key mentioned in this document appears in the configuration tree of the Settings tab after the first run.

'''4. Recording root.''' Set <code>/Recording/Root</code> to the recording disk, as on Windows.

'''5. Firewall.''' With <code>ufw</code>:

<pre>
sudo ufw allow 7000/udp # OSC
sudo ufw allow 5900,5800/tcp # VNC and browser viewer, only with VNC on
</pre>

'''6. Proxies for the portal.''' As on Windows, a take that is not H.264 is encoded to an H.264 proxy with <code>h264_nvenc</code> before the upload, which requires an NVIDIA GPU with its driver; without one the original is uploaded. The recorder finds <code>ffmpeg</code> at <code>/usr/bin/ffmpeg</code>; <code>/System/FFmpeg Path</code> overrides this.

'''7. Autostart.''' For a kiosk, start <code>tourette-stage-recorder</code> from the desktop session's autostart. The application needs a display and OpenGL; a system service without a session is not sufficient.

'''8. Restart policy.''' As on Windows, settings under <code>/System</code> are read once at startup; use '''Save & Restart''' after changing them.

== Part 3 — The video portal ==

The portal is the same on Windows and Linux: Docker with the Compose plugin, and the <code>portal/</code> directory that both installers place next to the application (<code>C:\Program Files\Tourette Stage Recorder 5.0\portal\</code> on Windows, <code>/opt/TouretteStageRecorder/portal/</code> on Linux; in the source tree it is <code>tools/installer/portal/</code>). Node.js is not needed on the host; the plugin is packed inside the image build.

The stack writes its database and media into <code>docker/volumes/</code> next to its compose file, and its secrets into <code>docker/.env</code>. Neither belongs under the installation directory, which is read-only for the operator. Copy <code>portal/</code> to a writable location first, on the machine that will run the portal:

<pre>
cp -r /opt/TouretteStageRecorder/portal ~/portal # Linux
xcopy /E /I "C:\Program Files\Tourette Stage Recorder 5.0\portal" %USERPROFILE%\portal (Windows)
</pre>

The paths in this part refer to that copy. For a separate portal host (topology B or C), copy the directory to that machine.

=== 3.1 Docker ===

* '''Linux (portal host or single machine):''' install Docker Engine and the Compose plugin from Docker's repository (<code>docker-ce</code>, <code>docker-compose-plugin</code>), add the operator to the <code>docker</code> group, log in again. Enable the service so the stack comes back after a reboot: <code>sudo systemctl enable docker</code>.
* '''Windows (single machine):''' install Docker Desktop with the WSL 2 backend and enable '''Start Docker Desktop when you sign in'''. Two properties of this configuration are relevant:
** WSL's '''mirrored networking''' mode makes the Linux side own the host's LAN address. A container can reach the Windows host only through <code>127.0.0.1</code>, not through the LAN address. For this reason the portal never connects to the recorder; no configuration is required for this, and no connection from the portal to the recorder should be set up.
** Transcoding runs inside WSL and competes with capture. Cap it in <code>%USERPROFILE%\.wslconfig</code> (for example <code>memory=8GB</code>, <code>processors=4</code>) and keep <code>MXR_TRANSCODE_RESOLUTIONS</code> to a single rendition.

=== 3.2 Configure and start ===

In the copy of the portal directory:

<pre>
cd ~/portal
python3 build_portal.py --env --hostname portal.local --recorder-url http://recorder-pc:5800
cd docker
</pre>

<code>--env</code> writes <code>docker/.env</code> from <code>.env.example</code> with fresh secrets. Open it and check:

{| class="wikitable"
! Key !! Set it to
|-
| <code>PEERTUBE_WEBSERVER_HOSTNAME</code> || the one name the portal is reached by (see "Choosing a topology"); on a single machine <code>localhost</code> works for the recorder, but other browsers then need the machine's name — prefer the name
|-
| <code>PEERTUBE_WEBSERVER_PORT</code>, <code>PEERTUBE_WEBSERVER_HTTPS</code> || <code>9000</code> and <code>false</code> on the LAN; <code>443</code> and <code>true</code> behind a TLS proxy
|-
| <code>PEERTUBE_ADMIN_EMAIL</code>, <code>PT_INITIAL_ROOT_PASSWORD</code> || the admin account; the setup logs in with this password on every start
|-
| <code>MXR_RECORDER_USER</code>, <code>MXR_RECORDER_PASSWORD</code>, <code>MXR_RECORDER_CHANNEL</code> || the recorder's account and channel; the same values go into the recorder's <code>/Portal/User</code>, <code>/Portal/Password</code>, <code>/Portal/Channel</code>
|-
| <code>MXR_RECORDER_URL</code> || informational, shown in the plugin settings; no connection is made to it
|-
| <code>MXR_KEEP_ORIGINAL</code> || <code>true</code> when the recorder uploads originals (<code>/Portal/Use Upload Original</code>) and the disk can hold them; otherwise only renditions are kept
|-
| <code>MXR_TRANSCODE_RESOLUTIONS</code> || <code>720p</code> on a single machine, <code>720p,1080p</code> on a dedicated host
|-
| <code>MXR_INSTANCE_NAME</code> || the name in the browser tab and in the portal's mails
|}

Then:

<pre>
docker compose up -d
docker compose logs -f peertube # wait for "mxr setup: done"
</pre>

The setup step runs on every start and is idempotent: it installs or updates the plugin and the theme, creates the recorder user and channel, closes registration, sets the default privacy to '''internal''' (logged-in users only), configures transcoding and uploads the branding. Open <code>http://<hostname>:9000</code> in a browser and log in as the recorder user once to confirm.

=== 3.3 Offline portal host ===

Build the image on a machine with internet access and transfer it:

<pre>
python3 build_portal.py --save mxr-peertube.tar
# copy mxr-peertube.tar and the docker/ directory (with .env) to the host
docker load -i mxr-peertube.tar
docker compose up -d
</pre>

=== 3.4 TLS and the outside world (topology C) ===

Put a reverse proxy with a certificate in front of port 9000 and expose only 443. With Caddy the complete configuration is one block:

<pre>
portal.example.org {
reverse_proxy 127.0.0.1:9000
}
</pre>

In <code>.env</code> set <code>PEERTUBE_WEBSERVER_HOSTNAME=portal.example.org</code>, <code>PEERTUBE_WEBSERVER_PORT=443</code>, <code>PEERTUBE_WEBSERVER_HTTPS=true</code>; the proxy's address must be covered by <code>PEERTUBE_TRUST_PROXY</code>. In the recorder <code>/Portal/URL</code> becomes <code>https://portal.example.org</code>. <code>/Portal/Use Insecure TLS</code> is only for a self-signed certificate on a LAN, never for a public host.

=== 3.5 Where the data lives, backup, updates ===

Everything is under <code>docker/volumes/</code> of the portal directory on the host:

{| class="wikitable"
! Directory !! Holds
|-
| <code>volumes/db/</code> || PostgreSQL — videos, chapters, users, the plugin's records and fetch queue
|-
| <code>volumes/data/streaming-playlists/hls/<uuid>/</code> || the transcoded renditions (what a fetch downloads when no original is kept)
|-
| <code>volumes/data/original-video-files/</code> || uploaded originals, only with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>volumes/data/thumbnails</code>, <code>previews</code>, <code>storyboards</code>, <code>captions</code>, <code>torrents</code> || derived assets
|-
| <code>volumes/config/</code> || PeerTube's production configuration
|}

* '''Backup:''' <code>docker compose stop</code>, copy <code>volumes/</code> and <code>.env</code> together, <code>docker compose start</code>. Database and files belong together — a video row points at its files by uuid.
* '''Move to another host:''' the same copy, then <code>docker compose up -d</code> there and a new <code>/Portal/URL</code> in the recorder if the name changed.
* '''Update:''' install the new recorder version, copy its <code>portal/</code> over the working copy (keeping <code>docker/volumes/</code> and <code>docker/.env</code>), <code>python3 build_portal.py</code>, <code>docker compose up -d</code>. The setup updates the plugin and theme when their version changed.
* '''Disk:''' originals require the full take size per upload; renditions require approximately the proxy bitrate (<code>/Portal/Proxy Bitrate Mbit</code>, default 12) times the duration. The recorder's own retention (<code>/Storage/*</code>) never touches the portal; deleting on the portal is done in its admin, and the recorder's '''Re-sync with portal''' button then drops those takes from its index.

== Part 4 — Connect the recorder to the portal ==

In the recorder's Settings tab (password from <code>/System/SettingsKey</code>, default <code>123456</code>):

{| class="wikitable"
! Key !! Value
|-
| <code>/Portal/URL</code> || <code>http://<PEERTUBE_WEBSERVER_HOSTNAME>:9000</code> — exactly the name from <code>.env</code>, no IP
|-
| <code>/Portal/User</code>, <code>/Portal/Password</code> || <code>MXR_RECORDER_USER</code> / <code>MXR_RECORDER_PASSWORD</code>
|-
| <code>/Portal/Channel</code> || <code>MXR_RECORDER_CHANNEL</code>, or empty for the user's default channel
|-
| <code>/Portal/Privacy</code> || <code>internal</code> (default): visible to logged-in users only
|-
| <code>/Portal/Use Upload Original</code> || on only together with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>/Portal/Use Transfer While Recording</code> || off (default) keeps the upload bandwidth and the disk away from a running take
|-
| <code>/Portal/Transfer From Hour</code>, <code>/Portal/Transfer To Hour</code> || a window, e.g. <code>1</code> and <code>7</code> for nights; <code>0</code> and <code>24</code> means always
|}

'''Save & Restart.''' Then verify the connection:

* Record a short take, load it in the player, press '''Publish to portal'''. The file browser's flags column runs through '''uploading n %'''; the log says <code>portal: published <name> -> <url></code>.
* The Files tab's '''Portal''' view lists it after '''Reload'''. Open the portal page: title, tags and the markers as chapters are there.
* Delete the local file in the browser, press '''Fetch to local''' in the Portal view (or '''Bring back to recorder''' on the portal page): the file returns to its date folder, protected, with its markers.

If the login fails with <code>http 403</code>, the URL is not the configured host name. If the listing fails with <code>T008</code>, check the account and the channel name.

== Part 5 — MQTT broker ==

Required only when show control or monitoring uses MQTT. Any MQTT 3.1.1 broker is suitable; Mosquitto is used in the examples below.

* '''Linux:''' <code>sudo apt install mosquitto</code>, then in <code>/etc/mosquitto/conf.d/lan.conf</code>:

<pre>
listener 1883
allow_anonymous true
</pre>

<code>sudo systemctl enable --now mosquitto</code>. Restrict anonymous access to the LAN (bind the listener to the LAN interface, or add a password file for other clients); the recorder itself does not support broker authentication.

* '''Windows:''' the Mosquitto installer from mosquitto.org, the same two lines in <code>mosquitto.conf</code>, installed as a service.

In the recorder: <code>/System/IO/MQTT/Use MQTT</code> on, <code>/System/IO/MQTT/Broker Address</code> = the broker's name or IP, <code>/System/IO/MQTT/System ID</code> unique per recorder when several share a broker. Save & Restart. The broker's log shows <code>mxr-client-…</code> connecting.

== Part 6 — Reminder mails ==

The recorder sends one digest a day listing takes that crossed the warning age and those within a week of deletion, with a '''keep''' and a '''publish''' link per take. The links point at the recorder's web port, so they work only for people who can reach the recorder on port 5800.

{| class="wikitable"
! Key !! Value
|-
| <code>/Mail/Use Reminders</code> || on
|-
| <code>/Mail/Server</code>, <code>/Mail/Port</code>, <code>/Mail/Use TLS</code> || the SMTP account, default port 587 with STARTTLS
|-
| <code>/Mail/User</code>, <code>/Mail/Password</code>, <code>/Mail/From</code> || its credentials and sender address
|-
| <code>/Mail/Recipients</code> || comma-separated
|-
| <code>/Mail/Recorder URL</code> || how recipients reach the recorder, default <code>http://<hostname>:5800</code>; must match the VNC web port
|-
| <code>/Mail/Send Hour</code> || default <code>8</code>
|}

<code>/System/IO/VNC/Use VNC</code> must be on with a non-zero web port, otherwise <code>N001</code> is logged and the links cannot be answered.

== Checklists ==

'''Single machine, Windows (topology A)'''

* Installer, dongle, first start, <code>/Recording/Root</code>
* Docker Desktop with WSL 2, <code>.wslconfig</code> limits, <code>MXR_TRANSCODE_RESOLUTIONS=720p</code>
* <code>build_portal.py --env --hostname <pc-name></code>, <code>.env</code> checked, <code>docker compose up -d</code>, "mxr setup: done"
* <code>/Portal/*</code> in the recorder, Save & Restart, verification of the connection
* Firewall: UDP 7000 in; TCP 9000 in for other viewers; TCP 5900/5800 in only with VNC
* Transfer window set to the hours without shows

'''Two machines (topology B)'''

* Recorder as in Part 1 or 2
* Portal host: Docker Engine enabled at boot, <code>build_portal.py --env --hostname <portal-name></code>, <code>docker compose up -d</code>
* Name resolution for <code><portal-name></code> on the recorder and on the viewers' machines
* <code>/Portal/URL = http://<portal-name>:9000</code>, verification of the connection
* Backup plan for <code>volumes/</code> and <code>.env</code>

'''Off site (topology C)'''

* Everything from B on the server
* Reverse proxy with TLS, <code>.env</code> on 443/https, <code>PEERTUBE_TRUST_PROXY</code>
* <code>/Portal/URL = https://…</code>, transfer window for the venue's uplink
* Only 443 open on the server; the recorder needs no inbound port at all

Stage Recorder Deployment

2026-09-29T21:04:55Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Deployment: Recorder and Video Portal =

'''Covers:''' Windows and Linux · recorder and portal on one machine or on two · MQTT broker · reminder mails

== Components ==

A complete installation has up to four parts. Only the recorder is mandatory.

{| class="wikitable"
! Part !! What it is !! Runs on
|-
| '''Recorder''' || the application: capture, playback, scheduling, file browser, OSC/MQTT/VNC || the machine with the capture hardware and the license dongle
|-
| '''Video portal''' || an unmodified PeerTube instance with the Stage Recorder plugin and theme, as three Docker containers (PeerTube, PostgreSQL, Redis) || the same machine, or any Linux machine, NAS or VM that runs Docker
|-
| '''MQTT broker''' || optional; needed only for MQTT remote control and status publishing || anywhere on the LAN, often the portal host
|-
| '''Mail server''' || optional; an existing SMTP account for the reminder digest || not deployed, only configured
|}

The recorder does not have to be reachable from the portal. Every transfer, including the portal's '''Bring back to recorder''' button, is initiated by the recorder: it uploads, it downloads, and it polls the portal every 30 s for fetch requests. The portal may therefore sit behind a firewall or a NAT the recorder cannot be reached through, and the recorder may sit behind one as well.

== Choosing a topology ==

{| class="wikitable"
! Topology !! When !! Trade-offs
|-
| '''A. One machine''' — recorder and portal on the recording PC || one venue, a few viewers on the same LAN, no spare hardware || simplest to set up; transcoding competes with real-time capture, so limit it (see below); Windows needs Docker Desktop with WSL 2
|-
| '''B. Two machines on the LAN''' — recorder plus a Linux portal host (NUC, NAS, VM) || the recommended configuration for a venue || the recording machine is not affected; the portal host performs the transcoding; each side needs only a host name and a port
|-
| '''C. Portal off site''' — a VPS or a server in the company network, reached over the internet || several venues share one portal, or viewers watch from outside the venue || put a TLS reverse proxy in front; uploads take the venue's upstream bandwidth, so use the transfer window; the recorder still needs no inbound port
|}

Rules that hold for every topology:

* The portal is addressed by '''exactly one name''' — <code>PEERTUBE_WEBSERVER_HOSTNAME</code> in its <code>.env</code>. PeerTube answers the login endpoint only when the <code>Host</code> header matches it; an IP address or a second alias gets <code>http 403</code>. Pick a name that every browser and the recorder can resolve (DNS, mDNS or a <code>hosts</code> entry), and use that same name in the recorder's <code>/Portal/URL</code>.
* <code>PEERTUBE_SECRET</code> is generated once and never changed after the instance has data.
* Keep the portal on plain HTTP only inside a trusted LAN. Any instance reachable from outside the LAN is placed behind a reverse proxy with TLS (topology C).

'''Recommendation:''' B for a venue, C when the portal serves more than one venue. A is adequate as a starting point and can be separated later: the recorder only knows the portal as a URL, so moving the stack means copying the <code>docker/</code> directory with its <code>volumes/</code> to the new host and changing <code>/Portal/URL</code>.

== Network reference ==

Inbound ports the recorder opens (all configurable in the settings tree):

{| class="wikitable"
! Port !! Protocol !! Purpose !! Key
|-
| 7000 || UDP || OSC commands || <code>/System/IO/OSC/Receive Port</code>
|-
| 5900 || TCP || VNC remote UI, only with VNC on || <code>/System/IO/VNC/Port</code>, <code>/System/IO/VNC/Use VNC</code>
|-
| 5800 || TCP || browser viewer and the links in the reminder mails, only with VNC on; <code>0</code> switches it off || <code>/System/IO/VNC/Web Port</code>
|}

Outbound connections the recorder makes:

{| class="wikitable"
! Target !! Port !! Purpose !! Key
|-
| MQTT broker || 1883 TCP || commands in, status out || <code>/System/IO/MQTT/Broker Address</code>, <code>/System/IO/MQTT/Use MQTT</code>
|-
| portal || 9000 TCP (443 behind a proxy) || uploads, downloads, fetch-request polling || <code>/Portal/URL</code>
|-
| SMTP server || 587 TCP || reminder digest || <code>/Mail/Server</code>, <code>/Mail/Port</code>
|}

Inbound port the portal opens: '''9000 TCP''' (<code>PEERTUBE_WEBSERVER_PORT</code>), or 80/443 on the reverse proxy in topology C.

The MQTT default <code>broker.hivemq.com</code> is a '''public''' broker. Either switch MQTT off or point it at a broker of your own (section "MQTT broker") before the system goes live.

== Part 1 — The recorder on Windows ==

'''1. Install.''' Run <code>Tourette_Stage_Recorder_5.0.<build>.exe</code> from <code>tools/installer/</code>. It installs the application to <code>C:\Program Files\Tourette Stage Recorder 5.0\</code> with the FFmpeg libraries, <code>ffmpeg.exe</code> (used to render H.264 proxies for the portal), the dongle library and the <code>files\</code> tree, and registers the <code>.mxr</code> / <code>.mxr_syncset</code> file types. A desktop and a start-menu shortcut are created.

'''2. Dongle.''' Plug in the Rockey4ND license dongle before the first start. Without it the application starts with no channels and a warning.

'''3. First start.''' Start from the shortcut. The settings file is created at <code>%APPDATA%\mxw_recorder\mxr_recorder.ini</code>; recordings go to <code>Documents\TouretteStageRecorder</code> until <code>/Recording/Root</code> says otherwise. Every key mentioned in this document appears in the configuration tree of the Settings tab after the first run.

'''4. Recording root.''' Set <code>/Recording/Root</code> to the recording disk. If that path is a mount that may be absent, note that a missing root at record start does not prevent the recording: the default root is used instead and the main tab shows a red banner.

'''5. Firewall.''' Windows asks on the first start; allow the application on the '''Private''' profile. If the rig's network is classified '''Public''', either reclassify it or add inbound rules by hand for UDP 7000 and, with VNC on, TCP 5900 and 5800:

<pre>
netsh advfirewall firewall add rule name="MXW Recorder OSC" dir=in action=allow protocol=UDP localport=7000
netsh advfirewall firewall add rule name="MXW Recorder VNC" dir=in action=allow protocol=TCP localport=5900,5800
</pre>

'''6. Proxies for the portal.''' With <code>/Portal/Use Upload Original</code> off (the default) every take that is not H.264 is encoded to an H.264 proxy with <code>h264_nvenc</code> before the upload; that needs an NVIDIA GPU. Without one the proxy step fails with <code>T003</code>/<code>T004</code> and the original goes up instead. <code>/System/FFmpeg Path</code> overrides the lookup (<code>ffmpeg.exe</code> next to the executable is found on its own).

'''7. Restart policy.''' Settings under <code>/System</code> are read once at startup. After changing any of them use the red '''Save & Restart''' button.

== Part 2 — The recorder on Linux ==

The recorder is installed from a <code>.deb</code> package. Description will follow.

== Part 3 — The video portal ==

The portal is the same on Windows and Linux: Docker with the Compose plugin, and the <code>tools/portal/</code> directory from the source tree. Node.js is not needed on the host; the plugin is packed inside the image build.

=== 3.1 Docker ===

* '''Linux (portal host or single machine):''' install Docker Engine and the Compose plugin from Docker's repository (<code>docker-ce</code>, <code>docker-compose-plugin</code>), add the operator to the <code>docker</code> group, log in again. Enable the service so the stack comes back after a reboot: <code>sudo systemctl enable docker</code>.
* '''Windows (single machine):''' install Docker Desktop with the WSL 2 backend and enable '''Start Docker Desktop when you sign in'''. Two properties of this configuration are relevant:
** WSL's '''mirrored networking''' mode makes the Linux side own the host's LAN address. A container can reach the Windows host only through <code>127.0.0.1</code>, not through the LAN address. For this reason the portal never connects to the recorder; no configuration is required for this, and no connection from the portal to the recorder should be set up.
** Transcoding runs inside WSL and competes with capture. Cap it in <code>%USERPROFILE%\.wslconfig</code> (for example <code>memory=8GB</code>, <code>processors=4</code>) and keep <code>MXR_TRANSCODE_RESOLUTIONS</code> to a single rendition.

=== 3.2 Configure and start ===

On the portal host, in a copy of the source tree (or only the <code>tools/portal/</code> directory):

<pre>
python3 tools/portal/build_portal.py --env --hostname portal.local --recorder-url http://recorder-pc:5800
cd tools/portal/docker
</pre>

<code>--env</code> writes <code>docker/.env</code> from <code>.env.example</code> with fresh secrets. Open it and check:

{| class="wikitable"
! Key !! Set it to
|-
| <code>PEERTUBE_WEBSERVER_HOSTNAME</code> || the one name the portal is reached by (see "Choosing a topology"); on a single machine <code>localhost</code> works for the recorder, but other browsers then need the machine's name — prefer the name
|-
| <code>PEERTUBE_WEBSERVER_PORT</code>, <code>PEERTUBE_WEBSERVER_HTTPS</code> || <code>9000</code> and <code>false</code> on the LAN; <code>443</code> and <code>true</code> behind a TLS proxy
|-
| <code>PEERTUBE_ADMIN_EMAIL</code>, <code>PT_INITIAL_ROOT_PASSWORD</code> || the admin account; the setup logs in with this password on every start
|-
| <code>MXR_RECORDER_USER</code>, <code>MXR_RECORDER_PASSWORD</code>, <code>MXR_RECORDER_CHANNEL</code> || the recorder's account and channel; the same values go into the recorder's <code>/Portal/User</code>, <code>/Portal/Password</code>, <code>/Portal/Channel</code>
|-
| <code>MXR_RECORDER_URL</code> || informational, shown in the plugin settings; no connection is made to it
|-
| <code>MXR_KEEP_ORIGINAL</code> || <code>true</code> when the recorder uploads originals (<code>/Portal/Use Upload Original</code>) and the disk can hold them; otherwise only renditions are kept
|-
| <code>MXR_TRANSCODE_RESOLUTIONS</code> || <code>720p</code> on a single machine, <code>720p,1080p</code> on a dedicated host
|-
| <code>MXR_INSTANCE_NAME</code> || the name in the browser tab and in the portal's mails
|}

Then:

<pre>
docker compose up -d
docker compose logs -f peertube # wait for "mxr setup: done"
</pre>

The setup step runs on every start and is idempotent: it installs or updates the plugin and the theme, creates the recorder user and channel, closes registration, sets the default privacy to '''internal''' (logged-in users only), configures transcoding and uploads the branding. Open <code>http://<hostname>:9000</code> in a browser and log in as the recorder user once to confirm.

=== 3.3 Offline portal host ===

Build the image on a machine with internet access and transfer it:

<pre>
python3 tools/portal/build_portal.py --save mxr-peertube.tar
# copy mxr-peertube.tar and tools/portal/docker/ (with .env) to the host
docker load -i mxr-peertube.tar
docker compose up -d
</pre>

=== 3.4 TLS and the outside world (topology C) ===

Put a reverse proxy with a certificate in front of port 9000 and expose only 443. With Caddy the complete configuration is one block:

<pre>
portal.example.org {
reverse_proxy 127.0.0.1:9000
}
</pre>

In <code>.env</code> set <code>PEERTUBE_WEBSERVER_HOSTNAME=portal.example.org</code>, <code>PEERTUBE_WEBSERVER_PORT=443</code>, <code>PEERTUBE_WEBSERVER_HTTPS=true</code>; the proxy's address must be covered by <code>PEERTUBE_TRUST_PROXY</code>. In the recorder <code>/Portal/URL</code> becomes <code>https://portal.example.org</code>. <code>/Portal/Use Insecure TLS</code> is only for a self-signed certificate on a LAN, never for a public host.

=== 3.5 Where the data lives, backup, updates ===

Everything is under <code>tools/portal/docker/volumes/</code> on the host:

{| class="wikitable"
! Directory !! Holds
|-
| <code>volumes/db/</code> || PostgreSQL — videos, chapters, users, the plugin's records and fetch queue
|-
| <code>volumes/data/streaming-playlists/hls/<uuid>/</code> || the transcoded renditions (what a fetch downloads when no original is kept)
|-
| <code>volumes/data/original-video-files/</code> || uploaded originals, only with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>volumes/data/thumbnails</code>, <code>previews</code>, <code>storyboards</code>, <code>captions</code>, <code>torrents</code> || derived assets
|-
| <code>volumes/config/</code> || PeerTube's production configuration
|}

* '''Backup:''' <code>docker compose stop</code>, copy <code>volumes/</code> and <code>.env</code> together, <code>docker compose start</code>. Database and files belong together — a video row points at its files by uuid.
* '''Move to another host:''' the same copy, then <code>docker compose up -d</code> there and a new <code>/Portal/URL</code> in the recorder if the name changed.
* '''Update:''' pull the new source tree, <code>python3 tools/portal/build_portal.py</code>, <code>docker compose up -d</code>. The setup updates the plugin and theme when their version changed.
* '''Disk:''' originals require the full take size per upload; renditions require approximately the proxy bitrate (<code>/Portal/Proxy Bitrate Mbit</code>, default 12) times the duration. The recorder's own retention (<code>/Storage/*</code>) never touches the portal; deleting on the portal is done in its admin, and the recorder's '''Re-sync with portal''' button then drops those takes from its index.

== Part 4 — Connect the recorder to the portal ==

In the recorder's Settings tab (password from <code>/System/SettingsKey</code>, default <code>123456</code>):

{| class="wikitable"
! Key !! Value
|-
| <code>/Portal/URL</code> || <code>http://<PEERTUBE_WEBSERVER_HOSTNAME>:9000</code> — exactly the name from <code>.env</code>, no IP
|-
| <code>/Portal/User</code>, <code>/Portal/Password</code> || <code>MXR_RECORDER_USER</code> / <code>MXR_RECORDER_PASSWORD</code>
|-
| <code>/Portal/Channel</code> || <code>MXR_RECORDER_CHANNEL</code>, or empty for the user's default channel
|-
| <code>/Portal/Privacy</code> || <code>internal</code> (default): visible to logged-in users only
|-
| <code>/Portal/Use Upload Original</code> || on only together with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>/Portal/Use Transfer While Recording</code> || off (default) keeps the upload bandwidth and the disk away from a running take
|-
| <code>/Portal/Transfer From Hour</code>, <code>/Portal/Transfer To Hour</code> || a window, e.g. <code>1</code> and <code>7</code> for nights; <code>0</code> and <code>24</code> means always
|}

'''Save & Restart.''' Then verify the connection:

* Record a short take, load it in the player, press '''Publish to portal'''. The file browser's flags column runs through '''uploading n %'''; the log says <code>portal: published <name> -> <url></code>.
* The Files tab's '''Portal''' view lists it after '''Reload'''. Open the portal page: title, tags and the markers as chapters are there.
* Delete the local file in the browser, press '''Fetch to local''' in the Portal view (or '''Bring back to recorder''' on the portal page): the file returns to its date folder, protected, with its markers.

If the login fails with <code>http 403</code>, the URL is not the configured host name. If the listing fails with <code>T008</code>, check the account and the channel name.

== Part 5 — MQTT broker ==

Required only when show control or monitoring uses MQTT. Any MQTT 3.1.1 broker is suitable; Mosquitto is used in the examples below.

* '''Linux:''' <code>sudo apt install mosquitto</code>, then in <code>/etc/mosquitto/conf.d/lan.conf</code>:

<pre>
listener 1883
allow_anonymous true
</pre>

<code>sudo systemctl enable --now mosquitto</code>. Restrict anonymous access to the LAN (bind the listener to the LAN interface, or add a password file for other clients); the recorder itself does not support broker authentication.

* '''Windows:''' the Mosquitto installer from mosquitto.org, the same two lines in <code>mosquitto.conf</code>, installed as a service.

In the recorder: <code>/System/IO/MQTT/Use MQTT</code> on, <code>/System/IO/MQTT/Broker Address</code> = the broker's name or IP, <code>/System/IO/MQTT/System ID</code> unique per recorder when several share a broker. Save & Restart. The broker's log shows <code>mxr-client-…</code> connecting.

== Part 6 — Reminder mails ==

The recorder sends one digest a day listing takes that crossed the warning age and those within a week of deletion, with a '''keep''' and a '''publish''' link per take. The links point at the recorder's web port, so they work only for people who can reach the recorder on port 5800.

{| class="wikitable"
! Key !! Value
|-
| <code>/Mail/Use Reminders</code> || on
|-
| <code>/Mail/Server</code>, <code>/Mail/Port</code>, <code>/Mail/Use TLS</code> || the SMTP account, default port 587 with STARTTLS
|-
| <code>/Mail/User</code>, <code>/Mail/Password</code>, <code>/Mail/From</code> || its credentials and sender address
|-
| <code>/Mail/Recipients</code> || comma-separated
|-
| <code>/Mail/Recorder URL</code> || how recipients reach the recorder, default <code>http://<hostname>:5800</code>; must match the VNC web port
|-
| <code>/Mail/Send Hour</code> || default <code>8</code>
|}

<code>/System/IO/VNC/Use VNC</code> must be on with a non-zero web port, otherwise <code>N001</code> is logged and the links cannot be answered.

== Checklists ==

'''Single machine, Windows (topology A)'''

* Installer, dongle, first start, <code>/Recording/Root</code>
* Docker Desktop with WSL 2, <code>.wslconfig</code> limits, <code>MXR_TRANSCODE_RESOLUTIONS=720p</code>
* <code>build_portal.py --env --hostname <pc-name></code>, <code>.env</code> checked, <code>docker compose up -d</code>, "mxr setup: done"
* <code>/Portal/*</code> in the recorder, Save & Restart, verification of the connection
* Firewall: UDP 7000 in; TCP 9000 in for other viewers; TCP 5900/5800 in only with VNC
* Transfer window set to the hours without shows

'''Two machines (topology B)'''

* Recorder as in Part 1 or 2
* Portal host: Docker Engine enabled at boot, <code>build_portal.py --env --hostname <portal-name></code>, <code>docker compose up -d</code>
* Name resolution for <code><portal-name></code> on the recorder and on the viewers' machines
* <code>/Portal/URL = http://<portal-name>:9000</code>, verification of the connection
* Backup plan for <code>volumes/</code> and <code>.env</code>

'''Off site (topology C)'''

* Everything from B on the server
* Reverse proxy with TLS, <code>.env</code> on 443/https, <code>PEERTUBE_TRUST_PROXY</code>
* <code>/Portal/URL = https://…</code>, transfer window for the venue's uplink
* Only 443 open on the server; the recorder needs no inbound port at all

Stage Recorder Deployment

2026-09-29T21:04:19Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Deployment: Recorder and Video Portal =

'''Covers:''' Windows and Linux · recorder and portal on one machine or on two · MQTT broker · reminder mails

== What gets deployed ==

A complete installation has up to four parts. Only the recorder is mandatory.

{| class="wikitable"
! Part !! What it is !! Runs on
|-
| '''Recorder''' || the application: capture, playback, scheduling, file browser, OSC/MQTT/VNC || the machine with the capture hardware and the license dongle
|-
| '''Video portal''' || an unmodified PeerTube instance with the Stage Recorder plugin and theme, as three Docker containers (PeerTube, PostgreSQL, Redis) || the same machine, or any Linux box, NAS or VM that runs Docker
|-
| '''MQTT broker''' || optional; needed only for MQTT remote control and status publishing || anywhere on the LAN, often the portal host
|-
| '''Mail server''' || optional; an existing SMTP account for the reminder digest || not deployed, only configured
|}

The recorder does not have to be reachable from the portal. Every transfer, including the portal's '''Bring back to recorder''' button, is initiated by the recorder: it uploads, it downloads, and it polls the portal every 30 s for fetch requests. The portal may therefore sit behind a firewall or a NAT the recorder cannot be reached through, and the recorder may sit behind one as well.

== Choosing a topology ==

{| class="wikitable"
! Topology !! When !! Trade-offs
|-
| '''A. One machine''' — recorder and portal on the recording PC || one venue, a few viewers on the same LAN, no spare hardware || simplest to set up; transcoding competes with real-time capture, so limit it (see below); Windows needs Docker Desktop with WSL 2
|-
| '''B. Two machines on the LAN''' — recorder plus a Linux portal host (NUC, NAS, VM) || the recommended configuration for a venue || the recording machine is not affected; the portal host performs the transcoding; each side needs only a host name and a port
|-
| '''C. Portal off site''' — a VPS or a server in the company network, reached over the internet || several venues share one portal, or viewers watch from outside the venue || put a TLS reverse proxy in front; uploads take the venue's upstream bandwidth, so use the transfer window; the recorder still needs no inbound port
|}

Rules that hold for every topology:

* The portal is addressed by '''exactly one name''' — <code>PEERTUBE_WEBSERVER_HOSTNAME</code> in its <code>.env</code>. PeerTube answers the login endpoint only when the <code>Host</code> header matches it; an IP address or a second alias gets <code>http 403</code>. Pick a name that every browser and the recorder can resolve (DNS, mDNS or a <code>hosts</code> entry), and use that same name in the recorder's <code>/Portal/URL</code>.
* <code>PEERTUBE_SECRET</code> is generated once and never changed after the instance has data.
* Keep the portal on plain HTTP only inside a trusted LAN. Anything reachable from outside gets a reverse proxy with TLS (topology C).

'''Recommendation:''' B for a venue, C when the portal serves more than one venue. A is adequate as a starting point and can be separated later: the recorder only knows the portal as a URL, so moving the stack means copying the <code>docker/</code> directory with its <code>volumes/</code> to the new host and changing <code>/Portal/URL</code>.

== Network reference ==

Inbound ports the recorder opens (all configurable in the settings tree):

{| class="wikitable"
! Port !! Protocol !! Purpose !! Key
|-
| 7000 || UDP || OSC commands || <code>/System/IO/OSC/Receive Port</code>
|-
| 5900 || TCP || VNC remote UI, only with VNC on || <code>/System/IO/VNC/Port</code>, <code>/System/IO/VNC/Use VNC</code>
|-
| 5800 || TCP || browser viewer and the links in the reminder mails, only with VNC on; <code>0</code> switches it off || <code>/System/IO/VNC/Web Port</code>
|}

Outbound connections the recorder makes:

{| class="wikitable"
! Target !! Port !! Purpose !! Key
|-
| MQTT broker || 1883 TCP || commands in, status out || <code>/System/IO/MQTT/Broker Address</code>, <code>/System/IO/MQTT/Use MQTT</code>
|-
| portal || 9000 TCP (443 behind a proxy) || uploads, downloads, fetch-request polling || <code>/Portal/URL</code>
|-
| SMTP server || 587 TCP || reminder digest || <code>/Mail/Server</code>, <code>/Mail/Port</code>
|}

Inbound port the portal opens: '''9000 TCP''' (<code>PEERTUBE_WEBSERVER_PORT</code>), or 80/443 on the reverse proxy in topology C.

The MQTT default <code>broker.hivemq.com</code> is a '''public''' broker. Either switch MQTT off or point it at a broker of your own (section "MQTT broker") before the system goes live.

== Part 1 — The recorder on Windows ==

'''1. Install.''' Run <code>Tourette_Stage_Recorder_5.0.<build>.exe</code> from <code>tools/installer/</code>. It installs the application to <code>C:\Program Files\Tourette Stage Recorder 5.0\</code> with the FFmpeg libraries, <code>ffmpeg.exe</code> (used to render H.264 proxies for the portal), the dongle library and the <code>files\</code> tree, and registers the <code>.mxr</code> / <code>.mxr_syncset</code> file types. A desktop and a start-menu shortcut are created.

'''2. Dongle.''' Plug in the Rockey4ND license dongle before the first start. Without it the application starts with no channels and a warning.

'''3. First start.''' Start from the shortcut. The settings file is created at <code>%APPDATA%\mxw_recorder\mxr_recorder.ini</code>; recordings go to <code>Documents\TouretteStageRecorder</code> until <code>/Recording/Root</code> says otherwise. Every key mentioned in this document appears in the configuration tree of the Settings tab after the first run.

'''4. Recording root.''' Set <code>/Recording/Root</code> to the recording disk. If that path is a mount that may be absent, note that a missing root at record start does not prevent the recording: the default root is used instead and the main tab shows a red banner.

'''5. Firewall.''' Windows asks on the first start; allow the application on the '''Private''' profile. If the rig's network is classified '''Public''', either reclassify it or add inbound rules by hand for UDP 7000 and, with VNC on, TCP 5900 and 5800:

<pre>
netsh advfirewall firewall add rule name="MXW Recorder OSC" dir=in action=allow protocol=UDP localport=7000
netsh advfirewall firewall add rule name="MXW Recorder VNC" dir=in action=allow protocol=TCP localport=5900,5800
</pre>

'''6. Proxies for the portal.''' With <code>/Portal/Use Upload Original</code> off (the default) every take that is not H.264 is encoded to an H.264 proxy with <code>h264_nvenc</code> before the upload; that needs an NVIDIA GPU. Without one the proxy step fails with <code>T003</code>/<code>T004</code> and the original goes up instead. <code>/System/FFmpeg Path</code> overrides the lookup (<code>ffmpeg.exe</code> next to the executable is found on its own).

'''7. Restart policy.''' Settings under <code>/System</code> are read once at startup. After changing any of them use the red '''Save & Restart''' button.

== Part 2 — The recorder on Linux ==

The recorder is installed from a <code>.deb</code> package. Description will follow.

== Part 3 — The video portal ==

The portal is the same on Windows and Linux: Docker with the Compose plugin, and the <code>tools/portal/</code> directory from the source tree. Node.js is not needed on the host; the plugin is packed inside the image build.

=== 3.1 Docker ===

* '''Linux (portal host or single machine):''' install Docker Engine and the Compose plugin from Docker's repository (<code>docker-ce</code>, <code>docker-compose-plugin</code>), add the operator to the <code>docker</code> group, log in again. Enable the service so the stack comes back after a reboot: <code>sudo systemctl enable docker</code>.
* '''Windows (single machine):''' install Docker Desktop with the WSL 2 backend and enable '''Start Docker Desktop when you sign in'''. Two facts matter on this setup:
** WSL's '''mirrored networking''' mode makes the Linux side own the host's LAN address. A container can reach the Windows host only through <code>127.0.0.1</code>, not through the LAN IP. For this reason the portal never connects to the recorder; no configuration is required for this, and no connection from the portal to the recorder should be set up.
** Transcoding runs inside WSL and competes with capture. Cap it in <code>%USERPROFILE%\.wslconfig</code> (for example <code>memory=8GB</code>, <code>processors=4</code>) and keep <code>MXR_TRANSCODE_RESOLUTIONS</code> to a single rendition.

=== 3.2 Configure and start ===

On the portal host, in a copy of the source tree (or just the <code>tools/portal/</code> directory):

<pre>
python3 tools/portal/build_portal.py --env --hostname portal.local --recorder-url http://recorder-pc:5800
cd tools/portal/docker
</pre>

<code>--env</code> writes <code>docker/.env</code> from <code>.env.example</code> with fresh secrets. Open it and check:

{| class="wikitable"
! Key !! Set it to
|-
| <code>PEERTUBE_WEBSERVER_HOSTNAME</code> || the one name the portal is reached by (see "Choosing a topology"); on a single machine <code>localhost</code> works for the recorder, but other browsers then need the machine's name — prefer the name
|-
| <code>PEERTUBE_WEBSERVER_PORT</code>, <code>PEERTUBE_WEBSERVER_HTTPS</code> || <code>9000</code> and <code>false</code> on the LAN; <code>443</code> and <code>true</code> behind a TLS proxy
|-
| <code>PEERTUBE_ADMIN_EMAIL</code>, <code>PT_INITIAL_ROOT_PASSWORD</code> || the admin account; the setup logs in with this password on every start
|-
| <code>MXR_RECORDER_USER</code>, <code>MXR_RECORDER_PASSWORD</code>, <code>MXR_RECORDER_CHANNEL</code> || the recorder's account and channel; the same values go into the recorder's <code>/Portal/User</code>, <code>/Portal/Password</code>, <code>/Portal/Channel</code>
|-
| <code>MXR_RECORDER_URL</code> || informational, shown in the plugin settings; no connection is made to it
|-
| <code>MXR_KEEP_ORIGINAL</code> || <code>true</code> when the recorder uploads originals (<code>/Portal/Use Upload Original</code>) and the disk can hold them; otherwise only renditions are kept
|-
| <code>MXR_TRANSCODE_RESOLUTIONS</code> || <code>720p</code> on a single machine, <code>720p,1080p</code> on a dedicated host
|-
| <code>MXR_INSTANCE_NAME</code> || the name in the browser tab and in the portal's mails
|}

Then:

<pre>
docker compose up -d
docker compose logs -f peertube # wait for "mxr setup: done"
</pre>

The setup step runs on every start and is idempotent: it installs or updates the plugin and the theme, creates the recorder user and channel, closes registration, sets the default privacy to '''internal''' (logged-in users only), configures transcoding and uploads the branding. Open <code>http://<hostname>:9000</code> in a browser and log in as the recorder user once to confirm.

=== 3.3 Offline portal host ===

Build the image on a machine with internet access and transfer it:

<pre>
python3 tools/portal/build_portal.py --save mxr-peertube.tar
# copy mxr-peertube.tar and tools/portal/docker/ (with .env) to the host
docker load -i mxr-peertube.tar
docker compose up -d
</pre>

=== 3.4 TLS and the outside world (topology C) ===

Put a reverse proxy with a certificate in front of port 9000 and expose only 443. With Caddy the complete configuration is one block:

<pre>
portal.example.org {
reverse_proxy 127.0.0.1:9000
}
</pre>

In <code>.env</code> set <code>PEERTUBE_WEBSERVER_HOSTNAME=portal.example.org</code>, <code>PEERTUBE_WEBSERVER_PORT=443</code>, <code>PEERTUBE_WEBSERVER_HTTPS=true</code>; the proxy's address must be covered by <code>PEERTUBE_TRUST_PROXY</code>. In the recorder <code>/Portal/URL</code> becomes <code>https://portal.example.org</code>. <code>/Portal/Use Insecure TLS</code> is only for a self-signed certificate on a LAN, never for a public host.

=== 3.5 Where the data lives, backup, updates ===

Everything is under <code>tools/portal/docker/volumes/</code> on the host:

{| class="wikitable"
! Directory !! Holds
|-
| <code>volumes/db/</code> || PostgreSQL — videos, chapters, users, the plugin's records and fetch queue
|-
| <code>volumes/data/streaming-playlists/hls/<uuid>/</code> || the transcoded renditions (what a fetch downloads when no original is kept)
|-
| <code>volumes/data/original-video-files/</code> || uploaded originals, only with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>volumes/data/thumbnails</code>, <code>previews</code>, <code>storyboards</code>, <code>captions</code>, <code>torrents</code> || derived assets
|-
| <code>volumes/config/</code> || PeerTube's production configuration
|}

* '''Backup:''' <code>docker compose stop</code>, copy <code>volumes/</code> and <code>.env</code> together, <code>docker compose start</code>. Database and files belong together — a video row points at its files by uuid.
* '''Move to another host:''' the same copy, then <code>docker compose up -d</code> there and a new <code>/Portal/URL</code> in the recorder if the name changed.
* '''Update:''' pull the new source tree, <code>python3 tools/portal/build_portal.py</code>, <code>docker compose up -d</code>. The setup updates the plugin and theme when their version changed.
* '''Disk:''' originals require the full take size per upload; renditions require approximately the proxy bitrate (<code>/Portal/Proxy Bitrate Mbit</code>, default 12) times the duration. The recorder's own retention (<code>/Storage/*</code>) never touches the portal; deleting on the portal is done in its admin, and the recorder's '''Re-sync with portal''' button then drops those takes from its index.

== Part 4 — Connect the recorder to the portal ==

In the recorder's Settings tab (password from <code>/System/SettingsKey</code>, default <code>123456</code>):

{| class="wikitable"
! Key !! Value
|-
| <code>/Portal/URL</code> || <code>http://<PEERTUBE_WEBSERVER_HOSTNAME>:9000</code> — exactly the name from <code>.env</code>, no IP
|-
| <code>/Portal/User</code>, <code>/Portal/Password</code> || <code>MXR_RECORDER_USER</code> / <code>MXR_RECORDER_PASSWORD</code>
|-
| <code>/Portal/Channel</code> || <code>MXR_RECORDER_CHANNEL</code>, or empty for the user's default channel
|-
| <code>/Portal/Privacy</code> || <code>internal</code> (default): visible to logged-in users only
|-
| <code>/Portal/Use Upload Original</code> || on only together with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>/Portal/Use Transfer While Recording</code> || off (default) keeps the upload bandwidth and the disk away from a running take
|-
| <code>/Portal/Transfer From Hour</code>, <code>/Portal/Transfer To Hour</code> || a window, e.g. <code>1</code> and <code>7</code> for nights; <code>0</code> and <code>24</code> means always
|}

'''Save & Restart.''' Then verify the connection:

* Record a short take, load it in the player, press '''Publish to portal'''. The file browser's flags column runs through '''uploading n %'''; the log says <code>portal: published <name> -> <url></code>.
* The Files tab's '''Portal''' view lists it after '''Reload'''. Open the portal page: title, tags and the markers as chapters are there.
* Delete the local file in the browser, press '''Fetch to local''' in the Portal view (or '''Bring back to recorder''' on the portal page): the file returns to its date folder, protected, with its markers.

If the login fails with <code>http 403</code>, the URL is not the configured host name. If the listing fails with <code>T008</code>, check the account and the channel name.

== Part 5 — MQTT broker ==

Required only when show control or monitoring uses MQTT. Any MQTT 3.1.1 broker is suitable; Mosquitto is used in the examples below.

* '''Linux:''' <code>sudo apt install mosquitto</code>, then in <code>/etc/mosquitto/conf.d/lan.conf</code>:

<pre>
listener 1883
allow_anonymous true
</pre>

<code>sudo systemctl enable --now mosquitto</code>. Restrict anonymous access to the LAN (bind the listener to the LAN interface, or add a password file for other clients); the recorder itself does not support broker authentication.

* '''Windows:''' the Mosquitto installer from mosquitto.org, the same two lines in <code>mosquitto.conf</code>, installed as a service.

In the recorder: <code>/System/IO/MQTT/Use MQTT</code> on, <code>/System/IO/MQTT/Broker Address</code> = the broker's name or IP, <code>/System/IO/MQTT/System ID</code> unique per recorder when several share a broker. Save & Restart. The broker's log shows <code>mxr-client-…</code> connecting.

== Part 6 — Reminder mails ==

The recorder sends one digest a day listing takes that crossed the warning age and those within a week of deletion, with a '''keep''' and a '''publish''' link per take. The links point at the recorder's web port, so they work only for people who can reach the recorder on port 5800.

{| class="wikitable"
! Key !! Value
|-
| <code>/Mail/Use Reminders</code> || on
|-
| <code>/Mail/Server</code>, <code>/Mail/Port</code>, <code>/Mail/Use TLS</code> || the SMTP account, default port 587 with STARTTLS
|-
| <code>/Mail/User</code>, <code>/Mail/Password</code>, <code>/Mail/From</code> || its credentials and sender address
|-
| <code>/Mail/Recipients</code> || comma-separated
|-
| <code>/Mail/Recorder URL</code> || how recipients reach the recorder, default <code>http://<hostname>:5800</code>; must match the VNC web port
|-
| <code>/Mail/Send Hour</code> || default <code>8</code>
|}

<code>/System/IO/VNC/Use VNC</code> must be on with a non-zero web port, otherwise <code>N001</code> is logged and the links cannot be answered.

== Checklists ==

'''Single machine, Windows (topology A)'''

* Installer, dongle, first start, <code>/Recording/Root</code>
* Docker Desktop with WSL 2, <code>.wslconfig</code> limits, <code>MXR_TRANSCODE_RESOLUTIONS=720p</code>
* <code>build_portal.py --env --hostname <pc-name></code>, <code>.env</code> checked, <code>docker compose up -d</code>, "mxr setup: done"
* <code>/Portal/*</code> in the recorder, Save & Restart, verification of the connection
* Firewall: UDP 7000 in; TCP 9000 in for other viewers; TCP 5900/5800 in only with VNC
* Transfer window set to the hours without shows

'''Two machines (topology B)'''

* Recorder as in Part 1 or 2
* Portal host: Docker Engine enabled at boot, <code>build_portal.py --env --hostname <portal-name></code>, <code>docker compose up -d</code>
* Name resolution for <code><portal-name></code> on the recorder and on the viewers' machines
* <code>/Portal/URL = http://<portal-name>:9000</code>, verification of the connection
* Backup plan for <code>volumes/</code> and <code>.env</code>

'''Off site (topology C)'''

* Everything from B on the server
* Reverse proxy with TLS, <code>.env</code> on 443/https, <code>PEERTUBE_TRUST_PROXY</code>
* <code>/Portal/URL = https://…</code>, transfer window for the venue's uplink
* Only 443 open on the server; the recorder needs no inbound port at all

Stage Recorder Deployment

2026-09-29T20:57:51Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Deployment: Recorder and Video Portal =

'''Covers:''' Windows and Linux · recorder and portal on one machine or on two · MQTT broker · reminder mails

== What gets deployed ==

A complete installation has up to four parts. Only the recorder is mandatory.

{| class="wikitable"
! Part !! What it is !! Runs on
|-
| '''Recorder''' || the application: capture, playback, scheduling, file browser, OSC/MQTT/VNC || the machine with the capture hardware and the license dongle
|-
| '''Video portal''' || a stock PeerTube instance with our plugin and theme, as three Docker containers (PeerTube, PostgreSQL, Redis) || the same machine, or any Linux box, NAS or VM that runs Docker
|-
| '''MQTT broker''' || optional; needed only for MQTT remote control and status publishing || anywhere on the LAN, often the portal host
|-
| '''Mail server''' || optional; an existing SMTP account for the reminder digest || not deployed, only configured
|}

The recorder never has to be reachable from the portal. Every transfer, including the portal's '''Bring back to recorder''' button, is initiated by the recorder: it uploads, it downloads, and it polls the portal every 30 s for fetch requests. The portal may therefore sit behind a firewall or a NAT the recorder cannot be reached through, and the recorder may sit behind one as well.

== Choosing a topology ==

{| class="wikitable"
! Topology !! When !! Trade-offs
|-
| '''A. One machine''' — recorder and portal on the recording PC || one venue, a few viewers on the same LAN, no spare hardware || simplest to set up; transcoding competes with real-time capture, so limit it (see below); Windows needs Docker Desktop with WSL 2
|-
| '''B. Two machines on the LAN''' — recorder plus a Linux portal host (NUC, NAS, VM) || the normal case for a venue || the recording PC stays untouched; the portal host does the transcoding; both sides only need a name and a port
|-
| '''C. Portal off site''' — a VPS or a server in the company network, reached over the internet || several venues share one portal, or people watch from home || put a TLS reverse proxy in front; uploads take the venue's upstream bandwidth, so use the transfer window; the recorder still needs no inbound port
|}

Rules that hold for every topology:

* The portal is addressed by '''exactly one name''' — <code>PEERTUBE_WEBSERVER_HOSTNAME</code> in its <code>.env</code>. PeerTube answers the login endpoint only when the <code>Host</code> header matches it; an IP address or a second alias gets <code>http 403</code>. Pick a name that every browser and the recorder can resolve (DNS, mDNS or a <code>hosts</code> entry), and use that same name in the recorder's <code>/Portal/URL</code>.
* <code>PEERTUBE_SECRET</code> is generated once and never changed after the instance has data.
* Keep the portal on plain HTTP only inside a trusted LAN. Anything reachable from outside gets a reverse proxy with TLS (topology C).

'''Recommendation:''' B for a venue, C when the portal serves more than one venue. A is fine to start with and can be split later: the recorder only knows the portal as a URL, so moving the stack means copying the <code>docker/</code> directory with its <code>volumes/</code> to the new host and changing <code>/Portal/URL</code>.

== Network reference ==

Inbound ports the recorder opens (all configurable in the settings tree):

{| class="wikitable"
! Port !! Protocol !! Purpose !! Key
|-
| 7000 || UDP || OSC commands || <code>/System/IO/OSC/Receive Port</code>
|-
| 5900 || TCP || VNC remote UI, only with VNC on || <code>/System/IO/VNC/Port</code>, <code>/System/IO/VNC/Use VNC</code>
|-
| 5800 || TCP || browser viewer and the links in the reminder mails, only with VNC on; <code>0</code> switches it off || <code>/System/IO/VNC/Web Port</code>
|}

Outbound connections the recorder makes:

{| class="wikitable"
! Target !! Port !! Purpose !! Key
|-
| MQTT broker || 1883 TCP || commands in, status out || <code>/System/IO/MQTT/Broker Address</code>, <code>/System/IO/MQTT/Use MQTT</code>
|-
| portal || 9000 TCP (443 behind a proxy) || uploads, downloads, fetch-request polling || <code>/Portal/URL</code>
|-
| SMTP server || 587 TCP || reminder digest || <code>/Mail/Server</code>, <code>/Mail/Port</code>
|}

Inbound port the portal opens: '''9000 TCP''' (<code>PEERTUBE_WEBSERVER_PORT</code>), or 80/443 on the reverse proxy in topology C.

The MQTT default <code>broker.hivemq.com</code> is a '''public''' broker. Either switch MQTT off or point it at a broker of your own (section "MQTT broker") before the system goes live.

== Part 1 — The recorder on Windows ==

'''1. Install.''' Run <code>Tourette_Stage_Recorder_5.0.<build>.exe</code> from <code>tools/installer/</code>. It installs to <code>C:\Program Files\Tourette Stage Recorder 5.0\</code> with the FFmpeg libraries, <code>ffmpeg.exe</code> (used to render H.264 proxies for the portal), the dongle library and the <code>files\</code> tree, and registers the <code>.mxr</code> / <code>.mxr_syncset</code> file types. A desktop and a start-menu shortcut are created.

'''2. Dongle.''' Plug in the Rockey4ND license dongle before the first start. Without it the application starts with no channels and a warning.

'''3. First start.''' Start from the shortcut. The settings file is created at <code>%APPDATA%\mxw_recorder\mxr_recorder.ini</code>; recordings go to <code>Documents\TouretteStageRecorder</code> until <code>/Recording/Root</code> says otherwise. Every key mentioned in this document appears in the Settings tab's configuration tree once the application has run once.

'''4. Recording root.''' Set <code>/Recording/Root</code> to the recording disk. If that path is a mount that can go away, know that a missing root at record start is not fatal: the default root stands in and the main tab shows a red banner.

'''5. Firewall.''' Windows asks on the first start; allow the application on the '''Private''' profile. If the rig's network is classified '''Public''', either reclassify it or add inbound rules by hand for UDP 7000 and, with VNC on, TCP 5900 and 5800:

<pre>
netsh advfirewall firewall add rule name="MXW Recorder OSC" dir=in action=allow protocol=UDP localport=7000
netsh advfirewall firewall add rule name="MXW Recorder VNC" dir=in action=allow protocol=TCP localport=5900,5800
</pre>

'''6. Proxies for the portal.''' With <code>/Portal/Use Upload Original</code> off (the default) every take that is not H.264 is encoded to an H.264 proxy with <code>h264_nvenc</code> before the upload; that needs an NVIDIA GPU. Without one the proxy step fails with <code>T003</code>/<code>T004</code> and the original goes up instead. <code>/System/FFmpeg Path</code> overrides the lookup (<code>ffmpeg.exe</code> next to the executable is found on its own).

'''7. Restart policy.''' Settings under <code>/System</code> are read once at startup. After changing any of them use the red '''Save & Restart''' button.

== Part 2 — The recorder on Linux ==

The recorder is installed from a <code>.deb</code> package. Description will follow.

== Part 3 — The video portal ==

The portal is the same on Windows and Linux: Docker with the Compose plugin, and the <code>tools/portal/</code> directory from the source tree. Node.js is not needed on the host; the plugin is packed inside the image build.

=== 3.1 Docker ===

* '''Linux (portal host or single machine):''' install Docker Engine and the Compose plugin from Docker's repository (<code>docker-ce</code>, <code>docker-compose-plugin</code>), add the operator to the <code>docker</code> group, log in again. Enable the service so the stack comes back after a reboot: <code>sudo systemctl enable docker</code>.
* '''Windows (single machine):''' install Docker Desktop with the WSL 2 backend and enable '''Start Docker Desktop when you sign in'''. Two facts matter on this setup:
** WSL's '''mirrored networking''' mode makes the Linux side own the host's LAN address. A container can reach the Windows host only through <code>127.0.0.1</code>, not through the LAN IP. That is why the portal never connects to the recorder — nothing to configure, but do not try to make it.
** Transcoding runs inside WSL and competes with capture. Cap it in <code>%USERPROFILE%\.wslconfig</code> (for example <code>memory=8GB</code>, <code>processors=4</code>) and keep <code>MXR_TRANSCODE_RESOLUTIONS</code> to a single rendition.

=== 3.2 Configure and start ===

On the portal host, in a copy of the source tree (or just the <code>tools/portal/</code> directory):

<pre>
python3 tools/portal/build_portal.py --env --hostname portal.local --recorder-url http://recorder-pc:5800
cd tools/portal/docker
</pre>

<code>--env</code> writes <code>docker/.env</code> from <code>.env.example</code> with fresh secrets. Open it and check:

{| class="wikitable"
! Key !! Set it to
|-
| <code>PEERTUBE_WEBSERVER_HOSTNAME</code> || the one name the portal is reached by (see "Choosing a topology"); on a single machine <code>localhost</code> works for the recorder, but other browsers then need the machine's name — prefer the name
|-
| <code>PEERTUBE_WEBSERVER_PORT</code>, <code>PEERTUBE_WEBSERVER_HTTPS</code> || <code>9000</code> and <code>false</code> on the LAN; <code>443</code> and <code>true</code> behind a TLS proxy
|-
| <code>PEERTUBE_ADMIN_EMAIL</code>, <code>PT_INITIAL_ROOT_PASSWORD</code> || the admin account; the setup logs in with this password on every start
|-
| <code>MXR_RECORDER_USER</code>, <code>MXR_RECORDER_PASSWORD</code>, <code>MXR_RECORDER_CHANNEL</code> || the recorder's account and channel; the same values go into the recorder's <code>/Portal/User</code>, <code>/Portal/Password</code>, <code>/Portal/Channel</code>
|-
| <code>MXR_RECORDER_URL</code> || informational, shown in the plugin settings; nothing connects to it
|-
| <code>MXR_KEEP_ORIGINAL</code> || <code>true</code> when the recorder uploads originals (<code>/Portal/Use Upload Original</code>) and the disk can hold them; otherwise only renditions are kept
|-
| <code>MXR_TRANSCODE_RESOLUTIONS</code> || <code>720p</code> on a single machine, <code>720p,1080p</code> on a dedicated host
|-
| <code>MXR_INSTANCE_NAME</code> || the name in the browser tab and in the portal's mails
|}

Then:

<pre>
docker compose up -d
docker compose logs -f peertube # wait for "mxr setup: done"
</pre>

The setup step runs on every start and is idempotent: it installs or updates the plugin and the theme, creates the recorder user and channel, closes registration, sets the default privacy to '''internal''' (logged-in users only), configures transcoding and uploads the branding. Open <code>http://<hostname>:9000</code> in a browser and log in as the recorder user once to confirm.

=== 3.3 Offline portal host ===

Build on a machine with internet access, carry the image over:

<pre>
python3 tools/portal/build_portal.py --save mxr-peertube.tar
# copy mxr-peertube.tar and tools/portal/docker/ (with .env) to the host
docker load -i mxr-peertube.tar
docker compose up -d
</pre>

=== 3.4 TLS and the outside world (topology C) ===

Put a reverse proxy with a certificate in front of port 9000 and expose only 443. With Caddy the whole configuration is one block:

<pre>
portal.example.org {
reverse_proxy 127.0.0.1:9000
}
</pre>

In <code>.env</code> set <code>PEERTUBE_WEBSERVER_HOSTNAME=portal.example.org</code>, <code>PEERTUBE_WEBSERVER_PORT=443</code>, <code>PEERTUBE_WEBSERVER_HTTPS=true</code>; the proxy's address must be covered by <code>PEERTUBE_TRUST_PROXY</code>. In the recorder <code>/Portal/URL</code> becomes <code>https://portal.example.org</code>. <code>/Portal/Use Insecure TLS</code> is only for a self-signed certificate on a LAN, never for a public host.

=== 3.5 Where the data lives, backup, updates ===

Everything is under <code>tools/portal/docker/volumes/</code> on the host:

{| class="wikitable"
! Directory !! Holds
|-
| <code>volumes/db/</code> || PostgreSQL — videos, chapters, users, the plugin's records and fetch queue
|-
| <code>volumes/data/streaming-playlists/hls/<uuid>/</code> || the transcoded renditions (what a fetch downloads when no original is kept)
|-
| <code>volumes/data/original-video-files/</code> || uploaded originals, only with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>volumes/data/thumbnails</code>, <code>previews</code>, <code>storyboards</code>, <code>captions</code>, <code>torrents</code> || derived assets
|-
| <code>volumes/config/</code> || PeerTube's production configuration
|}

* '''Backup:''' <code>docker compose stop</code>, copy <code>volumes/</code> and <code>.env</code> together, <code>docker compose start</code>. Database and files belong together — a video row points at its files by uuid.
* '''Move to another host:''' the same copy, then <code>docker compose up -d</code> there and a new <code>/Portal/URL</code> in the recorder if the name changed.
* '''Update:''' pull the new source tree, <code>python3 tools/portal/build_portal.py</code>, <code>docker compose up -d</code>. The setup updates the plugin and theme when their version changed.
* '''Disk:''' originals cost the full take size per upload; renditions cost roughly the proxy bitrate (<code>/Portal/Proxy Bitrate Mbit</code>, default 12) times the duration. The recorder's own retention (<code>/Storage/*</code>) never touches the portal; deleting on the portal is done in its admin, and the recorder's '''Re-sync with portal''' button then drops those takes from its index.

== Part 4 — Connect the recorder to the portal ==

In the recorder's Settings tab (password from <code>/System/SettingsKey</code>, default <code>123456</code>):

{| class="wikitable"
! Key !! Value
|-
| <code>/Portal/URL</code> || <code>http://<PEERTUBE_WEBSERVER_HOSTNAME>:9000</code> — exactly the name from <code>.env</code>, no IP
|-
| <code>/Portal/User</code>, <code>/Portal/Password</code> || <code>MXR_RECORDER_USER</code> / <code>MXR_RECORDER_PASSWORD</code>
|-
| <code>/Portal/Channel</code> || <code>MXR_RECORDER_CHANNEL</code>, or empty for the user's default channel
|-
| <code>/Portal/Privacy</code> || <code>internal</code> (default): visible to logged-in users only
|-
| <code>/Portal/Use Upload Original</code> || on only together with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>/Portal/Use Transfer While Recording</code> || off (default) keeps the upload bandwidth and the disk away from a running take
|-
| <code>/Portal/Transfer From Hour</code>, <code>/Portal/Transfer To Hour</code> || a window, e.g. <code>1</code> and <code>7</code> for nights; <code>0</code> and <code>24</code> means always
|}

'''Save & Restart.''' Then a smoke test:

* Record a short take, load it in the player, press '''Publish to portal'''. The file browser's flags column runs through '''uploading n %'''; the log says <code>portal: published <name> -> <url></code>.
* The Files tab's '''Portal''' view lists it after '''Reload'''. Open the portal page: title, tags and the markers as chapters are there.
* Delete the local file in the browser, press '''Fetch to local''' in the Portal view (or '''Bring back to recorder''' on the portal page): the file returns to its date folder, protected, with its markers.

If the login fails with <code>http 403</code>, the URL is not the configured host name. If the listing fails with <code>T008</code>, check the account and the channel name.

== Part 5 — MQTT broker ==

Only needed when show control or monitoring uses MQTT. Any MQTT 3.1.1 broker works; Mosquitto is the usual choice.

* '''Linux:''' <code>sudo apt install mosquitto</code>, then in <code>/etc/mosquitto/conf.d/lan.conf</code>:

<pre>
listener 1883
allow_anonymous true
</pre>

<code>sudo systemctl enable --now mosquitto</code>. Restrict <code>allow_anonymous</code> to the LAN (bind to the LAN interface, or add a password file) — the recorder supports no broker authentication.

* '''Windows:''' the Mosquitto installer from mosquitto.org, the same two lines in <code>mosquitto.conf</code>, installed as a service.

In the recorder: <code>/System/IO/MQTT/Use MQTT</code> on, <code>/System/IO/MQTT/Broker Address</code> = the broker's name or IP, <code>/System/IO/MQTT/System ID</code> unique per recorder when several share a broker. Save & Restart. The broker's log shows <code>mxr-client-…</code> connecting.

== Part 6 — Reminder mails ==

The recorder sends one digest a day listing takes that crossed the warning age and those within a week of deletion, with a '''keep''' and a '''publish''' link per take. The links point at the recorder's web port, so they work only for people who can reach the recorder on port 5800.

{| class="wikitable"
! Key !! Value
|-
| <code>/Mail/Use Reminders</code> || on
|-
| <code>/Mail/Server</code>, <code>/Mail/Port</code>, <code>/Mail/Use TLS</code> || the SMTP account, default port 587 with STARTTLS
|-
| <code>/Mail/User</code>, <code>/Mail/Password</code>, <code>/Mail/From</code> || its credentials and sender address
|-
| <code>/Mail/Recipients</code> || comma-separated
|-
| <code>/Mail/Recorder URL</code> || how recipients reach the recorder, default <code>http://<hostname>:5800</code>; must match the VNC web port
|-
| <code>/Mail/Send Hour</code> || default <code>8</code>
|}

<code>/System/IO/VNC/Use VNC</code> must be on with a non-zero web port, otherwise <code>N001</code> warns and the links lead nowhere.

== Checklists ==

'''Single machine, Windows (topology A)'''

* Installer, dongle, first start, <code>/Recording/Root</code>
* Docker Desktop with WSL 2, <code>.wslconfig</code> limits, <code>MXR_TRANSCODE_RESOLUTIONS=720p</code>
* <code>build_portal.py --env --hostname <pc-name></code>, <code>.env</code> checked, <code>docker compose up -d</code>, "mxr setup: done"
* <code>/Portal/*</code> in the recorder, Save & Restart, smoke test
* Firewall: UDP 7000 in; TCP 9000 in for other viewers; TCP 5900/5800 in only with VNC
* Transfer window set to the hours without shows

'''Two machines (topology B)'''

* Recorder as in Part 1 or 2
* Portal host: Docker Engine enabled at boot, <code>build_portal.py --env --hostname <portal-name></code>, <code>docker compose up -d</code>
* Name resolution for <code><portal-name></code> on the recorder and on the viewers' machines
* <code>/Portal/URL = http://<portal-name>:9000</code>, smoke test
* Backup plan for <code>volumes/</code> and <code>.env</code>

'''Off site (topology C)'''

* Everything from B on the server
* Reverse proxy with TLS, <code>.env</code> on 443/https, <code>PEERTUBE_TRUST_PROXY</code>
* <code>/Portal/URL = https://…</code>, transfer window for the venue's uplink
* Only 443 open on the server; the recorder needs no inbound port at all

Stage Recorder Deployment

2026-09-29T20:41:45Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Deployment: Recorder and Video Portal =

'''Covers:''' Windows and Linux · recorder and portal on one machine or on two · MQTT broker · reminder mails

== What gets deployed ==

A complete installation has up to four parts. Only the recorder is mandatory.

{| class="wikitable"
! Part !! What it is !! Runs on
|-
| '''Recorder''' || the application: capture, playback, scheduling, file browser, OSC/MQTT/VNC || the machine with the capture hardware and the license dongle
|-
| '''Video portal''' || a stock PeerTube instance with our plugin and theme, as three Docker containers (PeerTube, PostgreSQL, Redis) || the same machine, or any Linux box, NAS or VM that runs Docker
|-
| '''MQTT broker''' || optional; needed only for MQTT remote control and status publishing || anywhere on the LAN, often the portal host
|-
| '''Mail server''' || optional; an existing SMTP account for the reminder digest || not deployed, only configured
|}

The recorder never has to be reachable from the portal. Every transfer, including the portal's '''Bring back to recorder''' button, is initiated by the recorder: it uploads, it downloads, and it polls the portal every 30 s for fetch requests. The portal may therefore sit behind a firewall or a NAT the recorder cannot be reached through, and the recorder may sit behind one as well.

== Choosing a topology ==

{| class="wikitable"
! Topology !! When !! Trade-offs
|-
| '''A. One machine''' — recorder and portal on the recording PC || one venue, a few viewers on the same LAN, no spare hardware || simplest to set up; transcoding competes with real-time capture, so limit it (see below); Windows needs Docker Desktop with WSL 2
|-
| '''B. Two machines on the LAN''' — recorder plus a Linux portal host (NUC, NAS, VM) || the normal case for a venue || the recording PC stays untouched; the portal host does the transcoding; both sides only need a name and a port
|-
| '''C. Portal off site''' — a VPS or a server in the company network, reached over the internet || several venues share one portal, or people watch from home || put a TLS reverse proxy in front; uploads take the venue's upstream bandwidth, so use the transfer window; the recorder still needs no inbound port
|}

Rules that hold for every topology:

* The portal is addressed by '''exactly one name''' — <code>PEERTUBE_WEBSERVER_HOSTNAME</code> in its <code>.env</code>. PeerTube answers the login endpoint only when the <code>Host</code> header matches it; an IP address or a second alias gets <code>http 403</code>. Pick a name that every browser and the recorder can resolve (DNS, mDNS or a <code>hosts</code> entry), and use that same name in the recorder's <code>/Portal/URL</code>.
* <code>PEERTUBE_SECRET</code> is generated once and never changed after the instance has data.
* Keep the portal on plain HTTP only inside a trusted LAN. Anything reachable from outside gets a reverse proxy with TLS (topology C).

'''Recommendation:''' B for a venue, C when the portal serves more than one venue. A is fine to start with and can be split later: the recorder only knows the portal as a URL, so moving the stack means copying the <code>docker/</code> directory with its <code>volumes/</code> to the new host and changing <code>/Portal/URL</code>.

== Network reference ==

Inbound ports the recorder opens (all configurable in the settings tree):

{| class="wikitable"
! Port !! Protocol !! Purpose !! Key
|-
| 7000 || UDP || OSC commands || <code>/System/IO/OSC/Receive Port</code>
|-
| 5900 || TCP || VNC remote UI, only with VNC on || <code>/System/IO/VNC/Port</code>, <code>/System/IO/VNC/Use VNC</code>
|-
| 5800 || TCP || browser viewer and the links in the reminder mails, only with VNC on; <code>0</code> switches it off || <code>/System/IO/VNC/Web Port</code>
|}

Outbound connections the recorder makes:

{| class="wikitable"
! Target !! Port !! Purpose !! Key
|-
| MQTT broker || 1883 TCP || commands in, status out || <code>/System/IO/MQTT/Broker Address</code>, <code>/System/IO/MQTT/Use MQTT</code>
|-
| portal || 9000 TCP (443 behind a proxy) || uploads, downloads, fetch-request polling || <code>/Portal/URL</code>
|-
| SMTP server || 587 TCP || reminder digest || <code>/Mail/Server</code>, <code>/Mail/Port</code>
|}

Inbound port the portal opens: '''9000 TCP''' (<code>PEERTUBE_WEBSERVER_PORT</code>), or 80/443 on the reverse proxy in topology C.

The MQTT default <code>broker.hivemq.com</code> is a '''public''' broker. Either switch MQTT off or point it at a broker of your own (section "MQTT broker") before the system goes live.

== Part 1 — The recorder on Windows ==

'''1. Install.''' Run <code>Tourette_Stage_Recorder_5.0.<build>.exe</code> from <code>tools/installer/</code>. It installs to <code>C:\Program Files\Tourette Stage Recorder 5.0\</code> with the FFmpeg libraries, <code>ffmpeg.exe</code> (used to render H.264 proxies for the portal), the dongle library and the <code>files\</code> tree, and registers the <code>.mxr</code> / <code>.mxr_syncset</code> file types. A desktop and a start-menu shortcut are created.

'''2. Dongle.''' Plug in the Rockey4ND license dongle before the first start. Without it the application starts with no channels and a warning.

'''3. First start.''' Start from the shortcut. The settings file is created at <code>%APPDATA%\mxw_recorder\mxr_recorder.ini</code>; recordings go to <code>Documents\TouretteStageRecorder</code> until <code>/Recording/Root</code> says otherwise. Every key mentioned in this document appears in the Settings tab's configuration tree once the application has run once.

'''4. Recording root.''' Set <code>/Recording/Root</code> to the recording disk. If that path is a mount that can go away, know that a missing root at record start is not fatal: the default root stands in and the main tab shows a red banner.

'''5. Firewall.''' Windows asks on the first start; allow the application on the '''Private''' profile. If the rig's network is classified '''Public''', either reclassify it or add inbound rules by hand for UDP 7000 and, with VNC on, TCP 5900 and 5800:

<pre>
netsh advfirewall firewall add rule name="MXW Recorder OSC" dir=in action=allow protocol=UDP localport=7000
netsh advfirewall firewall add rule name="MXW Recorder VNC" dir=in action=allow protocol=TCP localport=5900,5800
</pre>

'''6. Proxies for the portal.''' With <code>/Portal/Use Upload Original</code> off (the default) every take that is not H.264 is encoded to an H.264 proxy with <code>h264_nvenc</code> before the upload; that needs an NVIDIA GPU. Without one the proxy step fails with <code>T003</code>/<code>T004</code> and the original goes up instead. <code>/System/FFmpeg Path</code> overrides the lookup (<code>ffmpeg.exe</code> next to the executable is found on its own).

'''7. Restart policy.''' Settings under <code>/System</code> are read once at startup. After changing any of them use the red '''Save & Restart''' button.

== Part 2 — The recorder on Linux ==

There is no package; the recorder is built from the source tree on the target machine or on an identical one.

'''1. Packages''' (Debian/Ubuntu names; the tree links wxWidgets 3.2 GTK3 with OpenGL, PortAudio from its submodule, system zlib and libcurl):

<pre>
sudo apt install build-essential cmake git python3 \
libwxgtk3.2-dev libgl1-mesa-dev libasound2-dev \
zlib1g-dev libcurl4-openssl-dev ffmpeg
</pre>

<code>ffmpeg</code> (the command line tool) is what renders the portal proxies; the recorder looks for it at <code>/usr/bin/ffmpeg</code> or wherever <code>/System/FFmpeg Path</code> points. Zlib and libcurl are fetched and built at configure time when the development packages are missing, so they are optional.

'''2. Build.'''

<pre>
git clone --recurse-submodules <repo> mxw_recorder
cd mxw_recorder
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
</pre>

The result is <code>build/mxw_recorder</code>. Run it from the '''repository root''' — the <code>files/</code> tree (skin, fonts, translations) is found relative to the working directory:

<pre>
cd /path/to/mxw_recorder && ./build/mxw_recorder
</pre>

'''3. Dongle.''' The Rockey4ND library talks to the dongle over USB; the user running the recorder needs access to that USB device. Add a udev rule for the dongle's vendor/product id (see <code>lsusb</code> with the dongle plugged in) that grants the recorder's group read/write access, then replug.

'''4. Settings and recordings.''' The settings file is <code>mxr_recorder.ini</code> in the application's user data directory (by default <code>~/.mxw_recorder/</code>). Set <code>/Recording/Root</code> after the first start.

'''5. Firewall.''' With <code>ufw</code>:

<pre>
sudo ufw allow 7000/udp # OSC
sudo ufw allow 5900,5800/tcp # VNC and browser viewer, only with VNC on
</pre>

'''6. Autostart.''' For a kiosk, start the recorder from the desktop session's autostart (it needs a display and OpenGL; a plain systemd service without a session will not do), with the working directory set to the repository root.

== Part 3 — The video portal ==

The portal is the same on Windows and Linux: Docker with the Compose plugin, and the <code>tools/portal/</code> directory from the source tree. Node.js is not needed on the host; the plugin is packed inside the image build.

=== 3.1 Docker ===

* '''Linux (portal host or single machine):''' install Docker Engine and the Compose plugin from Docker's repository (<code>docker-ce</code>, <code>docker-compose-plugin</code>), add the operator to the <code>docker</code> group, log in again. Enable the service so the stack comes back after a reboot: <code>sudo systemctl enable docker</code>.
* '''Windows (single machine):''' install Docker Desktop with the WSL 2 backend and enable '''Start Docker Desktop when you sign in'''. Two facts matter on this setup:
** WSL's '''mirrored networking''' mode makes the Linux side own the host's LAN address. A container can reach the Windows host only through <code>127.0.0.1</code>, not through the LAN IP. That is why the portal never connects to the recorder — nothing to configure, but do not try to make it.
** Transcoding runs inside WSL and competes with capture. Cap it in <code>%USERPROFILE%\.wslconfig</code> (for example <code>memory=8GB</code>, <code>processors=4</code>) and keep <code>MXR_TRANSCODE_RESOLUTIONS</code> to a single rendition.

=== 3.2 Configure and start ===

On the portal host, in a copy of the source tree (or just the <code>tools/portal/</code> directory):

<pre>
python3 tools/portal/build_portal.py --env --hostname portal.local --recorder-url http://recorder-pc:5800
cd tools/portal/docker
</pre>

<code>--env</code> writes <code>docker/.env</code> from <code>.env.example</code> with fresh secrets. Open it and check:

{| class="wikitable"
! Key !! Set it to
|-
| <code>PEERTUBE_WEBSERVER_HOSTNAME</code> || the one name the portal is reached by (see "Choosing a topology"); on a single machine <code>localhost</code> works for the recorder, but other browsers then need the machine's name — prefer the name
|-
| <code>PEERTUBE_WEBSERVER_PORT</code>, <code>PEERTUBE_WEBSERVER_HTTPS</code> || <code>9000</code> and <code>false</code> on the LAN; <code>443</code> and <code>true</code> behind a TLS proxy
|-
| <code>PEERTUBE_ADMIN_EMAIL</code>, <code>PT_INITIAL_ROOT_PASSWORD</code> || the admin account; the setup logs in with this password on every start
|-
| <code>MXR_RECORDER_USER</code>, <code>MXR_RECORDER_PASSWORD</code>, <code>MXR_RECORDER_CHANNEL</code> || the recorder's account and channel; the same values go into the recorder's <code>/Portal/User</code>, <code>/Portal/Password</code>, <code>/Portal/Channel</code>
|-
| <code>MXR_RECORDER_URL</code> || informational, shown in the plugin settings; nothing connects to it
|-
| <code>MXR_KEEP_ORIGINAL</code> || <code>true</code> when the recorder uploads originals (<code>/Portal/Use Upload Original</code>) and the disk can hold them; otherwise only renditions are kept
|-
| <code>MXR_TRANSCODE_RESOLUTIONS</code> || <code>720p</code> on a single machine, <code>720p,1080p</code> on a dedicated host
|-
| <code>MXR_INSTANCE_NAME</code> || the name in the browser tab and in the portal's mails
|}

Then:

<pre>
docker compose up -d
docker compose logs -f peertube # wait for "mxr setup: done"
</pre>

The setup step runs on every start and is idempotent: it installs or updates the plugin and the theme, creates the recorder user and channel, closes registration, sets the default privacy to '''internal''' (logged-in users only), configures transcoding and uploads the branding. Open <code>http://<hostname>:9000</code> in a browser and log in as the recorder user once to confirm.

=== 3.3 Offline portal host ===

Build on a machine with internet access, carry the image over:

<pre>
python3 tools/portal/build_portal.py --save mxr-peertube.tar
# copy mxr-peertube.tar and tools/portal/docker/ (with .env) to the host
docker load -i mxr-peertube.tar
docker compose up -d
</pre>

=== 3.4 TLS and the outside world (topology C) ===

Put a reverse proxy with a certificate in front of port 9000 and expose only 443. With Caddy the whole configuration is one block:

<pre>
portal.example.org {
reverse_proxy 127.0.0.1:9000
}
</pre>

In <code>.env</code> set <code>PEERTUBE_WEBSERVER_HOSTNAME=portal.example.org</code>, <code>PEERTUBE_WEBSERVER_PORT=443</code>, <code>PEERTUBE_WEBSERVER_HTTPS=true</code>; the proxy's address must be covered by <code>PEERTUBE_TRUST_PROXY</code>. In the recorder <code>/Portal/URL</code> becomes <code>https://portal.example.org</code>. <code>/Portal/Use Insecure TLS</code> is only for a self-signed certificate on a LAN, never for a public host.

=== 3.5 Where the data lives, backup, updates ===

Everything is under <code>tools/portal/docker/volumes/</code> on the host:

{| class="wikitable"
! Directory !! Holds
|-
| <code>volumes/db/</code> || PostgreSQL — videos, chapters, users, the plugin's records and fetch queue
|-
| <code>volumes/data/streaming-playlists/hls/<uuid>/</code> || the transcoded renditions (what a fetch downloads when no original is kept)
|-
| <code>volumes/data/original-video-files/</code> || uploaded originals, only with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>volumes/data/thumbnails</code>, <code>previews</code>, <code>storyboards</code>, <code>captions</code>, <code>torrents</code> || derived assets
|-
| <code>volumes/config/</code> || PeerTube's production configuration
|}

* '''Backup:''' <code>docker compose stop</code>, copy <code>volumes/</code> and <code>.env</code> together, <code>docker compose start</code>. Database and files belong together — a video row points at its files by uuid.
* '''Move to another host:''' the same copy, then <code>docker compose up -d</code> there and a new <code>/Portal/URL</code> in the recorder if the name changed.
* '''Update:''' pull the new source tree, <code>python3 tools/portal/build_portal.py</code>, <code>docker compose up -d</code>. The setup updates the plugin and theme when their version changed.
* '''Disk:''' originals cost the full take size per upload; renditions cost roughly the proxy bitrate (<code>/Portal/Proxy Bitrate Mbit</code>, default 12) times the duration. The recorder's own retention (<code>/Storage/*</code>) never touches the portal; deleting on the portal is done in its admin, and the recorder's '''Re-sync with portal''' button then drops those takes from its index.

== Part 4 — Connect the recorder to the portal ==

In the recorder's Settings tab (password from <code>/System/SettingsKey</code>, default <code>123456</code>):

{| class="wikitable"
! Key !! Value
|-
| <code>/Portal/URL</code> || <code>http://<PEERTUBE_WEBSERVER_HOSTNAME>:9000</code> — exactly the name from <code>.env</code>, no IP
|-
| <code>/Portal/User</code>, <code>/Portal/Password</code> || <code>MXR_RECORDER_USER</code> / <code>MXR_RECORDER_PASSWORD</code>
|-
| <code>/Portal/Channel</code> || <code>MXR_RECORDER_CHANNEL</code>, or empty for the user's default channel
|-
| <code>/Portal/Privacy</code> || <code>internal</code> (default): visible to logged-in users only
|-
| <code>/Portal/Use Upload Original</code> || on only together with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>/Portal/Use Transfer While Recording</code> || off (default) keeps the upload bandwidth and the disk away from a running take
|-
| <code>/Portal/Transfer From Hour</code>, <code>/Portal/Transfer To Hour</code> || a window, e.g. <code>1</code> and <code>7</code> for nights; <code>0</code> and <code>24</code> means always
|}

'''Save & Restart.''' Then a smoke test:

* Record a short take, load it in the player, press '''Publish to portal'''. The file browser's flags column runs through '''uploading n %'''; the log says <code>portal: published <name> -> <url></code>.
* The Files tab's '''Portal''' view lists it after '''Reload'''. Open the portal page: title, tags and the markers as chapters are there.
* Delete the local file in the browser, press '''Fetch to local''' in the Portal view (or '''Bring back to recorder''' on the portal page): the file returns to its date folder, protected, with its markers.

If the login fails with <code>http 403</code>, the URL is not the configured host name. If the listing fails with <code>T008</code>, check the account and the channel name.

== Part 5 — MQTT broker ==

Only needed when show control or monitoring uses MQTT. Any MQTT 3.1.1 broker works; Mosquitto is the usual choice.

* '''Linux:''' <code>sudo apt install mosquitto</code>, then in <code>/etc/mosquitto/conf.d/lan.conf</code>:

<pre>
listener 1883
allow_anonymous true
</pre>

<code>sudo systemctl enable --now mosquitto</code>. Restrict <code>allow_anonymous</code> to the LAN (bind to the LAN interface, or add a password file) — the recorder supports no broker authentication.

* '''Windows:''' the Mosquitto installer from mosquitto.org, the same two lines in <code>mosquitto.conf</code>, installed as a service.

In the recorder: <code>/System/IO/MQTT/Use MQTT</code> on, <code>/System/IO/MQTT/Broker Address</code> = the broker's name or IP, <code>/System/IO/MQTT/System ID</code> unique per recorder when several share a broker. Save & Restart. The broker's log shows <code>mxr-client-…</code> connecting.

== Part 6 — Reminder mails ==

The recorder sends one digest a day listing takes that crossed the warning age and those within a week of deletion, with a '''keep''' and a '''publish''' link per take. The links point at the recorder's web port, so they work only for people who can reach the recorder on port 5800.

{| class="wikitable"
! Key !! Value
|-
| <code>/Mail/Use Reminders</code> || on
|-
| <code>/Mail/Server</code>, <code>/Mail/Port</code>, <code>/Mail/Use TLS</code> || the SMTP account, default port 587 with STARTTLS
|-
| <code>/Mail/User</code>, <code>/Mail/Password</code>, <code>/Mail/From</code> || its credentials and sender address
|-
| <code>/Mail/Recipients</code> || comma-separated
|-
| <code>/Mail/Recorder URL</code> || how recipients reach the recorder, default <code>http://<hostname>:5800</code>; must match the VNC web port
|-
| <code>/Mail/Send Hour</code> || default <code>8</code>
|}

<code>/System/IO/VNC/Use VNC</code> must be on with a non-zero web port, otherwise <code>N001</code> warns and the links lead nowhere.

== Checklists ==

'''Single machine, Windows (topology A)'''

* Installer, dongle, first start, <code>/Recording/Root</code>
* Docker Desktop with WSL 2, <code>.wslconfig</code> limits, <code>MXR_TRANSCODE_RESOLUTIONS=720p</code>
* <code>build_portal.py --env --hostname <pc-name></code>, <code>.env</code> checked, <code>docker compose up -d</code>, "mxr setup: done"
* <code>/Portal/*</code> in the recorder, Save & Restart, smoke test
* Firewall: UDP 7000 in; TCP 9000 in for other viewers; TCP 5900/5800 in only with VNC
* Transfer window set to the hours without shows

'''Two machines (topology B)'''

* Recorder as in Part 1 or 2
* Portal host: Docker Engine enabled at boot, <code>build_portal.py --env --hostname <portal-name></code>, <code>docker compose up -d</code>
* Name resolution for <code><portal-name></code> on the recorder and on the viewers' machines
* <code>/Portal/URL = http://<portal-name>:9000</code>, smoke test
* Backup plan for <code>volumes/</code> and <code>.env</code>

'''Off site (topology C)'''

* Everything from B on the server
* Reverse proxy with TLS, <code>.env</code> on 443/https, <code>PEERTUBE_TRUST_PROXY</code>
* <code>/Portal/URL = https://…</code>, transfer window for the venue's uplink
* Only 443 open on the server; the recorder needs no inbound port at all

Stage Recorder Deployment

2026-09-29T20:40:45Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Deployment: Recorder and Video Portal =

'''Covers:''' Windows and Linux · recorder and portal on one machine or on two · MQTT broker · reminder mails

== What gets deployed ==

A complete installation has up to four parts. Only the recorder is mandatory.

{| class="wikitable"
! Part !! What it is !! Runs on
|-
| '''Recorder''' || the application: capture, playback, scheduling, file browser, OSC/MQTT/VNC || the machine with the capture hardware and the license dongle
|-
| '''Video portal''' || a stock PeerTube instance with our plugin and theme, as three Docker containers (PeerTube, PostgreSQL, Redis) || the same machine, or any Linux box, NAS or VM that runs Docker
|-
| '''MQTT broker''' || optional; needed only for MQTT remote control and status publishing || anywhere on the LAN, often the portal host
|-
| '''Mail server''' || optional; an existing SMTP account for the reminder digest || not deployed, only configured
|}

The recorder never has to be reachable from the portal. Every transfer, including the portal's ''Bring back to recorder'' button, is initiated by the recorder: it uploads, it downloads, and it polls the portal every 30 s for fetch requests. The portal may therefore sit behind a firewall or a NAT the recorder cannot be reached through, and the recorder may sit behind one as well.

== Choosing a topology ==

{| class="wikitable"
! Topology !! When !! Trade-offs
|-
| '''A. One machine''' — recorder and portal on the recording PC || one venue, a few viewers on the same LAN, no spare hardware || simplest to set up; transcoding competes with real-time capture, so limit it (see below); Windows needs Docker Desktop with WSL 2
|-
| '''B. Two machines on the LAN''' — recorder plus a Linux portal host (NUC, NAS, VM) || the normal case for a venue || the recording PC stays untouched; the portal host does the transcoding; both sides only need a name and a port
|-
| '''C. Portal off site''' — a VPS or a server in the company network, reached over the internet || several venues share one portal, or people watch from home || put a TLS reverse proxy in front; uploads take the venue's upstream bandwidth, so use the transfer window; the recorder still needs no inbound port
|}

Rules that hold for every topology:

* The portal is addressed by '''exactly one name''' — <code>PEERTUBE_WEBSERVER_HOSTNAME</code> in its <code>.env</code>. PeerTube answers the login endpoint only when the <code>Host</code> header matches it; an IP address or a second alias gets <code>http 403</code>. Pick a name that every browser and the recorder can resolve (DNS, mDNS or a <code>hosts</code> entry), and use that same name in the recorder's <code>/Portal/URL</code>.
* <code>PEERTUBE_SECRET</code> is generated once and never changed after the instance has data.
* Keep the portal on plain HTTP only inside a trusted LAN. Anything reachable from outside gets a reverse proxy with TLS (topology C).

'''Recommendation:''' B for a venue, C when the portal serves more than one venue. A is fine to start with and can be split later: the recorder only knows the portal as a URL, so moving the stack means copying the <code>docker/</code> directory with its <code>volumes/</code> to the new host and changing <code>/Portal/URL</code>.

== Network reference ==

Inbound ports the recorder opens (all configurable in the settings tree):

{| class="wikitable"
! Port !! Protocol !! Purpose !! Key
|-
| 7000 || UDP || OSC commands || <code>/System/IO/OSC/Receive Port</code>
|-
| 5900 || TCP || VNC remote UI, only with VNC on || <code>/System/IO/VNC/Port</code>, <code>/System/IO/VNC/Use VNC</code>
|-
| 5800 || TCP || browser viewer and the links in the reminder mails, only with VNC on; <code>0</code> switches it off || <code>/System/IO/VNC/Web Port</code>
|}

Outbound connections the recorder makes:

{| class="wikitable"
! Target !! Port !! Purpose !! Key
|-
| MQTT broker || 1883 TCP || commands in, status out || <code>/System/IO/MQTT/Broker Address</code>, <code>/System/IO/MQTT/Use MQTT</code>
|-
| portal || 9000 TCP (443 behind a proxy) || uploads, downloads, fetch-request polling || <code>/Portal/URL</code>
|-
| SMTP server || 587 TCP || reminder digest || <code>/Mail/Server</code>, <code>/Mail/Port</code>
|}

Inbound port the portal opens: '''9000 TCP''' (<code>PEERTUBE_WEBSERVER_PORT</code>), or 80/443 on the reverse proxy in topology C.

The MQTT default <code>broker.hivemq.com</code> is a '''public''' broker. Either switch MQTT off or point it at a broker of your own (section "MQTT broker") before the system goes live.

== Part 1 — The recorder on Windows ==

'''1. Install.''' Run <code>Tourette_Stage_Recorder_5.0.<build>.exe</code> from <code>tools/installer/</code>. It installs to <code>C:\Program Files\Tourette Stage Recorder 5.0\</code> with the FFmpeg libraries, <code>ffmpeg.exe</code> (used to render H.264 proxies for the portal), the dongle library and the <code>files\</code> tree, and registers the <code>.mxr</code> / <code>.mxr_syncset</code> file types. A desktop and a start-menu shortcut are created.

'''2. Dongle.''' Plug in the Rockey4ND license dongle before the first start. Without it the application starts with no channels and a warning.

'''3. First start.''' Start from the shortcut. The settings file is created at <code>%APPDATA%\mxw_recorder\mxr_recorder.ini</code>; recordings go to <code>Documents\TouretteStageRecorder</code> until <code>/Recording/Root</code> says otherwise. Every key mentioned in this document appears in the Settings tab's configuration tree once the application has run once.

'''4. Recording root.''' Set <code>/Recording/Root</code> to the recording disk. If that path is a mount that can go away, know that a missing root at record start is not fatal: the default root stands in and the main tab shows a red banner.

'''5. Firewall.''' Windows asks on the first start; allow the application on the ''Private'' profile. If the rig's network is classified ''Public'', either reclassify it or add inbound rules by hand for UDP 7000 and, with VNC on, TCP 5900 and 5800:

<pre>
netsh advfirewall firewall add rule name="MXW Recorder OSC" dir=in action=allow protocol=UDP localport=7000
netsh advfirewall firewall add rule name="MXW Recorder VNC" dir=in action=allow protocol=TCP localport=5900,5800
</pre>

'''6. Proxies for the portal.''' With <code>/Portal/Use Upload Original</code> off (the default) every take that is not H.264 is encoded to an H.264 proxy with <code>h264_nvenc</code> before the upload; that needs an NVIDIA GPU. Without one the proxy step fails with <code>T003</code>/<code>T004</code> and the original goes up instead. <code>/System/FFmpeg Path</code> overrides the lookup (<code>ffmpeg.exe</code> next to the executable is found on its own).

'''7. Restart policy.''' Settings under <code>/System</code> are read once at startup. After changing any of them use the red '''Save & Restart''' button.

== Part 2 — The recorder on Linux ==

There is no package; the recorder is built from the source tree on the target machine or on an identical one.

'''1. Packages''' (Debian/Ubuntu names; the tree links wxWidgets 3.2 GTK3 with OpenGL, PortAudio from its submodule, system zlib and libcurl):

<pre>
sudo apt install build-essential cmake git python3 \
libwxgtk3.2-dev libgl1-mesa-dev libasound2-dev \
zlib1g-dev libcurl4-openssl-dev ffmpeg
</pre>

<code>ffmpeg</code> (the command line tool) is what renders the portal proxies; the recorder looks for it at <code>/usr/bin/ffmpeg</code> or wherever <code>/System/FFmpeg Path</code> points. Zlib and libcurl are fetched and built at configure time when the development packages are missing, so they are optional.

'''2. Build.'''

<pre>
git clone --recurse-submodules <repo> mxw_recorder
cd mxw_recorder
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)
</pre>

The result is <code>build/mxw_recorder</code>. Run it from the '''repository root''' — the <code>files/</code> tree (skin, fonts, translations) is found relative to the working directory:

<pre>
cd /path/to/mxw_recorder && ./build/mxw_recorder
</pre>

'''3. Dongle.''' The Rockey4ND library talks to the dongle over USB; the user running the recorder needs access to that USB device. Add a udev rule for the dongle's vendor/product id (see <code>lsusb</code> with the dongle plugged in) that grants the recorder's group read/write access, then replug.

'''4. Settings and recordings.''' The settings file is <code>mxr_recorder.ini</code> in the application's user data directory (by default <code>~/.mxw_recorder/</code>). Set <code>/Recording/Root</code> after the first start.

'''5. Firewall.''' With <code>ufw</code>:

<pre>
sudo ufw allow 7000/udp # OSC
sudo ufw allow 5900,5800/tcp # VNC and browser viewer, only with VNC on
</pre>

'''6. Autostart.''' For a kiosk, start the recorder from the desktop session's autostart (it needs a display and OpenGL; a plain systemd service without a session will not do), with the working directory set to the repository root.

== Part 3 — The video portal ==

The portal is the same on Windows and Linux: Docker with the Compose plugin, and the <code>tools/portal/</code> directory from the source tree. Node.js is not needed on the host; the plugin is packed inside the image build.

=== 3.1 Docker ===

* '''Linux (portal host or single machine):''' install Docker Engine and the Compose plugin from Docker's repository (<code>docker-ce</code>, <code>docker-compose-plugin</code>), add the operator to the <code>docker</code> group, log in again. Enable the service so the stack comes back after a reboot: <code>sudo systemctl enable docker</code>.
* '''Windows (single machine):''' install Docker Desktop with the WSL 2 backend and enable ''Start Docker Desktop when you sign in''. Two facts matter on this setup:
** WSL's '''mirrored networking''' mode makes the Linux side own the host's LAN address. A container can reach the Windows host only through <code>127.0.0.1</code>, not through the LAN IP. That is why the portal never connects to the recorder — nothing to configure, but do not try to make it.
** Transcoding runs inside WSL and competes with capture. Cap it in <code>%USERPROFILE%\.wslconfig</code> (for example <code>memory=8GB</code>, <code>processors=4</code>) and keep <code>MXR_TRANSCODE_RESOLUTIONS</code> to a single rendition.

=== 3.2 Configure and start ===

On the portal host, in a copy of the source tree (or just the <code>tools/portal/</code> directory):

<pre>
python3 tools/portal/build_portal.py --env --hostname portal.local --recorder-url http://recorder-pc:5800
cd tools/portal/docker
</pre>

<code>--env</code> writes <code>docker/.env</code> from <code>.env.example</code> with fresh secrets. Open it and check:

{| class="wikitable"
! Key !! Set it to
|-
| <code>PEERTUBE_WEBSERVER_HOSTNAME</code> || the one name the portal is reached by (see "Choosing a topology"); on a single machine <code>localhost</code> works for the recorder, but other browsers then need the machine's name — prefer the name
|-
| <code>PEERTUBE_WEBSERVER_PORT</code>, <code>PEERTUBE_WEBSERVER_HTTPS</code> || <code>9000</code> and <code>false</code> on the LAN; <code>443</code> and <code>true</code> behind a TLS proxy
|-
| <code>PEERTUBE_ADMIN_EMAIL</code>, <code>PT_INITIAL_ROOT_PASSWORD</code> || the admin account; the setup logs in with this password on every start
|-
| <code>MXR_RECORDER_USER</code>, <code>MXR_RECORDER_PASSWORD</code>, <code>MXR_RECORDER_CHANNEL</code> || the recorder's account and channel; the same values go into the recorder's <code>/Portal/User</code>, <code>/Portal/Password</code>, <code>/Portal/Channel</code>
|-
| <code>MXR_RECORDER_URL</code> || informational, shown in the plugin settings; nothing connects to it
|-
| <code>MXR_KEEP_ORIGINAL</code> || <code>true</code> when the recorder uploads originals (<code>/Portal/Use Upload Original</code>) and the disk can hold them; otherwise only renditions are kept
|-
| <code>MXR_TRANSCODE_RESOLUTIONS</code> || <code>720p</code> on a single machine, <code>720p,1080p</code> on a dedicated host
|-
| <code>MXR_INSTANCE_NAME</code> || the name in the browser tab and in the portal's mails
|}

Then:

<pre>
docker compose up -d
docker compose logs -f peertube # wait for "mxr setup: done"
</pre>

The setup step runs on every start and is idempotent: it installs or updates the plugin and the theme, creates the recorder user and channel, closes registration, sets the default privacy to ''internal'' (logged-in users only), configures transcoding and uploads the branding. Open <code>http://<hostname>:9000</code> in a browser and log in as the recorder user once to confirm.

=== 3.3 Offline portal host ===

Build on a machine with internet access, carry the image over:

<pre>
python3 tools/portal/build_portal.py --save mxr-peertube.tar
# copy mxr-peertube.tar and tools/portal/docker/ (with .env) to the host
docker load -i mxr-peertube.tar
docker compose up -d
</pre>

=== 3.4 TLS and the outside world (topology C) ===

Put a reverse proxy with a certificate in front of port 9000 and expose only 443. With Caddy the whole configuration is one block:

<pre>
portal.example.org {
reverse_proxy 127.0.0.1:9000
}
</pre>

In <code>.env</code> set <code>PEERTUBE_WEBSERVER_HOSTNAME=portal.example.org</code>, <code>PEERTUBE_WEBSERVER_PORT=443</code>, <code>PEERTUBE_WEBSERVER_HTTPS=true</code>; the proxy's address must be covered by <code>PEERTUBE_TRUST_PROXY</code>. In the recorder <code>/Portal/URL</code> becomes <code>https://portal.example.org</code>. <code>/Portal/Use Insecure TLS</code> is only for a self-signed certificate on a LAN, never for a public host.

=== 3.5 Where the data lives, backup, updates ===

Everything is under <code>tools/portal/docker/volumes/</code> on the host:

{| class="wikitable"
! Directory !! Holds
|-
| <code>volumes/db/</code> || PostgreSQL — videos, chapters, users, the plugin's records and fetch queue
|-
| <code>volumes/data/streaming-playlists/hls/<uuid>/</code> || the transcoded renditions (what a fetch downloads when no original is kept)
|-
| <code>volumes/data/original-video-files/</code> || uploaded originals, only with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>volumes/data/{thumbnails,previews,storyboards,captions,torrents}</code> || derived assets
|-
| <code>volumes/config/</code> || PeerTube's production configuration
|}

* '''Backup:''' <code>docker compose stop</code>, copy <code>volumes/</code> and <code>.env</code> together, <code>docker compose start</code>. Database and files belong together — a video row points at its files by uuid.
* '''Move to another host:''' the same copy, then <code>docker compose up -d</code> there and a new <code>/Portal/URL</code> in the recorder if the name changed.
* '''Update:''' pull the new source tree, <code>python3 tools/portal/build_portal.py</code>, <code>docker compose up -d</code>. The setup updates the plugin and theme when their version changed.
* '''Disk:''' originals cost the full take size per upload; renditions cost roughly the proxy bitrate (<code>/Portal/Proxy Bitrate Mbit</code>, default 12) times the duration. The recorder's own retention (<code>/Storage/*</code>) never touches the portal; deleting on the portal is done in its admin, and the recorder's '''Re-sync with portal''' button then drops those takes from its index.

== Part 4 — Connect the recorder to the portal ==

In the recorder's Settings tab (password from <code>/System/SettingsKey</code>, default <code>123456</code>):

{| class="wikitable"
! Key !! Value
|-
| <code>/Portal/URL</code> || <code>http://<PEERTUBE_WEBSERVER_HOSTNAME>:9000</code> — exactly the name from <code>.env</code>, no IP
|-
| <code>/Portal/User</code>, <code>/Portal/Password</code> || <code>MXR_RECORDER_USER</code> / <code>MXR_RECORDER_PASSWORD</code>
|-
| <code>/Portal/Channel</code> || <code>MXR_RECORDER_CHANNEL</code>, or empty for the user's default channel
|-
| <code>/Portal/Privacy</code> || <code>internal</code> (default): visible to logged-in users only
|-
| <code>/Portal/Use Upload Original</code> || on only together with <code>MXR_KEEP_ORIGINAL=true</code>
|-
| <code>/Portal/Use Transfer While Recording</code> || off (default) keeps the upload bandwidth and the disk away from a running take
|-
| <code>/Portal/Transfer From Hour</code>, <code>/Portal/Transfer To Hour</code> || a window, e.g. <code>1</code> and <code>7</code> for nights; <code>0</code> and <code>24</code> means always
|}

'''Save & Restart.''' Then a smoke test:

* Record a short take, load it in the player, press '''Publish to portal'''. The file browser's flags column runs through ''uploading n %''; the log says <code>portal: published <name> -> <url></code>.
* The Files tab's '''Portal''' view lists it after '''Reload'''. Open the portal page: title, tags and the markers as chapters are there.
* Delete the local file in the browser, press '''Fetch to local''' in the Portal view (or ''Bring back to recorder'' on the portal page): the file returns to its date folder, protected, with its markers.

If the login fails with <code>http 403</code>, the URL is not the configured host name. If the listing fails with <code>T008</code>, check the account and the channel name.

== Part 5 — MQTT broker ==

Only needed when show control or monitoring uses MQTT. Any MQTT 3.1.1 broker works; Mosquitto is the usual choice.

* '''Linux:''' <code>sudo apt install mosquitto</code>, then in <code>/etc/mosquitto/conf.d/lan.conf</code>:

<pre>
listener 1883
allow_anonymous true
</pre>

<code>sudo systemctl enable --now mosquitto</code>. Restrict <code>allow_anonymous</code> to the LAN (bind to the LAN interface, or add a password file) — the recorder supports no broker authentication.

* '''Windows:''' the Mosquitto installer from mosquitto.org, the same two lines in <code>mosquitto.conf</code>, installed as a service.

In the recorder: <code>/System/IO/MQTT/Use MQTT</code> on, <code>/System/IO/MQTT/Broker Address</code> = the broker's name or IP, <code>/System/IO/MQTT/System ID</code> unique per recorder when several share a broker. Save & Restart. The broker's log shows <code>mxr-client-…</code> connecting.

== Part 6 — Reminder mails ==

The recorder sends one digest a day listing takes that crossed the warning age and those within a week of deletion, with a ''keep'' and a ''publish'' link per take. The links point at the recorder's web port, so they work only for people who can reach the recorder on port 5800.

{| class="wikitable"
! Key !! Value
|-
| <code>/Mail/Use Reminders</code> || on
|-
| <code>/Mail/Server</code>, <code>/Mail/Port</code>, <code>/Mail/Use TLS</code> || the SMTP account, default port 587 with STARTTLS
|-
| <code>/Mail/User</code>, <code>/Mail/Password</code>, <code>/Mail/From</code> || its credentials and sender address
|-
| <code>/Mail/Recipients</code> || comma-separated
|-
| <code>/Mail/Recorder URL</code> || how recipients reach the recorder, default <code>http://<hostname>:5800</code>; must match the VNC web port
|-
| <code>/Mail/Send Hour</code> || default <code>8</code>
|}

<code>/System/IO/VNC/Use VNC</code> must be on with a non-zero web port, otherwise <code>N001</code> warns and the links lead nowhere.

== Checklists ==

'''Single machine, Windows (topology A)'''

* Installer, dongle, first start, <code>/Recording/Root</code>
* Docker Desktop with WSL 2, <code>.wslconfig</code> limits, <code>MXR_TRANSCODE_RESOLUTIONS=720p</code>
* <code>build_portal.py --env --hostname <pc-name></code>, <code>.env</code> checked, <code>docker compose up -d</code>, "mxr setup: done"
* <code>/Portal/*</code> in the recorder, Save & Restart, smoke test
* Firewall: UDP 7000 in; TCP 9000 in for other viewers; TCP 5900/5800 in only with VNC
* Transfer window set to the hours without shows

'''Two machines (topology B)'''

* Recorder as in Part 1 or 2
* Portal host: Docker Engine enabled at boot, <code>build_portal.py --env --hostname <portal-name></code>, <code>docker compose up -d</code>
* Name resolution for <code><portal-name></code> on the recorder and on the viewers' machines
* <code>/Portal/URL = http://<portal-name>:9000</code>, smoke test
* Backup plan for <code>volumes/</code> and <code>.env</code>

'''Off site (topology C)'''

* Everything from B on the server
* Reverse proxy with TLS, <code>.env</code> on 443/https, <code>PEERTUBE_TRUST_PROXY</code>
* <code>/Portal/URL = https://…</code>, transfer window for the venue's uplink
* Only 443 open on the server; the recorder needs no inbound port at all

Stage Recorder MQTT Interface

2026-09-29T20:40:44Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Remote Control (MQTT) =

This page documents controlling and monitoring Stage Recorder over an '''MQTT''' broker. MQTT is an optional bridge over the OSC command tree; see [[Stage Recorder OSC Interface]] for the full command semantics and [[Stage Recorder User Interface]] for on-screen operation.

== Overview ==

Inbound MQTT messages are converted into OSC packets and injected into the OSC receive loop on localhost — there is no separate MQTT command handler. The entire OSC routing tree therefore applies to MQTT as well. MQTT additionally provides '''outbound status''' publishing that OSC does not.

MQTT runs on a dedicated background thread with automatic reconnection.

== Transport and Connection ==

{| class="wikitable"
! Parameter !! Default !! Config key
|-
| Protocol || TCP || —
|-
| Broker address || <code>broker.hivemq.com</code> || <code>/System/IO/MQTT/Broker Address</code>
|-
| Broker port || '''1883''' || — (fixed)
|-
| Client ID || <code>mxr-client-<4 random chars></code> || <code>/System/IO/MQTT/Client ID</code>
|-
| Subscribe pattern || <code>mxr/+/</code> || <code>/System/IO/MQTT/Subscribe Pattern</code>
|-
| Enabled || <code>true</code> || <code>/System/IO/MQTT/Use MQTT</code>
|-
| QoS || 1 || —
|}

To disable MQTT, set <code>/System/IO/MQTT/Use MQTT</code> to <code>false</code>.

== Topic Structure ==

Inbound (command) topics follow this pattern:

<pre>
mxr/<system-id>/channel/<n>/<receiver>
mxr/<system-id>/sync_control
mxr/<system-id>/schedule
</pre>

<code><system-id></code> is matched by the <code>+</code> wildcard in the default subscribe pattern <code>mxr/+/</code>. The value is not validated; it exists to distinguish multiple recorders on one broker. With the default pattern the recorder accepts commands from any system-id.

'''Topic → OSC mapping:'''

{| class="wikitable"
! MQTT topic pattern !! OSC address
|-
| <code>mxr/<id>/channel/<rest></code> || <code>/mxr/channel/<rest></code>
|-
| <code>mxr/<id>/sync_control</code> || <code>/mxr/sync_control</code>
|-
| <code>mxr/<id>/schedule</code> || <code>/mxr/schedule</code>
|}

Topics that match none of these patterns generate error <code>IO004</code>.

== Payload Format ==

The payload is a '''space-separated plain-text string'''. Each whitespace-delimited token is type-detected, in order:

# parses as a '''long integer''' → stored as <code>int32</code>
# parses as a '''double''' → stored as <code>float</code>
# otherwise → stored as <code>string</code>

The resulting argument list is forwarded to OSC exactly as described in [[Stage Recorder OSC Interface]].

'''Command reference:''' the available <code><receiver></code> commands and their arguments are identical to OSC:

{| class="wikitable"
! Topic !! Payload examples
|-
| <code>mxr/<id>/channel/<n>/player</code> || <code>open <filename></code> · <code>seek <ms></code> · <code>play</code> · <code>pause</code> · <code>stop</code> · <code>go_marker_back</code> · <code>go_marker_forward</code> · <code>set_marker</code> · <code>set_speed <0.0..1.0></code> · <code>status</code>
|-
| <code>mxr/<id>/channel/<n>/recorder</code> || <code>start</code> · <code>stop</code> · <code>start_with_duration <seconds></code> · <code>start_preemptive [seconds]</code> · <code>set_camera <camera> [cell]</code> · <code>set_end_time <unix></code> · <code>set_marker</code> · <code>status</code>
|-
| <code>mxr/<id>/sync_control</code> || <code><ch...> player|recorder <command> [args]</code> · <code>open <filepath></code>
|-
| <code>mxr/<id>/schedule</code> || <code>taskadd_local <unix> <osc_address> [args]</code>
|}

The payload is split on spaces, except after <code>open</code>: the rest of the payload is the file name, spaces included.

'''Examples:'''
<pre>
Topic: mxr/studio1/channel/1/player
Payload: open M:/takes/2026.09.25/taz_Integrated Camera_Channel01.mp4
-> OSC: /mxr/channel/1/player "open" "M:/takes/2026.09.25/taz_Integrated Camera_Channel01.mp4"

Topic: mxr/studio1/channel/1/player
Payload: play
-> OSC: /mxr/channel/1/player "play"

Topic: mxr/studio1/channel/1/player
Payload: seek 15000
-> OSC: /mxr/channel/1/player "seek" 15000

Topic: mxr/studio1/channel/1/player
Payload: set_speed 0.1
-> OSC: /mxr/channel/1/player "set_speed" 0.1f
(slow motion at a tenth of normal speed)

Topic: mxr/studio1/channel/1/player
Payload: set_speed 1
-> OSC: /mxr/channel/1/player "set_speed" 1
(back to normal speed — note "1" is tokenized as int32,
not float, which the handler accepts as well)

Topic: mxr/studio1/channel/2/recorder
Payload: start_with_duration 3600
-> OSC: /mxr/channel/2/recorder "start_with_duration" 3600

Topic: mxr/studio1/channel/2/recorder
Payload: start_preemptive
-> OSC: /mxr/channel/2/recorder "start_preemptive"
(pre-roll = configured Preemptive Recording Time)

Topic: mxr/studio1/channel/2/recorder
Payload: start_preemptive 5
-> OSC: /mxr/channel/2/recorder "start_preemptive" 5
(recording begins 5 s before the message arrived)

Topic: mxr/studio1/channel/2/recorder
Payload: set_camera 3
-> OSC: /mxr/channel/2/recorder "set_camera" 3
(the running recording switches to input pair 3)

Topic: mxr/studio1/channel/2/recorder
Payload: set_camera Integrated Camera 2
-> OSC: /mxr/channel/2/recorder "set_camera" "Integrated Camera" 2
(cell 2 of a multi-source recording; the name is reassembled
from the space separated tokens)

Topic: mxr/studio1/sync_control
Payload: 1 2 recorder start
-> OSC: /mxr/sync_control 1 2 "recorder" "start"
</pre>

== Status Publishing (Outbound) ==

The recorder and player publish state changes to the broker automatically. Messages are enqueued from the recording/playback threads and sent on the MQTT worker thread. <code><system-id></code> comes from <code>/System/IO/MQTT/System ID</code> (default <code>1</code>); <code><n></code> is the 1-based channel index; <code><filename></code> is the absolute path.

=== Recorder Status ===

{| class="wikitable"
! Topic !! Payload !! When
|-
| <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>started <filename></code> || Recording begins
|-
| <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>stopped <filename></code> || Recording ends
|-
| <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>camera <cell> <capture device></code> || A camera switch took effect on that cell
|}

A camera switch is only reported once it has actually been carried out on the recording thread, so a refused or impossible switch stays silent (and is logged as <code>R011</code>/<code>R010</code>). A <code>status</code> query answers with the recording state and, while recording, with one <code>camera</code> message per cell - enough for a remote control to rebuild its state after a reconnect.

=== Player Status ===

{| class="wikitable"
! Topic !! Payload !! When
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_started <filename></code> || A file is loaded and the player becomes active
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_stopped <filename></code> || The player is torn down / file unloaded
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>play</code> || Playback resumed (from the transport button or a <code>play</code> command)
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>pause</code> || Playback paused
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>stop</code> || Soft stop (paused and rewound to 0). A subsequent hard stop unloads the file and reports <code>player_stopped</code>.
|}

The <code>player_started</code>/<code>player_stopped</code> messages carry the filename, so a control surface can show ''which'' file is loaded; the bare <code>play</code>/<code>pause</code>/<code>stop</code> messages report the live transport state. Note these are published on the <code>.../player/status</code> topic — '''not''' on the bare <code>.../player</code> command topic, which the application subscribes to.

=== On-Demand Status Query ===

Publish <code>status</code> to a command topic and the matching <code>.../status</code> topic is published immediately with the current state, in the same format as the spontaneous messages:

{| class="wikitable"
! Query topic (inbound) !! Response topic (outbound) !! Response payload
|-
| <code>mxr/<id>/channel/<n>/recorder</code> || <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>started <file></code> or <code>stopped <file></code>
|-
| <code>mxr/<id>/channel/<n>/player</code> || <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_started <file></code> or <code>player_stopped <file></code>
|}

If nothing has been recorded/loaded yet, the filename is empty (e.g. <code>stopped </code> / <code>player_stopped </code>).

'''Example — query and response:'''
<pre>
# query (inbound)
Topic: mxr/1/channel/2/recorder
Payload: status

# response (outbound)
Topic: mxr/1/channel/2/recorder/status
Payload: started C:\recordings\2026-04-16_143012_ch2.mp4
</pre>

== Error Codes ==

{| class="wikitable"
! Code !! Message !! Cause
|-
| <code>IO001</code> || MQTT cannot resolve broker address || DNS lookup for the broker failed
|-
| <code>IO002</code> || MQTT receive callback exception || Unhandled exception in the receive handler
|-
| <code>IO003</code> || MQTT JSON payload not yet implemented || Payload starts with <code>{</code>
|-
| <code>IO004</code> || MQTT cannot assign topic <code><topic></code> || Topic matches no known pattern
|}

== Limitations ==

* JSON payloads are not implemented (error <code>IO003</code>).
* The broker port is fixed at 1883.

== See Also ==

* [[Stage Recorder OSC Interface]] — full command semantics and the configuration reference.
* [[Stage Recorder User Interface]] — on-screen operation.

Stage Recorder OSC Interface

2026-09-29T20:40:43Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Remote Control (OSC) =

This page documents controlling Stage Recorder over '''OSC''' (Open Sound Control). For the equivalent MQTT interface see [[Stage Recorder MQTT Interface]]; for the on-screen interface see [[Stage Recorder User Interface]].

== Overview ==

OSC is the primary remote-control protocol. MQTT commands are internally converted to OSC and injected into the same receive loop, so the entire address space below applies equally to both protocols.

All OSC processing happens on the main (render) thread: messages arrive on a UDP thread, are queued, and drained one per rendered frame. OSC bundles are supported — each message in a bundle is processed individually, in order.

== Transport ==

{| class="wikitable"
! Parameter !! Default !! Config key
|-
| Protocol || UDP || —
|-
| Listen address || ANY (0.0.0.0) || —
|-
| Listen port || '''7000''' || <code>/System/IO/OSC/Receive Port</code>
|}

The port is read once at startup; changing it requires a restart.

== Address Space ==

Every address must begin with <code>/mxr</code>; the first token is stripped before dispatch.

<pre>
/mxr/channel/<n>/player <command> [args]
/mxr/channel/<n>/recorder <command> [args]
/mxr/sync_control [args]
/mxr/schedule <command> [args]
</pre>

<code><n></code> is a '''1-based''' channel index.

== Player Commands ==

'''Address:''' <code>/mxr/channel/<n>/player</code>

{| class="wikitable"
! Argument 1 !! Argument 2 !! Description
|-
| <code>open</code> || <code><filename:string></code> || Open a media file. Resets markers. The file is opened asynchronously and starts paused at position 0.
|-
| <code>play</code> || — || Resume playback (unpause). Requires an open file.
|-
| <code>pause</code> || — || Pause playback. Requires an open file.
|-
| <code>stop</code> || — || Stop playback. With soft-stop enabled, the first call rewinds to 0 and pauses; the second call (or if soft-stop is disabled) unloads the file.
|-
| <code>seek</code> || <code><milliseconds:int32></code> || Seek to an absolute position in milliseconds.
|-
| <code>go_marker_back</code> || — || Jump to the previous cue marker.
|-
| <code>go_marker_forward</code> || — || Jump to the next cue marker.
|-
| <code>set_marker</code> || — || Insert a cue marker at the current position.
|-
| <code>set_speed</code> || <code><speed:float></code> || Frame-based slow motion. <code>0.0</code> holds the current frame, <code>1.0</code> is normal speed; values outside the range are clamped. Below normal speed consecutive frames are blended in a shader so motion stays smooth, and audio is muted — it cannot be stretched without shifting pitch. Also accepted as <code>double</code> or <code>int32</code>.
|-
| <code>status</code> || — || Query the current player status. The reply is published over MQTT — see [[Stage Recorder MQTT Interface#Status Publishing (Outbound)]].
|}

'''Notes:'''
* Commands that need an open file (<code>play</code>, <code>pause</code>, <code>stop</code>, <code>seek</code>, <code>go_marker_*</code>, <code>set_marker</code>) are silently ignored when no file is loaded.
* <code>open</code> is asynchronous. <code>play</code>, <code>pause</code>, <code>seek</code> and <code>set_speed</code> sent while the file is still opening (in a bundle, or without waiting for <code>player_started</code>) are kept and applied the moment the player activates, in the order seek, speed, play/pause. Other commands sent that early are ignored.
* Soft-stop is configured via <code>/Playback/Use Softstop</code> (default <code>true</code>).

'''Example bundle — open, seek to start, play:'''
<pre>
#bundle
/mxr/channel/1/player "open" "/media/clip.mp4"
/mxr/channel/1/player "seek" 0
/mxr/channel/1/player "play"
</pre>

== Recorder Commands ==

'''Address:''' <code>/mxr/channel/<n>/recorder</code>

{| class="wikitable"
! Argument 1 !! Argument 2 !! Description
|-
| <code>start</code> || — || Begin recording with the channel's selected recording profile. Any active playback on the channel is stopped first.
|-
| <code>stop</code> || — || Stop the active recording. Writes cue markers into the file as metadata, then auto-loads the recorded clip into the player (paused at 0).
|-
| <code>start_with_duration</code> || <code><seconds:int32></code> || Start recording and schedule an automatic stop after the given number of seconds. Registers a task visible in the Schedule tab.
|-
| <code>start_preemptive</code> || <code>[seconds:int32]</code> || Start recording ''including material captured before the command arrived'', to compensate for reaction time. Without an argument the configured ''Preemptive Recording Time'' is used; with one, that many seconds, clamped to 0–100 and to what the buffer currently holds. Requires ''Preemptive Recording Time'' to be above 0 — see the notes below.
|-
| <code>set_camera</code> || <code><camera> [cell:int32]</code> || Switch the camera feeding a running recording. See the notes below.
|-
| <code>set_end_time</code> || <code><unix_timestamp:int32></code> || Update the scheduled stop time of an active recording. Only effective while recording.
|-
| <code>set_marker</code> || — || Insert a cue marker at the current recording position. Only effective while recording.
|-
| <code>status</code> || — || Query the current recorder status. The reply is published over MQTT — see [[Stage Recorder MQTT Interface#Status Publishing (Outbound)]].
|}

'''Notes:'''
* On <code>stop</code>, the finished file is immediately opened in the channel's player.
* The scheduled stop from <code>start_with_duration</code> is also polled on every render frame as a safety net.
* Timestamps use the Unix epoch; the <code>int32</code> wire type is subject to the Y2038 limit.

'''Camera switching:'''
* <code>set_camera</code> changes the source of a running recording without interrupting it. The file keeps the frame size, the encoder and the timeline it was opened with — only the picture content changes, from the next frame on.
* <code><camera></code> is an '''input pair index''' (1-based <code>int32</code>), an '''input pair name''', or a '''capture device name'''. Names are matched case-insensitively, input pairs first.
* <code>[cell]</code> addresses one source of a multi-source recording (1-based) and defaults to the master source, which also drives the output frame rate.
* Sources of a different resolution or aspect ratio are '''scaled aspect preserving''' into the cell and centred; the remaining bars are black. A camera cannot change the frame size of a file that is already being written.
* The target must be a '''running capture source''', that is, configured as an input pair. Opening a device on demand would block the render thread for as long as the driver needs, so an unknown or stopped camera is refused and logged as <code>R011</code>.
* Switching also works while the preemptive buffer is armed: it is the same encoder throughout, so the switch is not a splice and the pre-roll stays decodable across it.
* A switch applies to the '''running take'''. The next recording starts from the input pairs of the recording profile again.
* Only the '''video''' source changes. The audio stream was opened with the channel count and sample rate of the first input pair's audio input and keeps running unchanged — the recording does not follow the new camera's audio.
* Every switch that took effect is published as <code>camera <cell> <capture device></code> on the recorder status topic — see [[Stage Recorder MQTT Interface#Status Publishing (Outbound)]].

'''Example — switch channel 1 to the camera of input pair 2:'''
<pre>
/mxr/channel/1/recorder "set_camera" 2
/mxr/channel/1/recorder "set_camera" "Stage Wide"
/mxr/channel/1/recorder "set_camera" "Integrated Camera" 2
</pre>

'''Preemptive recording:'''
* <code>start_preemptive</code> only reaches back in time when ''Settings → Recording Profile → Preemptive Recording Time'' is above 0. That setting is what keeps the encoders running continuously and the buffer filled; at 0 nothing is buffered.
* If no buffer is armed the recording still starts, but without pre-roll, and error <code>R008</code> is logged. A remote caller cannot otherwise distinguish the two cases.
* After the setting is changed, the buffer needs that many seconds to fill before a full pre-roll is available. In the user interface the <code>+n</code> button stays disabled until then; over the network an early <code>start_preemptive</code> simply returns less pre-roll than requested.
* The recording begins at the nearest keyframe at or before the requested point, so the result may contain slightly more than the requested seconds. A shorter GOP in the recording profile tightens this.
* The reported start time and the recording's own timeline begin at the ''pre-roll'' start, not at the moment the command arrived.

== Sync Control ==

'''Address:''' <code>/mxr/sync_control</code>

This endpoint has two independent forms.

=== Open a Sync-Set File ===

<pre>
/mxr/sync_control "open" "<filepath:string>"
</pre>

Opens a sync-set (<code>.mxr_syncset</code>). For each stored channel it stops the recorder, opens the stored file in the player, pauses, and seeks to 0; it also restores the saved channel selection.

=== Fan-Out Command to Multiple Channels ===

<pre>
/mxr/sync_control <ch1:int32> [ch2:int32 ...] <receiver:string> <command:string> [args...]
</pre>

{| class="wikitable"
! Position !! Type !! Description
|-
| 1..N || int32 || Target channel indices (1-based). All leading integers form the channel set.
|-
| N+1 || string || Receiver: <code>"player"</code> or <code>"recorder"</code>
|-
| N+2 || string || Command (any valid player or recorder command)
|-
| N+3.. || mixed || Optional command arguments
|}

One message per target channel is emitted as a single OSC bundle, so all channels are addressed atomically.

'''Example — start recorder on channels 1, 2 and 4:'''
<pre>
/mxr/sync_control 1 2 4 "recorder" "start"
</pre>

'''Example — seek all channels to 30 000 ms:'''
<pre>
/mxr/sync_control 1 2 3 "player" "seek" 30000
</pre>

== Scheduler ==

'''Address:''' <code>/mxr/schedule</code>

<pre>
/mxr/schedule "taskadd_local" <unix_timestamp:int32> <osc_address:string> [args...]
</pre>

{| class="wikitable"
! Position !! Type !! Description
|-
| 1 || string || Must be <code>"taskadd_local"</code>
|-
| 2 || int32 || Unix epoch time at which the task fires
|-
| 3 || string || OSC address to send when the task fires (e.g. <code>/mxr/channel/1/recorder</code>)
|-
| 4.. || mixed || Arguments to include in the fired message
|}

At execution time the scheduler sends the stored address and arguments as an OSC message to the local port. Tasks are one-shot and are removed after firing. The task list persists in the project file.

'''Example — start recorder on channel 2 at a specific time:'''
<pre>
/mxr/schedule "taskadd_local" 1711900800 "/mxr/channel/2/recorder" "start"
</pre>

'''Example — record for exactly 3600 seconds:'''
<pre>
/mxr/schedule "taskadd_local" 1711900800 "/mxr/channel/2/recorder" "start_with_duration" 3600
</pre>

== Argument Types ==

OSC arguments are typed on the wire. The following types are accepted:

{| class="wikitable"
! OSC type tag !! Type !! Notes
|-
| <code>s</code> || string || UTF-8
|-
| <code>i</code> || int32 || Most common numeric type
|-
| <code>h</code> || int64 || Treated as int32 internally
|-
| <code>f</code> || float ||
|}

Unrecognised types are logged and skipped.

== Quick Reference ==

<pre>
# Player
/mxr/channel/<n>/player open <file>
/mxr/channel/<n>/player play | pause | stop
/mxr/channel/<n>/player seek <ms>
/mxr/channel/<n>/player go_marker_back | go_marker_forward | set_marker | status
/mxr/channel/<n>/player set_speed <0.0..1.0>

# Recorder
/mxr/channel/<n>/recorder start | stop
/mxr/channel/<n>/recorder start_with_duration <seconds>
/mxr/channel/<n>/recorder start_preemptive [seconds]
/mxr/channel/<n>/recorder set_camera <camera> [cell]
/mxr/channel/<n>/recorder set_end_time <unix_timestamp>
/mxr/channel/<n>/recorder set_marker | status

# Sync — fan-out / open sync-set
/mxr/sync_control <ch> [ch ...] player|recorder <command> [args]
/mxr/sync_control open <filepath>

# Scheduler
/mxr/schedule taskadd_local <unix_timestamp> <osc_address> [args]
</pre>

== Configuration Reference ==

Keys are stored in the platform-native configuration (Windows Registry; INI file on Linux/macOS).

{| class="wikitable"
! Key !! Type !! Default !! Description
|-
| <code>/System/IO/OSC/Receive Port</code> || long || <code>7000</code> || UDP port to listen on
|-
| <code>/System/IO/MQTT/Use MQTT</code> || bool || <code>true</code> || Enable/disable MQTT
|-
| <code>/System/IO/MQTT/Broker Address</code> || string || <code>broker.hivemq.com</code> || MQTT broker hostname
|-
| <code>/System/IO/MQTT/Client ID</code> || string || <code>mxr-client-<rnd></code> || MQTT client identifier
|-
| <code>/System/IO/MQTT/Subscribe Pattern</code> || string || <code>mxr/+/</code> || MQTT subscription topic filter
|-
| <code>/System/IO/MQTT/System ID</code> || string || <code>1</code> || System identifier used in the outbound status topic prefix
|-
| <code>/Playback/Use Softstop</code> || bool || <code>true</code> || Two-stage stop behaviour for the player
|-
| <code>/System/SettingsKey</code> || string || <code>123456</code> || Password for the Settings tab
|-
| <code>/System/IO/VNC/Use VNC</code> || bool || <code>false</code> || Serve the user interface to VNC viewers on the LAN (restart required)
|-
| <code>/System/IO/VNC/Port</code> || long || <code>5900</code> || VNC port
|-
| <code>/System/IO/VNC/Password</code> || string || ''(empty)'' || Not enforced in this build (no VNC authentication without OpenSSL); a set value is logged as a warning
|-
| <code>/System/IO/VNC/Frame Rate</code> || long || <code>10</code> || Screen captures per second sent to viewers
|-
| <code>/System/IO/VNC/Scale</code> || long || <code>100</code> || Size of the picture sent to viewers, in percent (25–100, steps of 5)
|-
| <code>/System/IO/VNC/Name</code> || string || <code>Tourette Stage Recorder</code> || Name a viewer shows in its title bar
|-
| <code>/System/IO/VNC/Web Port</code> || long || <code>5800</code> || Browser viewer: <code>http://<recorder>:<port>/</code>. 0 switches it off
|-
| <code>/System/Use 10 Bit Recording</code> || bool || <code>false</code> || Run capture, compositing, encoding and textures at 10 bit (restart required)
|-
| <code>/System/Use 10 Bit Display</code> || bool || <code>false</code> || Also ask the window and the program outputs for a 10 bit visual (restart required)
|}

== See Also ==

* [[Stage Recorder MQTT Interface]] — the same command tree over an MQTT broker, plus outbound status.
* [[Stage Recorder User Interface]] — on-screen operation.

Stage Recorder User Interface

2026-09-29T20:40:42Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — User Interface =

Stage Recorder is a professional multi-channel media recorder and player. This page documents the on-screen interface. For controlling the application over the network, see [[Stage Recorder OSC Interface]] and [[Stage Recorder MQTT Interface]].

The interface is a single full-screen window built with Dear ImGui on an OpenGL surface. It is designed for touch panels as well as mouse operation — every text field opens an on-screen keyboard when focused.

== Window Layout ==

The window is divided into a large content area and a '''tab bar''' along the bottom edge. The tab bar switches the content area between the four main views and also hosts global actions:

{| class="wikitable"
! Tab / Button !! Purpose
|-
| '''Channels''' || Live recorder/player operation — the main working view. See [[#Channels Tab]].
|-
| '''Schedule''' || Time-based recording tasks and iCal import/export. See [[#Schedule Tab]].
|-
| '''Files''' || Browse, preview, load and delete recorded media. See [[#Files Tab]].
|-
| '''Settings''' || Inputs, outputs, recording/playback profiles and system configuration. See [[#Settings Tab]].
|-
| ''(right edge)'' || Current date and time.
|-
| '''Save & Restart''' || Appears in red only when a setting was changed that requires a restart to take effect. Saves the project and offers to relaunch the application.
|}

=== On-Screen Keyboard ===

Every editable text field (channel names, project name, profile names, filter text, settings values, passwords) opens a virtual keyboard when tapped or clicked. Press '''Enter''' to commit; the keyboard is intended for kiosk/touch installations without a physical keyboard.

== Channels Tab ==

The Channels tab is the primary operating view. It shows:

* a '''project name bar''' at the top,
* one panel per licensed '''channel''' (up to four side by side per screen width),
* a shared '''Channel Control''' strip at the bottom for synchronised operation.

The number of channels is determined by the license dongle. Without a dongle the application starts with no channels and shows a warning.

=== Project Name Bar ===

Displays the current project name and its file path. The '''...''' button opens a popup to rename the project; renaming also moves the project's working directory.

=== Channel Panel ===

Each channel is an independent recorder ''and'' player. A channel automatically shows the '''player''' when a file is loaded, and the '''recorder''' otherwise.

The panel contains, top to bottom:

* '''Channel name''' — click to edit.
* '''⚙ (cog) button''' — toggles the channel between ''operation mode'' and ''settings mode''. In settings mode the channel shows its recording-profile and playback-profile selectors instead of the video preview.
* '''Video preview''' — the live camera image (recorder) or the current frame (player). Multi-source recording profiles show a grid of source previews.
* '''Sound button''' — overlaid on the top-left of the preview. When more than one player is active, this acts as a radio button selecting which channel's audio is routed to the outputs (only one channel plays audio at a time).
* '''Seek slider''' — playback position / duration; drag to seek (player only).
* '''Transport controls''':
** Player: skip-to-start, previous marker, next marker, '''...''' (open file), '''Play''', '''Pause''', '''Stop'''.
** Recorder: '''Record''' and '''Stop''' (shown when no file is loaded).
* '''Camera selector''' — while a recording runs, one combo per recorded source shows which camera feeds it and switches it on the spot. See [[#Switching Cameras During a Recording]].
* '''Marker controls / aux panel''' — cue-point list. The aux panel opens automatically when the first marker is set during recording, or when a loaded file already contains markers.

==== Two-Stage Stop (Soft Stop) ====

The player '''Stop''' button is two-stage when soft-stop is enabled (default):

# First press — pause and rewind to position 0 (the file stays loaded).
# Second press — unload the file (the channel returns to recorder view).

Soft-stop can be disabled via '''Settings → /Playback/Use Softstop'''. The same behaviour applies to the `stop` command received over OSC/MQTT.

==== Switching Cameras During a Recording ====

While a channel records, a '''Camera''' combo appears above the transport row — one per recorded source, labelled ''Camera 1'', ''Camera 2'' … for a multi-source profile. Picking another entry switches that source without interrupting the recording: the file keeps its frame size and timeline, and the picture changes from the next frame on.

* The list offers every configured '''input pair'''; an entry whose capture source is not running is greyed out. A camera that should be switchable therefore has to be set up as an input pair in '''Settings''' — it is then started with the application.
* A camera with a different resolution or aspect ratio is '''scaled aspect preserving''' and centred in the frame, with black bars on the remaining sides. The frame size of a file that is already being written cannot change.
* The preview follows the switch, so the channel always shows what is actually being recorded.
* Switching also works while the preemptive buffer is armed, including inside the pre-roll.

The same switch can be triggered remotely — see [[Stage Recorder OSC Interface#Recorder Commands]] (<code>set_camera</code>).

==== Recording → Playback Hand-off ====

When a recording is stopped, its cue markers are written into the file as metadata and the finished clip is immediately opened in the same channel's player (paused at position 0), so it can be reviewed at once.

=== Channel Control (Synchronised Operation) ===

The strip below the channel panels drives '''several channels at once'''. Select the target channels with the checkboxes, then use the shared transport row:

* skip-to-start · previous marker · next marker · '''Play''' · '''Pause''' · '''Stop''' · '''Record''' (red) · '''Set marker''',
* a shared seek slider,
* '''Open sync-set''' (📄) and '''Save sync-set''' (💾) buttons.

A '''sync-set''' (`.mxr_syncset`) stores, per channel, the loaded filename and the channel selection, so a multi-channel arrangement can be recalled in one action. Internally, these controls emit the same commands as the network protocol, fanned out to the selected channels — see [[Stage Recorder OSC Interface#Sync Control]].

== Schedule Tab ==

The Schedule tab manages time-based recording tasks. Each task starts (and optionally stops) a recording on one or more channels at a given wall-clock time.

* '''Create new task''' — opens a dialog with a calendar date picker, start-time spinners (hour/min/sec), an optional '''Include stop''' duration, and channel checkboxes.
* '''Export .ics''' — writes all tasks to an iCal file (RFC 5545).
* '''Import .ics''' — drag a `.ics` file onto the window ''while the Schedule tab is open''. A dialog lists every calendar event with a checkbox to import it and a channel assignment; events without an assigned channel are highlighted and skipped. Generic calendar events (with an end time) are imported as fixed-duration recordings.

Each row in the '''task list''' shows the task name, a live countdown, and the scheduled time. Tasks can be '''Edit'''ed or, with '''Ctrl+Click''' on the ✖ button, deleted. A channel that is currently mid-recording under a scheduled stop shows a red '''Recording''' indicator.

Tasks are stored in the project file and persist across restarts. See also [[Stage Recorder OSC Interface#Scheduler]].

== Files Tab ==

The Files tab browses recorded media within the current project directory.

The header offers a '''project selector''' (choose which project directory to browse), a '''Filter''' field (comma-separated substrings), '''Reload''' (rebuild thumbnails/metadata) and '''Open project directory in file browser'''.

Each file row shows:

* the file name with its '''duration''' and '''size''',
* a '''thumbnail''' (generated in the background and cached; click to enlarge),
* one '''Player n''' button per channel to load the file into that channel (the button is disabled/highlighted if the file is already loaded there).

Right-click a file for a '''Delete''' option (files in use cannot be deleted). Sync-set files (`.mxr_syncset`) instead show a '''Sync Control''' button that recalls the stored arrangement.

Thumbnails and file metadata are cached on disk and validated against each file's modification time, so browsing large directories stays responsive.

== Settings Tab ==

The Settings tab is password-protected (default key `123456`, configurable at `/System/SettingsKey`). It presents several tables:

{| class="wikitable"
! Table !! Contents
|-
| '''Input pairs''' || Per channel: a display name, the '''video''' capture source, a capture '''size''' (Default, a preset, or Custom WIDTHxHEIGHT), and the '''audio''' capture source.
|-
| '''Output pairs''' || Per channel: a display name, the target '''monitor''' (video output), and the '''audio sink'''.
|-
| '''Recording profiles''' || Per channel: name, selected input pair(s), '''codec''', and '''GOP''' size. Multi-source recording is available; sources whose resolution does not match the first selected source are disabled. GOP does not apply to ProRes; NVENC H.264 enforces a minimum GOP of 4.
|-
| '''Playback profiles''' || Per channel: name and the set of output pairs the player feeds.
|-
| '''System configuration''' || A raw editable tree of every application configuration key (network ports, MQTT settings, etc.). Boolean, integer and string values are edited in place.
|}

Changing most hardware-related settings sets the '''Save & Restart''' flag: the change is stored but only takes effect after the application is relaunched.

The full configuration key reference is on the [[Stage Recorder OSC Interface#Configuration Reference]] page.

== Remote User Interface (VNC) ==

The complete on-screen interface can be operated from another machine on the local network with any VNC viewer (RealVNC, TightVNC, UltraVNC, macOS Screen Sharing, …). The recorder acts as a VNC server; the operator connects to the recorder's IP address and port and sees the same window the local operator sees, including the live previews, and drives it with mouse and keyboard.

Enable it in '''Settings → <code>/System/IO/VNC/Use VNC</code>''' (off by default; the VNC keys appear in the configuration tree from the first start on) and restart. Further keys: <code>Port</code> (5900), <code>Frame Rate</code> (captures per second, 10), <code>Scale</code> (size of the picture sent to viewers in percent, 25–100 in steps of 5, default 100 — VNC viewers do not scale, so a control laptop with a smaller screen than the recorder needs this). <code>Name</code> is what the viewer shows in its title bar (default ''Tourette Stage Recorder''). <code>Password</code> is '''not enforced''' in this build — the server has no VNC authentication without OpenSSL — so use it only on a trusted network.

'''From a browser:''' no viewer software is needed. Open <code>http://<recorder ip>:5800/</code> (key <code>Web Port</code>, 0 switches it off) on any machine, tablet or phone on the network — the page scales the recorder's window to fit, mouse, touch and keyboard drive the interface, and it reconnects by itself after the recorder restarts. On touch devices a keyboard button in the corner raises the on-screen keyboard. The viewer is noVNC, built into the recorder; nothing is installed or served from disk.

Notes:
* Local and remote input act on the same interface at the same time; the last event wins.
* Only changed parts of the screen are sent, so a static interface costs almost nothing; a moving preview sends the tiles it covers at the configured frame rate.
* There is no authentication in this build. Use it on a trusted network behind a firewall only.
* The connection carries the ''interface'', not a program signal: for the picture on stage displays use the output windows, for control from other software use OSC or MQTT.

== Colour Depth ==

The application can run its whole picture path at '''10 bit''': capture upload, the preview and program textures, the recording composite and the encoder. It is switched on with '''Settings → <code>/System/Use 10 Bit Recording</code>''' ('''off by default''') and is read once at startup, so a change needs a restart.

* '''Sources''' — a camera or capture card delivering '''P010''' or '''P016''' enters the pipeline at ten bits. An 8-bit source does not gain detail, but it no longer picks up the banding that repeated 8-bit conversions add while it is scaled and composited.
* '''Recording''' — the file is written at ten bits when the selected codec can store them. The codec list only offers encoders this build actually has; with the shipped Windows build that means '''hevc_nvenc''' and '''ProRes''' store 10 bit, while '''h264_nvenc''' and '''h264_qsv''' are 8-bit by design and record at their own depth. The log names the depth each codec can store.
* '''Display''' — sending ten bits to the screen and to the program outputs is a '''separate switch''', <code>/System/Use 10 Bit Display</code>, '''off by default'''. It is the only part that depends on the graphics driver, the cable and the panel all supporting it. With it off, everything up to the framebuffer still runs at ten bits and recordings are unaffected.

Switching the pipeline off restores the previous 8-bit behaviour exactly.

== Secondary Monitor Output ==

Every non-primary monitor detected at startup receives a borderless '''output window''' that displays the channel routed to it (via the output-pair '''Monitor''' setting). These windows carry the live program image full-screen with no UI chrome.

== See Also ==

* [[Stage Recorder OSC Interface]] — control the application over UDP/OSC.
* [[Stage Recorder MQTT Interface]] — control and monitor the application over an MQTT broker.

Stage Recorder MQTT Interface

2026-09-21T10:02:36Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Remote Control (MQTT) =

This page documents controlling and monitoring Stage Recorder over an '''MQTT''' broker. MQTT is an optional bridge over the OSC command tree; see [[Stage Recorder OSC Interface]] for the full command semantics and [[Stage Recorder User Interface]] for on-screen operation.

== Overview ==

Inbound MQTT messages are converted into OSC packets and injected into the OSC receive loop on localhost — there is no separate MQTT command handler. The entire OSC routing tree therefore applies to MQTT as well. MQTT additionally provides '''outbound status''' publishing that OSC does not.

MQTT runs on a dedicated background thread with automatic reconnection.

== Transport and Connection ==

{| class="wikitable"
! Parameter !! Default !! Config key
|-
| Protocol || TCP || —
|-
| Broker address || <code>broker.hivemq.com</code> || <code>/System/IO/MQTT/Broker Address</code>
|-
| Broker port || '''1883''' || — (fixed)
|-
| Client ID || <code>mxr-client-<4 random chars></code> || <code>/System/IO/MQTT/Client ID</code>
|-
| Subscribe pattern || <code>mxr/+/</code> || <code>/System/IO/MQTT/Subscribe Pattern</code>
|-
| Enabled || <code>true</code> || <code>/System/IO/MQTT/Use MQTT</code>
|-
| QoS || 1 || —
|}

To disable MQTT, set <code>/System/IO/MQTT/Use MQTT</code> to <code>false</code>.

== Topic Structure ==

Inbound (command) topics follow this pattern:

<pre>
mxr/<system-id>/channel/<n>/<receiver>
mxr/<system-id>/sync_control
mxr/<system-id>/schedule
</pre>

<code><system-id></code> is matched by the <code>+</code> wildcard in the default subscribe pattern <code>mxr/+/</code>. The value is not validated; it exists to distinguish multiple recorders on one broker. With the default pattern the recorder accepts commands from any system-id.

'''Topic → OSC mapping:'''

{| class="wikitable"
! MQTT topic pattern !! OSC address
|-
| <code>mxr/<id>/channel/<rest></code> || <code>/mxr/channel/<rest></code>
|-
| <code>mxr/<id>/sync_control</code> || <code>/mxr/sync_control</code>
|-
| <code>mxr/<id>/schedule</code> || <code>/mxr/schedule</code>
|}

Topics that match none of these patterns generate error <code>IO004</code>.

== Payload Format ==

The payload is a '''space-separated plain-text string'''. Each whitespace-delimited token is type-detected, in order:

# parses as a '''long integer''' → stored as <code>int32</code>
# parses as a '''double''' → stored as <code>float</code>
# otherwise → stored as <code>string</code>

The resulting argument list is forwarded to OSC exactly as described in [[Stage Recorder OSC Interface]].

'''Command reference:''' the available <code><receiver></code> commands and their arguments are identical to OSC:

{| class="wikitable"
! Topic !! Payload examples
|-
| <code>mxr/<id>/channel/<n>/player</code> || <code>open <filename></code> · <code>seek <ms></code> · <code>play</code> · <code>pause</code> · <code>stop</code> · <code>go_marker_back</code> · <code>go_marker_forward</code> · <code>set_marker</code> · <code>set_speed <0.0..1.0></code> · <code>status</code>
|-
| <code>mxr/<id>/channel/<n>/recorder</code> || <code>start</code> · <code>stop</code> · <code>start_with_duration <seconds></code> · <code>start_preemptive [seconds]</code> · <code>set_end_time <unix></code> · <code>set_marker</code> · <code>status</code>
|-
| <code>mxr/<id>/sync_control</code> || <code><ch...> player|recorder <command> [args]</code> · <code>open <filepath></code>
|-
| <code>mxr/<id>/schedule</code> || <code>taskadd_local <unix> <osc_address> [args]</code>
|}

'''Examples:'''
<pre>
Topic: mxr/studio1/channel/1/player
Payload: play
-> OSC: /mxr/channel/1/player "play"

Topic: mxr/studio1/channel/1/player
Payload: seek 15000
-> OSC: /mxr/channel/1/player "seek" 15000

Topic: mxr/studio1/channel/1/player
Payload: set_speed 0.1
-> OSC: /mxr/channel/1/player "set_speed" 0.1f
(slow motion at a tenth of normal speed)

Topic: mxr/studio1/channel/1/player
Payload: set_speed 1
-> OSC: /mxr/channel/1/player "set_speed" 1
(back to normal speed — note "1" is tokenized as int32,
not float, which the handler accepts as well)

Topic: mxr/studio1/channel/2/recorder
Payload: start_with_duration 3600
-> OSC: /mxr/channel/2/recorder "start_with_duration" 3600

Topic: mxr/studio1/channel/2/recorder
Payload: start_preemptive
-> OSC: /mxr/channel/2/recorder "start_preemptive"
(pre-roll = configured Preemptive Recording Time)

Topic: mxr/studio1/channel/2/recorder
Payload: start_preemptive 5
-> OSC: /mxr/channel/2/recorder "start_preemptive" 5
(recording begins 5 s before the message arrived)

Topic: mxr/studio1/sync_control
Payload: 1 2 recorder start
-> OSC: /mxr/sync_control 1 2 "recorder" "start"
</pre>

== Status Publishing (Outbound) ==

The recorder and player publish state changes to the broker automatically. Messages are enqueued from the recording/playback threads and sent on the MQTT worker thread. <code><system-id></code> comes from <code>/System/IO/MQTT/System ID</code> (default <code>1</code>); <code><n></code> is the 1-based channel index; <code><filename></code> is the absolute path.

=== Recorder Status ===

{| class="wikitable"
! Topic !! Payload !! When
|-
| <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>started <filename></code> || Recording begins
|-
| <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>stopped <filename></code> || Recording ends
|}

=== Player Status ===

{| class="wikitable"
! Topic !! Payload !! When
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_started <filename></code> || A file is loaded and the player becomes active
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_stopped <filename></code> || The player is torn down / file unloaded
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>play</code> || Playback resumed (from the transport button or a <code>play</code> command)
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>pause</code> || Playback paused
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>stop</code> || Soft stop (paused and rewound to 0). A subsequent hard stop unloads the file and reports <code>player_stopped</code>.
|}

The <code>player_started</code>/<code>player_stopped</code> messages carry the filename, so a control surface can show ''which'' file is loaded; the bare <code>play</code>/<code>pause</code>/<code>stop</code> messages report the live transport state. Note these are published on the <code>.../player/status</code> topic — '''not''' on the bare <code>.../player</code> command topic, which the application subscribes to.

=== On-Demand Status Query ===

Publish <code>status</code> to a command topic and the matching <code>.../status</code> topic is published immediately with the current state, in the same format as the spontaneous messages:

{| class="wikitable"
! Query topic (inbound) !! Response topic (outbound) !! Response payload
|-
| <code>mxr/<id>/channel/<n>/recorder</code> || <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>started <file></code> or <code>stopped <file></code>
|-
| <code>mxr/<id>/channel/<n>/player</code> || <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_started <file></code> or <code>player_stopped <file></code>
|}

If nothing has been recorded/loaded yet, the filename is empty (e.g. <code>stopped </code> / <code>player_stopped </code>).

'''Example — query and response:'''
<pre>
# query (inbound)
Topic: mxr/1/channel/2/recorder
Payload: status

# response (outbound)
Topic: mxr/1/channel/2/recorder/status
Payload: started C:\recordings\2026-04-16_143012_ch2.mp4
</pre>

== Error Codes ==

{| class="wikitable"
! Code !! Message !! Cause
|-
| <code>IO001</code> || MQTT cannot resolve broker address || DNS lookup for the broker failed
|-
| <code>IO002</code> || MQTT receive callback exception || Unhandled exception in the receive handler
|-
| <code>IO003</code> || MQTT JSON payload not yet implemented || Payload starts with <code>{</code>
|-
| <code>IO004</code> || MQTT cannot assign topic <code><topic></code> || Topic matches no known pattern
|}

== Limitations ==

* JSON payloads are not implemented (error <code>IO003</code>).
* The broker port is fixed at 1883.

== See Also ==

* [[Stage Recorder OSC Interface]] — full command semantics and the configuration reference.
* [[Stage Recorder User Interface]] — on-screen operation.

Stage Recorder OSC Interface

2026-09-21T10:02:35Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Remote Control (OSC) =

This page documents controlling Stage Recorder over '''OSC''' (Open Sound Control). For the equivalent MQTT interface see [[Stage Recorder MQTT Interface]]; for the on-screen interface see [[Stage Recorder User Interface]].

== Overview ==

OSC is the primary remote-control protocol. MQTT commands are internally converted to OSC and injected into the same receive loop, so the entire address space below applies equally to both protocols.

All OSC processing happens on the main (render) thread: messages arrive on a UDP thread, are queued, and drained one per rendered frame. OSC bundles are supported — each message in a bundle is processed individually, in order.

== Transport ==

{| class="wikitable"
! Parameter !! Default !! Config key
|-
| Protocol || UDP || —
|-
| Listen address || ANY (0.0.0.0) || —
|-
| Listen port || '''7000''' || <code>/System/IO/OSC/Receive Port</code>
|}

The port is read once at startup; changing it requires a restart.

== Address Space ==

Every address must begin with <code>/mxr</code>; the first token is stripped before dispatch.

<pre>
/mxr/channel/<n>/player <command> [args]
/mxr/channel/<n>/recorder <command> [args]
/mxr/sync_control [args]
/mxr/schedule <command> [args]
</pre>

<code><n></code> is a '''1-based''' channel index.

== Player Commands ==

'''Address:''' <code>/mxr/channel/<n>/player</code>

{| class="wikitable"
! Argument 1 !! Argument 2 !! Description
|-
| <code>open</code> || <code><filename:string></code> || Open a media file. Resets markers. The file is opened asynchronously and starts paused at position 0.
|-
| <code>play</code> || — || Resume playback (unpause). Requires an open file.
|-
| <code>pause</code> || — || Pause playback. Requires an open file.
|-
| <code>stop</code> || — || Stop playback. With soft-stop enabled, the first call rewinds to 0 and pauses; the second call (or if soft-stop is disabled) unloads the file.
|-
| <code>seek</code> || <code><milliseconds:int32></code> || Seek to an absolute position in milliseconds.
|-
| <code>go_marker_back</code> || — || Jump to the previous cue marker.
|-
| <code>go_marker_forward</code> || — || Jump to the next cue marker.
|-
| <code>set_marker</code> || — || Insert a cue marker at the current position.
|-
| <code>set_speed</code> || <code><speed:float></code> || Frame-based slow motion. <code>0.0</code> holds the current frame, <code>1.0</code> is normal speed; values outside the range are clamped. Below normal speed consecutive frames are blended in a shader so motion stays smooth, and audio is muted — it cannot be stretched without shifting pitch. Also accepted as <code>double</code> or <code>int32</code>.
|-
| <code>status</code> || — || Query the current player status. The reply is published over MQTT — see [[Stage Recorder MQTT Interface#Status Publishing (Outbound)]].
|}

'''Notes:'''
* Commands that need an open file (<code>play</code>, <code>pause</code>, <code>stop</code>, <code>seek</code>, <code>go_marker_*</code>, <code>set_marker</code>) are silently ignored when no file is loaded.
* <code>open</code> is asynchronous — commands sent immediately afterwards may run before the file is ready.
* Soft-stop is configured via <code>/Playback/Use Softstop</code> (default <code>true</code>).

'''Example bundle — open, seek to start, play:'''
<pre>
#bundle
/mxr/channel/1/player "open" "/media/clip.mp4"
/mxr/channel/1/player "seek" 0
/mxr/channel/1/player "play"
</pre>

== Recorder Commands ==

'''Address:''' <code>/mxr/channel/<n>/recorder</code>

{| class="wikitable"
! Argument 1 !! Argument 2 !! Description
|-
| <code>start</code> || — || Begin recording with the channel's selected recording profile. Any active playback on the channel is stopped first.
|-
| <code>stop</code> || — || Stop the active recording. Writes cue markers into the file as metadata, then auto-loads the recorded clip into the player (paused at 0).
|-
| <code>start_with_duration</code> || <code><seconds:int32></code> || Start recording and schedule an automatic stop after the given number of seconds. Registers a task visible in the Schedule tab.
|-
| <code>start_preemptive</code> || <code>[seconds:int32]</code> || Start recording ''including material captured before the command arrived'', to compensate for reaction time. Without an argument the configured ''Preemptive Recording Time'' is used; with one, that many seconds, clamped to 0–100 and to what the buffer currently holds. Requires ''Preemptive Recording Time'' to be above 0 — see the notes below.
|-
| <code>set_end_time</code> || <code><unix_timestamp:int32></code> || Update the scheduled stop time of an active recording. Only effective while recording.
|-
| <code>set_marker</code> || — || Insert a cue marker at the current recording position. Only effective while recording.
|-
| <code>status</code> || — || Query the current recorder status. The reply is published over MQTT — see [[Stage Recorder MQTT Interface#Status Publishing (Outbound)]].
|}

'''Notes:'''
* On <code>stop</code>, the finished file is immediately opened in the channel's player.
* The scheduled stop from <code>start_with_duration</code> is also polled on every render frame as a safety net.
* Timestamps use the Unix epoch; the <code>int32</code> wire type is subject to the Y2038 limit.

'''Preemptive recording:'''
* <code>start_preemptive</code> only reaches back in time when ''Settings → Recording Profile → Preemptive Recording Time'' is above 0. That setting is what keeps the encoders running continuously and the buffer filled; at 0 nothing is buffered.
* If no buffer is armed the recording still starts, but without pre-roll, and error <code>R008</code> is logged. A remote caller cannot otherwise distinguish the two cases.
* After the setting is changed, the buffer needs that many seconds to fill before a full pre-roll is available. In the user interface the <code>+n</code> button stays disabled until then; over the network an early <code>start_preemptive</code> simply returns less pre-roll than requested.
* The recording begins at the nearest keyframe at or before the requested point, so the result may contain slightly more than the requested seconds. A shorter GOP in the recording profile tightens this.
* The reported start time and the recording's own timeline begin at the ''pre-roll'' start, not at the moment the command arrived.

== Sync Control ==

'''Address:''' <code>/mxr/sync_control</code>

This endpoint has two independent forms.

=== Open a Sync-Set File ===

<pre>
/mxr/sync_control "open" "<filepath:string>"
</pre>

Opens a sync-set (<code>.mxr_syncset</code>). For each stored channel it stops the recorder, opens the stored file in the player, pauses, and seeks to 0; it also restores the saved channel selection.

=== Fan-Out Command to Multiple Channels ===

<pre>
/mxr/sync_control <ch1:int32> [ch2:int32 ...] <receiver:string> <command:string> [args...]
</pre>

{| class="wikitable"
! Position !! Type !! Description
|-
| 1..N || int32 || Target channel indices (1-based). All leading integers form the channel set.
|-
| N+1 || string || Receiver: <code>"player"</code> or <code>"recorder"</code>
|-
| N+2 || string || Command (any valid player or recorder command)
|-
| N+3.. || mixed || Optional command arguments
|}

One message per target channel is emitted as a single OSC bundle, so all channels are addressed atomically.

'''Example — start recorder on channels 1, 2 and 4:'''
<pre>
/mxr/sync_control 1 2 4 "recorder" "start"
</pre>

'''Example — seek all channels to 30 000 ms:'''
<pre>
/mxr/sync_control 1 2 3 "player" "seek" 30000
</pre>

== Scheduler ==

'''Address:''' <code>/mxr/schedule</code>

<pre>
/mxr/schedule "taskadd_local" <unix_timestamp:int32> <osc_address:string> [args...]
</pre>

{| class="wikitable"
! Position !! Type !! Description
|-
| 1 || string || Must be <code>"taskadd_local"</code>
|-
| 2 || int32 || Unix epoch time at which the task fires
|-
| 3 || string || OSC address to send when the task fires (e.g. <code>/mxr/channel/1/recorder</code>)
|-
| 4.. || mixed || Arguments to include in the fired message
|}

At execution time the scheduler sends the stored address and arguments as an OSC message to the local port. Tasks are one-shot and are removed after firing. The task list persists in the project file.

'''Example — start recorder on channel 2 at a specific time:'''
<pre>
/mxr/schedule "taskadd_local" 1711900800 "/mxr/channel/2/recorder" "start"
</pre>

'''Example — record for exactly 3600 seconds:'''
<pre>
/mxr/schedule "taskadd_local" 1711900800 "/mxr/channel/2/recorder" "start_with_duration" 3600
</pre>

== Argument Types ==

OSC arguments are typed on the wire. The following types are accepted:

{| class="wikitable"
! OSC type tag !! Type !! Notes
|-
| <code>s</code> || string || UTF-8
|-
| <code>i</code> || int32 || Most common numeric type
|-
| <code>h</code> || int64 || Treated as int32 internally
|-
| <code>f</code> || float ||
|}

Unrecognised types are logged and skipped.

== Quick Reference ==

<pre>
# Player
/mxr/channel/<n>/player open <file>
/mxr/channel/<n>/player play | pause | stop
/mxr/channel/<n>/player seek <ms>
/mxr/channel/<n>/player go_marker_back | go_marker_forward | set_marker | status
/mxr/channel/<n>/player set_speed <0.0..1.0>

# Recorder
/mxr/channel/<n>/recorder start | stop
/mxr/channel/<n>/recorder start_with_duration <seconds>
/mxr/channel/<n>/recorder start_preemptive [seconds]
/mxr/channel/<n>/recorder set_end_time <unix_timestamp>
/mxr/channel/<n>/recorder set_marker | status

# Sync — fan-out / open sync-set
/mxr/sync_control <ch> [ch ...] player|recorder <command> [args]
/mxr/sync_control open <filepath>

# Scheduler
/mxr/schedule taskadd_local <unix_timestamp> <osc_address> [args]
</pre>

== Configuration Reference ==

Keys are stored in the platform-native configuration (Windows Registry; INI file on Linux/macOS).

{| class="wikitable"
! Key !! Type !! Default !! Description
|-
| <code>/System/IO/OSC/Receive Port</code> || long || <code>7000</code> || UDP port to listen on
|-
| <code>/System/IO/MQTT/Use MQTT</code> || bool || <code>true</code> || Enable/disable MQTT
|-
| <code>/System/IO/MQTT/Broker Address</code> || string || <code>broker.hivemq.com</code> || MQTT broker hostname
|-
| <code>/System/IO/MQTT/Client ID</code> || string || <code>mxr-client-<rnd></code> || MQTT client identifier
|-
| <code>/System/IO/MQTT/Subscribe Pattern</code> || string || <code>mxr/+/</code> || MQTT subscription topic filter
|-
| <code>/System/IO/MQTT/System ID</code> || string || <code>1</code> || System identifier used in the outbound status topic prefix
|-
| <code>/Playback/Use Softstop</code> || bool || <code>true</code> || Two-stage stop behaviour for the player
|-
| <code>/System/SettingsKey</code> || string || <code>123456</code> || Password for the Settings tab
|}

== See Also ==

* [[Stage Recorder MQTT Interface]] — the same command tree over an MQTT broker, plus outbound status.
* [[Stage Recorder User Interface]] — on-screen operation.

Stage Recorder MQTT Interface

2026-09-20T19:32:22Z

Admin: probe

= Stage Recorder — Remote Control (MQTT) =

This page documents controlling and monitoring Stage Recorder over an '''MQTT''' broker. MQTT is an optional bridge over the OSC command tree; see [[Stage Recorder OSC Interface]] for the full command semantics and [[Stage Recorder User Interface]] for on-screen operation.

== Overview ==

Inbound MQTT messages are converted into OSC packets and injected into the OSC receive loop on localhost — there is no separate MQTT command handler. The entire OSC routing tree therefore applies to MQTT as well. MQTT additionally provides '''outbound status''' publishing that OSC does not.

MQTT runs on a dedicated background thread with automatic reconnection.

== Transport and Connection ==

{| class="wikitable"
! Parameter !! Default !! Config key
|-
| Protocol || TCP || —
|-
| Broker address || <code>broker.hivemq.com</code> || <code>/System/IO/MQTT/Broker Address</code>
|-
| Broker port || '''1883''' || — (fixed)
|-
| Client ID || <code>mxr-client-<4 random chars></code> || <code>/System/IO/MQTT/Client ID</code>
|-
| Subscribe pattern || <code>mxr/+/</code> || <code>/System/IO/MQTT/Subscribe Pattern</code>
|-
| Enabled || <code>true</code> || <code>/System/IO/MQTT/Use MQTT</code>
|-
| QoS || 1 || —
|}

To disable MQTT, set <code>/System/IO/MQTT/Use MQTT</code> to <code>false</code>.

== Topic Structure ==

Inbound (command) topics follow this pattern:

<pre>
mxr/<system-id>/channel/<n>/<receiver>
mxr/<system-id>/sync_control
mxr/<system-id>/schedule
</pre>

<code><system-id></code> is matched by the <code>+</code> wildcard in the default subscribe pattern <code>mxr/+/</code>. The value is not validated; it exists to distinguish multiple recorders on one broker. With the default pattern the recorder accepts commands from any system-id.

'''Topic → OSC mapping:'''

{| class="wikitable"
! MQTT topic pattern !! OSC address
|-
| <code>mxr/<id>/channel/<rest></code> || <code>/mxr/channel/<rest></code>
|-
| <code>mxr/<id>/sync_control</code> || <code>/mxr/sync_control</code>
|-
| <code>mxr/<id>/schedule</code> || <code>/mxr/schedule</code>
|}

Topics that match none of these patterns generate error <code>IO004</code>.

== Payload Format ==

The payload is a '''space-separated plain-text string'''. Each whitespace-delimited token is type-detected, in order:

# parses as a '''long integer''' → stored as <code>int32</code>
# parses as a '''double''' → stored as <code>float</code>
# otherwise → stored as <code>string</code>

The resulting argument list is forwarded to OSC exactly as described in [[Stage Recorder OSC Interface]].

'''Command reference:''' the available <code><receiver></code> commands and their arguments are identical to OSC:

{| class="wikitable"
! Topic !! Payload examples
|-
| <code>mxr/<id>/channel/<n>/player</code> || <code>open <filename></code> · <code>seek <ms></code> · <code>play</code> · <code>pause</code> · <code>stop</code> · <code>go_marker_back</code> · <code>go_marker_forward</code> · <code>set_marker</code> · <code>status</code>
|-
| <code>mxr/<id>/channel/<n>/recorder</code> || <code>start</code> · <code>stop</code> · <code>start_with_duration <seconds></code> · <code>start_preemptive [seconds]</code> · <code>set_end_time <unix></code> · <code>set_marker</code> · <code>status</code>
|-
| <code>mxr/<id>/sync_control</code> || <code><ch...> player|recorder <command> [args]</code> · <code>open <filepath></code>
|-
| <code>mxr/<id>/schedule</code> || <code>taskadd_local <unix> <osc_address> [args]</code>
|}

'''Examples:'''
<pre>
Topic: mxr/studio1/channel/1/player
Payload: play
-> OSC: /mxr/channel/1/player "play"

Topic: mxr/studio1/channel/1/player
Payload: seek 15000
-> OSC: /mxr/channel/1/player "seek" 15000

Topic: mxr/studio1/channel/2/recorder
Payload: start_with_duration 3600
-> OSC: /mxr/channel/2/recorder "start_with_duration" 3600

Topic: mxr/studio1/channel/2/recorder
Payload: start_preemptive
-> OSC: /mxr/channel/2/recorder "start_preemptive"
(pre-roll = configured Preemptive Recording Time)

Topic: mxr/studio1/channel/2/recorder
Payload: start_preemptive 5
-> OSC: /mxr/channel/2/recorder "start_preemptive" 5
(recording begins 5 s before the message arrived)

Topic: mxr/studio1/sync_control
Payload: 1 2 recorder start
-> OSC: /mxr/sync_control 1 2 "recorder" "start"
</pre>

== Status Publishing (Outbound) ==

The recorder and player publish state changes to the broker automatically. Messages are enqueued from the recording/playback threads and sent on the MQTT worker thread. <code><system-id></code> comes from <code>/System/IO/MQTT/System ID</code> (default <code>1</code>); <code><n></code> is the 1-based channel index; <code><filename></code> is the absolute path.

=== Recorder Status ===

{| class="wikitable"
! Topic !! Payload !! When
|-
| <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>started <filename></code> || Recording begins
|-
| <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>stopped <filename></code> || Recording ends
|}

=== Player Status ===

{| class="wikitable"
! Topic !! Payload !! When
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_started <filename></code> || A file is loaded and the player becomes active
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_stopped <filename></code> || The player is torn down / file unloaded
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>play</code> || Playback resumed (from the transport button or a <code>play</code> command)
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>pause</code> || Playback paused
|-
| <code>mxr/<id>/channel/<n>/player/status</code> || <code>stop</code> || Soft stop (paused and rewound to 0). A subsequent hard stop unloads the file and reports <code>player_stopped</code>.
|}

The <code>player_started</code>/<code>player_stopped</code> messages carry the filename, so a control surface can show ''which'' file is loaded; the bare <code>play</code>/<code>pause</code>/<code>stop</code> messages report the live transport state. Note these are published on the <code>.../player/status</code> topic — '''not''' on the bare <code>.../player</code> command topic, which the application subscribes to.

=== On-Demand Status Query ===

Publish <code>status</code> to a command topic and the matching <code>.../status</code> topic is published immediately with the current state, in the same format as the spontaneous messages:

{| class="wikitable"
! Query topic (inbound) !! Response topic (outbound) !! Response payload
|-
| <code>mxr/<id>/channel/<n>/recorder</code> || <code>mxr/<id>/channel/<n>/recorder/status</code> || <code>started <file></code> or <code>stopped <file></code>
|-
| <code>mxr/<id>/channel/<n>/player</code> || <code>mxr/<id>/channel/<n>/player/status</code> || <code>player_started <file></code> or <code>player_stopped <file></code>
|}

If nothing has been recorded/loaded yet, the filename is empty (e.g. <code>stopped </code> / <code>player_stopped </code>).

'''Example — query and response:'''
<pre>
# query (inbound)
Topic: mxr/1/channel/2/recorder
Payload: status

# response (outbound)
Topic: mxr/1/channel/2/recorder/status
Payload: started C:\recordings\2026-04-16_143012_ch2.mp4
</pre>

== Error Codes ==

{| class="wikitable"
! Code !! Message !! Cause
|-
| <code>IO001</code> || MQTT cannot resolve broker address || DNS lookup for the broker failed
|-
| <code>IO002</code> || MQTT receive callback exception || Unhandled exception in the receive handler
|-
| <code>IO003</code> || MQTT JSON payload not yet implemented || Payload starts with <code>{</code>
|-
| <code>IO004</code> || MQTT cannot assign topic <code><topic></code> || Topic matches no known pattern
|}

== Limitations ==

* JSON payloads are not implemented (error <code>IO003</code>).
* The broker port is fixed at 1883.

== See Also ==

* [[Stage Recorder OSC Interface]] — full command semantics and the configuration reference.
* [[Stage Recorder User Interface]] — on-screen operation.

Stage Recorder OSC Interface

2026-09-20T19:30:50Z

Admin: Sync from source docs: content, links and protocol updates

= Stage Recorder — Remote Control (OSC) =

This page documents controlling Stage Recorder over '''OSC''' (Open Sound Control). For the equivalent MQTT interface see [[Stage Recorder MQTT Interface]]; for the on-screen interface see [[Stage Recorder User Interface]].

== Overview ==

OSC is the primary remote-control protocol. MQTT commands are internally converted to OSC and injected into the same receive loop, so the entire address space below applies equally to both protocols.

All OSC processing happens on the main (render) thread: messages arrive on a UDP thread, are queued, and drained one per rendered frame. OSC bundles are supported — each message in a bundle is processed individually, in order.

== Transport ==

{| class="wikitable"
! Parameter !! Default !! Config key
|-
| Protocol || UDP || —
|-
| Listen address || ANY (0.0.0.0) || —
|-
| Listen port || '''7000''' || <code>/System/IO/OSC/Receive Port</code>
|}

The port is read once at startup; changing it requires a restart.

== Address Space ==

Every address must begin with <code>/mxr</code>; the first token is stripped before dispatch.

<pre>
/mxr/channel/<n>/player <command> [args]
/mxr/channel/<n>/recorder <command> [args]
/mxr/sync_control [args]
/mxr/schedule <command> [args]
</pre>

<code><n></code> is a '''1-based''' channel index.

== Player Commands ==

'''Address:''' <code>/mxr/channel/<n>/player</code>

{| class="wikitable"
! Argument 1 !! Argument 2 !! Description
|-
| <code>open</code> || <code><filename:string></code> || Open a media file. Resets markers. The file is opened asynchronously and starts paused at position 0.
|-
| <code>play</code> || — || Resume playback (unpause). Requires an open file.
|-
| <code>pause</code> || — || Pause playback. Requires an open file.
|-
| <code>stop</code> || — || Stop playback. With soft-stop enabled, the first call rewinds to 0 and pauses; the second call (or if soft-stop is disabled) unloads the file.
|-
| <code>seek</code> || <code><milliseconds:int32></code> || Seek to an absolute position in milliseconds.
|-
| <code>go_marker_back</code> || — || Jump to the previous cue marker.
|-
| <code>go_marker_forward</code> || — || Jump to the next cue marker.
|-
| <code>set_marker</code> || — || Insert a cue marker at the current position.
|-
| <code>status</code> || — || Query the current player status. The reply is published over MQTT — see [[Stage Recorder MQTT Interface#Status Publishing (Outbound)]].
|}

'''Notes:'''
* Commands that need an open file (<code>play</code>, <code>pause</code>, <code>stop</code>, <code>seek</code>, <code>go_marker_*</code>, <code>set_marker</code>) are silently ignored when no file is loaded.
* <code>open</code> is asynchronous — commands sent immediately afterwards may run before the file is ready.
* Soft-stop is configured via <code>/Playback/Use Softstop</code> (default <code>true</code>).

'''Example bundle — open, seek to start, play:'''
<pre>
#bundle
/mxr/channel/1/player "open" "/media/clip.mp4"
/mxr/channel/1/player "seek" 0
/mxr/channel/1/player "play"
</pre>

== Recorder Commands ==

'''Address:''' <code>/mxr/channel/<n>/recorder</code>

{| class="wikitable"
! Argument 1 !! Argument 2 !! Description
|-
| <code>start</code> || — || Begin recording with the channel's selected recording profile. Any active playback on the channel is stopped first.
|-
| <code>stop</code> || — || Stop the active recording. Writes cue markers into the file as metadata, then auto-loads the recorded clip into the player (paused at 0).
|-
| <code>start_with_duration</code> || <code><seconds:int32></code> || Start recording and schedule an automatic stop after the given number of seconds. Registers a task visible in the Schedule tab.
|-
| <code>start_preemptive</code> || <code>[seconds:int32]</code> || Start recording ''including material captured before the command arrived'', to compensate for reaction time. Without an argument the configured ''Preemptive Recording Time'' is used; with one, that many seconds, clamped to 0–100 and to what the buffer currently holds. Requires ''Preemptive Recording Time'' to be above 0 — see the notes below.
|-
| <code>set_end_time</code> || <code><unix_timestamp:int32></code> || Update the scheduled stop time of an active recording. Only effective while recording.
|-
| <code>set_marker</code> || — || Insert a cue marker at the current recording position. Only effective while recording.
|-
| <code>status</code> || — || Query the current recorder status. The reply is published over MQTT — see [[Stage Recorder MQTT Interface#Status Publishing (Outbound)]].
|}

'''Notes:'''
* On <code>stop</code>, the finished file is immediately opened in the channel's player.
* The scheduled stop from <code>start_with_duration</code> is also polled on every render frame as a safety net.
* Timestamps use the Unix epoch; the <code>int32</code> wire type is subject to the Y2038 limit.

'''Preemptive recording:'''
* <code>start_preemptive</code> only reaches back in time when ''Settings → Recording Profile → Preemptive Recording Time'' is above 0. That setting is what keeps the encoders running continuously and the buffer filled; at 0 nothing is buffered.
* If no buffer is armed the recording still starts, but without pre-roll, and error <code>R008</code> is logged. A remote caller cannot otherwise distinguish the two cases.
* After the setting is changed, the buffer needs that many seconds to fill before a full pre-roll is available. In the user interface the <code>+n</code> button stays disabled until then; over the network an early <code>start_preemptive</code> simply returns less pre-roll than requested.
* The recording begins at the nearest keyframe at or before the requested point, so the result may contain slightly more than the requested seconds. A shorter GOP in the recording profile tightens this.
* The reported start time and the recording's own timeline begin at the ''pre-roll'' start, not at the moment the command arrived.

== Sync Control ==

'''Address:''' <code>/mxr/sync_control</code>

This endpoint has two independent forms.

=== Open a Sync-Set File ===

<pre>
/mxr/sync_control "open" "<filepath:string>"
</pre>

Opens a sync-set (<code>.mxr_syncset</code>). For each stored channel it stops the recorder, opens the stored file in the player, pauses, and seeks to 0; it also restores the saved channel selection.

=== Fan-Out Command to Multiple Channels ===

<pre>
/mxr/sync_control <ch1:int32> [ch2:int32 ...] <receiver:string> <command:string> [args...]
</pre>

{| class="wikitable"
! Position !! Type !! Description
|-
| 1..N || int32 || Target channel indices (1-based). All leading integers form the channel set.
|-
| N+1 || string || Receiver: <code>"player"</code> or <code>"recorder"</code>
|-
| N+2 || string || Command (any valid player or recorder command)
|-
| N+3.. || mixed || Optional command arguments
|}

One message per target channel is emitted as a single OSC bundle, so all channels are addressed atomically.

'''Example — start recorder on channels 1, 2 and 4:'''
<pre>
/mxr/sync_control 1 2 4 "recorder" "start"
</pre>

'''Example — seek all channels to 30 000 ms:'''
<pre>
/mxr/sync_control 1 2 3 "player" "seek" 30000
</pre>

== Scheduler ==

'''Address:''' <code>/mxr/schedule</code>

<pre>
/mxr/schedule "taskadd_local" <unix_timestamp:int32> <osc_address:string> [args...]
</pre>

{| class="wikitable"
! Position !! Type !! Description
|-
| 1 || string || Must be <code>"taskadd_local"</code>
|-
| 2 || int32 || Unix epoch time at which the task fires
|-
| 3 || string || OSC address to send when the task fires (e.g. <code>/mxr/channel/1/recorder</code>)
|-
| 4.. || mixed || Arguments to include in the fired message
|}

At execution time the scheduler sends the stored address and arguments as an OSC message to the local port. Tasks are one-shot and are removed after firing. The task list persists in the project file.

'''Example — start recorder on channel 2 at a specific time:'''
<pre>
/mxr/schedule "taskadd_local" 1711900800 "/mxr/channel/2/recorder" "start"
</pre>

'''Example — record for exactly 3600 seconds:'''
<pre>
/mxr/schedule "taskadd_local" 1711900800 "/mxr/channel/2/recorder" "start_with_duration" 3600
</pre>

== Argument Types ==

OSC arguments are typed on the wire. The following types are accepted:

{| class="wikitable"
! OSC type tag !! Type !! Notes
|-
| <code>s</code> || string || UTF-8
|-
| <code>i</code> || int32 || Most common numeric type
|-
| <code>h</code> || int64 || Treated as int32 internally
|-
| <code>f</code> || float ||
|}

Unrecognised types are logged and skipped.

== Quick Reference ==

<pre>
# Player
/mxr/channel/<n>/player open <file>
/mxr/channel/<n>/player play | pause | stop
/mxr/channel/<n>/player seek <ms>
/mxr/channel/<n>/player go_marker_back | go_marker_forward | set_marker | status

# Recorder
/mxr/channel/<n>/recorder start | stop
/mxr/channel/<n>/recorder start_with_duration <seconds>
/mxr/channel/<n>/recorder start_preemptive [seconds]
/mxr/channel/<n>/recorder set_end_time <unix_timestamp>
/mxr/channel/<n>/recorder set_marker | status

# Sync — fan-out / open sync-set
/mxr/sync_control <ch> [ch ...] player|recorder <command> [args]
/mxr/sync_control open <filepath>

# Scheduler
/mxr/schedule taskadd_local <unix_timestamp> <osc_address> [args]
</pre>

== Configuration Reference ==

Keys are stored in the platform-native configuration (Windows Registry; INI file on Linux/macOS).

{| class="wikitable"
! Key !! Type !! Default !! Description
|-
| <code>/System/IO/OSC/Receive Port</code> || long || <code>7000</code> || UDP port to listen on
|-
| <code>/System/IO/MQTT/Use MQTT</code> || bool || <code>true</code> || Enable/disable MQTT
|-
| <code>/System/IO/MQTT/Broker Address</code> || string || <code>broker.hivemq.com</code> || MQTT broker hostname
|-
| <code>/System/IO/MQTT/Client ID</code> || string || <code>mxr-client-<rnd></code> || MQTT client identifier
|-
| <code>/System/IO/MQTT/Subscribe Pattern</code> || string || <code>mxr/+/</code> || MQTT subscription topic filter
|-
| <code>/System/IO/MQTT/System ID</code> || string || <code>1</code> || System identifier used in the outbound status topic prefix
|-
| <code>/Playback/Use Softstop</code> || bool || <code>true</code> || Two-stage stop behaviour for the player
|-
| <code>/System/SettingsKey</code> || string || <code>123456</code> || Password for the Settings tab
|}

== See Also ==

* [[Stage Recorder MQTT Interface]] — the same command tree over an MQTT broker, plus outbound status.
* [[Stage Recorder User Interface]] — on-screen operation.

Tutorials

2026-08-09T18:13:18Z

Admin: Remove mis-titled Streamdeck tutorial link (page was a Wii-tutorial copy, being deleted)

==General==
*[[Tutorial Opening Different Media]]
*[[Tutorial Setting up Stage Designer Output Windows]]
*[[Tutorial Triggering Four Media with the Keyboard]]
*[[Tutorial Coupling Video with Effects and Audio Signals]]
*[[Tutorial Creating Predefined Layer Position]]
*[[Tutorial Feedback]]
*[[Tutorial Creating an I/O Event]]
*[[Tutorial Creating an Autostart Showfile]]
*[[Tutorial Creating Compositions (Sets and Patches)]]
*[[Tutorial Creating Multiple Compositions and Patches]]
*[[Tutorial Creating and Playing an RTF Text File]]
*[[Tutorial Licensing New Features]]
*[[Tutorial Loading and Using JavaScripts in MXWendler]]
*[[Tutorial Configuring a Virtual Camera]]

==Playlist==
*[[Tutorial Creating Playlists (Cue Lists)]]
*[[Tutorial Playlists with Images and Keystone Correction]]
*[[Tutorial Playlists with Timeline]]
*[[Tutorial Playlists with Multi-Timeline]]
*[[Tutorial Playlists with Time and Date Conditions]]
*[[Tutorial Playlists with Timecode]]
*[[Tutorial Playlists with Subtitles]]
*[[Tutorial Playlists with IO - Commands]]
*[[Tutorial Playlists with PDF and Frame Step]]
*[[Tutorial Resetting Runtime Counter with IO Commands in Playlist]]
*[[Tutorial Playlists with Fade Clip]]
*[[Tutorial Playlists with Auto Step]]
*[[Tutorial Playlists with Reset Counter]]
*[[Tutorial Playlists with Shutdown]]
*[[Tutorial Playlists with Load Show]]
*[[Tutorial Playlists with OSC Command]]
*[[Tutorial Playlists with Sys Command]]
*[[Tutorial Playlists with PJlink Command]]
*[[Tutorial Playlists in Rehearsal Mode]]
*[[Tutorial Creating an Automated Show with Daily Event and Playlist Conditions]]

==Keystone==
*[[Tutorial Simultaneous Playback of two Videos with two Video Projectors]]
*[[Tutorial Mapping with UV View]]
*[[Tutorial Masked Output]]
*[[Tutorial Colored Output with Animations]]
*[[Tutorial Capture Output Sections with Artnet DMX and Network Grabbers]]
*[[Tutorial SVG Mapping with the MXWendler Automatic Calibration]]

==IO Devices==
*[[Reference Open Sound Control - OSC]]
*[[Reference JavaScript]]
*[[Tutorial Using the Akai APC Mini (Note On/Off)]]
*[[Tutorial Connecting the grandMA 2Port Node with MXWendler via Art-Net]]
*[[Tutorial Connecting Jands Vista2 with MXWendler via Art-Net]]
*[[Tutorial Set up the CITP Footage Library on the Media Server]]
*[[Tutorial Time-sync and sending IO Commands over OSC Protocol]]
*[[Tutorial Controlling MXWendler via TouchOSC]]
*[[Tutorial Optimum Audio Settings with an Integrated Audio Interface]]
*[[Tutorial Optimum Audio Settings with an External Audio Interface]]
*[[Tutorial Eventmaster Toolset Controlling MXWendler by e.g. e2 S3 Image Processor]]

==FXServer==
*[[Tutorial FXServer Output Windows]]

*[[Tutorial How to Setup a Datapath Fx4 for MXWendler with the Wall Designer Software]]

*[[Tutorial How to Optimize Video Footages With Blender]]

==Standalone Encoder==
*[[Tutorial Standalone Encoder / Video Batch Encoder]]

==EDID Manager==
*[[Tutorial MXWendler EDID Manager]]

==NDI Tools==
*[[Tutorial NDI Tools ]]
*[[Tutorial Sending and Receiving Multiple Video Streams with NDI]]

==Spout==
*[[Tutorial Sending and Receiving Media Through Spout]]
*[[Tutorial Connecting Winamp Generative Visuals with MXWendler via Spout]]

Tutorials

2026-08-09T17:25:23Z

Admin: Remove Wiimote tutorial link (feature removed)

==General==
*[[Tutorial Opening Different Media]]
*[[Tutorial Setting up Stage Designer Output Windows]]
*[[Tutorial Triggering Four Media with the Keyboard]]
*[[Tutorial Coupling Video with Effects and Audio Signals]]
*[[Tutorial Creating Predefined Layer Position]]
*[[Tutorial Feedback]]
*[[Tutorial Creating an I/O Event]]
*[[Tutorial Creating an Autostart Showfile]]
*[[Tutorial Creating Compositions (Sets and Patches)]]
*[[Tutorial Creating Multiple Compositions and Patches]]
*[[Tutorial Creating and Playing an RTF Text File]]
*[[Tutorial Licensing New Features]]
*[[Tutorial Loading and Using JavaScripts in MXWendler]]
*[[Tutorial Configuring a Virtual Camera]]

==Playlist==
*[[Tutorial Creating Playlists (Cue Lists)]]
*[[Tutorial Playlists with Images and Keystone Correction]]
*[[Tutorial Playlists with Timeline]]
*[[Tutorial Playlists with Multi-Timeline]]
*[[Tutorial Playlists with Time and Date Conditions]]
*[[Tutorial Playlists with Timecode]]
*[[Tutorial Playlists with Subtitles]]
*[[Tutorial Playlists with IO - Commands]]
*[[Tutorial Playlists with PDF and Frame Step]]
*[[Tutorial Resetting Runtime Counter with IO Commands in Playlist]]
*[[Tutorial Playlists with Fade Clip]]
*[[Tutorial Playlists with Auto Step]]
*[[Tutorial Playlists with Reset Counter]]
*[[Tutorial Playlists with Shutdown]]
*[[Tutorial Playlists with Load Show]]
*[[Tutorial Playlists with OSC Command]]
*[[Tutorial Playlists with Sys Command]]
*[[Tutorial Playlists with PJlink Command]]
*[[Tutorial Playlists in Rehearsal Mode]]
*[[Tutorial Creating an Automated Show with Daily Event and Playlist Conditions]]

==Keystone==
*[[Tutorial Simultaneous Playback of two Videos with two Video Projectors]]
*[[Tutorial Mapping with UV View]]
*[[Tutorial Masked Output]]
*[[Tutorial Colored Output with Animations]]
*[[Tutorial Capture Output Sections with Artnet DMX and Network Grabbers]]
*[[Tutorial SVG Mapping with the MXWendler Automatic Calibration]]

==IO Devices==
*[[Reference Open Sound Control - OSC]]
*[[Reference JavaScript]]
*[[Tutorial Using the Akai APC Mini (Note On/Off)]]
*[[Tutorial Connecting the grandMA 2Port Node with MXWendler via Art-Net]]
*[[Tutorial Connecting Jands Vista2 with MXWendler via Art-Net]]
*[[Tutorial Set up the CITP Footage Library on the Media Server]]
*[[Tutorial Time-sync and sending IO Commands over OSC Protocol]]
*[[Tutorial Controlling MXWendler via TouchOSC]]
*[[Tutorial Optimum Audio Settings with an Integrated Audio Interface]]
*[[Tutorial Optimum Audio Settings with an External Audio Interface]]
*[[Tutorial Controlling StageDesigner with Elgato Streamdeck]]
*[[Tutorial Eventmaster Toolset Controlling MXWendler by e.g. e2 S3 Image Processor]]

==FXServer==
*[[Tutorial FXServer Output Windows]]

*[[Tutorial How to Setup a Datapath Fx4 for MXWendler with the Wall Designer Software]]

*[[Tutorial How to Optimize Video Footages With Blender]]

==Standalone Encoder==
*[[Tutorial Standalone Encoder / Video Batch Encoder]]

==EDID Manager==
*[[Tutorial MXWendler EDID Manager]]

==NDI Tools==
*[[Tutorial NDI Tools ]]
*[[Tutorial Sending and Receiving Multiple Video Streams with NDI]]

==Spout==
*[[Tutorial Sending and Receiving Media Through Spout]]
*[[Tutorial Connecting Winamp Generative Visuals with MXWendler via Spout]]

Triggering

2026-08-09T17:25:22Z

Admin: Remove link to TUIO tutorial (feature removed)

MXWENDLER enables you to trigger a whole series of events and animations with a keystone, or a MIDI / DMX event.

*[[About Events]]
*[[Creating events]]
*[[Events / Widgets and Their Addresses / Intrinsic Values]]
*[[Examples of events]]

About Events

2026-08-09T17:25:21Z

Admin: Remove TUIO/Wii from trigger tool list (feature removed)

MXWendler enables you to trigger a whole series of events and animations with a keystroke or a MIDI/DMX event. All events work according to the same principle: a trigger activates an event, which sends a specific value to a receiver at a specific time.

Events are managed in the IO Devices Settings:

1. Open 'DMX/MIDI/Keyboard Events' in the settings: '''(A)'''
:'''Menu: Settings → IO Devices → DMX/MIDI/Keyboard Events'''
2. Determine the trigger by selecting the respective tool: DMX, MIDI, Keyboard or Timer. '''(B)'''

3. Create an event with the '+' button. '''(C)'''

4. Activate an event. '''(D)'''

5. Specify the various event settings (receiver / event type / time / value). '''(E)'''

[[File:Events_1.png|728px]]

Hardware

2026-08-09T17:25:20Z

Admin: Remove TUIO and WiiRemote controller support (feature removed)

=== Building an Optimum System ===

In general, you can be sure that any dedicated graphics card available today can run the MXWendler software. But there are performance differences, so feel free to ask at support[at]mxwendler.net.

Operating System
*Windows 7, Windows 8, Windows 8.1, Windows 10 - all 32 and 64 Bit
*Max OS X 10.7, 10.8, 10.9
Processor
*We equally work with AMD and Intel Processors.
*Many PCI devices: The AMD Threadripper series is recommended for the high number of PCI Lanes
*High Core speed: The Intel i7 and i9 series have a usually higher core speed
{{#mpdftags: pagebreak}}
Graphic card
*Our reference hardware in matter of graphic cards is AMD, especially the Radeon Pro series.
*NVidia Quadro series.
*More than 2Gb dedicated Memory is recommended.
*SLI or dual-GPU setups are not recommended.
Disk
*M.2 disks for fast access supported (Samsung 970 Plus)
*SSD
*Raid for HD content supported
*Any disk possible
External Controller
*Midi supported ( any standard midi )
*Midi motor fader supported
*DMX supported ( Enttec, Soundlight, e:cue )
*OSC supported
*Art-Net supported
{{#mpdftags: pagebreak}}
Memory
*Recommended 16GB
Audio
*Windows: Multichannel ASIO Audio supported
*Windows: System Audio
*Mac: Multichannel Core Audio supported

{{#mpdftags: pagebreak}}
System resource requirements, based on different performance needs:

'''Minimum'''
*CPU: Intel i7 7700k, Amd 1900x
*GPU: AMD: RadeonPro wx3100, NVIDIA: Quadro P620
*Disk: SSD Samsung 970 Evo or SATA 7200 Rpm
*RAM: 8GB
'''Medium'''
*CPU: Intel i7 9700k, Amd 2920x
*GPU: AMD: RadeonPro wx7100, NVIDIA: Quadro P2200
*Disk: M.2 Samsung 970 Plus Evo
*RAM: 16GB
'''High'''
*CPU: Intel i9 9900k, AMD Ryzen 9 3900x, Amd 2950x
*GPU: AMD: RadeonPro wx8200, NVIDIA: Quadro P4000
*Disk: M.2 Samsung 970 Plus Evo or 970 Pro
*RAM: 32GB+

Python plugin reference

2026-08-09T16:00:35Z

Admin: docs: audio streams — mxw.audio capture + audio-producing media plugins (device-rate adaptive)

MXWendler StageDesigner can be extended with '''Python plugins'''. A plugin is a plain folder containing a manifest file and a Python module; MXWendler discovers it at startup, shows it in the user interface and calls a defined set of Python functions (''hooks'') at the right moments.

Two plugin types exist:

* '''Media plugins''' produce pixels: they appear as a media source that can be placed in a clip like any video file. Examples: a web browser media, a generative OpenGL cube.
* '''Playlist plugins''' are items in the playlist grid: they run logic when their cue plays. Examples: advance the playlist at a given time of day, write video files, ping a host.

The embedded interpreter is '''Python 3.12'''. The general Python command interface (module <code>mxw</code>) is documented in the [[Python command reference|Python command reference]].

== Plugin anatomy ==

A plugin is one folder with at least two files:

<pre>
plugins/media/python/plugin_my_effect/
mxw_plugin.ini the manifest: identity, menu entries, addressing
mxw_main.py the Python module with the hook functions
(more .py files) optional: importable as "from plugin_my_effect.xyz import ..."
</pre>

The folder name is the Python package name: additional modules in the folder are imported with absolute imports, e.g. <code>from plugin_my_effect.helpers import foo</code>.

=== Plugin locations ===

Plugins are searched in several directories. '''User-controlled locations always override the bundled system location''', so a user can replace a built-in plugin by placing a same-named folder in a higher-precedence directory — even without write access to the installation.

Media plugins, descending precedence:

# The open <code>.mxw</code> project's <code>plugins/media/python/</code> tree (opt-in via settings, highest precedence)
# Directories configured explicitly in the settings (Python tab)
# The per-user data directory, e.g. <code>%APPDATA%/MXWendler/plugins/media/python/</code>
# The installation / resource directory: <code>plugins/media/python/</code> (also <code>plugins/media/python_dev/</code>, same precedence, for internal/unpublished plugins)

Playlist plugins, descending precedence:

# The open <code>.mxw</code> project's <code>plugins/playlist/python/</code> tree (opt-in via settings, highest precedence)
# Directories configured explicitly in the settings (Python tab)
# The per-user data directory: <code>.../plugins/playlist/python/</code>
# The installation / resource directory: <code>plugins/playlist/python/</code> (also <code>plugins/playlist/python_dev/</code>, same precedence, for internal/unpublished plugins)

=== The manifest: mxw_plugin.ini ===

<syntaxhighlight lang="ini">
[mxw_plugin] ; must be here
plugin_version = 1 ; must be V1
plugin_script_language = Python ; must be Python
</syntaxhighlight>

Common keys:

{| class="wikitable"
! Key !! Used by !! Meaning
|-
| <code>plugin_menu_parent</code> || both || Menu the plugin is listed under (e.g. <code>Media</code>, <code>IO</code>)
|-
| <code>plugin_menu_name</code> || both || Display name in the menu
|-
| <code>plugin_grid_name</code> || both || Short name shown in the grid / media list
|-
| <code>plugin_tooltip</code> || both || Tooltip text
|-
| <code>plugin_menu_level</code> (media) / <code>plugin_action_level</code> (playlist) || both || <code>user</code> (default, visible), <code>development</code> (visible in debug builds only), <code>disabled</code> (invisible)
|}

Media-only keys:

{| class="wikitable"
! Key !! Meaning
|-
| <code>plugin_media_scheme</code> || The URI scheme this plugin handles, e.g. <code>generative</code> or <code>web</code>. Media is addressed as <code><scheme>://<payload></code>.
|-
| <code>plugin_media_payload</code> || Optional. If set, the plugin handles exactly <code>scheme://payload</code>; if omitted, it handles every URI of its scheme. Several plugins can share one scheme and dispatch on the payload.
|-
| <code>plugin_media_create_uri</code> || The URI used when the user creates this media from the menu / Create button.
|-
| <code>plugin_playlist_playbackmode_default</code> || Optional. The clip playback mode a freshly added clip of this media starts in: <code>stop</code>, <code>loop</code>, <code>oneshot</code>, <code>bounce</code>, <code>jitter</code> or <code>random</code>. Omitted or unknown defaults to <code>loop</code>. Only seeds the initial mode - a project reload restores the clip's own saved mode.
|-
| <code>plugin_media_has_audio</code> || Optional. <code>1</code> to enable audio output: the host pulls <code>onRenderAudio()</code> and mixes the PCM into the master.
|-
| <code>plugin_media_audio_channels</code> || Optional (default <code>2</code>). Channel count of the produced audio. There is '''no''' sample-rate key – the rate always follows the output device (see Audio, below).
|}

Playlist-only keys:

{| class="wikitable"
! Key !! Meaning
|-
| <code>plugin_grid_bg_color</code> || Item background color as <code>r g b a</code> floats, e.g. <code>0.05 0.05 0.45 1.0</code>
|-
| <code>plugin_accepts_trigger</code> || <code>true</code>/<code>false</code> (default <code>false</code>). When <code>true</code>, dragging a TRIGGER item onto this item's grid cell connects it (the drag shows a green "connect" outline) instead of moving/swapping cells, and the plugin can read the connection with <code>mxw.pending_trigger_drop(item_id)</code>. Set it for a timeline; see [[#Connecting to a TRIGGER item]].
|-
| <code>plugin_cell_scrub</code> || <code>true</code>/<code>false</code> (default <code>false</code>). When <code>true</code>, ALT + left-drag across this item's grid cell scrubs instead of moving the item: the host draws a playhead line and stashes the 0..1 fraction of the cell width each frame, readable with <code>mxw.pending_cell_scrub(item_id)</code>. Set it for a timeline; see [[#Connecting to a TRIGGER item]].
|}

== The plugin environment ==

=== Per-instance state ===

One Python module serves '''many simultaneous instances''' (several clips using the same media plugin, several copies of a playlist item). Before every hook call, the host sets module globals identifying the instance:

* Media plugins: <code>media_id</code> (integer)
* Playlist plugins: <code>item_id</code> (integer) and <code>item_position</code> (tuple <code>(x, y)</code>, the grid position)

The standard pattern is a module-level dictionary keyed by the id:

<syntaxhighlight lang="python">
storage = {}

def onCreate(): # playlist; media plugins use onOpen(uri)
storage[item_id] = my_instance_state()

def onDelete():
storage.pop(item_id, None)
</syntaxhighlight>

=== Host modules ===

* <code>mxw</code> — the MXWendler command interface (playlist control, layers, clips, ...), see the [[Python command reference|Python command reference]].
* <code>mxw_imgui</code> — Dear ImGui bindings for drawing settings panels inside MXWendler (used by <code>onRenderPanel()</code>), documented in the [[Python imgui reference|Python ImGui Reference]].

=== Installing own modules with mxw-pip ===

Plugins may use third-party packages (<code>numpy</code>, <code>moderngl</code>, <code>opencv-python</code>, ...). Packages are not installed into the installation folder — the '''mxw-pip''' helper (shipped next to the StageDesigner executable) installs them into the current user's writable folder, '''no administrator rights required''':

<pre>
%APPDATA%\Python\Python312\site-packages
</pre>

This is exactly the directory StageDesigner prepends to <code>sys.path</code> when the option '''Prepend user site-path''' is enabled (Settings → Python tab).

mxw-pip runs <code>pip</code> with the '''Python 3.12 shipped with StageDesigner''' (<code>python.exe</code> in the installation folder / in its <code>python312/</code> subfolder) — nothing else needs to be installed. Only when the shipped interpreter is missing does it fall back to a system Python (<code>py -3.12</code>, then <code>python</code> on <code>PATH</code>), which must be 3.12 so binary wheels match the runtime ABI.

Step by step:

# Open '''Settings → Python''' and enable '''Prepend user site-path'''. The two installer buttons below are only active while this option is on, because mxw-pip installs into exactly that folder. Enabling applies immediately; disabling takes full effect after a restart.
# Click '''Launch CMD window with mxw-pip module installer..''' — this opens the installer shell (<code>mxw-pip-shell.bat</code>). In the shell, type:
#: <pre>mxw-pip install <modulename></pre>
#: for example:
#: <pre>mxw-pip install moderngl</pre>
# '''Restart MXWendler StageDesigner''' so the new module is loaded.

Other <code>pip</code> subcommands are passed through unchanged, e.g. <code>mxw-pip list</code>, <code>mxw-pip show moderngl</code>, <code>mxw-pip uninstall moderngl</code>. The button '''Open per-user module install folder..''' next to the installer button shows the target directory in the Explorer. Both <code>mxw-pip.bat</code> and <code>mxw-pip-shell.bat</code> can also be run directly from the installation folder in any command prompt.

Because the target folder lives in the user profile, every user keeps their own module set, and reinstalling / updating StageDesigner never touches the installed modules.

=== Error handling ===

Exceptions raised by a hook are reported to the interpreter console (IO dialog) — throttled, so a per-frame error does not flood the log. A '''per-frame hook that throws is blacklisted''': it is not called again until the plugin is reloaded, so one broken callback cannot stall the render loop. Playlist plugins can be hot-reloaded from disk (state is snapshotted via <code>onSave()</code>, the module source re-executed, then <code>onCreate()</code> + <code>onLoad()</code> restore each instance), which also clears the blacklist.

== Media plugins ==

A media plugin is addressed by a URI: <code><scheme>://<payload></code>, for example <code>generative://cube_spin_opengl</code> or <code>web://https://mxwendler.net</code>. Every created media instance internally carries a unique instance token so two clips never share state; the plugin always sees the clean URI.

=== Hooks ===

All hooks are optional except <code>onOpen</code> and '''one of the two render hooks'''.

{| class="wikitable"
! Hook !! Direction !! Meaning
|-
| <code>onOpen(uri)</code> || returns <code>(width, height, length, fps, has_alpha)</code> || Called when the media is created / loaded. Create the per-instance state here. Do '''not''' touch OpenGL yet (see below).
|-
| <code>onRenderFrame(frame)</code> || returns a pixel buffer || Approach 1 and 2: return a <code>H*W*4</code> <code>uint8</code> buffer (bytes / bytearray / numpy), '''BGRA''' byte order, top-down. The host uploads it into the media texture.
|-
| <code>onRenderFrameGL(frame, texture, width, height)</code> || returns <code>bool</code> || Approach 3: render '''directly into the media texture''' — <code>texture</code> is its raw GL handle. Return <code>True</code> when the frame is in the texture; the pixel upload path is then skipped. Tried before <code>onRenderFrame</code>; a plugin implements one of the two.
|-
| <code>onRenderAudio(num_frames)</code> || returns interleaved float32 || Audio-producing media: return ''num_frames''×channels interleaved '''float32''' samples (bytes / bytearray / numpy). The host pulls exactly the frames needed for a gapless cushion. Enabled by <code>plugin_media_has_audio</code>; generate at the injected <code>audio_samplerate</code> (see the Audio section).
|-
| <code>onClose()</code> || — || The media is destroyed: release per-instance resources.
|-
| <code>onRenderPanel()</code> || — || Draw ImGui controls (via <code>mxw_imgui</code>) in the clip panel, above the Video Info section.
|-
| <code>onSizeChange(w, h)</code> || — || The host changed the render size: recreate size-dependent resources.
|-
| <code>onSpeedRange()</code> || returns <code>(min, max)</code> || Allowed clip playback speed range. Without it the media is locked to speed 1.
|-
| <code>onSetSpeed(speed)</code> || — || The clip playback speed changed. Not clamped: 0 and negative values are allowed.
|-
| <code>onSave()</code> / <code>onLoad(state)</code> || string round-trip || Persist per-instance state in the project file.
|-
| <code>onDisplayName()</code> || returns string || Optional live display name (e.g. the web plugin reports the current page URL).
|-
| <code>onGetParams()</code> || returns a list of dicts || Declare addressable parameters, called once per instance and cached: <code>{"name": str, "type": "float"|"string", "min": float, "max": float, "default": float|str}</code> (<code>min</code>/<code>max</code> ignored for <code>"string"</code>; <code>type</code> defaults to <code>"float"</code>).
|-
| <code>onParamChanged(index, value)</code> || — || A parameter was set via OSC, Python or JS at <code>.../clip/media/1/param/<index+1></code> (0-based <code>index</code>). Store or apply it — the host never caches the value itself.
|}

Parameters are addressed exactly like shader effect parameters, e.g. <code>/mxw/track/2/layer/1/clip/media/1/param/1 0.8</code> or, for a <code>"string"</code>-typed param, <code>/mxw/track/2/layer/1/clip/media/1/param/2 "https://www.mxwendler.net"</code>. The <code>media/1</code> segment reflects the clip's single active media slot (any other index is out of range). Because the host does not persist a param's value, a plugin that wants one to survive a project reload must fold it into its own <code>onSave()</code>/<code>onLoad()</code> and hand the restored value back as <code>onGetParams()</code>'s <code>"default"</code> — which runs after <code>onLoad()</code> already restored the instance state.

=== Audio ===

A media plugin can also '''produce''' audio: implement <code>onRenderAudio(num_frames)</code> returning ''num_frames''×channels interleaved '''float32''' samples, and set <code>plugin_media_has_audio = 1</code> in the manifest (channel count via <code>plugin_media_audio_channels</code>, default 2). The host pulls exactly the frames it needs each render frame into a gapless lookahead cushion, so the sound survives render-loop hitches.

The '''sample rate always follows the current output device''' – there is no sample-rate manifest key. The host injects the live format as the module globals <code>audio_samplerate</code> and <code>audio_channels</code> (like <code>media_id</code>) before every call; generate at <code>audio_samplerate</code> and the audio adapts if the device is reopened at another rate. (An optional <code>onAudioFormat()</code> returning <code>(rate, channels)</code> may declare the channel count; its rate is ignored.)

To '''consume''' audio (audio-reactive media), read it with the <code>mxw.audio</code> capture API – see the [[Python command reference]]: <code>mxw.audio.output_capture()</code> for the master mix or <code>mxw.audio.input_capture()</code> for the input device.

=== OpenGL rules for media plugins ===

These rules apply to approaches 2 and 3:

* '''Never create a standalone GL context''' (no windowed/standalone <code>moderngl.create_context()</code> at import or in <code>onOpen</code>). MXWendler makes its own context current every frame; GL objects created in a foreign context will be dereferenced against the wrong context and crash the driver.
* Instead, '''lazily attach on the first render call''': <code>moderngl.create_context()</code> inside <code>onRenderFrame / onRenderFrameGL</code> attaches to MXWendler's context, which the host guarantees to be current there.
* The host '''snapshots and restores all relevant GL state''' around the render hooks (FBO bindings, program, VAO, buffers, viewport, enables, pixel store). The plugin does not need to unbind anything.

=== Approach 1: rendering into pixels (CPU) ===

The simplest approach: compute the frame on the CPU and return it. No OpenGL knowledge required. The host uploads the buffer into the media texture through a PBO (pixel buffer object) double-buffer, so the upload is asynchronous and cheap — the cost of this approach is the CPU rendering itself.

<syntaxhighlight lang="python">
import numpy as np

W, H = 640, 360
storage = {}

def onOpen(uri):
storage[media_id] = {"phase": 0.0}
return (W, H, 1, 60.0, True) # width, height, length, fps, has_alpha

def onRenderFrame(frame):
inst = storage[media_id]
inst["phase"] += 0.01
# a moving horizontal gradient, BGRA byte order, top-down
x = (np.linspace(0.0, 1.0, W) + inst["phase"]) % 1.0
row = np.zeros((W, 4), dtype=np.uint8)
row[:, 0] = (x * 255).astype(np.uint8) # B
row[:, 2] = ((1 - x) * 255).astype(np.uint8) # R
row[:, 3] = 255 # A
return np.ascontiguousarray(np.tile(row, (H, 1, 1)))

def onClose():
storage.pop(media_id, None)
</syntaxhighlight>

Use this for: generated images, PIL/Pillow output, OpenCV results, slow-changing content.

=== Approach 2: rendering into an FBO and streaming ===

Render with OpenGL (e.g. via '''ModernGL''', installed once with <code>mxw-pip install moderngl numpy</code>) into an offscreen framebuffer, read the pixels back and return them like in approach 1. The scene renders on the GPU, but every frame makes a round trip GPU → CPU (<code>fbo.read()</code>) → GPU (PBO upload).

Bundled reference: <code>plugins/media/python/plugin_opengl_cube</code> ([https://github.com/mxwendler/mxw-plugin-opengl-cube github]).

<syntaxhighlight lang="python">
import numpy as np
import moderngl

storage = {}

class inst_t:
def __init__(self):
self.ctx = None
self.fbo = None

def onOpen(uri):
storage[media_id] = inst_t()
return (1024, 1024, 1, 60.0, True)

def onRenderFrame(frame):
inst = storage[media_id]
if inst.ctx is None:
# first frame: attach to MXWendler's context (never earlier!)
inst.ctx = moderngl.create_context()
color = inst.ctx.texture((1024, 1024), 4)
depth = inst.ctx.depth_renderbuffer((1024, 1024))
inst.fbo = inst.ctx.framebuffer([color], depth)
# ... build program / vao here ...

inst.fbo.use()
inst.ctx.clear(0.0, 0.0, 0.0, 0.0, depth=1.0)
# ... draw the scene ...

# read back: GL is bottom-up RGBA, the host wants top-down BGRA
raw = inst.fbo.read(components=4, alignment=1)
img = np.frombuffer(raw, dtype=np.uint8).reshape((1024, 1024, 4))
img = np.flipud(img)
return np.ascontiguousarray(img[:, :, [2, 1, 0, 3]])
</syntaxhighlight>

Use this for: GPU-rendered content when you also need the pixels on the CPU (analysis, recording), or as a stepping stone to approach 3.

=== Approach 3: rendering into a bound texture target (direct) ===

The fastest path: the host passes the '''raw GL handle of the media texture''' to <code>onRenderFrameGL</code>. The plugin attaches it to its own framebuffer and renders straight into it. '''No readback, no upload, no texture streaming''' — the frame never leaves the GPU.

Bundled reference: <code>plugins/media/python/plugin_opengl_cube_direct</code>.

<syntaxhighlight lang="python">
import moderngl

storage = {}

class inst_t:
def __init__(self):
self.ctx = None
self.fbo = None
self.depth = None
self.fbo_key = None # (texture, w, h) the fbo was built for

def onOpen(uri):
storage[media_id] = inst_t()
return (1024, 1024, 1, 60.0, True)

def onRenderFrameGL(frame, texture, width, height):
inst = storage[media_id]
if inst.ctx is None:
inst.ctx = moderngl.create_context() # attach to MXWendler's context
# ... build program / vao here ...

# (re)wrap the host texture when the handle or size changed: the host
# recreates the media texture on a render size change
if inst.fbo_key != (texture, width, height):
if inst.fbo:
inst.fbo.release()
if inst.depth:
inst.depth.release()
color = inst.ctx.external_texture(texture, (width, height), 4, 0, "f1")
inst.depth = inst.ctx.depth_renderbuffer((width, height))
inst.fbo = inst.ctx.framebuffer([color], inst.depth)
inst.fbo_key = (texture, width, height)

inst.fbo.use()
inst.ctx.clear(0.0, 0.0, 0.0, 0.0, depth=1.0)
# ... draw the scene; flip Y in the projection, see below ...

return True # the frame is in the texture: host skips the upload path
</syntaxhighlight>

Rules specific to the direct approach:

* '''Never <code>release()</code> the external texture wrapper''' — the GL texture belongs to MXWendler. Only release your own framebuffer and depth renderbuffer.
* '''Rebuild the framebuffer when <code>(texture, width, height)</code> changes.''' The handle is not stable: a render size change makes the host recreate the media texture.
* '''Flip Y.''' MXWendler media textures are top-down (row 0 = top of the image), a GL render is bottom-up. Negate the Y row of your projection matrix (approaches 1/2 flip on the CPU instead, e.g. with <code>numpy.flipud</code>).

=== Choosing an approach ===

{| class="wikitable"
! !! 1: Pixels (CPU) !! 2: FBO + streaming !! 3: Direct texture
|-
| Scene renders on || CPU || GPU || GPU
|-
| Per-frame copies || CPU → GPU upload || GPU → CPU readback + CPU → GPU upload || none
|-
| OpenGL required || no || yes || yes
|-
| CPU access to the pixels || yes (you made them) || yes (after readback) || no
|-
| Typical use || generated images, PIL, OpenCV || GPU render that also needs CPU pixels || pure GPU generative content, best performance
|}

== Playlist plugins ==

A playlist plugin is an item placed in the playlist grid. It participates in the cue lifecycle: it can run logic when its cue is played, every frame while its cue is active, or every frame globally. Playlist control functions (<code>mxw.playlist.play()</code>, <code>mxw.playlist.navigate_index()</code>, ...) are documented in the [[Python command reference|Python command reference]].

=== Hooks ===

{| class="wikitable"
! Hook !! Required !! Meaning
|-
| <code>onCreate()</code> || yes || A new instance was placed in the grid (also called after hot-reload): create the per-instance state entry.
|-
| <code>onDelete()</code> || yes || The instance was deleted: release the state entry.
|-
| <code>onAction()</code> || yes || The item's cue was played (the item ''fires'').
|-
| <code>onPostAction()</code> || no || Called after the action completed.
|-
| <code>onSave()</code> / <code>onLoad(state)</code> || yes || Serialize / restore per-instance state (string). Called on project save/load and around hot-reload.
|-
| <code>onRenderPanel()</code> || yes || Draw the item's settings panel with <code>mxw_imgui</code>.
|-
| <code>getText()</code> || yes || Detail text appended to the item's grid label.
|-
| <code>onNewFrameAlways()</code> || no || Called every rendered frame, regardless of cue state.
|-
| <code>onNewFrameInPlayoutCue()</code> || no || Called every rendered frame while the item's cue is the active playout cue.
|-
| <code>onPause(is_paused)</code> || no || Pause was pressed / released.
|-
| <code>onPreparePlayback()</code> / <code>onCleanup()</code> || no || Prepare / release playout resources.
|-
| <code>onActivateInUI()</code> || no || The item was selected in the user interface.
|-
| <code>onActiveCueChange(direction)</code> || no || The active cue changed past this item (navigation).
|-
| <code>onSettingsChanged()</code> || no || Item settings were changed from outside.
|-
| <code>getDuration()</code> || no || Report the item's action duration in milliseconds.
|-
| <code>getTimeSinceOnActionIssued()</code> || no || Report elapsed action time in milliseconds (drives the progress display).
|-
| <code>getColorBG()</code> || no || Return a <code>mxw_imgui.Vec4</code> (rgb 0..255) to set the grid cell background color dynamically.
|-
| <code>renderBlinking()</code> || no || Return <code>True</code> to make the grid cell blink.
|-
| <code>getProgress()</code> || no || Return <code>0.0 .. 1.0</code> to fill the cell's bottom progress bar (the same bar the built-in advance/fade items draw); <code><= 0</code> draws nothing.
|}

=== Connecting to a TRIGGER item ===

A playlist plugin (e.g. a keyframe timeline) can bind to a TRIGGER item and animate its layer/clip controls. The user drops a trigger either onto the plugin's settings panel or onto its grid cell; the plugin resolves the connection to the trigger's grid <code>(col, row)</code> and enumerates its controls from there. No need to play the trigger first — the controls are read from the connected preload's fixture layer, and the very same <code>(col,row)</code> address resolves the ''live'' layer during playout.

{| class="wikitable"
! Function !! Meaning
|-
| <code>mxw_imgui.accept_trigger_drop()</code> || Makes the current panel window a drop target for a trigger; returns the dropped trigger's 1-based <code>(col, row)</code>, or <code>(-1, -1)</code>. Handles the "drop onto the panel" route.
|-
| <code>mxw.pending_trigger_drop(item_id)</code> || Returns a <code>(col, row)</code> stashed by the host when a trigger was dropped onto ''this'' plugin item's grid cell (pass your own <code>item_id</code>), or <code>(-1, -1)</code>. Handles the "drop onto the grid cell" route.
|-
| <code>mxw.trigger_controls(col, row)</code> || Returns the trigger's animatable (slider) controls as <code>(label, address)</code> pairs — layer, clip, effect and media params. Re-read it every frame: controls the user swaps on the clip appear/vanish live. Each <code>address</code> is usable with <code>mxw.widget(address).setValue()</code>.
|-
| <code>mxw.pending_cell_scrub(item_id)</code> || Returns the 0..1 fraction of an ALT + left-drag across ''this'' plugin item's grid cell (stashed by the host each frame while dragging, consumed on read), or <code>-1.0</code>. Needs the <code>plugin_cell_scrub</code> manifest opt-in. Poll it in <code>onNewFrameAlways()</code> so scrubbing also works while the panel is closed.
|}

Poll both drop routes at the top of <code>onRenderPanel()</code> and store the resulting <code>(col,row)</code>; then call <code>mxw.trigger_controls()</code> to (re)build your control list each frame.

A time connection between the connected clip and the plugin follows from these pieces: the clip's <code>.../clip/Position</code> control (normalized 0..1) is the clip's own time axis. Write it when your playhead moves (scrub → seek) and read it every frame to follow the clip when it is scrubbed — or simply playing. See the timeline plugin's <code>sync_time_link()</code> for a worked example including the echo filtering (a written Position reads back frame-quantized).

=== Minimal example ===

<syntaxhighlight lang="python">
import pickle, codecs
import mxw
import mxw_imgui

class state_t:
fire_count = 0

storage = {}

def onCreate():
storage[item_id] = state_t()

def onDelete():
storage.pop(item_id, None)

def onAction():
# the item's cue was played
storage[item_id].fire_count += 1

def getText():
return " : fired %d times" % storage[item_id].fire_count

def onRenderPanel():
inst = storage[item_id]
mxw_imgui.text_unformatted("Fired %d times" % inst.fire_count)
if mxw_imgui.button("Reset"):
inst.fire_count = 0

def onSave():
return codecs.encode(pickle.dumps(storage[item_id]), "base64").decode()

def onLoad(serialized):
storage[item_id] = pickle.loads(codecs.decode(serialized.encode(), "base64"))
</syntaxhighlight>

With a manifest:

<syntaxhighlight lang="ini">
[mxw_plugin]
plugin_version = 1
plugin_script_language = Python
plugin_menu_parent = IO
plugin_menu_name = Fire Counter
plugin_grid_name = Counter
plugin_tooltip = Counts how often its cue was played
</syntaxhighlight>

Bundled references, all in the [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist] repository: <code>plugins/playlist/python/plugin_advance_datetime</code> (timed playlist navigation, rich settings panel), <code>plugin_video_writer</code>, <code>plugin_comment</code> (a minimal example: a no-op annotation item).

== Example plugins on GitHub ==

The bundled example plugins are maintained as public repositories under [https://github.com/mxwendler github.com/mxwendler], grouped by type — good starting points to fork for an own plugin:

{| class="wikitable"
! Plugin !! Type !! Approach / purpose !! Repository
|-
| <code>plugin_opengl_cube</code> || media || Approach 2: ModernGL cube into an offscreen FBO, streamed || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_opengl_cube_direct</code> || media || Approach 3: same cube rendered directly into the media texture || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_web_media</code> || media || A web browser as media source (whole-scheme <code>web://</code> plugin) || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_fragcoord</code>, <code>plugin_shadertoy</code> || media || Shader-as-generative-media (FragCoord.xyz / Shadertoy) || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_advance_datetime</code> || playlist || Timed playlist navigation with a rich settings panel || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|-
| <code>plugin_video_writer</code> || playlist || Write video files from the playlist || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|-
| <code>plugin_comment</code> || playlist || Minimal example: a no-op text annotation item || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|}

=== Developing a new plugin inside a project ===

The most convenient place to develop a plugin is '''inside a project folder''': the plugin travels with the show, needs no write access to the installation, and overrides a same-named bundled plugin. Conceptually:

# '''Create a project folder''' — a plain directory that will hold everything belonging to the show, e.g. <code>D:/shows/particles/</code>.
# '''Save the project file there''' — ''File → Save As..'' into that folder, e.g. <code>D:/shows/particles/particles.mxw</code>. The folder containing the <code>.mxw</code> file ''is'' the project folder; loading the project later makes MXWendler pick up its plugins again.
# '''Create the plugin directory there''' — the project mirrors the installation layout: <code>D:/shows/particles/plugins/media/python/<plugin_folder>/</code> for media plugins (<code>plugins/playlist/python/...</code> for playlist plugins). Enable ''Settings → Python → Check for plugins inside the project folder'' — project plugins have the highest precedence of all plugin locations.

=== Letting Claude Code write the plugin ===

An AI coding agent like [https://claude.com/claude-code Claude Code] can write a complete plugin from the contract described on this page. Start it '''in the project folder''', so it creates the plugin directly where MXWendler looks for it:

<pre>
cd D:/shows/particles
claude
</pre>

Give it the reference material and a precise task — for a generative OpenGL particle system for example:

<pre>
Create an MXWendler media plugin under plugins/media/python/plugin_particle_system/
(folder + mxw_plugin.ini + mxw_main.py).

Reference: the bundled example in <MXWendler install dir>/plugins/media/python/
plugin_opengl_cube_direct/ - follow its structure and hook usage exactly, and the
plugin howto at https://wiki.mxwendler.net/index.php?title=Python_plugin_reference.

The plugin is a generative OpenGL particle system, addressed as
generative://particle_system, rendered with ModernGL directly into the media
texture via onRenderFrameGL (no readback, no onRenderFrame). Keep per-instance
state keyed by media_id. Emit particles from the center, integrate velocity and
gravity per frame scaled by the clip playback speed (onSetSpeed, onSpeedRange
-5..5). Expose particle count, gravity and start size as sliders in
onRenderPanel (mxw_imgui) and persist them via onSave/onLoad. Respect the GL
rules: attach with moderngl.create_context() lazily on the first render call,
never release the external texture, rebuild the fbo when (texture, w, h)
changes, flip Y in the projection.
</pre>

Then iterate: create the media in a clip (it appears under its <code>plugin_menu_name</code>, or address <code>generative://particle_system</code> directly) and refine with follow-up prompts ("make the particles fade out", "add a color gradient slider", ...). Errors show up in the interpreter console. For playlist plugins, ''Settings → Python → Reload Python Plugins'' hot-reloads the edited source; for media plugins, recreate the media (or restart) to re-import the module.

== Persistence ==

Both plugin types persist per-instance state through the <code>onSave() → string</code> / <code>onLoad(string)</code> pair. The string is stored inside the project file; anything goes, a common choice is base64-encoded pickle (see the playlist example above). Media plugins additionally have their render size stored and restored by the host automatically.

== Troubleshooting ==

* '''Nothing appears in the menu''' — check the manifest: <code>plugin_version = 1</code>, <code>plugin_script_language = Python</code>, a non-empty <code>plugin_menu_name</code>, and the level key (<code>development</code> plugins only show in debug builds).
* '''Errors''' — open the interpreter console (IO dialog): hook exceptions are reported there (throttled). Remember that a throwing per-frame hook is blacklisted until reload.
* '''Media shows black''' — <code>onRenderFrame</code> returned a buffer of the wrong size (must be <code>width*height*4</code> bytes), or a GL plugin created its own context instead of attaching to MXWendler's (see the OpenGL rules).
* '''Missing packages''' — install them with mxw-pip (see [[#Installing own modules with mxw-pip|Installing own modules with mxw-pip]]) and make sure '''Prepend user site-path''' is enabled: the embedded interpreter does not see a system-wide Python installation's packages.
[[Category:Python]]
[[Category:Reference]]

Python command reference

2026-08-09T16:00:34Z

Admin: docs: audio streams — mxw.audio capture + audio-producing media plugins (device-rate adaptive)

This page lists the commands of the Python module <code>mxw</code>, MXWendler's general Python command interface. It is available from the script console and from Python plugins (see the [[Python plugin reference|Python Plugin Howto]]). For drawing plugin panels see the [[Python imgui reference|Python ImGui Reference]].

The embedded interpreter is '''Python 3.12'''. Import is implicit in the script console; in a plugin module use <code>import mxw</code>.

'''The presented Python commands supported in version 7.2. and up'''

=== Legend ===
<div>

''FLOATS'' are written with one decimal: <code>0.0 .. 1.0</code> → every float between 0 and 1 inclusive.

''INTEGERS'' are written as plain numbers or ranges: <code>1 .. 5</code> → the integers 1,2,3,4,5.

''STRINGS'' are written between double quotes.

When <u>OR</u> appears, two alternative call formats produce a similar result; use one at a time.

'''Addressing:''' widgets are targeted by their OSC-style address string, e.g. <code>/mxw/track/active/layer/active/clip</code>. The same addresses used over OSC work here.

'''Access model (7.2):''' widget values are read/written through <code>mxw.widget(address)</code>; global functions live in the submodules/factories <code>mxw.playlist</code>, <code>mxw.io</code>, <code>mxw.preload(n)</code>, <code>mxw.media(name)</code>, <code>mxw.grabber(name)</code>.

</div>

=== Reference ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
!colspan="3" |Software Info
|-
|<code>mxw.millis</code> || milliseconds passed since the software was opened || <code>mxw.print_console("passed time is " + str(mxw.millis))</code>
|-
|<code>mxw.width</code> || current frame width in px || <code>mxw.print_console("frame width is " + str(mxw.width))</code>
|-
|<code>mxw.height</code> || current frame height in px || <code>mxw.print_console("frame height is " + str(mxw.height))</code>
|-
|<code>mxw.outwidth</code> || current output width in px || <code>mxw.print_console("output width is " + str(mxw.outwidth))</code>
|-
|<code>mxw.outheight</code> || current output height in px || <code>mxw.print_console("output height is " + str(mxw.outheight))</code>
|-
|<code>mxw.framecounter</code> || number of frames rendered since the software was opened || <code>mxw.print_console("frames rendered: " + str(mxw.framecounter))</code>
|-
|<code>mxw.print_console("text")</code> || print a line to the script console || <code>mxw.print_console("hello")</code>
|-
|<code>mxw.print_statusline("text")</code> || print text on the application status line || <code>mxw.print_statusline("running")</code>
|-
|<code>mxw.makescreenshot("path")</code> || save a full-frame screenshot as PNG (empty path → Desktop) || <code>mxw.makescreenshot("c:/Users/me/Desktop/shot.png")</code>
|-
|<code>mxw.makesectionscreenshot("path", x, y, w, h)</code> || save a cropped screenshot of the region (x, y, w, h) || <code>mxw.makesectionscreenshot("c:/Users/me/Desktop/crop.png", 0, 0, 400, 200)</code>
|-
|<code>mxw.describe()</code> || return a text listing of every operation known to the unified interface registry (auto-docs / discovery) || <code>mxw.print_console(mxw.describe())</code>
|-
!colspan="3" | I/O ( <code>mxw.io</code> )
|-
|<code>mxw.io.dmx(channel)</code> || return the DMX value received on the given channel || <code>v = mxw.io.dmx(4)</code>
|-
|<code>mxw.io.midi(device, channel)</code> || return the MIDI value received from device/channel || <code>v = mxw.io.midi(1, 6)</code>
|-
|<code>mxw.io.keyboard(state, key)</code> || return whether the given key (ASCII) is in the given state || <code>if mxw.io.keyboard(0, 65): pass</code>
|-
|<code>mxw.io.send_dmx(channel, value)</code> || send a DMX value on a channel || <code>mxw.io.send_dmx(4, 255)</code>
|-
|<code>mxw.io.send_midi(device, channel, value)</code> || send a MIDI value to device/channel || <code>mxw.io.send_midi(1, 6, 100)</code>
|-
|<code>mxw.io.pjlink("command", "ip", "pw")</code> || PJLink projector control. Commands: <code>on</code>, <code>off</code>, <code>avmute_on</code>, <code>avmute_off</code>, <code>vmute_on</code>, <code>vmute_off</code> || <code>mxw.io.pjlink("on", "192.168.1.2", "panasonic")</code>
|-
|<code>mxw.io.send_osc("host", port, "address", "tags", *args)</code> || send an OSC message. <code>tags</code> is one char per argument: <code>d</code> float, <code>i</code> int, <code>c</code> string, <code>b</code> blob (list of 0..255) || <code>mxw.io.send_osc("127.0.0.1", 7000, "/cue", "ci", "go", 5)</code>
|-
!colspan="3" |Playlist ( <code>mxw.playlist</code> )
|-
|<code>mxw.playlist.preload_media()</code> || preload the media used by the playlist || <code>mxw.playlist.preload_media()</code>
|-
|<code>mxw.playlist.play()</code> || play the playlist || <code>mxw.playlist.play()</code>
|-
|<code>mxw.playlist.pause()</code> || pause, or restart if already paused || <code>mxw.playlist.pause()</code>
|-
|<code>mxw.playlist.go_pause(True/False)</code> || halt (True) or resume (False) playback || <code>mxw.playlist.go_pause(True)</code>
|-
|<code>mxw.playlist.skiptonext()</code> || skip to the next cue || <code>mxw.playlist.skiptonext()</code>
|-
|<code>mxw.playlist.go_next()</code> || go to the next cue without playing || <code>mxw.playlist.go_next()</code>
|-
|<code>mxw.playlist.go_prev()</code> || go to the previous cue || <code>mxw.playlist.go_prev()</code>
|-
|<code>mxw.playlist.go_first()</code> || go to the first cue || <code>mxw.playlist.go_first()</code>
|-
|<code>mxw.playlist.navigate_index(index)</code> || go to the cue with the given index || <code>mxw.playlist.navigate_index(2)</code>
|-
|<code>mxw.playlist.navigate_string("name")</code> || go to the cue matching the given name || <code>mxw.playlist.navigate_string("BG_video2")</code>
|-
|<code>mxw.playlist.get_active_cue()</code> || return the active cue index (int) || <code>i = mxw.playlist.get_active_cue()</code>
|-
|<code>mxw.playlist.get_cue_count()</code> || return the number of cues (int) || <code>n = mxw.playlist.get_cue_count()</code>
|-
|<code>mxw.playlist.get_cue_names()</code> || return the list of cue names (index matches <code>navigate_index</code>) || <code>for name in mxw.playlist.get_cue_names(): pass</code>
|-
|<code>mxw.playlist.is_rehearsal()</code> || return True if the playlist is in rehearsal mode || <code>if mxw.playlist.is_rehearsal(): pass</code>
|-
!colspan="3" |Preload ( <code>mxw.preload(n)</code> )
|-
|<code>mxw.preload(n).isvalid()</code> || True if preload <code>n</code> exists || <code>if mxw.preload(2).isvalid(): pass</code>
|-
|<code>mxw.preload(n).clear()</code> || clear the selected preload || <code>mxw.preload(2).clear()</code>
|-
|<code>mxw.preload(n).set_media("filename")</code> || set the preload media by filename || <code>mxw.preload(2).set_media("try.mp4")</code>
|-
|<code>mxw.preload(n).set_name("name")</code> || rename the preload || <code>mxw.preload(2).set_name("new_background")</code>
|-
|<code>mxw.preload(n).add_preload()</code> || load the preload into the layers || <code>mxw.preload(2).add_preload()</code>
|-
|<code>mxw.preload(n).trigger_preload()</code> || trigger a layer from the preload || <code>mxw.preload(2).trigger_preload()</code>
|-
|<code>mxw.preload(n).get_activated()</code> || True if the preload is open for edit || <code>mxw.preload(2).get_activated()</code>
|-
|<code>mxw.preload(n).set_activated(True/False)</code> || open/close the preload for edit || <code>mxw.preload(2).set_activated(False)</code>
|-
|<code>mxw.preload(n).get_layer_position()</code> || return the preload's layer index || <code>mxw.preload(2).get_layer_position()</code>
|-
|<code>mxw.preload(n).get_track_position()</code> || return the preload's track index || <code>mxw.preload(2).get_track_position()</code>
|-
|<code>mxw.preload(n).set_layer_position(pos)</code> || set the preload's layer index || <code>mxw.preload(2).set_layer_position(2)</code>
|-
|<code>mxw.preload(n).set_track_position(pos)</code> || set the preload's track index || <code>mxw.preload(2).set_track_position(2)</code>
|-
|<code>mxw.preload(n).get_preload_names()</code> || return the list of preload comment/name strings || <code>names = mxw.preload(2).get_preload_names()</code>
|-
|<code>mxw.preload(n).get_image_sample_cvmat(w, h)</code> || return a <code>w</code>×<code>h</code> RGBA image sample of the preload as a buffer (OpenCV Mat) || <code>img = mxw.preload(2).get_image_sample_cvmat(64, 64)</code>
|-
!colspan="3" |Widgets ( <code>mxw.widget(address)</code> )
|-
|<code>mxw.widget("/mxw/path").getValue()</code> || return the widget's normalized value (float) || <code>o = mxw.widget("/mxw/track/active/layer/active/opacity").getValue()</code>
|-
|<code>mxw.widget("/mxw/path").setValue(v)</code> || set the widget's normalized value || <code>mxw.widget("/mxw/track/active/layer/active/opacity").setValue(0.5)</code>
|-
|<code>mxw.widget("/mxw/path").getStringValue()</code> || return the widget's string value (e.g. a cue/clip name) || <code>mxw.print_console(mxw.widget("/mxw/playlist/container/1/column/0/row/1").getStringValue())</code>
|-
|<code>mxw.widget("/mxw/path").setStringValue("text")</code> || set the widget's string value (e.g. name a cue) || <code>mxw.widget("/mxw/playlist/container/1/column/0/row/1").setStringValue("background videoclip")</code>
|-
|<code>mxw.widget("/mxw/path").setWidgetRealValue(d)</code> || set the widget's real (un-normalized) value || <code>mxw.widget("/mxw/path").setWidgetRealValue(120.0)</code>
|-
|<code>mxw.widget("/mxw/path").animate(initvalue, incomingvalue, duration, delta, type)</code> || animate the widget value over <code>duration</code> ms || <code>mxw.widget("/mxw/path").animate(0.0, 1.0, 1000, 0.0, 0)</code>
|-
|<code>mxw.widget("/mxw/path").info()</code> || return a list describing the widget. For a '''clip''': <code>[length, width, height, millis_per_frame, cache_state, media_path]</code>. Returns <code>[]</code> if the address does not resolve || <code>length, w, h, mspf, cache, path = mxw.widget("/mxw/track/active/layer/active/clip").info()</code>
|-
!colspan="3" |Media ( <code>mxw.media(name)</code> )
|-
|<code>mxw.media("name").isvalid()</code> || True if the named media exists || <code>if mxw.media("USB Cam").isvalid(): pass</code>
|-
|<code>mxw.media("name").reference(True/False)</code> || add (True) or remove (False) a reference that keeps the media loaded || <code>mxw.media("clip.mov").reference(True)</code>
|-
|<code>mxw.media("name").unload_media_full_if_not_used_by_clips()</code> || unload the media if no clip uses it (returns bool) || <code>mxw.media("clip.mov").unload_media_full_if_not_used_by_clips()</code>
|-
|<code>mxw.media("name").get_image_sample_cvmat(w, h)</code> || return a <code>w</code>×<code>h</code> RGBA image sample of the media (OpenCV Mat) || <code>img = mxw.media("clip.mov").get_image_sample_cvmat(64, 64)</code>
|-
|<code>mxw.media("name").get_image_sample_cvmat_async(w, h)</code> || non-blocking variant of the image sample || <code>img = mxw.media("clip.mov").get_image_sample_cvmat_async(64, 64)</code>
|-
|<code>mxw.media("name").get_capture_device_names()</code> || return the list of available capture-device names || <code>devs = mxw.media("").get_capture_device_names()</code>
|-
|<code>mxw.media("name").ptz("ptz_is_supported")</code> || return whether the (NDI) camera supports PTZ || <code>mxw.media("USB Cam").ptz("ptz_is_supported")</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom", value)</code> || zoom, 0 (in) .. 1 (out) || <code>mxw.media("USB Cam").ptz("ptz_zoom", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom_speed", value)</code> || zoom speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_zoom_speed", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt", pan, tilt)</code> || absolute pan/tilt, -1 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt", -0.5, 0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt_speed", pan_speed, tilt_speed)</code> || pan/tilt speed, -1 (right/down) .. 1 (left/up) || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt_speed", -0.3, 0.8)</code>
|-
|<code>mxw.media("name").ptz("ptz_store_preset", n)</code> || store position/focus/zoom into preset 0 .. 99 || <code>mxw.media("USB Cam").ptz("ptz_store_preset", 75)</code>
|-
|<code>mxw.media("name").ptz("ptz_recall_preset", n, speed)</code> || recall preset 0 .. 99 at speed 0 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_recall_preset", 4, 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_auto_focus")</code> || toggle auto-focus || <code>mxw.media("USB Cam").ptz("ptz_auto_focus")</code>
|-
|<code>mxw.media("name").ptz("ptz_focus", value)</code> || absolute focus, 0 (infinity) .. 1 (closest) || <code>mxw.media("USB Cam").ptz("ptz_focus", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_focus_speed", value)</code> || focus speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_focus_speed", -0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_auto")</code> || auto white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_indoor")</code> || indoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_indoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_outdoor")</code> || outdoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_outdoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_oneshot")</code> || set white balance once from current brightness || <code>mxw.media("USB Cam").ptz("ptz_white_balance_oneshot")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_manual", red, blue)</code> || manual white balance, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_white_balance_manual", 0.1, 0.7)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_auto")</code> || auto exposure || <code>mxw.media("USB Cam").ptz("ptz_exposure_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual", level)</code> || manual exposure iris, 0.0 (dark) .. 1.0 (light) || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual", 0.4)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual_v2", iris, gain, shutter)</code> || manual exposure iris/gain/shutter, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual_v2", 0.4, 0.2, 0.5)</code>
|-
!colspan="3" |Grabber ( <code>mxw.grabber(name)</code> )
|-
|<code>mxw.grabber("name").isvalid()</code> || True if the named keystone grabber exists || <code>if mxw.grabber("cam").isvalid(): pass</code>
|-
|<code>mxw.grabber("name").getGrabSizeX()</code> || grabber width in px || <code>mxw.grabber("cam").getGrabSizeX()</code>
|-
|<code>mxw.grabber("name").getGrabSizeY()</code> || grabber height in px || <code>mxw.grabber("cam").getGrabSizeY()</code>
|-
|<code>mxw.grabber("name").getData()</code> || return the grabber's pixels as a byte list (RGBA, width×height×4) || <code>px = mxw.grabber("cam").getData()</code>
|-
!colspan="3" |Audio capture ( <code>mxw.audio</code> )
|-
|<code>mxw.audio.output_capture(capacity_seconds=4.0)</code> || open a gapless capture of the master OUTPUT mix; returns a capture handle backed by a lock-free ring (''capacity_seconds'' of buffer) || <code>cap = mxw.audio.output_capture()</code>
|-
|<code>mxw.audio.input_capture(capacity_seconds=4.0)</code> || open a capture of the selected audio INPUT device (same source the analyzer uses) || <code>cap = mxw.audio.input_capture()</code>
|-
|<code>cap.channels</code> || channel count of the capture || <code>ch = cap.channels</code>
|-
|<code>cap.sample_rate</code> || sample rate in Hz (follows the device) || <code>sr = cap.sample_rate</code>
|-
|<code>cap.available()</code> || frames currently readable in the ring || <code>n = cap.available()</code>
|-
|<code>cap.read(max_frames)</code> || read up to ''max_frames'' frames as interleaved '''float32''' bytes (length = frames×channels×4) || <code>import numpy as np; a = np.frombuffer(cap.read(cap.available()), np.float32).reshape(-1, cap.channels)</code>
|-
|<code>cap.is_closed()</code> || True after a device reopen (rate/channel change) – drop and re-acquire the handle || <code>if cap.is_closed(): cap = mxw.audio.output_capture()</code>
|-
|<code>cap.close()</code> || release the capture (idempotent) || <code>cap.close()</code>
|-
|<code>cap.dropped()</code> || frames dropped because read() fell behind (ring overrun) || <code>cap.dropped()</code>
|-
|<code>cap.starved()</code> || times the ring was empty on read || <code>cap.starved()</code>
|}

=== See also ===

* [[Python imgui reference|Python ImGui Reference]] – drawing plugin panels with <code>mxw_imgui</code>
* [[Python plugin reference|Python Plugin Howto]] – writing media and playlist plugins
[[Category:Python]]
[[Category:Reference]]

Tutorial Opening Different Media

2026-08-08T19:27:24Z

Admin:

This tutorial applies to all different OS and MXWendler versions.
==Supported Media Sources==

===Video Formats===

All the standard video formats, commonly known as container formats, such as '''.avi, .mov, .vob or .mpg''' can be used in the software. Inside these containers are media in the form of so-called codecs for video and audio. MXWendler can read and process all standard codecs, differentiating thereby between ‘internal’ and ‘external’ processing. <div class="noprint"></div>
In internal processing, media are transferred – aided by system codecs - into an own format specifically developed for real-time compositing with high-resolution video streams: the CPU in the computer is no longer required to unpack the converted media and can concentrate instead on the graphics. This method enables the 5-times forwards/backwards warping controls, excellent latency at keypoints, frame blending slow motion, and the processing of image sequences. However, to do this, the video material must first be imported. For the direct processing of video material, MXWendler uses an FFMpeg-based decoder that can play performance-optimized videos of up to 4K, and supports multi-channel audio (also via ASIO).

{{#mpdftags: pagebreak}}
===Live Video===

MXWendler supports nearly all industry-standard grabber- and live input hardware components through Quicktime and DirectShow interfaces. Grabbers for BNC, DVI and SDI video are possible. Latency can be reduced to a minimum, down to under 0,08 seconds, by overclocking the system. Webcams and NDI can be used as live video sources as well. See also: [[Tutorial NDI Tools]].

===Images===

All standard image formats are supported ('''.jpg, .png, .psd''', etc.).

===PDF===

PDF files are supported in MXWendler version 6 and above and can be used as a media source. A PDF file will be played back as an image sequence. Each page of the PDF will be played as one frame. The playback speed can be changed to acquire the desired tempo of the playback. The playback of each frame can be also triggered through the Playlist function, Frame Step.
See also: [[Tutorial Playlists with PDF and Frame Step]] <br>

{{#mpdftags: pagebreak}}
==Opening Different Media==

Different media can be opened/imported in MXWendler by:
:The file browser in Output Pipeline, in Preload box, or Live Editor.
:Drag&dropping from explorer to a Preload Clip, a Playlist Cell, in Live Editor, or Layer Manager.
:Import Multiple Clips through Preload's function Menu.

===Opening Video & Image Files===

1. Click on the first Preload. The Preload Preview opens (red box). '''(A)'''

2. Left-click on Open to search for the desired file. '''(B)'''

3. Select and open the file. '''(C)'''

The file is now in preload and is ready for use.

''Tip: Alternatively, you can also drag&drop the file into the Preload from a file browser, or allocate media to a number of Preloads with Multi Clip Import.''
{{#mpdftags: pagebreak}}

[[File:Opening different Media Trigger 1.png|728px]]

===Opening PDF Files===

1. Click on an empty Preload cell to open it.

2. Left-click on Open to search for the desired PDF file.

3. Select and open the file.

The PDF file will be played as an image sequence frame by frame.

4. You can change the playback speed by choosing Speed amounts from 0.0 to 5.0. '''(A)'''

5. You can change the dpi settings (for the resolution of each frame) in settings. '''(B)'''
:'''Settings → Media - Clips, Live, Virtual → PDF '''
6. In the Preload Preview, click on Reload Media to make the dpi changes effective. '''(C)'''

[[File:pdf.png|728px]]

===Opening a Live Video===

1. Connect the camera to the computer; you may need to restart the software.

2. The Live-Camera must first be activated in MXWendler. '''(A)'''
:'''Settings → Media → Live devices → Double-click ‘unknown’ → ‘known’'''
:The camera can now be loaded into the Preload.
3. Open the next Preload. Select the camera in the preview menu under Live Media. '''(B)'''

The live video is now in Preload and is ready for use.

''Tip: The camera only needs to be activated a single time. For improved performance, cameras can also be temporarily disabled in the same manner. Please refer to the chapter ‘Media Tips’ for more advanced camera settings.''

{{#mpdftags: pagebreak}}

[[File:Opening different Media Trigger 2.png|728px]]

===Opening and Creating Image Sequences===

Two things must be considered before the images can be loaded into the Preload:

The images should be stored in a separate folder, and must contain sequential numbering: e.g. Clip_001.png, Clip_002.png...

1. Open the next Preload. '''(A)'''

2. Click on Open to open the folder containing the images. '''(B)'''

3. Open the first image in the folder. Confirm with Yes to import as a sequence, and set the desired compression quality. '''(C)'''

The sequence is now in Preload and is ready for use.

''Tip: Please refer to the chapter ‘Media Tips’ for the proper creation of image sequences.''

[[File:Opening different Media Trigger 3.png|728px]]

Main Page

2026-08-08T19:20:05Z

Admin:

= MXWendler Stage Designer and FXServer Knowledge Base =
MXWendler FXServer and Stage Designer serves the best video playout for Theatres, Facade Projections, Video Mapping, Architectural Lighting, Clubs, and LED Lighting. ''This video software places a strong emphasis on the composition and positioning of the output, because the projection is just as important as the content - no space, stage or scene is like another''. It is a professional real-time video software, which works quickly, securely and robustly. The clearly laid-out interface makes it easy to use and easy to learn. The only limit is the user’s imagination.

== Getting started ==
* [[Introduction]]
* [[User Interface V7|User Interface]]
* [[Tutorials|Try a Tutorial]]
* [[Triggering|Triggering Events]]
* [[Trouble Shooting|Troubleshoot Problems]]
* [[Usage Tips]]
* [[Performance|Performance Tips]]
* [[Translations]]

Trouble Shooting

2026-08-08T19:17:15Z

Admin: Restore Aero Peek link; remove outdated 'Windows 7 + NDI Tools' link (bot)

Sometimes a driver update or a new hardware or a new operating system screws things up badly. We have collected a lot of knowledge from our test farm and our users over the years to help you across the most common pitfalls.

'''All OS'''
*[[Performance Problems]]
*[[Smooth Playback/ Frame Drops and Audio Drivers]]
*[[Keystone: not Opening ./skin/keystone/Video.png: file does not exist]]
*[[Licenser: Wrong Key Format]]
*[[Playlist: Crossfading Between Bright Media Becomes Temporarily Dark]]
*[[Capture Cards (e.g. BM Decklink Studio2)]]
*[[Memory Allocation Error]]
*[[Time and Event Sync all PCs]]
*[[MXW does not start any more]]
*[[Projector Calculator]]
*[[Artnet connection issues: Firewall]]
*[[DMX CITP and Image Sequences]]
*[[MAudio UC-33 to MXWendler controller programming]]
*[[OSC Messages - Correct Text and Value Example]]
*[[User Interface - outside of the main display]]
*[[PJLink commands for DZ21]]
*[[SDI Inputs - YUV Format and Wrong Color Output]]
*[[Vision SDI - Internal Loop/Input]]

'''Windows'''
*[[Windows 11 + No Audio Device]]
*[[Windows 10 + Optimizing Font]]
*[[Windows 10 + Focusrite 18i20 Audio Issues]]
*[[Windows 10 + Corrupted Live Video]]
*[[Windows 10 + VCRUNTTIME140.dll missing]]
*[[Windows 10 + AJA Kona 5]]
*[[Windows 10 + Asus Motherboards - Multimonitoring Issues]]
*[[Windows 10 x64 + Stage Designer/FXServer does not start]]
*[[Windows 10 + Nvidia and Intel Cards]]
*[[Windows + Blackmagic Decklink Capture Cards]]
*[[Windows + Unexpected Output Window Size]]
*[[Windows + No Output in Output Window]]
*[[Windows + How to Deactivate Aero Peek to Prevent Unwanted Output Blackouts]]
*[[Windows 7 + AMD + Stuttering Output]]
*[[Windows 7 + AMD + Output Window On Wrong Screen]]
*[[Windows 7 + Artnet]]
*[[Windows 7 + No Audio]]
*[[Windows 7 + Configuration (config.xml)]]
*[[Windows 7 + Richtexteditor Glitches and ClearType]]

'''Linux'''
*[[Linux and No Dongle Detection]]

'''Mac OSX'''
*[[Mac and No Default Clip]]
*[[Mac and No Translation]]
*[[Mac and No Shaders Update]]
*[[Mac Sierra 10.12 Disable App Translocation]]
*[[Macbook Pro Core 2 Duo with NVidia 9400M]]
*[[Mac and Graphic Card Performance]]
*[[Mac Yosemite 10.10 Multimonitor]]
*[[Mac and Internal Cached Video]]
*[[Mac and Audio]]
*[[Mac and Soundflower 64ch Audio]]
*[[Mac and DMX]]

Trouble Shooting

2026-08-08T19:15:28Z

Admin: Remove link to deleted page 'Windows + How to Deactivate Aero Peek...' (bot)

Sometimes a driver update or a new hardware or a new operating system screws things up badly. We have collected a lot of knowledge from our test farm and our users over the years to help you across the most common pitfalls.

'''All OS'''
*[[Performance Problems]]
*[[Smooth Playback/ Frame Drops and Audio Drivers]]
*[[Keystone: not Opening ./skin/keystone/Video.png: file does not exist]]
*[[Licenser: Wrong Key Format]]
*[[Playlist: Crossfading Between Bright Media Becomes Temporarily Dark]]
*[[Capture Cards (e.g. BM Decklink Studio2)]]
*[[Memory Allocation Error]]
*[[Time and Event Sync all PCs]]
*[[MXW does not start any more]]
*[[Projector Calculator]]
*[[Artnet connection issues: Firewall]]
*[[DMX CITP and Image Sequences]]
*[[MAudio UC-33 to MXWendler controller programming]]
*[[OSC Messages - Correct Text and Value Example]]
*[[User Interface - outside of the main display]]
*[[PJLink commands for DZ21]]
*[[SDI Inputs - YUV Format and Wrong Color Output]]
*[[Vision SDI - Internal Loop/Input]]

'''Windows'''
*[[Windows 11 + No Audio Device]]
*[[Windows 10 + Optimizing Font]]
*[[Windows 10 + Focusrite 18i20 Audio Issues]]
*[[Windows 10 + Corrupted Live Video]]
*[[Windows 10 + VCRUNTTIME140.dll missing]]
*[[Windows 10 + AJA Kona 5]]
*[[Windows 10 + Asus Motherboards - Multimonitoring Issues]]
*[[Windows 10 x64 + Stage Designer/FXServer does not start]]
*[[Windows 10 + Nvidia and Intel Cards]]
*[[Windows + Blackmagic Decklink Capture Cards]]
*[[Windows + Unexpected Output Window Size]]
*[[Windows + No Output in Output Window]]
*[[Windows 7 + AMD + Stuttering Output]]
*[[Windows 7 + AMD + Output Window On Wrong Screen]]
*[[Windows 7 + Artnet]]
*[[Windows 7 + No Audio]]
*[[Windows 7 + Configuration (config.xml)]]
*[[Windows 7 + Richtexteditor Glitches and ClearType]]
*[[Windows 7 + NDI Tools]]

'''Linux'''
*[[Linux and No Dongle Detection]]

'''Mac OSX'''
*[[Mac and No Default Clip]]
*[[Mac and No Translation]]
*[[Mac and No Shaders Update]]
*[[Mac Sierra 10.12 Disable App Translocation]]
*[[Macbook Pro Core 2 Duo with NVidia 9400M]]
*[[Mac and Graphic Card Performance]]
*[[Mac Yosemite 10.10 Multimonitor]]
*[[Mac and Internal Cached Video]]
*[[Mac and Audio]]
*[[Mac and Soundflower 64ch Audio]]
*[[Mac and DMX]]

Trouble Shooting

2026-08-08T19:15:10Z

Admin: Remove link to deleted page 'Windows XP + No output on second screen' (bot)

Sometimes a driver update or a new hardware or a new operating system screws things up badly. We have collected a lot of knowledge from our test farm and our users over the years to help you across the most common pitfalls.

'''All OS'''
*[[Performance Problems]]
*[[Smooth Playback/ Frame Drops and Audio Drivers]]
*[[Keystone: not Opening ./skin/keystone/Video.png: file does not exist]]
*[[Licenser: Wrong Key Format]]
*[[Playlist: Crossfading Between Bright Media Becomes Temporarily Dark]]
*[[Capture Cards (e.g. BM Decklink Studio2)]]
*[[Memory Allocation Error]]
*[[Time and Event Sync all PCs]]
*[[MXW does not start any more]]
*[[Projector Calculator]]
*[[Artnet connection issues: Firewall]]
*[[DMX CITP and Image Sequences]]
*[[MAudio UC-33 to MXWendler controller programming]]
*[[OSC Messages - Correct Text and Value Example]]
*[[User Interface - outside of the main display]]
*[[PJLink commands for DZ21]]
*[[SDI Inputs - YUV Format and Wrong Color Output]]
*[[Vision SDI - Internal Loop/Input]]

'''Windows'''
*[[Windows 11 + No Audio Device]]
*[[Windows 10 + Optimizing Font]]
*[[Windows 10 + Focusrite 18i20 Audio Issues]]
*[[Windows 10 + Corrupted Live Video]]
*[[Windows 10 + VCRUNTTIME140.dll missing]]
*[[Windows 10 + AJA Kona 5]]
*[[Windows 10 + Asus Motherboards - Multimonitoring Issues]]
*[[Windows 10 x64 + Stage Designer/FXServer does not start]]
*[[Windows 10 + Nvidia and Intel Cards]]
*[[Windows + Blackmagic Decklink Capture Cards]]
*[[Windows + How to Deactivate Aero Peek to Prevent Unwanted Output Blackouts]]
*[[Windows + Unexpected Output Window Size]]
*[[Windows + No Output in Output Window]]
*[[Windows 7 + AMD + Stuttering Output]]
*[[Windows 7 + AMD + Output Window On Wrong Screen]]
*[[Windows 7 + Artnet]]
*[[Windows 7 + No Audio]]
*[[Windows 7 + Configuration (config.xml)]]
*[[Windows 7 + Richtexteditor Glitches and ClearType]]
*[[Windows 7 + NDI Tools]]

'''Linux'''
*[[Linux and No Dongle Detection]]

'''Mac OSX'''
*[[Mac and No Default Clip]]
*[[Mac and No Translation]]
*[[Mac and No Shaders Update]]
*[[Mac Sierra 10.12 Disable App Translocation]]
*[[Macbook Pro Core 2 Duo with NVidia 9400M]]
*[[Mac and Graphic Card Performance]]
*[[Mac Yosemite 10.10 Multimonitor]]
*[[Mac and Internal Cached Video]]
*[[Mac and Audio]]
*[[Mac and Soundflower 64ch Audio]]
*[[Mac and DMX]]

Trouble Shooting

2026-08-08T19:14:41Z

Admin: Remove link to deleted page 'Re-Converting Video files using AVANTI GUI' (bot)

Sometimes a driver update or a new hardware or a new operating system screws things up badly. We have collected a lot of knowledge from our test farm and our users over the years to help you across the most common pitfalls.

'''All OS'''
*[[Performance Problems]]
*[[Smooth Playback/ Frame Drops and Audio Drivers]]
*[[Keystone: not Opening ./skin/keystone/Video.png: file does not exist]]
*[[Licenser: Wrong Key Format]]
*[[Playlist: Crossfading Between Bright Media Becomes Temporarily Dark]]
*[[Capture Cards (e.g. BM Decklink Studio2)]]
*[[Memory Allocation Error]]
*[[Time and Event Sync all PCs]]
*[[MXW does not start any more]]
*[[Projector Calculator]]
*[[Artnet connection issues: Firewall]]
*[[DMX CITP and Image Sequences]]
*[[MAudio UC-33 to MXWendler controller programming]]
*[[OSC Messages - Correct Text and Value Example]]
*[[User Interface - outside of the main display]]
*[[PJLink commands for DZ21]]
*[[SDI Inputs - YUV Format and Wrong Color Output]]
*[[Vision SDI - Internal Loop/Input]]

'''Windows'''
*[[Windows 11 + No Audio Device]]
*[[Windows 10 + Optimizing Font]]
*[[Windows 10 + Focusrite 18i20 Audio Issues]]
*[[Windows 10 + Corrupted Live Video]]
*[[Windows 10 + VCRUNTTIME140.dll missing]]
*[[Windows 10 + AJA Kona 5]]
*[[Windows 10 + Asus Motherboards - Multimonitoring Issues]]
*[[Windows 10 x64 + Stage Designer/FXServer does not start]]
*[[Windows 10 + Nvidia and Intel Cards]]
*[[Windows + Blackmagic Decklink Capture Cards]]
*[[Windows + How to Deactivate Aero Peek to Prevent Unwanted Output Blackouts]]
*[[Windows + Unexpected Output Window Size]]
*[[Windows + No Output in Output Window]]
*[[Windows 7 + AMD + Stuttering Output]]
*[[Windows 7 + AMD + Output Window On Wrong Screen]]
*[[Windows 7 + Artnet]]
*[[Windows 7 + No Audio]]
*[[Windows 7 + Configuration (config.xml)]]
*[[Windows 7 + Richtexteditor Glitches and ClearType]]
*[[Windows 7 + NDI Tools]]
*[[Windows XP + No output on second screen|Windows XP + NVidia No output on second screen]]

'''Linux'''
*[[Linux and No Dongle Detection]]

'''Mac OSX'''
*[[Mac and No Default Clip]]
*[[Mac and No Translation]]
*[[Mac and No Shaders Update]]
*[[Mac Sierra 10.12 Disable App Translocation]]
*[[Macbook Pro Core 2 Duo with NVidia 9400M]]
*[[Mac and Graphic Card Performance]]
*[[Mac Yosemite 10.10 Multimonitor]]
*[[Mac and Internal Cached Video]]
*[[Mac and Audio]]
*[[Mac and Soundflower 64ch Audio]]
*[[Mac and DMX]]

OSC Reference

2026-08-08T19:13:01Z

Admin:

This reference applies to all different OS.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address
== Contents ==
{|
|-
| style="padding: 0px 10px" | [[Controlling MXW through OSC]]
|-
| style="padding: 0px 10px" | [[MXW OSC command structure]]
|-
| style="padding: 0px 10px" | [[OSC command reference]]
|-
| style="padding: 0px 10px" | [[OSC Troubleshooting|Troubleshooting]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC Reference

2026-08-08T19:12:10Z

Admin:

OSC Reference

2026-08-08T19:08:59Z

Admin: Update link after renaming Troubleshooting -> OSC Troubleshooting (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''Sending OSC Values''
|-
| style="padding: 0px 30px" | ''Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[OSC Troubleshooting|Troubleshooting]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC Troubleshooting

2026-08-08T19:08:57Z

Admin: Admin moved page Troubleshooting to OSC Troubleshooting: Clarify: OSC-specific troubleshooting

Common issues that can arise while using OSC and MXW are generally linked to network malfunctions.

===Network diagnostics===

Make sure that the system you want to control is correctly connected to the same network as the ‘master’ machine.

==== To proof if the two machines are able to communicate in the network try to ping reciprocally the two systems: ====
:* For Windows users:
::1. Open the “Command Prompt” in the ‘master’ system as Administrator
::2. Type <code> ipconfig </code> take note of the IPv4 Address
::3. Repeat for the ‘slave’ system
::4.In the ‘master’ test if the other machine is reachable by typing <code> ping </code> followed by the IP of the ‘slave’ (e.g. <code> ping 192.168.178.7 </code>)
::5. If the machine is reachable a similar message will appear:
</div>
Pinging 192.168.178.7 with 32 bytes of data:
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64

Ping statistics for 192.168.178.7:
Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 0ms, Maximum = 0ms, Average = 0ms
</div>
::* In case it is not reachable the message will show in the statistics
Received = 0 , Lost = 4 (100% Loss)
::* Repeat the steps sending the ping from the ‘slave’ to the ‘master’ IP to proof the connections
:* For Mac OS X users:
::1. Press “Apple” + "SPACE BAR" and search for “Terminal” in the ‘master’ system
::2. Type <code> ping </code> followed by the IP Address of the ‘slave’
::3. Proof if the ping get through
::4. Repeat for the ‘slave’ system pinging the IP of the ‘master’

==== In case of failure to connect: ====
:*Verify that the firewall is not blocking the communication:
::* For Windows users:
:::1. Search for “Firewall & Network Protection” in the “Start” menu
:::2. Deactivate all three (Domain, Private and Public) firewalls by entering the respective window and switching the protection to “Off” in all of them
::* For Mac OS X users:
:::1. In the Apple menu, select “System Preferences”
:::2. In the System Preferences window, select “Security and Privacy”
:::3. In the tab “Firewall” turn off the Firewall by pressing the “Turn Off” Button (10.6 or higher) or by deselecting the checkbox “Block all incoming connections” (10.5 or lower)
</div>
::* In your Router settings page (see the manufacturers manual for instructions) disable AP (access point) isolation, also known as 'Client Isolation' or 'Guest Mode' when active

==== In case of occasional loss of OSC packages: ====
::* The maximum size of every OSC package is defined by the MTU (minimum transport unit) of the network in use. Big packages tend to get lost more easily depending on the characteristics of the network so reducing the amount of big blobs (e.g. preview requests) can lower the loss rate. See
::* In case of loss of small packages, verify if the packages are getting sent and their size with a package sniffer (e.g. "Wireshark") and try different settings on your receiving console/device.
</br>
</br>
If none of the above solutions solves the issue try by restarting the software and reconnecting all the network chain from start.

For further diagnostics activate the Log of received data in MXW and the dispatch of livesigns (See Points 2.2 and 2.2 d. of the Open Sound Control References) to test the receiving and sending functionality on the wished OSC console, Pd patch or the Protokol App for a mobile option (see point 4.).

OSC Reference

2026-08-08T19:04:34Z

Admin: Remove index numbering from OSC contents (links + sub-items) (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''Sending OSC Values''
|-
| style="padding: 0px 30px" | ''Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[Troubleshooting]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC Troubleshooting

2026-08-08T19:04:14Z

Admin: Admin moved page 5. Troubleshooting to Troubleshooting: Remove leading index prefix from title

MXW OSC command structure

2026-08-08T19:04:13Z

Admin: Admin moved page 2. MXW OSC command structure to MXW OSC command structure: Remove leading index prefix from title

View source for 2. MXW OSC command structure
← 2. MXW OSC command structure
Jump to navigationJump to search
You do not have permission to edit this page, for the following reason:

The action you have requested is limited to users in the group: Users.

You can view and copy the source of this page.

Commands to the MXW OSC interface always follow the same syntax:

<code>/mxw/<address of widget> [MSGID] <float|integer|string></code>

for example:

<code>/mxw/track/1 0.5</code><br>
or:<br>
<code>/mxw/set play patch1</code><br>
or:<br>
<code>/mxw/playlist MSGID0001 info</code> <br>

Commands always begin with /mxw/ and it is followed by the address of the receiver and an argument that can be a numeric value, a string, or a combination of both.
The only optional element is the “Message-ID”.

== 2.1 Sending OSC Values ==
</div>
The command receivers listen to a value that is either a float or an integer (if they are widgets), or to strings (e.g. to choose patches or clips).
==== Faders ====
Receivers in MXW connected to faders in the user interface are responding to Float values. Floats are always in the range of 0.0 to 1.0 and will be scaled to the actual range of the recalled widget. <br>
For instance, the speed fader has a range in MXW that goes between -5 and 5 and its active range is dependent on the type of played media. <br> If a float value like 0.6 is sent to the OSC address of the clip speed, the fader moves to the value 1.0 (original speed of the clip).

==== Buttons and Checkboxes ====
Widgets in MXW that have an '''ON/OFF''' state accept integers as values. Buttons have the functions Press and Release assigned respectively to <code>1</code> and <code>0</code> and checkboxes have assigned ON and OFF respectively to <code>1</code> and <code>0</code>. </br> This means that if one wants to send a button press, e.g. a "play" button press, a value "0" has to be sent (to send a command, like with a mouse-click, a button must be pressed <u>and released</u> after)

==== Drop-down Boxes and Combo Boxes ====
Drop-down lists and Combo Boxes are indexed with integers ranging between <code>1</code> and the maximum number of elements. For example to select the third element of a list the integer <code>3</code> will be sent to the address of the Combo Box.

=== String Tokens ===
</div>
Specific string tokens can also be sent to the command receivers and they can respectively activate specific functions paired with a numeric value or another string. The usable strings are <code>play</code><code>info</code> <code>select</code> <code>preview</code> <code>clear</code>.
==== play ====
The string play can be sent together with another string containing the name of a saved patch in the address <code>/mxw/set </code> to start the playback of the recalled patch.

<code>/mxw/set play patch1</code>.
==== info ====
The string variable info can be sent to a specific address to acquire information about one field or clip through a reply sent by MXW.
The reply bundle coming from MXW will also be sent through OSC and will have this format:

* A reply header composed by:

1. Message <code>mxw/reply</code> <br>
2. <code>MSGID</code> (if specified in the info request)<br>
3. Address pattern of the request<br>
4. Time as a long variable<br>

* The actual '''reply content''' following this table:<br>

{| class="wikitable"
|-
! ADDRESS !! REPLY CONTENT
|-
| <code>/mxw/playlist info </code>|| 1. State of the playback (<code>play</code>, <code>paused</code>, <code>stopped</code>)
|-
| <code>/mxw/playlist/container/active info </code>|| 1. Active container index <br> 2. Number of columns <br> 3. Number of rows
|-
| <code>mxw/playlist/container/active/column/1/row/1 info </code>|| 1. Label of media in the container in column 1, row 1
|-
| <code>/mxw/track/active/layer/active/clip info </code>|| 1. Length of media <br> 2. Width <br>3. Height<br>4. ms per frame<br> 5. Completition of cache (<code>cachecomplete</code>/<code>cachenotcomplete</code>)<br> 6. Path directory of the active clip
|-
| <code>/mxw/preload/1 info </code>|| 1. Length of media <br> 2. Width <br>3. Height<br>4. ms per frame<br> 5. Completition of cache (<code>cachecomplete</code>/<code>cachenotcomplete</code>)<br> 6. Path directory of the media of the first preload
|-
| <code>mxw/keystone info </code>|| 1. Active keystone element index <br> 2. Name of active keystone element<br> 3. Amount of total keystone elements <br> 4. Names of keystone elements separated by commas <br> 5. Active softedge index <br> 6. Name of active softedge <br> 7. Amount of total softedges <br> 8. Names of softedges separated by commas <br> 9. Active grabber element index <br> 10. Name of active grabber element<br> 11. Amount of total grabber elements <br> 12. Names of grabber elements separated by commas <br> 13. Active blacklevel element index <br> 14. Name of active blacklevel element<br> 15. Amount of total blacklevel elements <br> 16. Names of blacklevel elements separated by commas
|-
| <code>mxw/keystone/element/1 info </code>|| 1. Element name <br> 2. Element type <br> 3. Video track number <br> 4. Video layer number <br> 5. Precision <br> 6. Number of pivots x <br> 7. Number of pivots y <br> 8. Scale <br> 9. Opacity <br> 10. Rotation of element number 1
|-
| <code>/mxw/keystone/element/1/pivot/col/1/row/1 info </code>|| 1. Pivot translation x <br> 2. Translation y <br> 3. Translation z <br> 4. UV value x <br> 5. UV values y <br> 6. UV normalized x <br> 7. UV normalized y <br> 8. RGB COLOUR
|-
| <code>mxw/layermanager info</code>|| 1. Active layer index <br> 2. Name of active layer <br> 3. Amount of total layers <br> 4. Names of layers separated by commas
|-
| <code>mxw/set info</code> || 1. Active patch index <br> 2. Name of active patch <br> 3. Amount of total patches <br> 4. Names of patches separated by commas
|-
| <code>mxw/trackmanager info</code>|| 1. Active track index <br> 2. Name of active track<br> 3. Amount of total tracks <br> 4. Names of tracks separated by commas
|-
| Addresses of Drop-down Boxes and Combo Boxes in MXW <br>(e.g. <code>mxw/render/effect info</code>)|| 1. Index and Name of currently selected item <br> 2. Amount of total items <br> 3. Names of items separated by commas
|-
| Addresses of Faders in MXW <br>(e.g. <code>mxw/render/opacity info</code> )|| 1. Value of position of fader (<code>0 .. 1</code>)
|-
| Addresses of Buttons/Checkboxes in MXW <br>(e.g. <code>mxw/track/1/crossfade info</code>)|| 1. State of the widget (<code>0 = released/OFF , 1 = pressed/ON</code>)
|-
|colspan="2" | NOTE: The token <code>active</code> can be substituted with an integer corresponding to the index of the wished element
|}

As an example, if we send:

<code>/mxw/playlist/container/active info</code>

MXWendler will reply:

<code>mxw/reply /mxw/playlist/container/active &emsp;&emsp;&emsp;&emsp;&emsp; 980451 &emsp;&emsp;&emsp;0 &emsp;&emsp;&emsp;&ensp;3 &emsp;&emsp; &emsp; 20</code> <br>
Reply Message Address of Request Time Index Col. Row

====select====
The token select can be added to different addresses to select the single elements on a list of many using a string. This command is can be used in combination with the token <code>info</code> as the names of the elements can be recalled with <code>info</code> first and then selected with the <code>select</code> token.
The receivers that respond with the token select are:
* trackmanager
* layermanager
* combo-boxes

<code>/mxw/trackmanager select track2</code>

====active====
The token active is used in the receiver address and can be used in multiple situations to act on the selected element of a list. For example the command:

<code>/mxw/track/active/fader 0.5</code>

will move the fader of the selected (active) track to his middle position, setting its opacity to 50%.

====preview====
The string preview can be used to get in return an OSC blob, containing a 128x128px '''jpg''' file that is a preview of the currently played media or a thumbnail of the selected clip. Here are the available addresses for a preview:
{| class="wikitable"
|-
! NAME !! ADDRESS
|-
| Render || <code>/mxw/render preview</code>
|-
| Track || <code>/mxw/track/active preview</code>
|-
| Layer || <code>/mxw/track/active/layer/active preview</code>
|-
| Clip || <code>/mxw/track/active/layer/active/clip preview</code>
|-
| Preload || <code>/mxw/preload/"preload index" preview</code> <br><code>/mxw/preload/7 preview</code>
|-
| Patch/Set || <code>/mxw/patch/"patch index" preview</code> <br> E.G.<code>/mxw/patch/3 preview</code>
|-
|colspan="2" | NOTE: The token <code>active</code> can be substituted with an integer corresponding to the index of the wished element
|}

====clear====

The function clear can be sent to the preloads to empty one of the preload spaces.

E.G. <code>mxw/preload/1 clear</code> will clear the first preload slot.

=== Message-ID ===
</div>
The “Message-ID” allows for clear communication and categorization of replies. When a command that generates a reply is sent, it is possible to prepend the command with a “Message-ID” which will be then in the reply as well. This message must have the format <code> MSGIDXXXX </code> and it must follow the OSC address like in the following example:

<code>/mxw/preload/3 MSGID0123 info</code>

will return a reply similar to:

<code>/mxw/reply MSGID0123 /mxw/preload/3 112 320 240 40 cachecomplete c:\footage\clip.avi</code>

== 2.2 Examples ==
To address the main fader and fade the opacity of the render from zero to full in ten steps, you would send a command sequence:
<br>
<code>/mxw/render 0.0</code><br>
<code>/mxw/render 0.1</code><br>
<code>/mxw/render 0.2</code><br>
<code>/mxw/render 0.3</code><br>
<code>/mxw/render 0.4</code><br>
<code>/mxw/render 0.5</code><br>
<code>/mxw/render 0.6</code><br>
<code>/mxw/render 0.7</code><br>
<code>/mxw/render 0.8</code><br>
<code>/mxw/render 0.9</code><br>
<code>/mxw/render 1.0</code>

Finer-grained values can be sent if needed. The commands will be evaluated as soon as they arrive in MXW and the last command before a new frame is drawn will set the widget's value.

<code>/mxw/track/active 0.5</code><br>Sets the active track opacity to 0.5

<code>/mxw/track/1 0.5</code><br>Sets track 1 opacity to 0.5

<code>/mxw/preload/1/trigger 1.0</code><br>Adds a layer with the contents of preload slot 1

<code>/mxw/track/1/layer/1/opacity 0.5</code><br>Sets the opacity of the first layer of the first track to 0.5 (if there is a layer playing content)

<code>/mxw/set 5</code><br>The active track will load patch 5

<code>/mxw/track/active/layer/active/clip/speed 0.6</code><br>Sets the speed of the clip of the active layer of the active track to 1.0 (0.6 translates to 1.0 in a -5 .. +5 range)

<code>/mxw/track/active/layer/active/clip/speed 0.5</code><br>Sets the speed of the clip of the active layer of the active track to 0.5 (clip stops)

<code>/mxw/trackmanager 1</code><br>Activate the first track

<code>/mxw/trackmanager 3</code><br>Activate the third track

<code>/mxw/trackmanager select track3</code><br>Activate the third track

<code>/mxw/track/2/layer/1/clip/effect/2 select ag_AnimWarp</code><br>Instructs the clip of the first layer of the second track to load the effect with the name "ag_AnimWarp" in the effect slot number 2

<code>/mxw/track/2/layer/1/clip/effect/1/param/1 0.8</code><br>Set to the value of 0.8, the parameter 1 of the first effect of the clip of the first layer of the second track

<code>/mxw/preload/2 c:/footage/clip.avi</code><br>Preload slot 2 will load c:/footage/clip.avi (and answer with info). Note the direction of the slashes.

<code>/mxw/preload/2 clear</code><br>Preload slot 2 will unload

<code>/mxw/preload/2 info</code><br>Preload 2 will answer with clip info like <br>
<code>/mxw/reply /mxw/preload/3 112 320 240 40 cachecomplete
c:\footage\clip.avi</code>

<code>/mxw/preload/2 MSGID0123 info</code><br>Preload 2 will answer with clip info like <br>
<code>/mxw/reply MSGID0123 /mxw/preload/3 112 320 240 40 cachecomplete c:\footage\clip.avi</code>

<code>/mxw/master/load_showfile c:/footage/showfile.mxw</code><br>Load the stated showfile

<code>/mxw/master/load_keystonefile c:/footage/keystonefile.mxw_keystone2</code><br>Load the stated keystonefile

Controlling MXW through OSC

2026-08-08T19:04:11Z

Admin: Admin moved page 1. Controlling MXW through OSC to Controlling MXW through OSC: Remove leading index prefix from title

MXW is designed to be a high-performance real-time video software for media servers. It interactively composites high-resolution footage and interactive media.
OSC commands can be generated, sent, and received by MXWendler and a wide range of applications: signaling frameworks like Pure Data, Max/MSP, TouchOSC, and TouchDesigner, audio workstations like Ableton Live, Logic, or Protools, programming environments like Processing, Perl, Java, Unity, and TidalCycles, other Multimedia, Sensoring, Signal Processing software, Microcontrollers and many more, offering a compatible and fast intercommunication method.

Separating the media server from the controlling infrastructure offers various creative and usability options:

*Control multiple machines from one single point
*Control a single machine from multiple points
*Replicate a state into a remote system
*Custom user interfaces
*Intercommunication with external software and platforms
*Control via WAN
*Control via a microcontroller
*Connect scene-analysis with scene-composition systems
*Extract control features e.g mapping or triggering

<div class="noprint">
== 1.1 Receiving OSC commands in MXW ==
</div>

To enable OSC receiving open the software MXWendler: <br>
1. In '''Menu: Settings → Input and Output ''(CTRL+1)'' →''' in the tab '''OSC''', activate the box '''Receive OSC''' ( '''(A)''' In the following picture) <br>
2. Set the port ( 7000 is recommended as an OSC Standard) <br>
3. The box '''Log received data''' will log commands in the Error and Log Window visible through '''Menu: Settings → Error and Log Window ''(CTRL+SHFT+L)'' ''' <br>

This is particularly useful for testing and troubleshooting as it will make visible what OSC commands are received by MXW. The logging of data has a performance impact on the system so it is important to turn it off when not in use.
As this option is marked (r) in the menu, to activate the changes, please restart the software.
<div class="noprint">

== 1.2 Output OSC from MXW: Send vs. Reply ==
</div>
MXW can send OSC commands as well. Multiple distinct options are available in '''Menu: Settings → Input and Output ''(CTRL+1)'' →''' tab '''OSC''' : <br>

[[File:mxwIO.png|728px]]

{{#mpdftags: pagebreak}}

=== Broadcast and Receive Time over OSC '''(B)''' ===
This option will broadcast the MXW time into the selected subnet to synchronize the time among a pool of machines.
To achieve this a selection mechanism is applied: every machine sends its time until it receives the time from a machine with a lower IP address. In the end, the machine with the lowest IP is selected as the 'master' and controls the pool clock.
IO Events can be forwarded by selecting the relative checkbox. You can for example connect a MIDI device and it will send the MIDI events to the pool.

=== Receive OSC over RS232 '''(C)''' ===
Check this box if the OSC commands are received through a Serial Port instead of a network port. Options for port selection and integer indexing are available.

=== Send OSC '''(D)''' ===
This option will send any action on the running host to another host/network defined in the command options. Moving a track slider will generate the commands that make the track slider in the remote machine move to the same position. The goal is to make another machine (pretended it carries the same media data) produce exactly the same result as the master machine by sending osc commands to replicate the same behaviour.
Sometimes it is desireable to send only a selction of the generated actions. You can filter the sent commands using the following rules:
<br>
- Adding a + before a *token*, [comment(optional)]<br>
- Adding a - before a token*, [comment(optional)]<br>
<br>
The *token* is a part of the string like "playlist" or "opacity", a comment can be added after a comma in case we want to specify the reason of the filter. So adding the line <code>+,*playlist*</code> will result into that only commands containing the keyword "playlist" will be sent. In the same way using the filter <code>-,*opacity*, opacity_does_not_change</code> any command referring to "opacity" will not be sent through and everything else will.

=== OSC reply channel '''(E)''' ===
Many OSC commands are capable of asking for specific information e.g. the name of a clip in the preload or the playback status of the playlist. This option must be active in MXW to allow the software to reply to the received OSC commands. Options for a specific IP address of the host/subnet and Port are given in the settings. The last checkbox “Send periodical livesigns” allows to receive a constant periodical flow of data from MXW regarding performance and render information, useful as well for diagnostic reasons.

OSC Reference

2026-08-08T19:02:08Z

Admin: Remove useless '6. External links' entry from contents (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC Reference

2026-08-08T19:00:26Z

Admin: Remove outdated 'Practical examples: Pure Data and TouchOSC' entry from contents (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|-
| style="padding: 10px" | [[6. External links]]
|}
[[Category:OSC]]
[[Category:Reference]]

Python Reference

2026-08-08T18:58:04Z

Admin: Point TOC to de-numbered 'Controlling MXW through Python'; drop index prefixes (bot)

== Introduction ==
This document describes the MXWendler (MXW) Python command interface through an overview of the programming structure, with practical examples of automation and internal scripting. The presented Python commands are for most part supported in version 7.2.

== What is Python? ==
Python is a standardized interpreted, high level programming language. It is used in many applications, mainly in AI and generative tasks. The amount of available libraries is outstanding.

== Contents ==
{|
|-
| style="padding: 10px" | [[Controlling MXW through Python]]
|-
| style="padding: 10px" | [[Python command reference]]
|-
| style="padding: 10px" | [[Python imgui reference]]
|-
| style="padding: 10px" | [[Python plugin reference]]
|-
|}
[[Category:Python]]
[[Category:Reference]]

Controlling MXW through Python

2026-08-08T18:58:03Z

Admin: Admin moved page 1. Controlling MXW through Python to Controlling MXW through Python: Remove leading index prefix from title

MXWendler StageDesigner embeds '''Python 3.12'''. Python is used in two ways:

* '''Command interface / scripting''' – the module <code>mxw</code> controls the running software (playlist, layers, clips, media, I/O, widgets by their address, ...) from the script console or from within a plugin.
* '''Plugins''' – self-contained folders that add a media source or a playlist item and are called back by the host through a defined set of functions (''hooks'').

'''The presented Python interface is supported in version 7.2. and up'''

== Where to go ==

The detailed documentation lives on three dedicated pages; this page only points to them so nothing is documented twice.

{| class="wikitable"
|-
! Topic !! Page
|-
| The <code>mxw</code> command interface – software info, <code>playlist</code>, <code>io</code>, <code>widget(address)</code>, <code>media(name)</code>, <code>preload(n)</code>, <code>grabber(name)</code> || [[Python command reference|Python command reference]]
|-
| Drawing plugin settings panels with <code>mxw_imgui</code> (MXWendler's Dear ImGui binding) || [[Python imgui reference|Python ImGui reference]]
|-
| Writing '''plugins''' – media and playlist – the manifest (<code>mxw_plugin.ini</code>), the hooks, per-instance state, examples || [[Python plugin reference|Python plugin reference]]
|}

== Quick start ==

A minimal look at each entry point; follow the links above for the full reference.

'''Scripting.''' From the script console (or any hook), the <code>mxw</code> module reaches the software:

<syntaxhighlight lang="Python" line>
import mxw
mxw.print_console("frame " + str(mxw.framecounter))
mxw.playlist.play()
mxw.widget("/mxw/track/active/layer/active/opacity").setValue(0.5)
</syntaxhighlight>

'''Plugins.''' A plugin is a folder holding a manifest and a Python module:

<pre>
plugins/playlist/python/plugin_my_item/
mxw_plugin.ini the manifest: identity, menu entries
mxw_main.py the Python module with the hook functions
</pre>

The host discovers it at startup, shows it in the user interface and calls its hooks at the right moments. See the [[Python plugin reference|Python plugin reference]] for the manifest fields, the full hook list for media and playlist plugins, plugin locations, installing extra packages with <code>mxw-pip</code>, and complete examples.

== See also ==

* [[Python command reference|Python command reference]] – the <code>mxw</code> module
* [[Python imgui reference|Python ImGui reference]] – drawing plugin panels with <code>mxw_imgui</code>
* [[Python plugin reference|Python plugin reference]] – writing media and playlist plugins

JavaScript Reference

2026-08-08T18:51:36Z

Admin: Point TOC to de-numbered page titles; drop index prefixes (bot)

External Resources

2026-08-08T18:51:22Z

Admin: Admin moved page 6. External Resources to External Resources: Remove leading index prefix from title

</br>
1 https://en.wikipedia.org/wiki/JavaScript</br>
2 https://developer.mozilla.org/en-US/docs/Web/JavaScript </br>
3 https://curlie.org/Computers/Programming/Languages/JavaScript/ </br>
4 https://duktape.org/index.html </br>

Troubleshooting scripts

2026-08-08T18:51:21Z

Admin: Admin moved page 5. Troubleshooting scripts to Troubleshooting scripts: Remove leading index prefix from title

'''Problem'''

JavaScript is not functioning as intended. No corresponding action happens when the trigger button for the event is pressed.

'''Hints'''

# Open the JavaScript console by pressing Ctrl+Shift+J (Mac:Command+Shift+J) and look for error messages.
# Check for syntax errors in your code and ensure that interface functions are written correctly.
# Check that predefined hooks and functions like e.g. on_trigger() are written correctly. Syntax highlighting and coloring may help you identify these issues.
# When resolving widgets, verify the used widgets address (e.g. "/mxw/render/opacity") and make sure that it is valid. To find the correct address, maybe refer to the list of address suggestions available in the 'Receiver' menu.

Practical examples

2026-08-08T18:51:19Z

Admin: Admin moved page 4. Practical examples to Practical examples: Remove leading index prefix from title

Download the Javascript Reference folder from https://www.mxwendler.net/de/downloads.html

1) Double click on the "js-demo.mxw" to load the demo.<div>

2) Open the I/O Settings Window (CTRL+1) or click on "Settings" → "Inputs and Outputs - Keyboard, Midi, DMX" <div>
&emsp; and click on SHOW JAVASCRIPT CONSOLE, almost at the bottom of the I/O window.

3) Follow the instructions on the Javascript Console. <div>

===Commands:===

Remember to click on the interface header before giving commands,
the operating System needs to know where the keyboard signals are directed.

<code>backspace</code> starts the patch and selects the LiveEditor Tab.
<div>
<code>spacebar</code> (6 times at least) to set up a tap tempo
<div>
<code>1</code> Sets the render opacity to 0
<div>
<code>2</code> Sets the render opacity to 0.5
<div>
<code>3</code> Sets the render opacity to 1
<div>
<code>4</code> Writes Output informations on the Javascript console.
Takes a screenshot of the output and saves it in "C:\screen"
(if the directory already exists)

Controlling MXW through JavaScript

2026-08-08T18:51:18Z

Admin: Admin moved page 1. Controlling MXW through JavaScript to Controlling MXW through JavaScript: Remove leading index prefix from title

Although there are many ways to control MXWendler with a lot of I/O devices, e.g. mouse buttons, keyboard, DMX and MIDI devices, and automation commands in MXWendler using events in the playlist, some desired behaviours are too complex to be offered through a GUI element.
JavaScript allows instead to script any animation and behaviour sequence. Additionally, JavaScript allows you to emit values to I/O devices like DMX, OSC or MIDI and set various internal variables in media and in the software.

The JavaScript engine used by the MXWendler scripting is Duktape, standardized under ECMAScript E5/E5.1. (more info at the Duktape [https://duktape.org/index.html website])

To write JavaScripts open MXWendler "StageDesigner" or "FxServer" and access the editor by clicking "Settings" → "Inputs and Outputs - Keyboard, Midi, DMX" (or with the hotkey <code>CTRL + 1</code>)
<div>

[[File:Open settings.jpeg|728px]]
{{#mpdftags: pagebreak}}
<div>
On the window, in the first tab ("DMX/Midi/Keyboard Events") the editor is available in the lower right corner.
<div>

[[File:Editor.jpeg|728px]]
{{#mpdftags: pagebreak}}
<div>

To facilitate debugging, a script-wide function "print_console" is available and the Javascript console is available to be opened from either the checkbox under the editor, or from the menu: "Settings" → "Open Javascript Console" (<code>CTRL + J</code>)

Python imgui reference

2026-08-08T18:00:10Z

Admin: Fix example (mxw.print_console) and repoint broken Python Plugin Howto link (bot)

Here are listed the commands available in module <code>mxw_imgui</code>, MXWendler's Python binding of '''Dear ImGui'''. This is how plugins draw their settings panel, in the <code>onRenderPanel()</code> hook (see the [[Python plugin reference|Python plugin reference]]).

<code>mxw_imgui</code> mirrors the Dear ImGui C++ API almost function-for-function: the C++ <code>ImGui::PascalCase</code> names become Python <code>snake_case</code>, one argument at a time. If you already know Dear ImGui (or its C++/other-language bindings), the name of a call is usually a mechanical translation away.

=== Legend ===
<div>

Everything from the [[Python_Reference|Python Reference]] Legend applies (floats, integers, strings, <u>OR</u> for alternative formats). In addition:

Dear ImGui widgets that take a pointer to their value in C++ (so the value can be written back) instead return a '''tuple''' <code>(changed, value)</code> in Python: <code>changed</code> is <code>true</code> when the user edited the widget this frame, <code>value</code> is the (possibly new) value to keep and pass back in next frame. E.g.:

<code>changed, value = mxw_imgui.slider_float("Speed", value, 0.0, 1.0)</code>

Widgets with several packed floats/ints (<code>drag_float2</code>, <code>slider_int4</code>, ...) take and return a plain Python list/tuple of that length instead of a C array.

'''Flags''' (<code>ImGuiTreeNodeFlags</code>, <code>ImGuiWindowFlags</code>, <code>ImGuiCol</code>, ...) are '''not''' exposed as named Python constants — pass the plain integer value of the Dear ImGui enum (default <code>0</code> means "no flags" for nearly every call). Consult the Dear ImGui headers/docs for the numeric values if you need non-default flags.

Parameters shown as <code>= value</code> in the tables below are '''optional''' with that default; omit them to use the default.

Plugins draw '''into an existing panel''' — there is no <code>begin</code>/<code>end</code> for top-level windows; start directly with widget calls.

</div>

=== Data types ===

{| class="wikitable"
|-
! PYTHON TYPE !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.Vec2()</code> OR <code>mxw_imgui.Vec2(x, y)</code> || 2D float vector (<code>.x</code>, <code>.y</code>), used for sizes and positions || <code>size = mxw_imgui.Vec2(200, 0)</code>
|-
|<code>mxw_imgui.Vec4()</code> OR <code>mxw_imgui.Vec4(x, y, z, w)</code> || 4D float vector (<code>.x</code>, <code>.y</code>, <code>.z</code>, <code>.w</code>), used for colors (RGBA) and rectangles || <code>col = mxw_imgui.Vec4(1.0, 0.0, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.Vector_char</code>, <code>Vector_float</code>, <code>Vector_unsignedchar</code>, <code>Vector_unsignedshort</code>, <code>Vector_DrawCmd</code>, <code>Vector_DrawVert</code>, <code>Vector_FontGlyph</code> || Read-only iterable wrappers around Dear ImGui's internal <code>ImVector<T></code> buffers, returned by some getters (e.g. draw list data). Support <code>len()</code>, iteration and indexing || <code>for glyph in font.Glyphs: pass</code>
|}

=== Style & Fonts ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_font(font)</code> || push a font onto the font stack for subsequent widgets || <code>mxw_imgui.push_font(mxw_imgui.get_font())</code>
|-
|<code>mxw_imgui.pop_font()</code> || pop the last pushed font || <code>mxw_imgui.pop_font()</code>
|-
|<code>mxw_imgui.push_style_color(idx, col)</code> || push a style color override (<code>col</code> as packed <code>u32</code> OR <code>Vec4</code>) || <code>mxw_imgui.push_style_color(0, mxw_imgui.Vec4(1,0,0,1))</code>
|-
|<code>mxw_imgui.pop_style_color(count = 1)</code> || pop <code>count</code> previously pushed style colors || <code>mxw_imgui.pop_style_color()</code>
|-
|<code>mxw_imgui.push_style_var(idx, val)</code> || push a style var override (<code>val</code> as float OR <code>Vec2</code>) || <code>mxw_imgui.push_style_var(0, 4.0)</code>
|-
|<code>mxw_imgui.pop_style_var(count = 1)</code> || pop <code>count</code> previously pushed style vars || <code>mxw_imgui.pop_style_var()</code>
|-
|<code>mxw_imgui.push_allow_keyboard_focus(allow_keyboard_focus)</code> || allow/disallow tab-focusing the next widgets || <code>mxw_imgui.push_allow_keyboard_focus(false)</code>
|-
|<code>mxw_imgui.pop_allow_keyboard_focus()</code> || pop the keyboard-focus override || <code>mxw_imgui.pop_allow_keyboard_focus()</code>
|-
|<code>mxw_imgui.push_button_repeat(repeat)</code> || make subsequent buttons behave as repeating (held = repeated clicks) || <code>mxw_imgui.push_button_repeat(true)</code>
|-
|<code>mxw_imgui.pop_button_repeat()</code> || pop the button-repeat override || <code>mxw_imgui.pop_button_repeat()</code>
|-
|<code>mxw_imgui.get_font()</code> || returns the current font object || <code>f = mxw_imgui.get_font()</code>
|-
|<code>mxw_imgui.get_font_size()</code> || returns the current font size in px || <code>sz = mxw_imgui.get_font_size()</code>
|-
|<code>mxw_imgui.get_font_tex_uv_white_pixel()</code> || returns UV coordinate of a white pixel in the font texture, for custom draw-list use || <code>uv = mxw_imgui.get_font_tex_uv_white_pixel()</code>
|-
|<code>mxw_imgui.get_color_u32(idx, alpha_mul = 1.0)</code> OR <code>mxw_imgui.get_color_u32(col)</code> || resolve a style color index, a <code>Vec4</code>, or a packed <code>u32</code> to a final packed <code>u32</code> color || <code>c = mxw_imgui.get_color_u32(0)</code>
|-
|<code>mxw_imgui.get_style_color_vec4(idx)</code> || returns the raw <code>Vec4</code> for a style color index || <code>c = mxw_imgui.get_style_color_vec4(0)</code>
|-
|<code>mxw_imgui.get_style_color_name(idx)</code> || returns the readable name of a style color index || <code>mxw.print_console(mxw_imgui.get_style_color_name(0))</code>
|-
|<code>mxw_imgui.set_color_edit_options(flags)</code> || set default flags for every subsequent color_edit/color_picker call || <code>mxw_imgui.set_color_edit_options(0)</code>
|}

=== Cursor & Layout ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_item_width(item_width)</code> || push a fixed width (px, or negative = right-aligned) for subsequent widgets || <code>mxw_imgui.push_item_width(150)</code>
|-
|<code>mxw_imgui.pop_item_width()</code> || pop the pushed item width || <code>mxw_imgui.pop_item_width()</code>
|-
|<code>mxw_imgui.set_next_item_width(item_width)</code> || set the width of just the next widget || <code>mxw_imgui.set_next_item_width(300)</code>
|-
|<code>mxw_imgui.calc_item_width()</code> || returns the width the next widget would use || <code>w = mxw_imgui.calc_item_width()</code>
|-
|<code>mxw_imgui.push_text_wrap_pos(wrap_local_pos_x = 0.0)</code> || push a word-wrap position (0 = wrap at window edge) for subsequent text || <code>mxw_imgui.push_text_wrap_pos()</code>
|-
|<code>mxw_imgui.pop_text_wrap_pos()</code> || pop the pushed wrap position || <code>mxw_imgui.pop_text_wrap_pos()</code>
|-
|<code>mxw_imgui.separator()</code> || draw a thin horizontal separator line || <code>mxw_imgui.separator()</code>
|-
|<code>mxw_imgui.same_line(offset_from_start_x = 0.0, spacing = -1.0)</code> || keep the next widget on the same line as the previous one || <code>mxw_imgui.same_line()</code>
|-
|<code>mxw_imgui.new_line()</code> || force a following widget to start on a new line || <code>mxw_imgui.new_line()</code>
|-
|<code>mxw_imgui.spacing()</code> || add vertical spacing || <code>mxw_imgui.spacing()</code>
|-
|<code>mxw_imgui.dummy(size)</code> || reserve an empty invisible <code>size</code> (<code>Vec2</code>) area, e.g. as a spacer || <code>mxw_imgui.dummy(mxw_imgui.Vec2(0, 10))</code>
|-
|<code>mxw_imgui.indent(indent_w = 0.0)</code> || move the cursor right (indent) || <code>mxw_imgui.indent()</code>
|-
|<code>mxw_imgui.unindent(indent_w = 0.0)</code> || move the cursor back left (unindent), matching a prior indent() || <code>mxw_imgui.unindent()</code>
|-
|<code>mxw_imgui.begin_group()</code> || start a layout group (following widgets are treated as one unit for layout purposes) || <code>mxw_imgui.begin_group()</code>
|-
|<code>mxw_imgui.end_group()</code> || close the current layout group || <code>mxw_imgui.end_group()</code>
|-
|<code>mxw_imgui.get_cursor_pos()</code> || returns the cursor position (<code>Vec2</code>) relative to the current window || <code>p = mxw_imgui.get_cursor_pos()</code>
|-
|<code>mxw_imgui.get_cursor_pos_x()</code> OR <code>mxw_imgui.get_cursor_pos_y()</code> || returns just the X or Y cursor coordinate || <code>x = mxw_imgui.get_cursor_pos_x()</code>
|-
|<code>mxw_imgui.set_cursor_pos(local_pos)</code> || set the cursor position (<code>Vec2</code>), window-relative || <code>mxw_imgui.set_cursor_pos(mxw_imgui.Vec2(0, 0))</code>
|-
|<code>mxw_imgui.set_cursor_pos_x(local_x)</code> OR <code>mxw_imgui.set_cursor_pos_y(local_y)</code> || set just the X or Y cursor coordinate || <code>mxw_imgui.set_cursor_pos_x(20)</code>
|-
|<code>mxw_imgui.get_cursor_start_pos()</code> || returns the initial cursor position of the current window/child || <code>p = mxw_imgui.get_cursor_start_pos()</code>
|-
|<code>mxw_imgui.get_cursor_screen_pos()</code> || returns the cursor position in absolute screen coordinates || <code>p = mxw_imgui.get_cursor_screen_pos()</code>
|-
|<code>mxw_imgui.set_cursor_screen_pos(pos)</code> || set the cursor in absolute screen coordinates || <code>mxw_imgui.set_cursor_screen_pos(p)</code>
|-
|<code>mxw_imgui.align_text_to_frame_padding()</code> || vertically align following text with standard framed widgets on the same line || <code>mxw_imgui.align_text_to_frame_padding()</code>
|-
|<code>mxw_imgui.get_text_line_height()</code> OR <code>mxw_imgui.get_text_line_height_with_spacing()</code> || returns one text line's height, with or without inter-line spacing || <code>h = mxw_imgui.get_text_line_height()</code>
|-
|<code>mxw_imgui.get_frame_height()</code> OR <code>mxw_imgui.get_frame_height_with_spacing()</code> || returns a standard framed widget's height, with or without spacing || <code>h = mxw_imgui.get_frame_height()</code>
|}

=== ID stack ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_id(str_id)</code> OR <code>mxw_imgui.push_id(str_id_begin, str_id_end)</code> OR <code>mxw_imgui.push_id(ptr_id)</code> OR <code>mxw_imgui.push_id(int_id)</code> || push a scope onto the ID stack, so same-labelled widgets in a loop don't collide || <code>mxw_imgui.push_id(i)</code>
|-
|<code>mxw_imgui.pop_id()</code> || pop the last pushed ID scope || <code>mxw_imgui.pop_id()</code>
|-
|<code>mxw_imgui.get_id(str_id)</code> OR <code>mxw_imgui.get_id(str_id_begin, str_id_end)</code> OR <code>mxw_imgui.get_id(ptr_id)</code> || compute a widget ID without pushing it || <code>uid = mxw_imgui.get_id("my_widget")</code>
|}

=== Text ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.text_unformatted(text, text_end = None)</code> || draw raw text, faster than <code>text()</code> for long/dynamic strings (no format parsing) || <code>mxw_imgui.text_unformatted("Ready.")</code>
|-
|<code>mxw_imgui.text(fmt)</code> || draw a line of text || <code>mxw_imgui.text("Frame: " + str(mxw.framecounter))</code>
|-
|<code>mxw_imgui.text_colored(col, fmt)</code> || draw text in the given <code>Vec4</code> color || <code>mxw_imgui.text_colored(mxw_imgui.Vec4(1,0,0,1), "Error")</code>
|-
|<code>mxw_imgui.text_disabled(fmt)</code> || draw text in the disabled/grey style color || <code>mxw_imgui.text_disabled("(no signal)")</code>
|-
|<code>mxw_imgui.text_wrapped(fmt)</code> || draw text that wraps at the window edge, regardless of the wrap-pos stack || <code>mxw_imgui.text_wrapped(status_message)</code>
|-
|<code>mxw_imgui.label_text(label, fmt)</code> || draw a "label: value"-style line (label aligned like other widgets) || <code>mxw_imgui.label_text("Status", "OK")</code>
|-
|<code>mxw_imgui.bullet_text(fmt)</code> || draw a bulleted line of text || <code>mxw_imgui.bullet_text("first item")</code>
|}

=== Main widgets ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.button(label, size = Vec2(0,0))</code> || a clickable button; returns <code>true</code> the frame it's clicked || <code>if mxw_imgui.button("Reload"): reload()</code>
|-
|<code>mxw_imgui.small_button(label)</code> || a button with no extra vertical padding, fits inline with text || <code>if mxw_imgui.small_button("x"): close()</code>
|-
|<code>mxw_imgui.invisible_button(str_id, size, flags = 0)</code> || an invisible clickable/draggable area || <code>mxw_imgui.invisible_button("drag_area", mxw_imgui.Vec2(50,50))</code>
|-
|<code>mxw_imgui.arrow_button(str_id, dir)</code> || a small square button with an arrow glyph (<code>dir</code>: 0=left,1=right,2=up,3=down) || <code>mxw_imgui.arrow_button("up", 2)</code>
|-
|<code>mxw_imgui.image(user_texture_id, size, uv0 = Vec2(0,0), uv1 = Vec2(1,1), tint_col = Vec4(1,1,1,1), border_col = Vec4(0,0,0,0))</code> || draw a texture (GL texture id) as an image || <code>mxw_imgui.image(tex_id, mxw_imgui.Vec2(128,128))</code>
|-
|<code>mxw_imgui.image_button(user_texture_id, size, uv0 = Vec2(0,0), uv1 = Vec2(1,1), frame_padding = -1, bg_col = Vec4(0,0,0,0), tint_col = Vec4(1,1,1,1))</code> || a clickable image button || <code>if mxw_imgui.image_button(tex_id, mxw_imgui.Vec2(32,32)): pass</code>
|-
|<code>mxw_imgui.checkbox(label, v)</code> || a checkbox; <code>v</code>/return is <code>bool</code> || <code>changed, enabled = mxw_imgui.checkbox("Enabled", enabled)</code>
|-
|<code>mxw_imgui.checkbox_flags(label, flags, flags_value)</code> || a checkbox that toggles one bit(mask) of an int flags value || <code>changed, flags = mxw_imgui.checkbox_flags("Bit 1", flags, 1)</code>
|-
|<code>mxw_imgui.radio_button(label, active)</code> OR <code>mxw_imgui.radio_button(label, v, v_button)</code> || a radio button; single-bool form for manual state, or bind directly to an int selection variable || <code>changed, mode = mxw_imgui.radio_button("Mode A", mode, 0)</code>
|-
|<code>mxw_imgui.progress_bar(fraction, size_arg = Vec2(-FLT_MIN, 0), overlay = None)</code> || a progress bar, <code>fraction</code> 0.0..1.0 || <code>mxw_imgui.progress_bar(0.5)</code>
|-
|<code>mxw_imgui.bullet()</code> || draw just a bullet glyph, e.g. before inline text/widgets || <code>mxw_imgui.bullet()</code>
|}

=== Combo box ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.combo(label, current_item, items, popup_max_height_in_items = -1)</code> || a combo box built from a Python list of strings; simplest way to pick one of several options || <code>changed, sel = mxw_imgui.combo("Mode", sel, ["A", "B", "C"])</code>
|-
|<code>mxw_imgui.begin_combo(label, preview_value, flags = 0)</code> / <code>mxw_imgui.end_combo()</code> || low-level combo box: build the popup content yourself (e.g. with <code>selectable()</code>) between these two calls || <code>if mxw_imgui.begin_combo("Mode", preview): mxw_imgui.end_combo()</code>
|}

=== Drag sliders ===
Click-and-drag widgets; typing is also possible (Ctrl+click / double-click).

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.drag_float(label, v, v_speed = 1.0, v_min = 0.0, v_max = 0.0, format = None, flags = 0)</code> || drag a single float; <code>v_min == v_max == 0</code> means unbounded || <code>changed, value = mxw_imgui.drag_float("Speed", value, 0.01, 0.0, 2.0)</code>
|-
|<code>mxw_imgui.drag_float2(label, v, ...)</code> / <code>drag_float3</code> / <code>drag_float4</code> || same, for a list of 2/3/4 floats (e.g. a color or position) || <code>changed, xyz = mxw_imgui.drag_float3("Position", xyz)</code>
|-
|<code>mxw_imgui.drag_float_range2(label, v_current_min, v_current_max, v_speed = 1.0, v_min = 0.0, v_max = 0.0, format = None, format_max = None, flags = 0)</code> || drag a min/max float range with two handles || <code>changed, lo, hi = mxw_imgui.drag_float_range2("Range", lo, hi)</code>
|-
|<code>mxw_imgui.drag_int(label, v, v_speed = 1.0, v_min = 0, v_max = 0, format = None, flags = 0)</code> || drag a single int || <code>changed, value = mxw_imgui.drag_int("Count", value, 1, 0, 10)</code>
|-
|<code>mxw_imgui.drag_int2(label, v, ...)</code> / <code>drag_int3</code> / <code>drag_int4</code> || same, for a list of 2/3/4 ints || <code>changed, rgb = mxw_imgui.drag_int3("RGB", rgb, 1, 0, 255)</code>
|-
|<code>mxw_imgui.drag_int_range2(label, v_current_min, v_current_max, ...)</code> || drag a min/max int range with two handles || <code>changed, lo, hi = mxw_imgui.drag_int_range2("Range", lo, hi)</code>
|-
|<code>mxw_imgui.drag_scalar(label, data_type, p_data, v_speed, p_min = None, p_max = None, format = None, flags = 0)</code> / <code>drag_scalar_n(..., components, ...)</code> || generic drag widget for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.drag_scalar("Value", 0, ptr, 1.0)</code>
|}

=== Sliders ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.slider_float(label, v, v_min, v_max, format = None, flags = 0)</code> || slide a single float between <code>v_min</code> and <code>v_max</code> || <code>changed, value = mxw_imgui.slider_float("Mouse X", value, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.slider_float2(label, v, v_min, v_max, ...)</code> / <code>slider_float3</code> / <code>slider_float4</code> || same, for a list of 2/3/4 floats || <code>changed, rgba = mxw_imgui.slider_float4("Color", rgba, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.slider_angle(label, v_rad, v_degrees_min = -360.0, v_degrees_max = 360.0, format = None, flags = 0)</code> || slide an angle, stored in radians but displayed/typed in degrees || <code>changed, rot = mxw_imgui.slider_angle("Rotation", rot)</code>
|-
|<code>mxw_imgui.slider_int(label, v, v_min, v_max, format = None, flags = 0)</code> || slide a single int || <code>changed, idx = mxw_imgui.slider_int("Preset", idx, 0, 99)</code>
|-
|<code>mxw_imgui.slider_int2(label, v, v_min, v_max, ...)</code> / <code>slider_int3</code> / <code>slider_int4</code> || same, for a list of 2/3/4 ints || <code>changed, xy = mxw_imgui.slider_int2("Grid pos", xy, 0, 10)</code>
|-
|<code>mxw_imgui.slider_scalar(label, data_type, p_data, p_min, p_max, format = None, flags = 0)</code> / <code>slider_scalar_n(..., components, ...)</code> || generic slider for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.slider_scalar("Value", 0, ptr, p_min, p_max)</code>
|-
|<code>mxw_imgui.v_slider_float(label, size, v, v_min, v_max, format = None, flags = 0)</code> || vertical slider variant of <code>slider_float</code> || <code>changed, value = mxw_imgui.v_slider_float("##vol", mxw_imgui.Vec2(20,100), value, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.v_slider_int(label, size, v, v_min, v_max, format = None, flags = 0)</code> || vertical slider variant of <code>slider_int</code> || <code>changed, value = mxw_imgui.v_slider_int("##lvl", mxw_imgui.Vec2(20,100), value, 0, 10)</code>
|-
|<code>mxw_imgui.v_slider_scalar(label, size, data_type, p_data, p_min, p_max, format = None, flags = 0)</code> || generic vertical slider for any <code>ImGuiDataType</code> || <code>mxw_imgui.v_slider_scalar("##v", size, 0, ptr, p_min, p_max)</code>
|}

=== Input widgets ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.input_text(label, data, max_size, flags = 0)</code> || a single-line text field; <code>data</code> is the current string, <code>max_size</code> the max length in bytes || <code>changed, value = mxw_imgui.input_text("URL", url_text, 512)</code>
|-
|<code>mxw_imgui.input_text_multiline(label, data, max_size, size = Vec2(0,0), flags = 0)</code> || a multi-line text field || <code>changed, value = mxw_imgui.input_text_multiline("Notes", notes, 2048, mxw_imgui.Vec2(300,100))</code>
|-
|<code>mxw_imgui.input_float(label, v, step = 0.0, step_fast = 0.0, format = None, flags = 0)</code> || a typed float field with optional +/- step buttons || <code>changed, value = mxw_imgui.input_float("Gain", value, 0.1)</code>
|-
|<code>mxw_imgui.input_float2(label, v, ...)</code> / <code>input_float3</code> / <code>input_float4</code> || same, for a list of 2/3/4 floats || <code>changed, xyz = mxw_imgui.input_float3("Pos", xyz)</code>
|-
|<code>mxw_imgui.input_int(label, v, step = 1, step_fast = 100, flags = 0)</code> || a typed int field with +/- step buttons || <code>changed, value = mxw_imgui.input_int("Count", value)</code>
|-
|<code>mxw_imgui.input_int2(label, v, flags = 0)</code> / <code>input_int3</code> / <code>input_int4</code> || same, for a list of 2/3/4 ints || <code>changed, rgb = mxw_imgui.input_int3("RGB", rgb)</code>
|-
|<code>mxw_imgui.input_double(label, v, step = 0.0, step_fast = 0.0, format = None, flags = 0)</code> || a typed double field || <code>changed, value = mxw_imgui.input_double("Precise", value)</code>
|-
|<code>mxw_imgui.input_scalar(label, data_type, p_data, p_step = None, p_step_fast = None, format = None, flags = 0)</code> / <code>input_scalar_n(..., components, ...)</code> || generic typed field for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.input_scalar("Value", 0, ptr)</code>
|}

=== Color editor & picker ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.color_edit3(label, col, flags = 0)</code> || a compact RGB color editor (swatch + popup picker); <code>col</code> is a 3-float list || <code>changed, rgb = mxw_imgui.color_edit3("Tint", rgb)</code>
|-
|<code>mxw_imgui.color_edit4(label, col, flags = 0)</code> || same, RGBA (4-float list) || <code>changed, rgba = mxw_imgui.color_edit4("Tint", rgba)</code>
|-
|<code>mxw_imgui.color_picker3(label, col, flags = 0)</code> || a full RGB color picker widget, always expanded || <code>changed, rgb = mxw_imgui.color_picker3("Tint", rgb)</code>
|-
|<code>mxw_imgui.color_picker4(label, col, flags = 0, ref_col = None)</code> || same, RGBA, optionally showing a reference color for comparison || <code>changed, rgba = mxw_imgui.color_picker4("Tint", rgba)</code>
|-
|<code>mxw_imgui.color_button(desc_id, col, flags = 0, size = Vec2(0,0))</code> || a non-editable color swatch button (e.g. as a preview/trigger) || <code>if mxw_imgui.color_button("preview", col): open_picker()</code>
|}

=== Trees ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.tree_node(label)</code> OR <code>mxw_imgui.tree_node(str_id, fmt)</code> OR <code>mxw_imgui.tree_node(ptr_id, fmt)</code> || an expandable/collapsible tree node; returns <code>true</code> while open. Call <code>tree_pop()</code> if it returned <code>true</code> || <code>if mxw_imgui.tree_node("Advanced"): mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_node_ex(label, flags = 0)</code> OR <code>mxw_imgui.tree_node_ex(str_id, flags, fmt)</code> OR <code>mxw_imgui.tree_node_ex(ptr_id, flags, fmt)</code> || <code>tree_node()</code> with explicit flags (e.g. default-open, leaf, selected) || <code>if mxw_imgui.tree_node_ex("Node", 0): mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_push(str_id)</code> OR <code>mxw_imgui.tree_push(ptr_id = None)</code> || push an indent level without drawing a node (paired with <code>tree_pop()</code>) || <code>mxw_imgui.tree_push("scope"); mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_pop()</code> || pop one indent level pushed by <code>tree_node()</code>/<code>tree_push()</code> || <code>mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.get_tree_node_to_label_spacing()</code> || returns the horizontal spacing between a tree node arrow and its label || <code>s = mxw_imgui.get_tree_node_to_label_spacing()</code>
|-
|<code>mxw_imgui.collapsing_header(label, flags = 0)</code> OR <code>mxw_imgui.collapsing_header(label, p_visible, flags = 0)</code> || a top-level collapsible section header; optionally with a close ("x") button when <code>p_visible</code> is passed || <code>if mxw_imgui.collapsing_header("Settings"): mxw_imgui.text("...")</code>
|-
|<code>mxw_imgui.set_next_item_open(is_open, cond = 0)</code> || force the next <code>tree_node()</code>/<code>collapsing_header()</code> open/closed state || <code>mxw_imgui.set_next_item_open(true)</code>
|}

=== Selectables & list boxes ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.selectable(label, selected = false, flags = 0, size = Vec2(0,0))</code> OR <code>mxw_imgui.selectable(label, p_selected, flags = 0, size = Vec2(0,0))</code> || a clickable, highlightable row (typically inside a list box) || <code>if mxw_imgui.selectable("Item 1", is_sel): pick(1)</code>
|-
|<code>mxw_imgui.begin_list_box(label, size = Vec2(0,0))</code> / <code>mxw_imgui.end_list_box()</code> || low-level list box: build the rows yourself (e.g. with <code>selectable()</code>) between these two calls || <code>if mxw_imgui.begin_list_box("Items"): mxw_imgui.end_list_box()</code>
|-
|<code>mxw_imgui.list_box(label, current_item, items, height_in_items = -1)</code> || a list box built from a Python list of strings, single-select || <code>changed, sel = mxw_imgui.list_box("Presets", sel, ["A", "B", "C"])</code>
|-
|<code>mxw_imgui.list_box_stretch(label, current_item, items)</code> || MXWendler custom variant of <code>list_box()</code> that stretches to fill the remaining panel height || <code>changed, sel = mxw_imgui.list_box_stretch("Presets", sel, names)</code>
|}

=== Data plotting ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.plot_lines(label, values, values_offset = 0, overlay_text = None, scale_min = FLT_MAX, scale_max = FLT_MAX, graph_size = Vec2(0,0))</code> || draw a line graph from a Python list of floats || <code>mxw_imgui.plot_lines("Levels", history)</code>
|-
|<code>mxw_imgui.plot_histogram(label, values, values_offset = 0, overlay_text = None, scale_min = FLT_MAX, scale_max = FLT_MAX, graph_size = Vec2(0,0))</code> || draw a bar histogram from a Python list of floats || <code>mxw_imgui.plot_histogram("Levels", history)</code>
|}

=== Value() helpers ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.value(prefix, b)</code> OR <code>mxw_imgui.value(prefix, v)</code> (int/uint) OR <code>mxw_imgui.value(prefix, v, float_format = None)</code> || draw a "prefix: value" line for a bool/int/float, without building the string yourself || <code>mxw_imgui.value("FPS", mxw.fps)</code>
|}

=== Menus ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_menu_bar()</code> / <code>mxw_imgui.end_menu_bar()</code> || start/end a menu bar inside the current window || <code>if mxw_imgui.begin_menu_bar(): mxw_imgui.end_menu_bar()</code>
|-
|<code>mxw_imgui.begin_main_menu_bar()</code> / <code>mxw_imgui.end_main_menu_bar()</code> || start/end the application's main (top-level) menu bar || <code>if mxw_imgui.begin_main_menu_bar(): mxw_imgui.end_main_menu_bar()</code>
|-
|<code>mxw_imgui.begin_menu(label, enabled = true)</code> / <code>mxw_imgui.end_menu()</code> || start/end a (sub)menu; call <code>end_menu()</code> only if <code>begin_menu()</code> returned <code>true</code> || <code>if mxw_imgui.begin_menu("File"): mxw_imgui.end_menu()</code>
|-
|<code>mxw_imgui.menu_item(label, shortcut = None, selected = false, enabled = true)</code> OR <code>mxw_imgui.menu_item(label, shortcut, p_selected, enabled = true)</code> || a clickable (optionally checkable) menu entry || <code>if mxw_imgui.menu_item("Save", "Ctrl+S"): save()</code>
|}

=== Tooltips ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_tooltip()</code> / <code>mxw_imgui.end_tooltip()</code> || build a custom tooltip (any widgets) between these two calls || <code>mxw_imgui.begin_tooltip(); mxw_imgui.text("info"); mxw_imgui.end_tooltip()</code>
|-
|<code>mxw_imgui.set_tooltip(fmt)</code> || a quick one-line tooltip for the last hovered item || <code>if mxw_imgui.is_item_hovered(): mxw_imgui.set_tooltip("Explain this")</code>
|}

=== Popups & modals ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.open_popup(str_id, flags = 0)</code> || flag a popup to open (by ID) on the next matching <code>begin_popup()</code> || <code>mxw_imgui.open_popup("confirm_delete")</code>
|-
|<code>mxw_imgui.begin_popup(str_id, flags = 0)</code> / <code>mxw_imgui.end_popup()</code> || build a plain popup's content; call <code>end_popup()</code> only if <code>begin_popup()</code> returned <code>true</code> || <code>if mxw_imgui.begin_popup("menu"): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_modal(name, p_open = None, flags = 0)</code> || build a modal popup's content (blocks interaction with the rest of the UI) || <code>opened, _ = mxw_imgui.begin_popup_modal("Confirm")</code>
|-
|<code>mxw_imgui.open_popup_on_item_click(str_id = None, popup_flags = 1)</code> || open a popup when the last item is clicked (e.g. right-click context menu) || <code>mxw_imgui.open_popup_on_item_click("ctx")</code>
|-
|<code>mxw_imgui.close_current_popup()</code> || close the popup currently being drawn (e.g. after a button inside it) || <code>if mxw_imgui.button("OK"): mxw_imgui.close_current_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_item(str_id = None, popup_flags = 1)</code> || combined open+begin for a right-click context popup on the last item || <code>if mxw_imgui.begin_popup_context_item(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_window(str_id = None, popup_flags = 1)</code> || same, anchored to the current window instead of the last item || <code>if mxw_imgui.begin_popup_context_window(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_void(str_id = None, popup_flags = 1)</code> || same, opens on right-click on empty space (no window/item under cursor) || <code>if mxw_imgui.begin_popup_context_void(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.is_popup_open(str_id, flags = 0)</code> || returns whether the given popup is currently open || <code>open = mxw_imgui.is_popup_open("menu")</code>
|}

=== Tables ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_table(str_id, column, flags = 0, outer_size = Vec2(0,0), inner_width = 0.0)</code> / <code>mxw_imgui.end_table()</code> || start/end a table; call <code>end_table()</code> only if <code>begin_table()</code> returned <code>true</code> || <code>if mxw_imgui.begin_table("grid", 3): mxw_imgui.end_table()</code>
|-
|<code>mxw_imgui.table_next_row(row_flags = 0, min_row_height = 0.0)</code> || start the next table row || <code>mxw_imgui.table_next_row()</code>
|-
|<code>mxw_imgui.table_next_column()</code> || advance to the next cell (wraps to the next row automatically) || <code>mxw_imgui.table_next_column()</code>
|-
|<code>mxw_imgui.table_set_column_index(column_n)</code> || jump directly to a given column in the current row || <code>mxw_imgui.table_set_column_index(1)</code>
|-
|<code>mxw_imgui.table_setup_column(label, flags = 0, init_width_or_weight = 0.0, user_id = 0)</code> || declare a column's header label / sizing before the first row || <code>mxw_imgui.table_setup_column("Name")</code>
|-
|<code>mxw_imgui.table_setup_scroll_freeze(cols, rows)</code> || freeze N leading columns/rows while the rest scrolls || <code>mxw_imgui.table_setup_scroll_freeze(0, 1)</code>
|-
|<code>mxw_imgui.table_headers_row()</code> || draw the header row from the declared <code>table_setup_column()</code> labels || <code>mxw_imgui.table_headers_row()</code>
|-
|<code>mxw_imgui.table_header(label)</code> || draw a single header cell manually (instead of <code>table_headers_row()</code>) || <code>mxw_imgui.table_header("Name")</code>
|-
|<code>mxw_imgui.table_get_sort_specs()</code> || returns the current column sort specification, if the table is sortable || <code>specs = mxw_imgui.table_get_sort_specs()</code>
|-
|<code>mxw_imgui.table_get_column_count()</code> || returns the number of columns of the current table || <code>n = mxw_imgui.table_get_column_count()</code>
|-
|<code>mxw_imgui.table_get_column_index()</code> || returns the current column index || <code>i = mxw_imgui.table_get_column_index()</code>
|-
|<code>mxw_imgui.table_get_row_index()</code> || returns the current row index || <code>i = mxw_imgui.table_get_row_index()</code>
|-
|<code>mxw_imgui.table_get_column_name(column_n = -1)</code> || returns a column's declared label (-1 = current column) || <code>name = mxw_imgui.table_get_column_name(0)</code>
|-
|<code>mxw_imgui.table_get_column_flags(column_n = -1)</code> || returns a column's current flags (e.g. is it hidden/sorted) || <code>flags = mxw_imgui.table_get_column_flags()</code>
|-
|<code>mxw_imgui.table_set_bg_color(target, color, column_n = -1)</code> || set the background color of a cell/row/column || <code>mxw_imgui.table_set_bg_color(0, mxw_imgui.color_convert_float4_to_u32(mxw_imgui.Vec4(1,0,0,1)))</code>
|}

=== Legacy columns ===
Superseded by [[#Tables|Tables]] above, kept for compatibility.

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.columns(count = 1, id = None, border = true)</code> || switch the rest of the window into a simple N-column layout (<code>count = 1</code> ends it) || <code>mxw_imgui.columns(2)</code>
|-
|<code>mxw_imgui.next_column()</code> || move to the next column (wraps to the next row) || <code>mxw_imgui.next_column()</code>
|-
|<code>mxw_imgui.get_column_index()</code> || returns the current column index || <code>i = mxw_imgui.get_column_index()</code>
|-
|<code>mxw_imgui.get_column_width(column_index = -1)</code> / <code>mxw_imgui.set_column_width(column_index, width)</code> || get/set a column's width || <code>w = mxw_imgui.get_column_width()</code>
|-
|<code>mxw_imgui.get_column_offset(column_index = -1)</code> / <code>mxw_imgui.set_column_offset(column_index, offset_x)</code> || get/set a column's X offset || <code>x = mxw_imgui.get_column_offset()</code>
|-
|<code>mxw_imgui.get_columns_count()</code> || returns the current column count || <code>n = mxw_imgui.get_columns_count()</code>
|}

=== Tabs ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_tab_bar(str_id, flags = 0)</code> / <code>mxw_imgui.end_tab_bar()</code> || start/end a tab bar; call <code>end_tab_bar()</code> only if <code>begin_tab_bar()</code> returned <code>true</code> || <code>if mxw_imgui.begin_tab_bar("tabs"): mxw_imgui.end_tab_bar()</code>
|-
|<code>mxw_imgui.begin_tab_item(label, p_open = None, flags = 0)</code> / <code>mxw_imgui.end_tab_item()</code> || start/end one tab's content; call <code>end_tab_item()</code> only if <code>begin_tab_item()</code> returned <code>true</code> || <code>opened, _ = mxw_imgui.begin_tab_item("Settings")</code>
|-
|<code>mxw_imgui.tab_item_button(label, flags = 0)</code> || a button drawn as a tab (e.g. a "+" to add a tab) || <code>if mxw_imgui.tab_item_button("+"): add_tab()</code>
|-
|<code>mxw_imgui.set_tab_item_closed(tab_or_docked_window_label)</code> || programmatically close a tab by label || <code>mxw_imgui.set_tab_item_closed("Old Tab")</code>
|}

=== Logging / capture ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.log_to_tty(auto_open_depth = -1)</code> || start capturing following widgets' text output to the app's TTY/console || <code>mxw_imgui.log_to_tty()</code>
|-
|<code>mxw_imgui.log_to_file(auto_open_depth = -1, filename = None)</code> || start capturing to a file || <code>mxw_imgui.log_to_file(-1, "log.txt")</code>
|-
|<code>mxw_imgui.log_to_clipboard(auto_open_depth = -1)</code> || start capturing to the OS clipboard || <code>mxw_imgui.log_to_clipboard()</code>
|-
|<code>mxw_imgui.log_finish()</code> || stop the current capture || <code>mxw_imgui.log_finish()</code>
|-
|<code>mxw_imgui.log_buttons()</code> || draw the standard "Log/Copy to clipboard" buttons || <code>mxw_imgui.log_buttons()</code>
|-
|<code>mxw_imgui.log_text(fmt)</code> || add text directly to the active log capture, without drawing a widget || <code>mxw_imgui.log_text("captured line")</code>
|}

=== Drag and drop ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_drag_drop_source(flags = 0)</code> / <code>mxw_imgui.end_drag_drop_source()</code> || make the last item a drag source; build the payload/preview between these two calls || <code>if mxw_imgui.begin_drag_drop_source(): mxw_imgui.end_drag_drop_source()</code>
|-
|<code>mxw_imgui.set_drag_drop_payload(type, data, sz, cond = 0)</code> || attach a payload to the drag currently being sourced || <code>mxw_imgui.set_drag_drop_payload("CLIP", data, len(data))</code>
|-
|<code>mxw_imgui.begin_drag_drop_target()</code> / <code>mxw_imgui.end_drag_drop_target()</code> || make the last item/window a drop target; check <code>accept_drag_drop_payload()</code> between these two calls || <code>if mxw_imgui.begin_drag_drop_target(): mxw_imgui.end_drag_drop_target()</code>
|-
|<code>mxw_imgui.accept_drag_drop_payload(type, flags = 0)</code> || accept a payload of the given type while inside a drop target || <code>p = mxw_imgui.accept_drag_drop_payload("CLIP")</code>
|-
|<code>mxw_imgui.get_drag_drop_payload()</code> || peek the payload of the drag currently in progress, even outside a target || <code>p = mxw_imgui.get_drag_drop_payload()</code>
|}

=== Clipping ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_clip_rect(clip_rect_min, clip_rect_max, intersect_with_current_clip_rect)</code> || push a manual clipping rectangle (<code>Vec2</code> corners) for subsequent drawing || <code>mxw_imgui.push_clip_rect(p_min, p_max, true)</code>
|-
|<code>mxw_imgui.pop_clip_rect()</code> || pop the pushed clip rect || <code>mxw_imgui.pop_clip_rect()</code>
|}

=== Focus & activation ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.set_item_default_focus()</code> || make the last item the one focused by default when the panel first appears || <code>mxw_imgui.set_item_default_focus()</code>
|-
|<code>mxw_imgui.set_keyboard_focus_here(offset = 0)</code> || focus the next widget for keyboard input (e.g. auto-focus a text field) || <code>mxw_imgui.set_keyboard_focus_here()</code>
|}

=== Item / widgets utilities ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.is_item_hovered(flags = 0)</code> || returns whether the last item is hovered by the mouse || <code>if mxw_imgui.is_item_hovered(): mxw_imgui.set_tooltip("info")</code>
|-
|<code>mxw_imgui.is_item_active()</code> || returns whether the last item is currently active (e.g. being held/edited) || <code>active = mxw_imgui.is_item_active()</code>
|-
|<code>mxw_imgui.is_item_focused()</code> || returns whether the last item has keyboard focus || <code>focused = mxw_imgui.is_item_focused()</code>
|-
|<code>mxw_imgui.is_item_clicked(mouse_button = 0)</code> || returns whether the last item was clicked this frame || <code>if mxw_imgui.is_item_clicked(): pass</code>
|-
|<code>mxw_imgui.is_item_visible()</code> || returns whether the last item is visible (not clipped) || <code>visible = mxw_imgui.is_item_visible()</code>
|-
|<code>mxw_imgui.is_item_edited()</code> || returns whether the last item's value changed this frame || <code>edited = mxw_imgui.is_item_edited()</code>
|-
|<code>mxw_imgui.is_item_activated()</code> || returns whether the last item just became active this frame || <code>started = mxw_imgui.is_item_activated()</code>
|-
|<code>mxw_imgui.is_item_deactivated()</code> || returns whether the last item just stopped being active this frame || <code>stopped = mxw_imgui.is_item_deactivated()</code>
|-
|<code>mxw_imgui.is_item_deactivated_after_edit()</code> || returns whether the last item stopped being active after its value changed (e.g. commit-on-release) || <code>if mxw_imgui.is_item_deactivated_after_edit(): save()</code>
|-
|<code>mxw_imgui.is_item_toggled_open()</code> || returns whether the last tree node/collapsing header was just opened or closed || <code>toggled = mxw_imgui.is_item_toggled_open()</code>
|-
|<code>mxw_imgui.is_any_item_hovered()</code> / <code>mxw_imgui.is_any_item_active()</code> / <code>mxw_imgui.is_any_item_focused()</code> || returns whether any item at all is hovered/active/focused || <code>busy = mxw_imgui.is_any_item_active()</code>
|-
|<code>mxw_imgui.get_item_rect_min()</code> / <code>mxw_imgui.get_item_rect_max()</code> / <code>mxw_imgui.get_item_rect_size()</code> || returns the last item's bounding rectangle (screen-space corners, or size) || <code>size = mxw_imgui.get_item_rect_size()</code>
|-
|<code>mxw_imgui.set_item_allow_overlap()</code> || allow the next widget to visually overlap the last item without stealing its hover/click || <code>mxw_imgui.set_item_allow_overlap()</code>
|}

=== Viewport & miscellaneous ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_main_viewport()</code> || returns the main viewport object (position/size of the whole application) || <code>vp = mxw_imgui.get_main_viewport()</code>
|-
|<code>mxw_imgui.is_rect_visible(size)</code> OR <code>mxw_imgui.is_rect_visible(rect_min, rect_max)</code> || returns whether a rectangle at the cursor (or explicit corners) is visible/unclipped || <code>visible = mxw_imgui.is_rect_visible(mxw_imgui.Vec2(50,50))</code>
|-
|<code>mxw_imgui.get_time()</code> || returns Dear ImGui's internal time in seconds (accumulates while the app runs) || <code>t = mxw_imgui.get_time()</code>
|-
|<code>mxw_imgui.get_frame_count()</code> || returns the number of ImGui frames rendered so far || <code>n = mxw_imgui.get_frame_count()</code>
|-
|<code>mxw_imgui.get_background_draw_list()</code> / <code>mxw_imgui.get_foreground_draw_list()</code> || returns the draw list rendered behind/in front of all windows, for custom drawing || <code>dl = mxw_imgui.get_foreground_draw_list()</code>
|-
|<code>mxw_imgui.get_draw_list_shared_data()</code> || returns data shared across draw lists (font atlas, clip rect stack, ...), rarely needed from Python || <code>d = mxw_imgui.get_draw_list_shared_data()</code>
|-
|<code>mxw_imgui.set_state_storage(storage)</code> / <code>mxw_imgui.get_state_storage()</code> || set/get the key-value storage backing tree/collapsing-header open states || <code>s = mxw_imgui.get_state_storage()</code>
|-
|<code>mxw_imgui.begin_child_frame(id, size, flags = 0)</code> / <code>mxw_imgui.end_child_frame()</code> || a framed, scrollable child region (styled like a text/list box) || <code>if mxw_imgui.begin_child_frame(1, mxw_imgui.Vec2(0,100)): mxw_imgui.end_child_frame()</code>
|-
|<code>mxw_imgui.calc_text_size(text, text_end = None, hide_text_after_double_hash = false, wrap_width = -1.0)</code> || returns the pixel size a string would occupy with the current font || <code>w = mxw_imgui.calc_text_size("0").x</code>
|}

=== Color utilities ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.color_convert_u32_to_float4(in)</code> || convert a packed <code>u32</code> color to a <code>Vec4</code> || <code>col = mxw_imgui.color_convert_u32_to_float4(0xFFFFFFFF)</code>
|-
|<code>mxw_imgui.color_convert_float4_to_u32(in)</code> || convert a <code>Vec4</code> color to a packed <code>u32</code> || <code>u = mxw_imgui.color_convert_float4_to_u32(mxw_imgui.Vec4(1,1,1,1))</code>
|-
|<code>mxw_imgui.color_convert_rg_bto_hsv(r, g, b)</code> || returns <code>(h, s, v)</code> for the given RGB floats (0.0..1.0) || <code>h, s, v = mxw_imgui.color_convert_rg_bto_hsv(1.0, 0.0, 0.0)</code>
|-
|<code>mxw_imgui.color_convert_hs_vto_rgb(h, s, v)</code> || returns <code>(r, g, b)</code> for the given HSV floats (0.0..1.0) || <code>r, g, b = mxw_imgui.color_convert_hs_vto_rgb(0.0, 1.0, 1.0)</code>
|}

=== Keyboard input ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_key_index(imgui_key)</code> || map a Dear ImGui <code>ImGuiKey_*</code> value to the user's backend key index || <code>idx = mxw_imgui.get_key_index(0)</code>
|-
|<code>mxw_imgui.is_key_down(user_key_index)</code> || returns whether a key is currently held down || <code>held = mxw_imgui.is_key_down(idx)</code>
|-
|<code>mxw_imgui.is_key_pressed(user_key_index, repeat = true)</code> || returns whether a key was just pressed (optionally auto-repeating while held) || <code>if mxw_imgui.is_key_pressed(idx): pass</code>
|-
|<code>mxw_imgui.is_key_released(user_key_index)</code> || returns whether a key was just released || <code>if mxw_imgui.is_key_released(idx): pass</code>
|-
|<code>mxw_imgui.get_key_pressed_amount(key_index, repeat_delay, rate)</code> || returns how many times a key auto-repeated this frame, given a delay/rate || <code>n = mxw_imgui.get_key_pressed_amount(idx, 0.3, 0.1)</code>
|}

=== Mouse input ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.is_mouse_down(button)</code> || returns whether a mouse button is currently held (0=left,1=right,2=middle) || <code>held = mxw_imgui.is_mouse_down(0)</code>
|-
|<code>mxw_imgui.is_mouse_clicked(button, repeat = false)</code> || returns whether a mouse button was just clicked || <code>if mxw_imgui.is_mouse_clicked(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_released(button)</code> || returns whether a mouse button was just released || <code>if mxw_imgui.is_mouse_released(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_double_clicked(button)</code> || returns whether a mouse button was just double-clicked || <code>if mxw_imgui.is_mouse_double_clicked(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_hovering_rect(r_min, r_max, clip = true)</code> || returns whether the mouse is over the given screen-space rectangle || <code>over = mxw_imgui.is_mouse_hovering_rect(p_min, p_max)</code>
|-
|<code>mxw_imgui.is_mouse_pos_valid(mouse_pos = None)</code> || returns whether the (current or given) mouse position is valid (app has focus etc.) || <code>valid = mxw_imgui.is_mouse_pos_valid()</code>
|-
|<code>mxw_imgui.is_any_mouse_down()</code> || returns whether any mouse button is currently held || <code>held = mxw_imgui.is_any_mouse_down()</code>
|-
|<code>mxw_imgui.get_mouse_pos()</code> || returns the current mouse position (<code>Vec2</code>, screen-space) || <code>p = mxw_imgui.get_mouse_pos()</code>
|-
|<code>mxw_imgui.get_mouse_pos_on_opening_current_popup()</code> || returns the mouse position captured when the current popup was opened || <code>p = mxw_imgui.get_mouse_pos_on_opening_current_popup()</code>
|-
|<code>mxw_imgui.is_mouse_dragging(button, lock_threshold = -1.0)</code> || returns whether the mouse is dragging with the given button held || <code>dragging = mxw_imgui.is_mouse_dragging(0)</code>
|-
|<code>mxw_imgui.get_mouse_drag_delta(button = 0, lock_threshold = -1.0)</code> || returns the drag distance (<code>Vec2</code>) since the drag started || <code>d = mxw_imgui.get_mouse_drag_delta()</code>
|-
|<code>mxw_imgui.reset_mouse_drag_delta(button = 0)</code> || reset the tracked drag distance for a button || <code>mxw_imgui.reset_mouse_drag_delta()</code>
|-
|<code>mxw_imgui.get_mouse_cursor()</code> / <code>mxw_imgui.set_mouse_cursor(cursor_type)</code> || get/set the desired OS mouse cursor shape || <code>mxw_imgui.set_mouse_cursor(1)</code>
|}

=== Clipboard ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_clipboard_text()</code> || returns the current OS clipboard text || <code>txt = mxw_imgui.get_clipboard_text()</code>
|-
|<code>mxw_imgui.set_clipboard_text(text)</code> || set the OS clipboard text || <code>mxw_imgui.set_clipboard_text("copied value")</code>
|}

=== Disabled blocks & MXWendler extras ===
The last two functions are MXWendler additions, not part of stock Dear ImGui bindings.

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_disabled(disabled = false)</code> / <code>mxw_imgui.end_disabled()</code> || grey out and block interaction with all widgets in between || <code>mxw_imgui.begin_disabled(not enabled); mxw_imgui.button("Go"); mxw_imgui.end_disabled()</code>
|-
|<code>mxw_imgui.render_frame(p_min, p_max, colf, border = true, rounding = 0.0)</code> || draw a filled/bordered rectangle (screen-space corners as <code>Vec2</code>, color as <code>Vec4</code>) directly, e.g. for custom backgrounds || <code>mxw_imgui.render_frame(mxw_imgui.Vec2(0,0), mxw_imgui.Vec2(100,20), mxw_imgui.Vec4(0.2,0.2,0.2,1))</code>
|}
[[Category:Python]]
[[Category:Reference]]

Tutorial Eventmaster Toolset Controlling MXWendler by e.g. e2 S3 Image Processor

2026-08-08T15:41:17Z

Admin: Update link after renaming to 'OSC command reference' (bot)

This tutorial applies to all different OS and MXWendler versions > 6.0.04

== Introduction==
This tutorial explains how to set up a Barco Eventmaster to trigger and control media playback on StageDesigner or FXServer.

==Control Setup==

1. Open SD (StageDesigner) and load a clip into preload 1:

[[File:e2_01.png|600px]]

2. Open Settings->IO->Barco e2 and activate TCP listening. Also note down the port number.

[[File:e2_02.png|600px]]

3. In the Barco Eventmaster Toolset, create an 'External Device', name it e.g. 'StageDesigner'.

[[File:e2_03.png|600px]]

4. In the 'Adjust: StageDesigner' tab, set IP address and port number.

[[File:e2_04.png|600px]]

5. In the 'Adjust: StageDesigner' tab, add a new command. Store the command content, e.g.
* /mxw/preload/1 play to start a clip
* /mxw/preload/1 play to stop a clip

More possible commands are in the OSC control section: [[OSC command reference]]

[[File:e2_05.png|600px]]

6. In the 'Cue' section, add a cue.

[[File:e2_06.png|600px]]

7. In this 'Cue', add actions.

[[File:e2_07.png|600px]]

8. From 'External Devices' drop an available command onto the 'Commands' field of the action.

[[File:e2_08c.png|600px]]

9. Play this cue, a clip should be started in the StageDesigner

OSC Reference

2026-08-08T15:40:47Z

Admin: Update link after renaming to 'OSC command reference' (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 0px 10px 0px" | [[4. Practical examples: Pure Data and TouchOSC]]
|-
| style="padding: 0px 30px" | ''4.1 Install Pure Data''
|-
| style="padding: 0px 30px" | ''4.2 MXW Pd Patch''
|-
| style="padding: 0px 30px 0px" | ''4.3 OSC for portable Devices: TouchOSC and Protokol''
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|-
| style="padding: 10px" | [[6. External links]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC command reference

2026-08-08T15:40:46Z

Admin: Admin moved page MXW OSC command reference to OSC command reference: Rename: omit 'MXW' prefix

Here are listed all the commands that MXW recognizes.

=== Legend ===
<div>
==== Variables ====
When variables are found in the address of a command ( and not only as the value to be sent), the <code>$+index</code> notation has been employed :

<code>/mxw/track/$1 [value] </code> indicates that a variable <code>$1</code> has to be chosen and will specify the correct address where the value will be sent.<br>If the goal is, for example, to reduce of 50% the opacity of the 2nd track, the correct command would be:

<code>/mxw/track/2 0.5 </code>

==== Values ====
The standard used to represent the available values for each command (column “RANGE or TOKEN”) is:

''FLOATS'' are represented with one decimal:

<code>0.0 .. 1.0</code> → all float values between 0 and 1 included

''INTEGERS'' are represented with numbers or descriptions:

<code>1 .. 5</code> → all integers between 1 and 5 included ( 1 , 2 , 3 , 4 , 5 ) <br>
<code>1 .. (MAX n layers)</code> → all the integers between 1 and the maximum index of layers in MXW (e.g. if 6 layers are being used the values are integers between 1 and 6 included)

When only one number is indicated it means that only one option is given. This is found in addresses of buttons, checkboxes and in the options where "0" or "1" are the only significant values

''STRINGS'' are represented between quotation marks:

<code>“info”</code> means that the string info has to be used at the end of the command

E.G. to ask for information about the patches the command

<code>/mxw/set info </code>

would be sent.

When <code>“name”</code> is contained in the available string variable, then the content is to be substituted with the actual name.

E.G. : to select and play a patch called “patch_one” from its name, the address <code>/mxw/set</code> with tokens <code>"play" "name_of_patch"</code> has to be used, resulting in this OSC command:

<code>/mxw/set play patch_one</code>

When <u>OR</u> is found it means that two options can deliver a similar result. One of the two formats has to be used at one time.

===Set Reference===

{| class="wikitable"
|-
! OSC ADDRESS !! DESCRIPTION !! RANGE or TOKEN
|-
|<code> /mxw/set</code>||get information on the patches|| <code>“info”</code>
|-
| <code>/mxw/set</code>||play a specific patch|| <code>“play” “name_of_patch”</code>
|-
| <code>/mxw/set</code>||choose a patch|| <code>1 .. (MAX n patches)</code>
|-
| <code>/mxw/editor</code>||choose UI tab|| <code>0 .. 5</code>
|-
| <code>/mxw/trackmanager</code>||choose active track || <code>0.0 .. 1.0</code> <u>OR</u> <code>1 .. 4</code>
|-
| <code>/mxw/trackmanager</code>||clear all tracks || <code>"clear"</code>
|-
| <code>/mxw/layermanager</code> ||choose active layer || <code>1 .. (MAX n layers)</code>
|-
| <code>/mxw/layermanager</code>||clear layers in active track|| <code>"clear"</code>
|-
| <code>/mxw/beatbutton</code> || Send pulse to beat-button (BPM)|| <code>1</code>
|-
| <code>/mxw/playlist info</code> || return information on the state of the playback of playlist|| <code>"info"</code>
|-
| <code>/mxw/playlist select</code> || jump to cue by name || <code>"select" "cuename"</code>
|-
| <code>/mxw/playlist/gotostart</code> || stop and go to first track on list<ref>The functionality of ''gotostart'' is the same as the ''gotostart'' button in the MXW playlist GUI ( ❙❙◀ ), so the command has to be sent two times to reset the playlist at the original state.</ref>|| <code>0</code>
|-
| <code>/mxw/playlist/gotoprev</code> || go to previous cue|| <code>0</code>
|-
| <code>/mxw/playlist/play</code> || play active item|| <code>0</code>
|-
| <code>/mxw/playlist/pause</code> || pause active playing clip|| <code>0</code>
|-
| <code>/mxw/playlist/gotonext</code> || go to next cue|| <code>0</code>
|-
| <code>/mxw/playlist/gotocueandplay</code> || go to a specific cue and immediately play|| <code>0..n (MAX n rows)</code>
|-
| <code>/mxw/playlist/gotocue</code> || go to a specific cue|| <code>0..n (MAX n rows)</code>
|-
| <code>/mxw/playlist/container/active</code> || info about the total playlist container|| <code>"info"</code>
|-
| <code>/mxw/playlist/container/active/column/$1/row/$2</code> || info about the selected field in the playlist grid|| $1 → <code>0 .. (MAX n columns)</code><br>$2 → <code>1 .. (MAX n rows)</code><br><code>"info"</code>
|-
| <code>/mxw/set/first</code> || go to first patch on the list|| <code>0</code>
|-
| <code>/mxw/set/prev</code> || select the previous patch || <code>0</code>
|-
| <code>/mxw/set/play</code> || play selected patch <ref>The button play in the patch tab works like the play button in the MXW playlist GUI, every click will play the following patch.</ref>|| <code>0</code>
|-
| <code>/mxw/set/next</code>|| select to next patch|| <code>0</code>
|-
| <code>/mxw/set</code>|| clear all patches || <code>"clear"</code>
|-
| <code>/mxw/render</code>|| change of render opacity|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/opacity</code>|| change of render opacity|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/scale</code>|| change of render scale|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/scalexy</code>|| change of render scale ratio|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/translationx</code>|| change of render position x|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/translationy</code>|| change of render position y|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/rotation</code>|| change of render rotation|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/reset</code>|| reset render changes|| <code>0</code>
|-
| <code>/mxw/render/effect</code>|| selects wished render fx|| <code>1 .. (MAX n fx)
</code>
|-
| <code>/mxw/render/effect/1/param/$1 </code>|| modifies value of one parameter($1) of the render fx|| $1→ <code>1 .. (MAX n parameters)</code><br>
VALUE → <code>0.0 .. 1.0</code>
|-
| <code>/mxw/track/$1</code>|| set opacity value of a specific track ($1)|| $1 → <code>1 .. 4</code>
VALUE → <code>0.0 .. 1.0</code>
|-
| <code>/mxw/track/active</code>|| change opacity of active track moving the fader|| <code>0.0 .. 1.0
</code>
|-
| <code>/mxw/track/active/fader</code>|| change opacity of active track moving the fader|| <code>0.0 .. 1.0
</code>
|-
| <code>/mxw/track/active/crossfader</code>|| activates the crossfading between tracks|| <code>0.0 (OFF) <u>OR</u> 1.0 (ON)</code>
|-
| <code>/mxw/track/active/mode</code>|| changes the mode of fading|| <code>1 .. 8</code>
|-
| <code>/mxw/preload/$1/trigger</code>|| trigger preload $1 content to current track|| $1 → <code>1 .. (MAX n preloads)</code>
VALUE → <code>0</code>
|-
| <code>/mxw/preload/$1/flipflop</code>|| flipflop preload $1 content to current track|| $1 → <code>1 .. (MAX n preloads)</code>
VALUE → <code>0</code>
|-
| <code>/mxw/track/active/layer/active/clip/play</code> || toggles play-pause button of live editor || <code>0</code>
|-
| <code>/mxw/track/active/layer/active/scale</code> || change of layer scale || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/scalexy</code> || change of layer scale ratio || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/translationx</code> || change of layer position x || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/translationy</code> || change of layer position y || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/rotation</code> || change of layer rotation || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/mode</code> || change of layer blend mode || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/aspectmode</code> || change of layer aspect mode || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/reset</code> || reset layer changes || <code>0</code>
|-
| <code>/mxw/track/active/layer/active/clip/keyin</code> || set keyin of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/keyout</code> || set keyout of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/speed</code> || set speed of clip of active layer <ref> The values are sent to the "speed fader", which values go between 5 and -5, they do not act directly on the "speed value". This means that depending on the active media the available values in the fader will differ. </ref> || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/position</code> || set position of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/mode</code> || set mode of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect</code> || choose active effect || <code>0 .. (MAX n of fx)</code>
|-
| <code>/mxw/track/active/layer/active/clip/effectbank</code> || selects active effect || <code>0 .. (MAX n of fx)</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/active/param/$1</code> || set param $1 of effect || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/red</code> || set red component of color param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/green</code> || set green component param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/blue</code> || set blue component param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/hue</code> || set huecomponent param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/saturation</code> || set saturation | <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/value</code> || set value component param. || <code>0 .. 1</code>
|-
| <code>/mxw/keystone/element/$1/pivot/col/$2/row/$3/xposition</code> || move keystone pivot in x || $1 → <code>1 .. (MAX n elements)</code>
$2 (COLUMN) → <code>1 <u>OR</u> 2</code>
$3 (ROW) → <code>1 <u>OR</u> 2</code>
VALUE → <code>0 .. 1</code>
|-
| <code>/mxw/keystone/element/$1/pivot/col/$2/row/$3/yposition</code> || move keystone pivot in y|| $1 → <code>1 .. (MAX n elements)</code>
$2 (COLUMN) → <code>1 <u>OR</u> 2</code>
$3 (ROW) → <code>1 <u>OR</u> 2</code>
VALUE → <code>0 .. 1</code>
|-
| <code>/mxw/keystone_io_animator</code> || keystone io animator fader|| <code>0 .. 1</code>
|-
|}
[[Category:OSC]]
[[Category:Reference]]

Category:OSC

2026-08-08T15:36:03Z

Admin: Create category page (bot)

Pages documenting how to control MXWendler through the Open Sound Control (OSC) protocol.

The list below is generated automatically from pages tagged <code><nowiki>[[Category:OSC]]</nowiki></code>.

[[Category:Reference]]

OSC command reference

2026-08-08T15:36:00Z

Admin: Add Category:OSC at page end (bot)

OSC Reference

2026-08-08T15:35:58Z

Admin: Add Category:OSC at page end (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[MXW OSC command reference]]
|-
| style="padding: 0px 10px 0px" | [[4. Practical examples: Pure Data and TouchOSC]]
|-
| style="padding: 0px 30px" | ''4.1 Install Pure Data''
|-
| style="padding: 0px 30px" | ''4.2 MXW Pd Patch''
|-
| style="padding: 0px 30px 0px" | ''4.3 OSC for portable Devices: TouchOSC and Protokol''
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|-
| style="padding: 10px" | [[6. External links]]
|}
[[Category:OSC]]
[[Category:Reference]]