API 文档

这一页是当前 h265web.js PRO 浏览器 SDK 的精简参考。

路径规则

当前 SDK 对资源路径和媒体路径都支持以下写法：

• 完整 URL：https://example.com/output/h265web_wasm.js
• 站点绝对路径：/output/h265web_wasm.js
• 相对路径：./output/h265web_wasm.js

如果你希望四个 SDK 资源统一从同一个目录解析，可以使用 base_url。

构建流程

推荐的公开接入方式：

1. 创建播放器对象。
2. 绑定需要的回调。
3. 调用 build(config)。
4. 调用 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)

配置字段

参数	类型	必需	说明
player_id	string	是	播放器容器元素 id
wasm_js_uri	string	是	h265web_wasm.js 的资源路径
wasm_wasm_uri	string	是	h265web_wasm.wasm 的资源路径
ext_src_js_uri	string	否	extjs.js 的资源路径
ext_wasm_js_uri	string	否	extwasm.js 的资源路径
base_url	string	否	SDK 资源统一基准路径
width	number | string	否	播放器宽度
height	number | string	否	播放器高度
color	string	否	播放器背景色
auto_play	boolean	否	媒体就绪后自动播放
readframe_multi_times	number	否	demux 读取倍率
core	string	否	显式指定内核：mse_hevc、wasm_hevc、webcodec_hevc、webrtc
hls_strategy	string	否	HLS 路由策略：auto（默认）、mainline 或 legacy；只有显式设置 legacy 才会加载 past-core/ext*
ignore_audio	boolean	否	完全跳过音频链；该配置不是静音
media_uri	string	否	可选媒体地址；公开示例仍推荐 build() 后再 load_media()

HLS 路由策略

hls_strategy 用来决定 HLS 使用当前主线内核，还是历史 past-core/ext* 实现：

配置	实际行为
不设置	使用 auto；只尝试兼容的主线候选，不会加载 past-core/ext*
hls_strategy: 'auto'	根据浏览器能力、指定的 core 和已绑定回调自动选择主线候选；不会加载 past-core/ext*
hls_strategy: 'mainline'	只使用主线候选；不会加载 past-core/ext*
仅设置 hls_legacy_fallback: true	无效。该旧参数已废弃，不能再开启自动 legacy 兜底
hls_strategy: 'legacy'	直接使用历史 past-core/ext* HLS 内核；不会尝试主线候选

只有明确需要历史内核时才使用 legacy。ext_src_js_uri 和 ext_wasm_js_uri 只会被这条显式 legacy 路由使用。auto 或 mainline 的全部主线候选失败后，播放器会报告 HLS 路由错误，不会静默切换到 ext*。

WebRTC 路由

SDK 可以识别标准 WHEP、webrtc:// 兼容地址和 ZLMediaKit 私有 WebRTC 接口：

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 判断在 SDK 内完成。不设置 core 时自动选链；设置 core: 'webrtc' 时强制使用 WebRTC。不需要增加信令选择器或第二套公开 API。

WHEP 是推荐的拉流播放地址。WHIP 是对应的推流协议，不是播放地址。HTTP(S) 请求负责 SDP 信令，协商后媒体通过 WebRTC ICE/DTLS/SRTP 传输。

ZLMediaKit 将 RTMP 转换为 WebRTC 时，需要在 [protocol] 中配置 modify_stamp=1 和 paced_sender_ms=0。modify_stamp=1 使用接收时钟重建并平滑时间戳。实际验证中，modify_stamp=2 虽然仍以正常速率解码，但 Chrome 会丢弃处在过期原生 WebRTC 时间轴上的帧。它是服务端时间戳要求，不是播放器解码设置。

原生 WebRTC 是默认的兼容性和性能路径，固定 1x、不支持 Seek，可接收音视频、仅视频或仅音频协商结果。浏览器 WebRTC 栈不接受的编码，必须由服务器实现可选的 h265web-rtc-encoded/v1 编码媒体协议后，才可能进入 WebCodecs/WASM 链路。

核心方法

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);

原生 WebRTC 直播固定保持 1x，不支持的倍速修改返回 false。

set_voice(volume)

ylplayer.set_voice(0.5);

当 ignore_audio: false 时，set_voice(0) 只让输出静音，之后设置大于 0 的值会恢复对应音量；原生/MSE video 元素也会在设置正音量时解除 muted。

set_mute()

ylplayer.set_mute();

可逆静音应使用 set_mute() / set_voice()。如果构建时设置了 ignore_audio: true，音轨不会初始化，之后调节音量无法恢复，必须以 ignore_audio: false 重建播放器。

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();

必需回调

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);
};

功能回调

回调感知选核

请在 build()/load_media() 前绑定回调。HLS、MP4、FLV、TS 选核都会保留调用方要求的回调契约，不会选择一个无法产生该回调的内核后静默丢弃：

• 原始 NAL、帧、渲染、队列、GPU、A/V 同步回调要求使用软件核。
• av_sync_callback 只使用 WebCodec 核，因为 FFmpeg/WASM 核没有等价的同步事件。
• SEI 回调会排除原生 HLS；流能够输出 SEI 时仍可使用 MSE。
• probe、首帧、播放时间、seek、缓存、release、错误和全屏回调覆盖原生、MSE 与软件主线核。
• 显式选择的路由无法满足已绑定回调时，播放器会报错，不会静默丢回调。
• 当前精简构建的非 HLS H.264 TS 必须使用 MSE；绑定软件核专属回调时会明确返回 CALLBACK_CONTRACT_H264_TS_UNSUPPORTED，不会伪装成支持。

WebRTC 继续使用已有回调名称，没有增加 WebRTC 专属回调 API。原生 WebRTC 会触发真实的 probe、首帧、loading/缓存状态、播放时间、视频渲染、release、error 和全屏事件；原生 <video> 无法取得 NAL、解码后 YUV、内部纹理队列、SEI 或 A/V 对齐数据，因此不会伪造这些结果。只有服务器支持的可选 encoded WebCodecs/WASM 链路实际产生对应数据时，才触发这些低层回调。

主线各核的时间单位保持一致：on_play_time、seek 回调和 mediaInfo.duration 使用秒；NAL、帧、渲染、SEI、缓存进度时间戳使用毫秒。SEI 的 codec 为数值 264 或 265。

video_sei_raw_callback(rawSei, pts, dts, codec)

如果你需要拿到当前播放链路里的原始 SEI 数据，可以接这个回调。

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)

如果当前播放链路可以把 SEI 数据解成可读文本，可以接这个回调。

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

软件核低层回调

下面这些回调需要访问解封装或解码数据；HLS 绑定任意一个后会选择兼容的软件核：

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 的状态为 audio-slower-too-much、audio-faster-too-much、aligned。

nalu_length_callback 与 tex_length_callback 是查询结果回调，分别由 get_nalu_len()、get_tex_len() 触发。调用 gpu_memory_info() 后触发 gpu_info_callback，参数是只读的 WebGL MAX_TEXTURE_SIZE 能力值。WebGL 不提供总显存查询，因此该接口不会分配测试纹理，也不会通过耗尽 GPU 的方式估算显存。

播放与跳转回调

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);
};

两个 seek 回调都返回目标秒数。on_seek_done_callback 每次 seek 只触发一次；软件核在目标帧就绪/渲染后才触发。

缓存相关回调

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);
};

生命周期与错误回调

on_release_done_callback()

活动内核和 Worker 确认释放后只触发一次。Worker 未确认时，SDK 会在有界超时后终止该 Worker，再触发释放完成回调。

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

on_error_callback(error)

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

全屏回调

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