Control Network

DearScenario Player keeps the control-plane binding and the address shown to operators as two separate settings:

Setting	Purpose	Default
`network.listen_address`	Address used by HTTP, OSC/UDP, and Maintenance Remote Debug	`0.0.0.0`
`network.advertise_address`	Address shown in the idle-screen QR code and local status views	`auto`

The default listener covers all IPv4 interfaces. It does not make a network trusted: reachability is still determined by routing, VLANs, host firewalls, VPNs, and any optional controller_ip_whitelist.

Configure the listener

For the normal field deployment, keep the default:

{
  "network": {
    "listen_address": "0.0.0.0",
    "advertise_address": "auto"
  }
}

To limit the service to one interface, set listen_address to that interface's current IP address. DearScenario Player respects an explicit address and does not silently switch to another interface if it later disappears; it reports the bind failure so the operator can correct the configuration or restart the process.

advertise_address never controls binding or authorization. Set it explicitly on multi-NIC installations when automatic address selection would show the wrong QR code. Network changes refresh the automatic display address but do not rebind listeners or revoke Maintenance/Remote Debug state.

Optional source restriction

network.controller_ip_whitelist contains exact source IPs. An empty list adds no player-level source restriction. A non-empty list applies equally to HTTP, OSC, and Maintenance/Remote Debug. The list is additive to the network controls outside DearScenario Player; it is not a subnet detector or a replacement for a firewall.

Verify the control path

From a controller on the intended network:

Open http://<advertised-address>:<base-port>/ (default port 18290).
Confirm GET /api/health succeeds.
Check the local Status page for the actual listen_address and advertised address.
If a whitelist is configured, verify the controller's exact source IP is present.

Common failures

Symptom	Likely cause	What to do
Web Console is unreachable	Listener is loopback-only, the explicit address is gone, or a firewall blocks the port	Check `listen_address`, the health/status view, routing, and firewall rules
Controller gets `403`	Its source IP is not in the optional whitelist or the request is cross-origin	Correct the exact whitelist entry or use the native HTTP client path
QR code shows the wrong IP	Automatic display selection chose another interface	Set `advertise_address` explicitly; this does not change listener binding
Remote Debug is unavailable	Normal process, disabled feature, bind failure, or source/origin policy rejection	Start the Maintenance entry and inspect `/api/health` and logs

Security boundary

HTTP and OSC are plaintext local control protocols. DearScenario Player does not provide internet-grade authentication or encryption. Do not publish the ports through a router or cloud security group. For cross-site maintenance use a VPN, SSH tunnel, or a project security gateway with its own authentication and ACLs.

See Security and Production Guide.

Previous / Next

Previous: Production Guide
Next: Playback Recovery