Window & Display

Fullscreen modes

Mode	Notes
Borderless (default)	Fills the screen without changing the display mode. Recommended for exhibition / kiosk use with `always_on_top`.
Exclusive	Changes the display mode. Prefer for performance-critical setups or Raspberry Pi KMS when you need a specific resolution. Refresh rate follows the display's current desktop mode.

Neither mode can block OS-level UI (Windows activation prompts, UAC, secure desktop, antivirus overlays, or other system notifications). Suppress those at the OS / kiosk layer.

{
  "window": {
    "fullscreen": {
      "enabled": true,
      "mode": "borderless"
    },
    "always_on_top": true
  }
}

Performance / KMS example:

{
  "window": {
    "fullscreen": {
      "enabled": true,
      "mode": "exclusive",
      "width": 1920,
      "height": 1080
    }
  }
}

Screen index

When multiple displays are connected, screen_index sets which output the player uses. Index 0 is the primary display.

{
  "window": {
    "screen_index": 2,
    "fullscreen": {
      "enabled": true,
      "mode": "borderless"
    }
  }
}

Index assignments can change when monitors are reconnected. Verify the mapping after any hardware change.

Always-on-top

{ "window": { "always_on_top": true } }

On non-exclusive fullscreen, DearScenario Player enables always_on_top so ordinary taskbars and app windows stay underneath. On Windows, if the window drifts off the target display bounds or loses topmost / fullscreen state, the player re-applies the configured layout (skipped while a native file dialog is open).

Multiple instances on one machine

Give each instance a different screen index and a different port.

dearscenario-player.exe --config config_screen0.json
dearscenario-player.exe --config config_screen1.json --base-port 18293

Troubleshooting

Wrong screen: re-check screen_index and display enumeration.
Black screen after power cycle: the projector likely lost EDID.
Overlapping instances: each config needs a unique screen_index.
System toast / activation balloon still appears: activate Windows and harden the host; player fullscreen cannot intercept that UI.
Playback Basics
Troubleshooting