Minimal integration examples

This page is a copyable starting point for four common show-control consumers. It describes the stable playback surface only: load, play_media, play, pause, stop, cue, seek, volume_set, mute_set, and loop_set.

These are documentation examples, not hardware test evidence. QLab, Crestron, Companion, and Node-RED still need real-project validation during release acceptance.

QLab Network Cue (OSC)

Create an OSC destination in QLab using the DearScenario Player IP and UDP port 18290. Each Network Cue sends one message; no JSON response is read.

/player/play_media  "opening.mp4"  0.0  0
/player/stop
/player/prepare  "opening.mp4"  0.0  0
/player/play

The two media addresses accept either s (source) or sfi (source, cue seconds, loop integer). Other stable addresses are:

/player/pause
/player/cue
/player/seek_sec  30.0
/player/volume    0.8
/player/mute      1
/player/loop      0

OSC is fire-and-forget. It has no playback-status reply; optionally poll /api/status over HTTP for observation.

Crestron HTTP module

Send ordinary HTTP POST requests to /api/command:

POST http://<player-ip>:18290/api/command
Content-Type: application/json

{"cmd":"play_media","params":{"source":"opening.mp4"}}

Other examples:

{"cmd":"play","params":{}}
{"cmd":"seek","params":{"position_sec":30.0}}
{"cmd":"volume_set","params":{"volume":0.8}}
{"cmd":"mute_set","params":{"enabled":true}}
{"cmd":"loop_set","params":{"enabled":false}}

HTTP 200 {"ok":true} means synchronous validation succeeded and the command was queued. It does not mean the video has finished loading or is visible. A Crestron installation may use fire-and-forget and ignore the body. There is no need for request_id, expect, Job lookup, job_id, 202 Accepted, or Idempotency-Key. Optional feedback is a separate GET /api/status request.

Companion

Use the official DearScenario Player module with the player IP and port 18290. Its stable playback actions are Play, Pause, Stop, Cue, Load File, Seek to Position, Set Volume, Set Mute, and Set Loop. Toggle and relative convenience actions are implemented by the module; they are not additional server-side stable commands.

The module can optionally poll GET /api/status for button feedback and variables. Commands do not wait for a poll and the module does not expose Job, request ID, or other internal protocol concepts to the user.

Node-RED

Add diria-config for the player IP and port, then add diria-command with API surface: Stable playback. Use the stable command selector or provide a message override:

msg.cmd = "play_media";
msg.payload = { source: "opening.mp4", cue_position_sec: 0.0, loop: false };
return msg;

For optional feedback, connect diria-status, which reads GET /api/status. The command flow does not wait for that node. Extension and maintenance surfaces are intentionally not part of the stable playback baseline.

Validation boundary

The examples above have not been validated against real QLab or Crestron hardware, nor against a named production Companion or Node-RED project. Real transport checks, platform coverage, and the final v1 freeze belong to the fifth phase and on-site acceptance.