Stage Recorder MQTT Interface

From MXWendler Wiki
Jump to navigation Jump to search

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

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

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

Topic Structure

Inbound (command) topics follow this pattern: 

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

<system-id> is matched by the + wildcard in the default subscribe pattern mxr/+/. 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:

MQTT topic pattern OSC address
mxr/<id>/channel/<rest> /mxr/channel/<rest>
mxr/<id>/sync_control /mxr/sync_control
mxr/<id>/schedule /mxr/schedule

Topics that match none of these patterns generate error IO004.

Payload Format

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

  1. parses as a long integer → stored as int32
  2. parses as a double → stored as float
  3. otherwise → stored as string

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

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

Topic Payload examples
mxr/<id>/channel/<n>/player open <filename> · seek <ms> · play · pause · stop · go_marker_back · go_marker_forward · set_marker · status
mxr/<id>/channel/<n>/recorder start · stop · start_with_duration <seconds> · set_end_time <unix> · set_marker · status
mxr/<id>/sync_control recorder <command> [args] · open <filepath>
mxr/<id>/schedule taskadd_local <unix> <osc_address> [args]

Examples: 

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/sync_control
Payload:  1 2 recorder start
-> OSC:   /mxr/sync_control  1  2  "recorder"  "start"

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. <system-id> comes from /System/IO/MQTT/System ID (default 1); <n> is the 1-based channel index; <filename> is the absolute path.

Recorder Status

Topic Payload When
mxr/<id>/channel/<n>/recorder/status started <filename> Recording begins
mxr/<id>/channel/<n>/recorder/status stopped <filename> Recording ends

Player Status

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

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

On-Demand Status Query

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

Query topic (inbound) Response topic (outbound) Response payload
mxr/<id>/channel/<n>/recorder mxr/<id>/channel/<n>/recorder/status started <file> or stopped <file>
mxr/<id>/channel/<n>/player mxr/<id>/channel/<n>/player/status player_started <file> or player_stopped <file>

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

Example — query and response: 

# 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

Error Codes

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

Limitations

  • JSON payloads are not implemented (error IO003).
  • The broker port is fixed at 1883.

See Also

Retrieved from "https://wiki.mxwendler.net/index.php?title=Stage_Recorder_MQTT_Interface&oldid=6108"