API Docs

This page is the compact reference for the current h265web.js PRO browser SDK.

Path Rules

The current SDK accepts these path styles for both SDK resources and media URLs:

• Full URL: https://example.com/output/h265web_wasm.js
• Site-absolute path: /output/h265web_wasm.js
• Relative path: ./output/h265web_wasm.js

If you want to resolve the four SDK resource files from one shared base path, use base_url.

Build Flow

Recommended public usage:

1. Create the player object.
2. Bind the callbacks you need.
3. Call build(config).
4. Call load_media(mediaUrl).

const ylplayer = H265webjsPlayer();

ylplayer.on_ready_show_done_callback = function () {
  console.log('ready');
};

ylplayer.video_probe_callback = function (mediaInfo) {
  console.log('probe', mediaInfo);
};

ylplayer.build({
  player_id: 'canvas111',
  base_url: './output/',
  wasm_js_uri: 'h265web_wasm.js',
  wasm_wasm_uri: 'h265web_wasm.wasm',
  ext_src_js_uri: 'extjs.js',
  ext_wasm_js_uri: 'extwasm.js',
  width: '100%',
  height: 480,
  auto_play: true,
  ignore_audio: false
});

ylplayer.load_media('./resource/demo.mp4');

build(config)

Config Fields

Parameter	Type	Required	Description
player_id	string	Yes	Player container element id
wasm_js_uri	string	Yes	Resource path for h265web_wasm.js
wasm_wasm_uri	string	Yes	Resource path for h265web_wasm.wasm
ext_src_js_uri	string	No	Resource path for extjs.js
ext_wasm_js_uri	string	No	Resource path for extwasm.js
base_url	string	No	Optional shared base path for SDK resource resolution
width	number | string	No	Player width
height	number | string	No	Player height
color	string	No	Player background color
auto_play	boolean	No	Auto play after media is ready
readframe_multi_times	number	No	Demux feed scale
core	string	No	Explicit core: mse_hevc, wasm_hevc, webcodec_hevc, webrtc
hls_strategy	string	No	HLS route policy: auto (default), mainline, or legacy; only explicit legacy loads past-core/ext*
ignore_audio	boolean	No	Skip the audio pipeline entirely; this is not mute
media_uri	string	No	Optional media URL. Public examples still recommend build() followed by load_media()

HLS Route Policy

hls_strategy controls whether HLS uses the current mainline cores or the historical past-core/ext* implementation:

Configuration	Result
Omitted	Uses auto; tries compatible mainline candidates only and never loads past-core/ext*
hls_strategy: 'auto'	Uses the default mainline route selected from browser capabilities, the requested core, and bound callbacks; never loads past-core/ext*
hls_strategy: 'mainline'	Uses mainline candidates only; never loads past-core/ext*
hls_legacy_fallback: true only	No effect. This deprecated option no longer enables an automatic legacy fallback
hls_strategy: 'legacy'	Directly uses the historical past-core/ext* HLS core; no mainline candidate is attempted

Use legacy only when you intentionally need the historical core. ext_src_js_uri and ext_wasm_js_uri are only used by that explicit legacy route. If every mainline candidate fails under auto or mainline, the player reports an HLS route error instead of silently switching to ext*.

WebRTC Route

The SDK recognizes standard WHEP, the webrtc:// compatibility form and the ZLMediaKit private WebRTC API:

http://127.0.0.1/index/api/whep?app=live&stream=test
webrtc://127.0.0.1/live/test
http://127.0.0.1/index/api/webrtc?app=live&stream=test&type=play

URL recognition happens inside the SDK. Omit core for automatic routing, or set core: 'webrtc' to require WebRTC. No signaling selector or second public API is needed.

WHEP is the recommended playback input. WHIP is the corresponding publishing protocol and is not a playback URL. The HTTP(S) request carries SDP signaling; media uses WebRTC ICE/DTLS/SRTP after negotiation.

For ZLMediaKit RTMP-to-WebRTC conversion, configure [protocol] modify_stamp=1 and paced_sender_ms=0. modify_stamp=1 rebuilds and smooths timestamps from the receive clock. In the tested modify_stamp=2 case, decoding continued at the expected rate while Chrome dropped frames that arrived on a late native WebRTC timeline. This is a server timestamp requirement, not a player decode setting.

Native WebRTC is the default compatibility/performance route. It is fixed at 1x, does not support seek, and accepts AV, video-only or audio-only negotiation results. Codecs not accepted by the browser's WebRTC stack require server support for the optional h265web-rtc-encoded/v1 encoded-media protocol before a WebCodecs/WASM route is possible.

Core Methods

release()

ylplayer.release();

load_media(mediaUrl)

ylplayer.load_media('./resource/hevc_test_moov_set_head_16s.mp4');

change_media(mediaUrl)

ylplayer.change_media('/resource/another-demo.mp4');

play()

ylplayer.play();

pause()

ylplayer.pause();

seek(seconds)

ylplayer.seek(10);

set_playback_rate(rate)

ylplayer.set_playback_rate(2.0);

Native WebRTC live playback remains at 1x and returns false for unsupported rate changes.

set_voice(volume)

ylplayer.set_voice(0.5);

With ignore_audio: false, set_voice(0) silences output and a later positive value restores the selected volume. Native/MSE media elements are also unmuted when a positive volume is applied.

set_mute()

ylplayer.set_mute();

Use set_mute() / set_voice() for reversible mute controls. If the player was built with ignore_audio: true, the audio track was not initialized and changing volume cannot restore it; rebuild with ignore_audio: false instead.

screenshot(imgId)

<img id="screenshot" style="width:400px;height:340px;background:#e9e9e9;" />

