API 文档

播放失败、MP4 moov/Range、自动播放、CORS 和 WASM 的排查入口见 QA WIKI（常见问题）。

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

想直接复制运行？按场景选：VR360 视频、WebRTC 拉流、HTTP-FLV/HLS 直播、MP4 点播。

路径规则

当前 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',
  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 的资源路径
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；均使用主线核心
ignore_audio	boolean	否	完全跳过音频链；该配置不是静音
format_type	string	否	可选格式提示；无后缀 WebM 接口可设置 'webm'
media_uri	string	否	可选媒体地址；公开示例仍推荐 build() 后再 load_media()
projection	'flat' | 'erp360'	否	播放方式：普通平面 flat（默认）或 VR360 erp360；不改变视频编码或解码内核
vr	object	否	VR360 初始视角和鼠标/触摸控制，可选 {yaw, pitch, fov, mouse_control, touch_control}

WebM、无音轨 FLV 与 PyMKUI

WebM 播放接口没有 .webm 后缀时，可设置 format_type: 'webm'。WebM 在 Auto/MSE 选择及兼容回调要求下走原生 video 路径。浏览器能力不足、指定软件核心或回调要求不兼容时，报告 WEBM_NATIVE_UNSUPPORTED；原生播放失败不进入 VP8/VP9 软件路径。这项路由没有新增 VP8/VP9 WASM 解码器。

FLV 缺少音频元数据，不等于已确认存在音轨。ignore_audio: true 完全跳过音频链；需要保留音频但静音时使用 set_voice(0)。HTTP-FLV/WebCodec 的 AAC 起播在实际首帧及 AudioContext 激活后对齐队列，其他协议和核心保留原有起播方式。

PyMKUI 接入分支将 RTMP 行映射为 HTTP-FLV、TS 行映射为 HTTP-TS，每次尝试新取 on_play 授权。H.265 MPEG-TS HLS 使用 SDK；H.264 原生 HLS 仅在终止媒体错误 3/4 后尝试一次 SDK MSE 回退。单文件 MP4/WebM 录像提供平面/ERP 切换与播放控件。ERP 需要对真实全景源手动选择，不按尺寸自动判断。此接入尚未实现 H.265 HLS-fMP4。

VR360 视频播放

想播放可拖动视角的 360° 视频或直播，请使用 VR360 片源，并在播放器中显式选择 erp360。erp360 是 SDK 的配置值，表示把全景画面按观看方向显示；不开启时默认按普通平面视频播放。播放中也能在两种方式之间切换，无需更换视频地址或解码内核。

什么视频能用于 VR360？

片源需要是单目、覆盖四周及上下方向的等距柱状全景视频（英文 equirectangular，简称 ERP）。常见画面宽高比为 2:1。普通平面视频即使设置了 erp360，也不会自动变成全景；播放器也不会仅凭文件名、分辨率或元数据自动打开 VR360。

更特殊的 1920×1080、SAR 9:8 等非方形像素 ERP 视频也可使用：以完整的可见画面作为全景输入，编码补齐区域不算入画面。当前不支持六面体 Cubemap、圆柱全景、立体 VR、WebXR 和陀螺仪控制。

• flat：像普通视频一样显示整张画面。
• erp360：显示全景中的一个可转动视角；这是透视观看效果，不会改写视频文件。

怎么开启和控制视角？

在现有 build() 配置中加入 projection: 'erp360'，再照常调用 load_media()：

当前 SDK 发布版包含这些 VR360 API。官网 demo 默认加载同源构建；?sdk=cdn 显式选择固定 CDN 诊断。演示页默认静音、默认普通平面播放，需要手动选择 VR360。若旧缓存 SDK 没有这些接口，请更新文件。

ylplayer.on_error_callback = function (error) {
  if (error.domain === 'vr' && error.fatal === false) {
    console.warn('VR 降级：', error.code, error.fallback);
    return; // 不要因 VR 单独失败而重新加载媒体或切解码核心。
  }
  console.error('播放错误：', error);
};
ylplayer.build({
  player_id: 'canvas111',
  base_url: './output/',
  wasm_js_uri: 'h265web_wasm.js',
  wasm_wasm_uri: 'h265web_wasm.wasm',
  width: '100%', height: 480, auto_play: true,
  projection: 'erp360',
  vr: {yaw: 0, pitch: 0, fov: 75, mouse_control: true, touch_control: true}
});
ylplayer.set_voice(0); // 静音输出，但保留音频链。
ylplayer.load_media('./your-mono-erp.mp4');

播放和暂停期间均可调用以下 API 切回平面、转动视角或重置：

