How It Works

DearScenario Player plays the picture for a scenario on the display machine. The system that owns that scenario — middle-control, show-control software, a kiosk app, or a custom automation layer — decides what should happen. The player receives commands, executes local playback, and reports state back.

That boundary is the product: DearScenario Player is not a CMS and not a scheduler. It owns the local playback endpoint. Your system owns the cue logic, operator workflow, and multi-device coordination.

The Basic Model

In a typical installation, each screen or projection machine runs one DearScenario Player instance. The player opens its control ports, loads its startup configuration, initializes the playback engine, and waits for commands from the control network.

Middle-control system, show-control software, kiosk app, or script
        |
        | HTTP or OSC
        v
DearScenario Player on the display machine
        |
        | local video playback, audio, masks, overlays, state, logs
        v
Projector, LED processor, display, or audio chain

The controller can be anything that can speak one of the supported protocols: a web app, QLab, TouchDesigner, Bitfocus Companion, Node-RED, a PLC bridge, a Python script, or an in-house middle-control platform. DearScenario Player does not need the operator to sit at the playback machine with a keyboard and mouse.

Startup

On startup, DearScenario Player reads configuration from the configured sources, opens the playback window or output display, starts the local playback runtime, and brings up the network interfaces. By default, the HTTP control surface is on port 18290. OSC uses the same port over UDP when enable_osc is on. Remote Debug uses 18292 when enabled.

After startup, the player is ready to accept commands on network.listen_address. It shows the idle screen and exposes local tools such as the Web Console depending on the current configuration; playback begins only from an explicit launch target or control command.

Configuration defines the shape of the local endpoint: display selection, window behavior, network settings, maintenance access policies, media paths, masks, overlays, and other player-level behavior. The controller can then treat that endpoint as a stable device.

Commands

All control protocols share the same command idea. A request names a command and optionally supplies parameters:

{ "cmd": "play_media", "params": { "source": "C:\\media\\intro.mp4" } }

HTTP exposes POST /api/command with a JSON cmd + params body. OSC does not use that JSON envelope: it uses an OSC address, type tags, and positional arguments, such as /player/play. Both entrances map to the same internal command model and are useful when integrating with show-control and creative tools.

The important part is that these protocols are entrances to the same command model. A play command means the same kind of intent whether it comes from HTTP or OSC.

Common commands include loading media, starting playback, pausing, stopping, seeking, setting volume, toggling loop behavior, reading information, and managing on-screen elements. Exact request bodies, response envelopes, status codes, and generated examples live in the Command Reference.

Playback And Rendering

When a playback command is accepted, DearScenario Player changes local player state and lets the playback runtime do the media work on the display machine. Video decoding and rendering are local to the player. This keeps high-bandwidth media traffic off the control network and lets the controller send small intent-level messages instead of pushing frames.

The player can also apply local presentation features such as projection masks, calibration patterns, image overlays, OSD text, and an idle screen. These features are still part of the playback endpoint. They are useful when the display machine needs site-specific adjustment, but they do not change the integration boundary: your system still decides what should happen, and DearScenario Player executes it locally.

State Readback

A controllable player is only useful if the controller can tell what happened. DearScenario Player exposes state readback so your system can query the player, update operator UI, and recover from venue problems.

The usual pattern is:

1. Send an explicit command such as load, play, or seek.
2. Read the response to see whether the command was accepted.
3. Poll /api/status for live state changes.
4. Decide in your controller whether to continue, retry, alert an operator, or move to a fallback state.

HTTP polling exposes playback status, maintenance diagnostics, and runtime health through dedicated endpoints for remote control surfaces.

Web Console and debug panel

DearScenario Player includes a technician-facing Web Console and a separate engineering debug surface; neither one replaces your control system.

The Web Console is a browser-based tool served by the player. It is useful for local setup, node identity checks, simple absolute manual control, and troubleshooting when the playback machine is mounted somewhere awkward. In Normal mode it stays a small status/control surface; Maintenance adds calibration and engineering diagnostics.

The debug panel is an on-screen tool for site adjustment, testing, and integration. When launched with --maintenance, it exposes the full local engineering controls so you can try an action and copy the matching network command. In normal production mode these tools stay locked down so an unattended machine behaves like a stable playback endpoint rather than an editable workstation.

Failure And Recovery

Production installations should assume that displays, files, networks, and operators can all fail in boring ways. DearScenario Player provides health checks, status endpoints, logs, crash dumps, and watchdog guidance so the playback endpoint can be observed and recovered.

Your controller should not assume that sending a command is the end of the workflow. For important cues, read back state. For unattended deployments, configure a watchdog and keep logs available. This makes the player easier to treat as infrastructure rather than as a manual desktop app.

What This Page Does Not Cover

This page is a mental model, not the formal contract. Use the Command Reference for exact schemas, fields, errors, and examples. Use the deployment and reference pages for configuration, watchdog setup, platform notes, and production checklists.

Previous / Next

• Previous: Overview
• Next: Dev vs Production Mode