ylplayer.screenshot('screenshot');

next_frame()

ylplayer.next_frame();

resize(width, height)

ylplayer.resize(640, 480);

fullScreen()

ylplayer.fullScreen();

closeFullScreen()

ylplayer.closeFullScreen();

Required Callbacks

on_ready_show_done_callback

ylplayer.on_ready_show_done_callback = function () {
  console.log('on_ready_show_done_callback');
};

video_probe_callback(mediaInfo)

ylplayer.video_probe_callback = function (mediaInfo) {
  console.log('video_probe_callback', mediaInfo);
};

Feature Callbacks

Callback-aware core routing

Bind callbacks before build()/load_media(). HLS, MP4, FLV, and TS routing preserve the requested callback contract instead of silently selecting a core that cannot emit it:

• Raw NAL/frame/render/queue/GPU/A-V-sync callbacks require a software core.
• av_sync_callback specifically requires the WebCodec core because the FFmpeg/WASM core does not expose equivalent alignment events.
• SEI callbacks exclude native HLS, but may use MSE when the stream exposes SEI.
• Probe, ready, play-time, seek, cache, release, error, and fullscreen callbacks are available on native, MSE, and software mainline cores.
• If an explicitly requested route cannot satisfy the bound callbacks, the player reports an error rather than dropping those callbacks.
• In this compact build, non-HLS H.264 TS requires MSE. If software-only callbacks are bound, the player reports CALLBACK_CONTRACT_H264_TS_UNSUPPORTED instead of pretending those callbacks are available.

WebRTC uses the existing callback names; no WebRTC-only callback API was added. Native WebRTC emits real probe, ready, loading/cache-state, play-time, video-render, release, error and fullscreen events. It does not fabricate NAL, decoded YUV, internal texture queue, SEI or A/V alignment data that a native <video> element cannot expose. Those low-level callbacks are emitted only when the optional server-supported encoded WebCodecs/WASM route actually produces the corresponding data.

Timestamp units are stable across mainline cores: on_play_time, seek callbacks, and mediaInfo.duration use seconds; NAL/frame/render/SEI/cache-process timestamps use milliseconds. codec in SEI callbacks is numeric (264 or 265).

video_sei_raw_callback(rawSei, pts, dts, codec)

Use this when you need the raw SEI payload from the current playback chain.

ylplayer.video_sei_raw_callback = function (rawSei, pts, dts, codec) {
  console.log('video_sei_raw_callback', rawSei, pts, dts, codec);
};

video_sei_text_callback(text, pts, dts, codec)

Use this when the current playback chain can decode SEI data into readable text.

ylplayer.video_sei_text_callback = function (text, pts, dts, codec) {
  console.log('video_sei_text_callback', text, pts, dts, codec);
};

Low-level software-core callbacks

These callbacks require access to demuxed or decoded data, so binding any of them makes HLS select a compatible software core:

ylplayer.video_nalu_callback = function (ptsMs, dtsMs) {};
ylplayer.video_frame_callback = function (ptsMs, width, height, cacheSize) {};
ylplayer.audio_frame_callback = function (ptsMs, cacheSize) {};
ylplayer.video_render_callback = function (ptsMs, width, height) {};
ylplayer.audio_render_callback = function (ptsMs) {};
ylplayer.request_pkt_callback = function (videoPacketCount, audioPacketCount) {};
ylplayer.nalu_length_callback = function (length) {};
ylplayer.tex_length_callback = function (length) {};
ylplayer.gpu_info_callback = function (info) {};
ylplayer.av_sync_callback = function (state, detail) {};

av_sync_callback states are audio-slower-too-much, audio-faster-too-much, and aligned.

nalu_length_callback and tex_length_callback are query responses; call get_nalu_len() and get_tex_len() respectively. gpu_info_callback is emitted after gpu_memory_info() and receives the read-only WebGL MAX_TEXTURE_SIZE capability. WebGL does not expose total GPU memory, so this API does not allocate test textures or estimate memory by exhausting the GPU.

Playback And Seek Callbacks

on_play_time(pts)

ylplayer.on_play_time = function (pts) {
  console.log('on_play_time', pts);
};

on_play_finished()

ylplayer.on_play_finished = function () {
  console.log('on_play_finished');
};

on_seek_start_callback(seekTarget)

ylplayer.on_seek_start_callback = function (seekTarget) {
  console.log('on_seek_start_callback', seekTarget);
};

on_seek_done_callback(seekTarget)

ylplayer.on_seek_done_callback = function (seekTarget) {
  console.log('on_seek_done_callback', seekTarget);
};

Both seek callbacks receive the requested target in seconds. on_seek_done_callback fires once when the selected core has completed the seek; software cores wait until the target frame is ready/rendered.

Cache Callbacks

on_cache_process_callback(timestamp)

ylplayer.on_cache_process_callback = function (timestamp) {
  console.log('on_cache_process_callback', timestamp);
};

on_load_caching_callback(data)

ylplayer.on_load_caching_callback = function (data) {
  console.log('on_load_caching_callback', data);
};

on_finish_cache_callback(data)

ylplayer.on_finish_cache_callback = function (data) {
  console.log('on_finish_cache_callback', data);
};

Lifecycle And Error Callbacks

on_release_done_callback()

Fires exactly once after the active core and workers have been released. If a worker does not acknowledge release, the SDK terminates it after the bounded release timeout before firing this callback.

ylplayer.on_release_done_callback = function () {
  console.log('released');
};

on_error_callback(error)

ylplayer.on_error_callback = function (error) {
  console.error('player error', error);
};

Fullscreen callbacks

ylplayer.on_open_fullscreen = function () {};
ylplayer.on_close_fullscreen = function () {};