ylplayer.set_projection('flat');
ylplayer.set_projection('erp360');
ylplayer.set_vr_view({yaw: 90, pitch: 10, fov: 75});
ylplayer.rotate_vr_view({yaw: 5});
const view = ylplayer.get_vr_view(); // {yaw, pitch, fov, projection}，状态副本
ylplayer.reset_vr_view();
ylplayer.set_vr_controls({mouse: true, touch: false});

字段 / 方法	说明
yaw	度，正值向右，归一化到 [-180,180)；默认 0
pitch	度，正值向上，限制到 [-85,85]；默认 0
fov	垂直视场角（度），限制到 [30,120]；默认 75
set_vr_view / rotate_vr_view	接受 yaw/pitch/fov 的非空部分更新，仅有限 number；rotate 为相对增量。flat 模式也保存视角
set_vr_controls	{mouse,touch} 的非空部分更新，仅 boolean；默认均关闭
所有设置方法	true 只表示参数已接受，不表示 VR 画面已经显示；非法参数、未 build、release 后返回 false，状态不变
get_vr_view	返回请求的播放方式；如 VR360 已降级为平面，以错误回调为准。未 build / release 后为 null；不新增视角回调
reset_vr_view	恢复初始 build 视角，不改变 projection 或 controls

未知 VR 字段、数字字符串、NaN 和 Infinity 均非法。启动 VR 配置非法时报告 VR_CONFIG_INVALID，VR 使用默认 flat/视角/控制配置；其余媒体配置有效时仍可构建。运行时参数非法仅返回 false。

鼠标支持拖动和滚轮缩放；触摸支持单指拖动。只在活动 ERP surface 上绑定输入，flat/解绑/release 时移除。不安装键盘监听，业务可用自己的键盘 UI 调用 rotate_vr_view()。change_media()、rebuild() 和内部核心回退保留当前视角、初始 reset 基准、请求模式和控制开关；完整 release() 销毁这些状态，下次 build 建立新基准。

进阶：切换画面与截图时会发生什么？

普通画面与 VR360 之间的正常切换保留同一个 canvas/context/decoder，仅切换已缓存的 shader program。Native/MSE 原 video 继续负责解码、音频和播放时间，VR360 canvas 覆盖显示；不会通过 display:none 停止 video，也不会主动把每帧拷到 CPU。暂停时转动视角或改变窗口大小，只重绘当前帧，不推进播放时间或重复发播放进度回调。screenshot(imageId) 沿用原 API，截取当前实际显示的画面；Worker 截图可能异步完成。浏览器/驱动内部是否拷贝不作零拷贝保证。

浏览器不支持或 VR360 显示失败时会怎样？

VR360 只改变画面显示方式，不会让浏览器获得新的解码能力。如果 VR360 渲染失败，播放器尽量继续平面播放，并通过原有 on_error_callback 报告非致命 VR 错误；视频解码失败则仍按原播放链路处理。

VR 不增加解码能力，也不改变选核优先级。Native/MSE、主线 HLS、WebCodec、WASM、WebRTC 沿用现有解码路径。encoded WebRTC 仍要求 Job4 的服务端/帧协议支持，普通 ZLM native WebRTC 地址不提供该协议。纯音频播放没有 VR surface。

build 请求 ERP 时，URL 型原生 video 在设置 src 前使用 crossOrigin='anonymous'，媒体服务器必须允许对应 CORS 请求。若失败，同一 candidate 至多重建一次普通 video，报告 VR_SOURCE_CORS，普通播放成功则继续平面；只有普通媒体加载也失败，才回到原路由错误流程。MSE 拉流/分片 CORS 和 MediaStream 信令权限仍按原规则处理。

已经以非 CORS 模式加载的跨域 video，即使服务器现在允许跨域，也不能通过运行时改属性无损获得纹理读取权限。此时请求 ERP 会保留原 video 连续平面播放，报告 VR_SOURCE_CORS，不自动 reload/seek。请使用同源媒体，或初次 build 显式 ERP 并提供支持 CORS 的 URL。

ERP 填满播放器 viewport，DPR 上限为 2，backing 大小还受 GPU 能力和内部像素预算限制。源纹理上限是另一项约束：缩小输出无法让超大的源纹理变得可用。全屏应使用播放器容器；原生 video-only 全屏可能临时退回 flat，退出后再恢复。context lost 可能丢弃排队 GPU 帧，更换 surface 时出现短暂视频中断；不保证零丢帧，也不会为此主动重建 decoder。

内部后端回退成功（例如 C++→JS GL、WebGL2→WebGL1、VideoFrame→ImageBitmap）不触发公共 VR 错误。最终 ERP→flat 才通过既有 on_error_callback 报告，每个媒体 generation/render attachment 至多一次，字段含 domain:'vr'、fatal:false、projection:'erp360'、fallback:'flat'、code、stage、message 及诊断上下文。请求模式仍为 erp360；普通视角变化不会反复重试失败的 renderer，显式 flat→ERP 可重新尝试。平面播放本身仍依赖可用的 native/2D renderer 和正常解码。

