How to Build an HTTP-Controlled Video Playback Node

Turn a DearScenario Player machine into a remotely controlled playback node with one stable HTTP command envelope.

What you will build

You will launch DearScenario Player, load and play a local video from another machine, and observe the player state. Every control action is submitted to POST /api/command.

Prerequisites

• A Windows PC (7/10/11) or Raspberry Pi 4B/5 running Raspberry Pi OS 64-bit Desktop
• A video file on the player machine
• Network access between the controller and player

Launch the player

Launch DearScenario Player and note the IP address shown on the screen. The default control port is 18290. Press F1 to open the debug overlay if needed.

Load and play video

PLAYER=http://192.168.1.100:18290/api/command

curl -X POST "$PLAYER" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"play_media","params":{"source":"C:\\media\\intro.mp4"}}'

curl -X POST "$PLAYER" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"play","params":{}}'

All control commands follow this shape:

{ "cmd": "command_name", "params": { } }

For example, seek with {"cmd":"seek","params":{"position_sec":30.0}} or set volume with {"cmd":"volume_set","params":{"volume":0.8}}.

Source rules

Use a path relative to the configured media_root (for example hall-a/opening.mp4) when the show should be portable across machines. The file must already exist and be readable. Windows and POSIX absolute paths are also supported and are checked for existence/readability without being sandboxed to media_root. Network sources may use http://, https://, or rtmp://; these are checked for URI structure only, so the actual open failure (if any) is reported asynchronously in the playback status. Credentials in a URL are not written to ordinary player logs.

Read state

curl http://192.168.1.100:18290/api/status
curl http://192.168.1.100:18290/api/health

/api/status returns the media source, seven-state playback state, position, duration, and volume. /api/health is the connectivity check. The player does not serve runtime /api/spec (removed). Browse the command catalog in the Command Reference.

Python example

import requests

endpoint = "http://192.168.1.100:18290/api/command"

def command(name, params=None):
    payload = {"cmd": name, "params": params or {}}
    response = requests.post(endpoint, json=payload, timeout=5)
    response.raise_for_status()
    return response.json()

command("play_media", {"source": r"C:\media\intro.mp4"})
command("play")