Playback Watchdog

The optional watchdog monitors requested playback and applies staged recovery actions when the backend remains paused or stops advancing.

Detection#

The watchdog runs at checkIntervalSeconds intervals while a source is open and playback has been requested. It monitors two conditions:

Unexpected pause: the backend reports that it is paused even though the caller has not called Pause().
Playback stall: the presented-frame count does not change between checks. If the backend exposes no frame counter, the watchdog falls back to CurrentTime and can therefore detect only stalls in which the playhead also stops.

Default recovery sequence#

Condition	Stage ID	Action
Paused at a health check	—	Call `Play()` again.
Paused for 2 checks while unmuted on WebGL	`mute_dance`	Mute, call `Play()`, then restore the configured mute state after playback starts.
Paused for 9 checks, then every 30 additional checks	`reload_paused`	Reload the current source.
No frame progress for 3 checks	`kick`	Call `Pause()`, then `Play()`.
No frame progress for 6 checks	`seek_flush`	Seek to the current time, then call `Play()`.
No frame progress for 9 checks, then every 30 additional checks	`reload`	Reload the current source.

Each named stage invokes OnRecoveryAttempted. The initial repeated Play() call has no stage event.

void OnEnable()
{
    player.OnRecoveryAttempted.AddListener(ReportRecovery);
}

void OnDisable()
{
    player.OnRecoveryAttempted.RemoveListener(ReportRecovery);
}

void ReportRecovery(string stage)
{
    Debug.Log($"Video recovery attempted: {stage}");
}

When monitoring is suspended#

The watchdog resets its counters while a source is opening, after an explicit Pause(), and during the seek grace period. It also stops acting after a non-looping source ends. Disabling the component stops its update loop; with Pause When Disabled enabled, the backend is paused until the component is enabled again.

Configuration#

The Self-Healing Watchdog Inspector section serializes these WatchdogSettings fields. Thresholds are counts of health checks, so their approximate elapsed time changes with checkIntervalSeconds.

Field	Default	Description
`enabled`	On	Enables watchdog monitoring and recovery.
`checkIntervalSeconds`	1	Unscaled seconds between health checks.
`muteDanceAtPausedChecks`	2	Paused checks before the WebGL muted-play recovery.
`kickAtStalledChecks`	3	Stalled checks before a pause/play recovery.
`seekFlushAtStalledChecks`	6	Stalled checks before seeking to the current time.
`reloadAtStalledChecks`	9	Paused or stalled checks before reloading the source.
`reloadRetryEveryChecks`	30	Additional checks between reload attempts after the first reload.