Control

Status API

GET /api/status is optional feedback. Commands only require synchronous validation and queue admission; callers do not need to read status or correlate it with a request.

The response is a fixed PlayerStatus object:

{
  "state": "playing",
  "source": "D:\\media\\main_loop.mp4",
  "cue_position_sec": 0.0,
  "position_sec": 12.45,
  "duration_sec": 60.0,
  "volume": 0.8,
  "muted": false,
  "loop": true,
  "error": null
}

All fields are always present. source, cue_position_sec, position_sec, duration_sec, and error use null when unavailable. error is populated only for state=error; decoder metadata, seekability, normalized progress, device identity, and timestamps remain internal or belong to other diagnostic APIs.

FieldTypeDescription
statestringidle, loading, ready, playing, paused, ended, or error.
sourcestring or nullCurrent media source.
cue_position_secnumber or nullCue point for the current media.
position_secnumber or nullCurrent playback position.
duration_secnumber or nullDuration when known.
volumenumber0.0–1.0.
mutedbooleanCurrent mute state.
loopbooleanCurrent media loop policy.
errorobject or nullNormalized asynchronous playback error.