Skip to main content

Check Before Play

What it does​

Instead of relying on periodic HEAD-request polling to detect media updates, the player checks each media file for updates immediately before playing it. This ensures content is always fresh at the moment of playback.

How it works​

  • Right before a media element (video, image, widget) is played, the player makes a HEAD request to check if the source file has changed.
  • If an update is detected, the new file is downloaded and committed before playback begins.
  • Interval-based media checking is automatically disabled (onlySmilUpdate is forced to true internally) — only the SMIL file itself is still polled on the refresh interval.

How to enable​

Add the checkBeforePlay="true" attribute to the <meta> tag in the SMIL <head>:


<smil>
    <head>
        <meta http-equiv="Refresh" content="60" checkBeforePlay="true"/>
    </head>
    <!-- Additional elements here -->

</smil>

Note​

When checkBeforePlay is enabled, there is no need to set onlySmilUpdate="true" explicitly — the player sets it automatically. The periodic refresh interval (content) still applies to the SMIL file itself.

Lookahead via checkAheadCount​

Without a lookahead, the HEAD check for element N happens right before element N plays — which can visibly delay the transition while the HEAD (and any triggered download) completes. Set checkAheadCount to have the player check the element N positions ahead while the current element is still playing:

<meta http-equiv="Refresh" content="60" checkBeforePlay="true" checkAheadCount="2"/>

With checkAheadCount="2", while element K is playing the player issues a HEAD for element K+2. The lookahead wraps around modulo the number of media entries in the current playlist container, so an indefinite <seq> checks every slot, including the last few items (they are checked when the start of the playlist plays). A slot that previously returned a skipContentOnHttpStatus code (e.g. a 404) is still re-checked by the lookahead on later cycles — that periodic HEAD is what lets the element recover automatically once its URL serves content again. When the K+N slot is currently skipped, the lookahead additionally checks the next playable slot, so a healthy target fires exactly one HEAD per transition and a recovering one at most two. Non-positive or invalid checkAheadCount values disable the lookahead.

Updates are discovered via this lookahead; the subsequent background download and commit may land later — up to the next full iteration of the playlist. Worst-case detection latency is roughly checkAheadCount × average_element_duration. Lower checkAheadCount keeps the HEAD closer to the moment the change becomes visible; higher values give slow networks more lead time to finish the download before the element plays.

When to use​

This option is useful when content freshness at playback time matters more than update latency — for example:

  • Playlists with long-duration items where polling might miss a mid-cycle update.
  • Infrequent loop cycles where you want to guarantee the latest version plays on the next iteration.
  • Scenarios where you want to reduce unnecessary network traffic from polling media files that haven't changed.

Important​

checkBeforePlay replaces the interval-based media update mechanism; it does not add a second check on top of it. Media files are only checked right before they are played, not on a timer.

Relation to the playCheckUrl playability gate​

checkBeforePlay and the per-element playCheckUrl gate are independent HEAD channels that can be combined freely. The update check (this page) decides whether content changed and rides the checkAheadCount lookahead when configured; the gate decides whether the element plays this pass and always fires inline right before play — it never rides the lookahead, so its answer is always fresh. Neither channel reads the other's status-code list (skipContentOnHttpStatus vs skipPlaybackOnHttpStatus).

Source: a-smil.org