错误码	含义
VR_CONFIG_INVALID	初始 VR 配置非法
VR_RENDERER_UNAVAILABLE	无可用 ERP renderer/surface，或全屏目标不支持
VR_SHADER_INIT	尝试可用后端后，ERP shader 仍初始化失败
VR_TEXTURE_UPLOAD	帧无法上传用于 ERP
VR_SOURCE_CORS	原生源不可读取为纹理，或启动 CORS 重试
VR_TEXTURE_TOO_LARGE	源纹理超过 GPU 上限
VR_CONTEXT_LOST	ERP context 无法继续工作

HLS 路由策略

hls_strategy 选择主线 HLS 路由策略。SDK 不再加载扩展内核：

配置	实际行为
不设置	使用 auto；只尝试兼容的主线候选
hls_strategy: 'auto'	根据浏览器能力、指定的 core 和已绑定回调自动选择主线候选
hls_strategy: 'mainline'	只使用主线候选

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。

稳定音量：audio_leveling、set_audio_leveling(strategy)

const modes = H265webjsPlayer.AudioLeveling;
// 在正常 build 配置中增加该字段；省略时默认为 None。
config.audio_leveling = modes.StableVolume;
ylplayer.build(config);
ylplayer.set_audio_leveling(modes.None);
ylplayer.set_audio_leveling(modes.StableVolume);
const state = ylplayer.get_audio_leveling_state();

枚举包含 None（关闭、默认）和 StableVolume。支持初始化配置和播放中切换。set_audio_leveling() 返回 true 仅表示请求已接受；实际能力查看 state.status（disabled、pending、active、unavailable）与 state.reason。未知枚举返回 false 并保留原策略；非法初始化值使用 None，无法安全读取的配置对象返回 false，不抛错。release 后调用返回 false，须重新 build。

稳定音量采用有上下限、声道联动的 RMS 自动增益与 sample-peak 保护，缓解片段大小声差异；它不是 EQ、人声增强、LUFS 归一化或 true-peak 认证。浏览器音频处理能力、媒体来源安全和用户手势决定是否可用。不支持时保留原播放并报告原因，不为此强制更换视频内核。

自动测量及处理在用户 0～1 音量之前。set_voice() 不改变均衡策略或自动增益计算；开关稳定音量不改变用户音量、不解除静音。set_voice(0) 始终让最终输出无声。内部换源/rebuild 保留最新策略；显式新的 build 未配置时默认为 None。

Demo 的音量均衡开关只改变均衡请求，不调用播放或用户手势通知。音频仍因激活条件处于 pending 时，播放并激活音频是独立的明确操作：通过该入口的播放处理函数开始或恢复播放，保留用户音量/静音并同步播放按钮状态。

无需等视频 ready 才提交均衡请求。音频链尚未就绪时为 pending，可用音轨和处理节点开始工作后才是 active。这是运行时开关，不要求重新加载视频；关闭或开启都保留用户音量和静音。

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

普通 HTTP 媒体经解封装 Worker 请求失败时，错误对象包含 {type:'http-transport', code, status, message}。HTTP 401/403/404 不重试；暂时性失败有限次重试。浏览器因 CORS 限制无法读取响应时，可能只能得到 status: 0。其他播放链路仍沿用各自的错误格式。

全屏回调

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

实验性超分

本地 SDK 已接入同 WebGL2 context 的固定小型 AN CNN，默认关闭。当前属于工程实验模型；开启请求不代表原片真实画质、原生细节恢复、设备性能或生产验收通过。码率不直接开放更高分辨率。

player.on_super_resolution_state = state => console.log(state);
player.build({
  player_id: 'player', wasm_js_uri: './output/h265web_wasm.js',
  wasm_wasm_uri: './output/h265web_wasm.wasm', width: 1280, height: 720,
  super_resolution: { enabled: false, input_color: 'sdr', level: 'standard' }
});
player.load_media(url);
player.set_super_resolution({enabled: true, level: 'light', targetKey: null}); // 当前最小可用增强档
const state = player.get_super_resolution_state();
if (state.options.length) player.set_super_resolution({ enabled: true, targetKey: state.options[0].targetKey });
player.set_super_resolution(false);

input_color 缺省为 unknown，不做增强；仅对已确认的 SDR 输入设置 sdr。VideoFrame 已知的不支持色彩/位深信息优先拒绝。I420 还需要新可选解码描述 ABI，确认 8-bit YUV420P/YUVJ420P planar、方形像素以及兼容的 matrix/transfer/range；旧 WASM 继续普通播放，超分报告旁路。HDR、广色域、ERP、原生视频画中画/全屏和不能合成的原生字幕旁路。

