Proper Video Player Documentation

Autoplay & CORS

WebGL playback is subject to browser autoplay and cross-origin media policies. Configure both as part of deployment.

Autoplay#

Browsers generally allow media to start automatically only when it is muted or has no audio track. Playback with audio normally requires a recent user interaction, and exact policy varies by browser, device, user setting, and embedding context. See the browser autoplay guide for an overview.

  1. Enable Muted for a player that uses Play On Start or calls Open during page initialization.
  2. Provide a visible control that enables audio from a click or tap.
  3. Call both SetMuted(false) and Play() from that handler so playback also resumes if the browser paused it.
// Connect this method to a Unity UI Button.
public void PlayWithAudio()
{
    player.SetMuted(false);
    player.Play();
}

When an unmuted WebGL player is opened, the component temporarily requests muted playback and restores the configured mute state after the browser reports that playback started. This improves recovery in browsers that permit the transition, but it does not override autoplay policy. A browser can pause the video when audio is restored without a user gesture.

If the build is hosted in a cross-origin iframe, the parent page may also need to delegate autoplay permission, for example with allow="autoplay". This permission does not remove the user-interaction requirement for audible playback.

Cross-origin media#

The WebGL backend sets the browser video element to anonymous CORS mode by default. This is required before decoded frames from another origin can be uploaded to a Unity texture. Every cross-origin media response must include an Access-Control-Allow-Origin value that permits the WebGL build's origin.

  • For public media, the server can return Access-Control-Allow-Origin: *.
  • Files deployed in StreamingAssets are normally served from the build's own origin and do not require CORS headers.
  • For HLS and DASH, apply the required CORS headers to manifests, playlists, segments, and encryption-key responses.
  • An HTTPS page cannot load an HTTP media source. Serve the build and its media over HTTPS in production.

Credentialed requests#

Call SetUseCredentials(true) before Open when cross-origin requests must include cookies. The server must then return both:

Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://game.example.com

Credentialed requests cannot use * for Access-Control-Allow-Origin. Non-safelisted custom request headers, including Authorization, also require a successful CORS preflight. See Token-Authenticated Streams for authentication-specific configuration.

Diagnose deployment errors#

  1. Open the browser developer tools for the hosted WebGL build.
  2. Check the Console for autoplay, mixed-content, CORS, decode, or texture-upload errors.
  3. In the Network panel, inspect the response headers for the failed media request and, when applicable, its OPTIONS preflight.

See Troubleshooting for the full playback checklist.