Troubleshooting

Use the browser console, network inspector, and [ProperVideo] logs to identify whether a failure is caused by media delivery, decoding, autoplay policy, or texture binding.

Collect diagnostic information#

1. Reproduce the issue in a hosted WebGL build, not from a local file:// URL.
2. Enable Verbose Logging on the component.
3. Open the browser developer tools and preserve the Console and Network logs while reproducing the issue.
4. Record messages from OnError and stages reported by OnRecoveryAttempted.

Video is visible in the Editor but not in WebGL#

• CORS error: configure the media server to return an Access-Control-Allow-Origin header for the WebGL build's origin. For HLS or DASH, check every manifest, playlist, segment, and key response. See Autoplay & CORS.
• Mixed-content error: replace an HTTP media URL with HTTPS when the build is served over HTTPS.
• Decode or media error: verify the container, video codec, and audio codec in the target browser. H.264/AAC MP4 is a broadly supported baseline, but the target browser determines compatibility. In WebGL, probe a specific MIME type with ProperVideoPlayer.CanPlayType(mimeType).
• No rendering error: assign Output Image, or bind CurrentTexture to a material after OnOpened. Do not share a Target Texture between players.

Playback does not start or has no audio#

Check Muted, Volume, the source's audio tracks, and the browser or operating-system volume. If playback was requested automatically, start it muted. Enable audio and call Play() from a click or tap handler. A play() rejected message in the console indicates that the browser denied the request; see Autoplay & CORS.

Video is upside down in a custom material#

WebGL textures require a vertical UV flip. Apply it when RequiresVerticalFlip is true, as shown in Textures & Rendering. The Output Image path applies the flip automatically.

Playback works in WebGL but not in the Editor#

The Editor fallback uses Unity's VideoPlayer and the operating system's media stack. Its supported containers, codecs, and network protocols can differ from those of the browser. Validate WebGL-specific sources in a hosted WebGL build.

HLS or DASH fails outside WebGL#

The fallback passes the URL to Unity's VideoPlayer. The component reports HLS support on iOS, tvOS, macOS, and Android; it reports no HLS support on Windows and no DASH support outside WebGL. Check ProperVideoPlayer.IsStreamingSupported(type) before opening an adaptive stream. See HLS & DASH Streaming.

An authenticated stream fails#

• Custom headers are supported for HLS and DASH requests on WebGL, not for progressive MP4 or WebM sources.
• A non-safelisted custom header, including Authorization, triggers a CORS preflight. The server must accept OPTIONS and list the header in Access-Control-Allow-Headers.
• Credentialed cookie requests require Access-Control-Allow-Credentials: true and an explicit Access-Control-Allow-Origin value.
• The Editor and non-WebGL fallback do not provide request-header or credential hooks.

Inspect each request in the browser Network panel and see Token-Authenticated Streams.

The watchdog repeatedly reloads a source#

A reload or reload_paused stage means playback remained stalled or paused after earlier recovery attempts. Inspect the preceding OnRecoveryAttempted stages together with media requests, buffer state, tab visibility, and console errors. You can temporarily disable the watchdog to isolate recovery behavior, but doing so does not resolve the underlying delivery, decode, or autoplay issue. See Playback Watchdog.

An additional player will not start on mobile#

Mobile devices and browsers limit concurrent hardware decoder sessions. Reduce the number, resolution, or frame rate of simultaneously active videos, and disable inactive players. See Multiple Players.

Request support#

If the issue remains, collect the asset version, Unity version, browser and OS versions, a minimal reproduction, the [ProperVideo] and browser console messages, and relevant Network-panel details. See Support.