构建配置：enabled 布尔；backend: 'auto' | 'webgl2'；level: 'light' | 'standard'；input_color: 'unknown' | 'sdr'；可选 model_manifest_uri、targetKey。缺省 manifest 是 WASM JS 同目录的 models/sr/model.json，显式相对地址按资源 base 解析；权重相对最终 manifest URL 解析。需要部署完整 models/sr 目录并保留两个 MIT 许可。仅在显式开启且源/显示条件合格后按需下载，检查完整性、形状、大小和超时。

超分支持创建后运行时请求开关和档位，不要求先等 ready。实际增强要等可用帧、模型和性能评估；C++ 渲染器需要重建的例外见下文。input_color、后端与模型 URL 属于 build 参数，运行时 setter 不接受这些字段。Demo 首次开启用 {enabled:true, level:'light', targetKey:null} 直接高一档；用户选“自动”用 {enabled:true, level:'standard', targetKey:null}。light 取当前最小可用候选，standard 取当前最大可用候选；没有候选时说明原因并保持原画。SDK 未指定 level 的默认值仍为 standard。

set_super_resolution(boolean | { enabled?, level?, targetKey? }) 返回参数请求是否被接受，拒绝时不修改当前设置。targetKey: null 恢复按 level 自动选择；手选目标跨换源/重建保留偏好，但重新准入，可能不可用。状态通知不进入媒体错误回调。get_super_resolution_state() 返回副本，含 off/loading/warming/active/bypass/released、请求开关、原因、模型 hash、源/输出尺寸、revision 标识、至多两档增强选项。warming 可能已显示增强画面但还在评估性能；active 需要当前增强输出及合格 GPU 计时窗口，不等于生产画质批准。

仅评估源短边≤720 的输入；1.25/1.5/2 倍候选保持源比例、适合实际显示区域，且输出长边≤1920、短边≤1080、像素≤2073600。原画（包括本来 1080p/4K）保持原行为。720p 可提供 900p/1080p，高码率不开放 1440p/4K。原生 x2 先完整重建，再 bicubic 重采样到分数档。

已有 C++ 渲染器在播放中开启时报告 renderer-recreate-required，继续原队列播放；只在真实渲染器创建边界（如显式 rebuild(true)）应用。build 时显式开启可在创建时选择 JS WebGL2。浮点/计时能力不足、模型错误或持续超预算仅旁路增强，不重载、不换解码核心。预算包含播放倍速。resize/截图复用当前残差，不重复 CNN、不推进 PTS；不增加解码器、媒体队列或音频路径。

控件初始化请在 build 后读取 get_super_resolution_state()。从未启用超分的实例不安排超分通知微任务；启用过后，关闭与释放的真实状态变化仍会通知，避免让未使用功能干扰普通播放生命周期。

SDK 资源采用 file:/blob:/data: 且无法推导 HTTP 模型地址时，仍保留普通 build/播放；实际开启超分报告 model-url-unavailable，需要显式 HTTP(S) model_manifest_uri。暂停时首次加载模型可能等待下一个实际源帧，恢复播放后评估性能；已经增强的暂停帧在仅切输出档位、截图时保留当前 CNN 结果。

在线保护使用有效 GPU timer 样本，以及原 renderer 已选呈现 entry 中的增强比例；该比例的分母不是全部输入/预期解码帧，不能据此推断原片画质，或宣布整链掉帧、A/V 偏移、温升与移动功耗已达标。这些仍属于独立生产验收，experimental 保持 true。

sdr 输入声明指兼容的 8-bit SDR（sRGB/BT.709/已验证 BT.601 范围）；“不是 HDR”不自动等于色域合格。DOM video 暴露的元数据少于 VideoFrame，需要集成方确认该输入范围，不能期待 SDK 自动识别任意广色域片源。

lastEnhancedTime 在各渲染 realm 统一使用 Unix epoch 毫秒，仅作诊断，不是媒体 PTS；GPU/窗口预算另用单调时钟，二者不混用。

model_manifest_uri 用于更换固定工程模型的资源托管地址，不代表可加载任意 ONNX 网络或未经验证的替换权重；当前 id、配方、形状与 SHA-256 仍固定。

显示准入沿用 shared renderer 的有效 viewport：DPR 保守上限为 2，另受已有 viewport/硬件上限约束。更高物理 DPR 可能少给档位，这是性能政策，不是根据码率或画面判断源质量不足。

原生 video 的同条件 SR 旁路会停止反复上传隐藏画布；截图取当前 video，暂停切 ERP 也会更新过期纹理。seek 使旧增强帧失效，但不解除相同请求/输入的 GPU 预算失败锁定；用户明确重新请求可重试，实际输入尺寸/描述或播放 cadence 改变则重新评估。

稳定音量、超分与框架接入的组合示例见播放增强与 skills。