QA WIKI · Frequently Asked Questions

This troubleshooting page selects still-useful topics from the project Wiki and describes them for the current SDK. It is not a copy of the 2022 Wiki's old build options. Start with the browser's Console and Network tabs, the media response, and on_error_callback; then use the matching question below.

MP4 loads forever: what are moov, mdat, and HTTP Range?

An MP4 stores media samples in mdat and the index/timing information needed to locate them in moov. Putting moov before mdat lets an ordinary HTTP client discover the index without downloading the whole file first. A trailing moov is not inherently unplayable when the server and playback path support byte-range requests, but it is a common cause of slow startup or probe failure. Check both the file and the HTTP response:

ffprobe -v trace -i input.mp4 2>&1 | grep -E "type:'(moov|mdat)'"
curl -sS -D - -o /dev/null -H 'Range: bytes=0-1023' 'https://example.com/video.mp4'

For a byte-range request, expect 206 Partial Content and a valid Content-Range. If the file is otherwise valid but moov is at the end, remux to a new file without re-encoding:

ffmpeg -i input.mp4 -map 0 -c copy -movflags +faststart output-faststart.mp4

Also verify that the URL is reachable, the response is actually MP4 rather than an HTML error page, and the codec is supported by the selected browser/core. The Wiki's original MP4 answer and FFmpeg guide cover the historical context.

The first frame is ready, but the player looks black

on_ready_show_done_callback means a first frame is available; it does not mean playback started. With auto_play: false, call play() after the user clicks, or set auto_play: true and comply with browser autoplay policy. The media itself may start with a black frame: inspect it with ffmpeg -i input.mp4 -frames:v 1 first.png, then try playing or seeking forward. In the root demo, Autoplay: Off means Create + Load must be followed by Play. The bundled videos/vr.mp4 has a black first frame, whereas its following frames contain the scene.

Why does autoplay have no sound, or play() reject?

Browsers often block unmuted playback before a user gesture. Start muted, then let the user explicitly enable sound. Do not treat an autoplay-policy rejection as a decoder or network error. ignore_audio: true skips the audio path; it is not a way to later unmute an already running player. This updates the Wiki autoplay answers to the current auto_play API.

The demo or WASM fails to initialize

Serve the page over HTTP(S), not file://. In Network, check the actual URLs and status codes for h265web.js, h265web_wasm.js, h265web_wasm.wasm, and any explicitly used legacy ext* files. A 200 response containing an HTML fallback page is still the wrong WASM file; check its response body and application/wasm MIME type. Keep SDK JS/WASM artifacts from the same build. If a multi-threaded path reports SharedArrayBuffer unavailable, verify a secure context and cross-origin isolation (Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Embedder-Policy: require-corp) on the page, plus CORS/CORP access for cross-origin subresources. Do not apply old Wiki dist or missile-* package advice blindly to this build. See the Wiki initialization questions.

A media URL works in VLC but not in the browser

VLC and the browser do not have identical demuxers, decoders, MIME handling, autoplay rules, or CORS restrictions. Run ffprobe -hide_banner input.mp4 to identify container, video and audio codecs; inspect the actual HTTP response and video_probe_callback/on_error_callback. For HEVC MP4, check whether the video sample entry is hvc1 when targeting a native/MSE HEVC path; a remux with -tag:v hvc1 -movflags +faststart can help only if the encoded video is already compatible. MediaSource.isTypeSupported() is a capability hint, not proof that a particular file will play. On unsupported browsers the SDK may select WebCodec or WASM instead of native/MSE. See the Wiki codec/HEVC questions.

A HEVC elementary stream will not open

Check that the URL returns the elementary stream itself and has a recognized .265, .h265, or .hevc suffix. Use a real HTTP(S) URL or a path that resolves correctly from the page; inspect Network before changing decoder settings. Unlike an MP4, a raw stream has no MP4 moov box or built-in audio track. The Wiki raw-stream answer describes the original format constraints.

CORS errors during VR360 playback

The page origin and media origin differ if protocol, host or port differs. Configure the media server to allow the page origin; check redirects and the final media/segment responses, not just the initial request. VR360 display needs to read video frames, so a cross-origin URL needs a CORS-readable response. If startup with VR360 fails because of CORS, the player can retry ordinary flat video once and report VR_SOURCE_CORS. Switching an already loaded non-CORS video to VR360 cannot repair CORS without a new load. See VR360 playback API and the Wiki CORS answer.

HEVC or VR playback stutters or runs out of memory

First identify the actual selected core, source resolution/bitrate/frame rate, and whether the device supports the browser's native codec path. WASM/software decoding uses CPU and memory; lowering output canvas size alone does not reduce source decode cost. Test with one player and a simpler stream, then inspect memory pressure and Console errors. An ERP frame covers the full sphere, so low source resolution can also look soft after you zoom in. Avoid interpreting the Wiki's old fixed bitrate or missile-256mb suggestions as universal requirements. See the Wiki playback-performance questions.

Which VR360 video or live URL should I test?

Use a monoscopic equirectangular panorama (ERP), typically a 2:1 image. projection: 'erp360' is the switch for VR360 viewing; it cannot turn an ordinary flat MP4 into a panorama. The root index.html has VR360 VOD presets and live URL templates. A live template needs a real VR360 stream to be published first. For HLS, keep hls_strategy: 'auto' or 'mainline'; explicit 'legacy' remains flat. Native WebRTC can display VR360 after negotiation, while the optional encoded WebCodec/WASM WebRTC route requires the separate server protocol in API Docs.

Where should I put this FAQ in a support report?

If the question remains unresolved, include the page URL, media URL with secrets removed, browser/OS, selected core, build() configuration, Console/Network errors, ffprobe summary, whether autoplay is on, and whether a small known-good sample plays. Do not post credentials or private stream tokens. The GitHub Wiki and issue tracker remain available for historical answers and reports.