Stage Recorder OSC Interface

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

Parameter	Default	Config key
Protocol	UDP	—
Listen address	ANY (0.0.0.0)	—
Listen port	7000	/System/IO/OSC/Receive Port

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

Address Space

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

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

<n> is a 1-based channel index.

Player Commands

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

Argument 1	Argument 2	Description
open	<filename:string>	Open a media file. Resets markers. The file is opened asynchronously and starts paused at position 0.
play	—	Resume playback (unpause). Requires an open file.
pause	—	Pause playback. Requires an open file.
stop	—	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.
seek	<milliseconds:int32>	Seek to an absolute position in milliseconds.
go_marker_back	—	Jump to the previous cue marker.
go_marker_forward	—	Jump to the next cue marker.
set_marker	—	Insert a cue marker at the current position.
status	—	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 (play, pause, stop, seek, go_marker_*, set_marker) are silently ignored when no file is loaded.
• open is asynchronous — commands sent immediately afterwards may run before the file is ready.
• Soft-stop is configured via /Playback/Use Softstop (default true).

Example bundle — open, seek to start, play:

#bundle
/mxr/channel/1/player  "open"  "/media/clip.mp4"
/mxr/channel/1/player  "seek"  0
/mxr/channel/1/player  "play"

Recorder Commands

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

Argument 1	Argument 2	Description
start	—	Begin recording with the channel's selected recording profile. Any active playback on the channel is stopped first.
stop	—	Stop the active recording. Writes cue markers into the file as metadata, then auto-loads the recorded clip into the player (paused at 0).
start_with_duration	<seconds:int32>	Start recording and schedule an automatic stop after the given number of seconds. Registers a task visible in the Schedule tab.
set_end_time	<unix_timestamp:int32>	Update the scheduled stop time of an active recording. Only effective while recording.
set_marker	—	Insert a cue marker at the current recording position. Only effective while recording.
status	—	Query the current recorder status. The reply is published over MQTT — see Stage Recorder MQTT Interface#Status Publishing (Outbound).

Notes:

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

Sync Control

Address: /mxr/sync_control

This endpoint has two independent forms.

Open a Sync-Set File

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

Opens a sync-set (.mxr_syncset). 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

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

Position	Type	Description
1..N	int32	Target channel indices (1-based). All leading integers form the channel set.
N+1	string	Receiver: "player" or "recorder"
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:

/mxr/sync_control  1  2  4  "recorder"  "start"

Example — seek all channels to 30 000 ms:

/mxr/sync_control  1  2  3  "player"  "seek"  30000

Scheduler

Address: /mxr/schedule

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

Position	Type	Description
1	string	Must be "taskadd_local"
2	int32	Unix epoch time at which the task fires
3	string	OSC address to send when the task fires (e.g. /mxr/channel/1/recorder)
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:

/mxr/schedule  "taskadd_local"  1711900800  "/mxr/channel/2/recorder"  "start"

Example — record for exactly 3600 seconds:

/mxr/schedule  "taskadd_local"  1711900800  "/mxr/channel/2/recorder"  "start_with_duration"  3600

Argument Types

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

OSC type tag	Type	Notes
s	string	UTF-8
i	int32	Most common numeric type
h	int64	Treated as int32 internally
f	float

Unrecognised types are logged and skipped.

Quick Reference

# 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  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]

Configuration Reference

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

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