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.
set_speed	<speed:float>	Frame-based slow motion. 0.0 holds the current frame, 1.0 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 double or int32.
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. play, pause, seek and set_speed sent while the file is still opening (in a bundle, or without waiting for player_started) 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 /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.
start_preemptive	[seconds:int32]	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.
set_camera	<camera> [cell:int32]	Switch the camera feeding a running recording. See the notes below.
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.

Camera switching:

• set_camera 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.
• <camera> is an input pair index (1-based int32), an input pair name, or a capture device name. Names are matched case-insensitively, input pairs first.
• [cell] 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 R011.
• 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 camera <cell> <capture device> on the recorder status topic — see Stage Recorder MQTT Interface#Status Publishing (Outbound).

Example — switch channel 1 to the camera of input pair 2:

/mxr/channel/1/recorder  "set_camera"  2
/mxr/channel/1/recorder  "set_camera"  "Stage Wide"
/mxr/channel/1/recorder  "set_camera"  "Integrated Camera"  2

Preemptive recording:

• start_preemptive 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 R008 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 +n button stays disabled until then; over the network an early start_preemptive 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: /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
/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]

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
/System/IO/VNC/Use VNC	bool	false	Serve the user interface to VNC viewers on the LAN (restart required)
/System/IO/VNC/Port	long	5900	VNC port
/System/IO/VNC/Password	string	(empty)	Not enforced in this build (no VNC authentication without OpenSSL); a set value is logged as a warning
/System/IO/VNC/Frame Rate	long	10	Screen captures per second sent to viewers
/System/IO/VNC/Scale	long	100	Size of the picture sent to viewers, in percent (25–100, steps of 5)
/System/IO/VNC/Name	string	Tourette Stage Recorder	Name a viewer shows in its title bar
/System/IO/VNC/Web Port	long	5800	Browser viewer: http://<recorder>:<port>/. 0 switches it off
/System/Use 10 Bit Recording	bool	false	Run capture, compositing, encoding and textures at 10 bit (restart required)
/System/Use 10 Bit Display	bool	false	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.