Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 152 additions & 29 deletions common/src/main/assets/web/app.js

Large diffs are not rendered by default.

2 changes: 2 additions & 0 deletions common/src/main/assets/web/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ <h2 id="setup-title">{{ui_settings}}</h2>
<label id="renderer-video-canvas-card" class="renderer-card" for="renderer-video-canvas"><input id="renderer-video-canvas" type="radio" name="video-renderer" value="video-canvas"><span><strong>{{web_video_renderer_compat}}</strong><em>{{web_video_renderer_experimental}}</em><small>{{web_video_renderer_compat_description}}</small></span></label>
<label id="renderer-track-canvas-card" class="renderer-card" for="renderer-track-canvas"><input id="renderer-track-canvas" type="radio" name="video-renderer" value="track-canvas"><span><strong>{{web_video_renderer_direct}}</strong><em>{{web_video_renderer_experimental}}</em><small>{{web_video_renderer_direct_description}}</small></span></label>
</div><p id="renderer-hint" class="renderer-hint" role="status" hidden>{{web_video_renderer_hint}}</p></fieldset>
<label class="launch-option" for="canvas-webgl"><input id="canvas-webgl" type="checkbox" autocomplete="off" disabled aria-describedby="canvas-webgl-help"><span><strong>{{web_canvas_webgl_title}}</strong><small id="canvas-webgl-help">{{web_canvas_webgl_help}}</small></span></label>
<label class="launch-option" for="ignore-browser-zoom"><input id="ignore-browser-zoom" type="checkbox"><span><strong>{{web_ignore_browser_zoom}}</strong><small>{{web_ignore_browser_zoom_help}}</small></span></label>
<label class="launch-option" for="browser-location"><input id="browser-location" type="checkbox" autocomplete="off" aria-describedby="location-status"><span><strong>{{web_location_title}}</strong><small>{{web_location_help}}</small></span></label>
<p id="location-status" class="hint" role="status" aria-live="polite"></p>
Expand Down Expand Up @@ -86,6 +87,7 @@ <h2 id="debug-title" class="sr-only">{{web_debug_title}}</h2>
<canvas id="held-frame" width="0" height="0" aria-label="{{web_live_carplay_display}}" hidden></canvas>
<div id="media-message" role="status" aria-live="polite" hidden></div>
<canvas id="video-canvas" width="0" height="0" aria-label="{{web_live_carplay_video_canvas}}" hidden></canvas>
<canvas id="video-canvas-webgl" width="0" height="0" aria-label="{{web_live_carplay_video_canvas}}" hidden></canvas>
<button id="desktop-back" type="button" hidden>{{web_desktop_back}}</button>
<div id="touch-surface" aria-hidden="true"></div>
<div id="location-message" hidden role="status" aria-live="polite"></div>
Expand Down
2 changes: 1 addition & 1 deletion common/src/main/assets/web/style.css

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,8 @@ internal object BrowserStrings {
UiR.string.web_display_video_with_canvas_experimental,
"web_decode_video_offscreen_then_draw_it_on_a_canvas" to
UiR.string.web_decode_video_offscreen_then_draw_it_on_a_canvas,
"web_canvas_webgl_title" to UiR.string.web_canvas_webgl_title,
"web_canvas_webgl_help" to UiR.string.web_canvas_webgl_help,
"web_video_renderer_title" to UiR.string.web_video_renderer_title,
"web_video_renderer_native" to UiR.string.web_video_renderer_native,
"web_video_renderer_native_description" to UiR.string.web_video_renderer_native_description,
Expand Down
10 changes: 8 additions & 2 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,21 @@ v3 可使用 WebP,最多两帧在途,并以媒体版本和帧序号精确 AC

## 浏览器三种渲染方式

`native` 为默认原生 Video;`video-canvas` 使用离屏 Video 与可见 Canvas;实验性 `track-canvas` 使用主线程 `MediaStreamTrackProcessor({ track, maxBufferSize: 1 })` → `VideoFrame` → Canvas 2D。不新增网络消息、解码器或依赖。两个旧模式按需创建自己的 Video 元素,停止时移除;直接 Canvas 及其 JPEG / WebP 回退期间不创建 Video。
`native` 为默认原生 Video;`video-canvas` 使用离屏 Video 与可见 Canvas;实验性 `track-canvas` 使用主线程 `MediaStreamTrackProcessor({ track, maxBufferSize: 1 })` → `VideoFrame` → Canvas。两种 Canvas 默认使用 Canvas 2D;连接页提供默认关闭的「Canvas 使用 WebGL(实验性)」开关。开启后直接上传浏览器的 Video / VideoFrame 至纹理,以全屏四边形绘制;WebGL 上下文不可用时使用 Canvas 2D。不新增网络消息、解码器或依赖。两个旧模式按需创建自己的 Video 元素,停止时移除;直接 Canvas 及其 JPEG / WebP 回退期间不创建 Video。

WebGL 每次启动创建一组纹理、顶点缓冲和着色器程序,逐帧复用对象,停止时删除资源;尺寸来自实际帧,旋转时更新画布和 viewport。保持视频新帧去重及 250 ms 回调停滞补偿;不在 JS 中读取像素或每帧创建 GPU 对象。首次上传及尺寸变化时检查 GL 错误,避免逐帧查询错误带来的同步开销。画布上下文类型在其生命周期内固定,因此页面为默认 2D 和 WebGL 实验各保留一个初始为空的画布,两种 Canvas 模式使用所选后端对应的画布。取得 WebGL 后的初始化或绘制失败沿用 JPEG / WebP 回退;此时同一画布无法改为 2D。上下文丢失会触发可恢复错误,允许恢复后的接收器重试。

`preserveDrawingBuffer=true` 保留跨任务复制 held-frame 的能力,带来额外缓冲开销;GPU 上下文丢失时旧 GPU 画面可能无法保留。上传和颜色转换的实际执行路径由浏览器决定。原有 Canvas 2D 也可能使用 GPU,WebGL 的帧率收益应在目标设备、相同输入下测量,尤其需区分解码速度与屏幕呈现速度。

接收器通过渲染器工厂创建适配器,调用 `start(track, streams)`、`stop()` 和 `snapshot()`,由适配器报告首次就绪、尺寸变化及错误。接收器持有 PeerConnection、远端轨道及恢复计时器;适配器持有 reader、绘制上下文、元素及绘制回调。关闭先使代次失效,再停止适配器、移除监听、停止远端轨道并关闭 PeerConnection;关闭前先复制当前画面至上游 held-frame,按媒体版本与恢复期限管理显示和触控;取消读取不阻塞重连,读取结束后释放锁。每个读出的 VideoFrame 均在 finally 中 close,包含错误和过期帧。

两种 Canvas 仅在首次绘制成功后发送 `rtc-ready`。画面尺寸来自实际显示帧或 JPEG,心跳中的默认宽高不能覆盖它,以避免竖屏触控失准。直接 Canvas 不要求 `VideoDecoder` 或安全上下文检测;按主线程 Processor 的实际可用性判断,Worker-only 实现使用 JPEG。

偏好键 `wheelplay.videoRenderer` 保存三种模式;有效新值优先,否则旧 `wheelplay.canvasVideo=true` 迁移为 `video-canvas`,其余默认 native。只写新键并保留旧键;连接时固定模式,自动重连沿用。缺少 Processor 时跳过 rtc-start 并记录本地原因,运行失败使用现有 rtc-fallback,不改变用户选择。

`wheelplayStats.presentation` 包含 selectedMode、activeMode(含 waiting / jpeg)、renderedFps、renderedFrames、fallbackReason。绘制指标为 Canvas 的成功提交次数,不代表屏幕刷新率;兼容 Canvas 的补偿重绘可能重复同一解码帧。receiver 保留现有统计字段并新增 renderedFps / renderedFrames,rtc-feedback 仍报告 WebRTC framesDecoded。
WebGL 偏好键 `wheelplay.canvasWebgl` 仅在值为 `true` 时启用,无法读取存储时默认关闭;原生 Video 下禁用开关但保留选择。选择在用户启动显示时固定,自动重连沿用,修改在下一次手动连接生效。关闭后使用独立的 2D 画布,可在同一页面反复开关。

`wheelplayStats.presentation` 包含 selectedMode、activeMode(含 waiting / jpeg)、renderBackend、renderedFps、renderedFrames、fallbackReason。统计采样后 renderBackend 为 webgl、2d 或 native,未建立或已停止时为 null;receiver 统计也包含 renderBackend。绘制指标为 Canvas 的成功提交次数,不代表屏幕刷新率;兼容 Canvas 的补偿重绘可能重复同一解码帧。receiver 保留现有统计字段并新增 renderedFps / renderedFrames,rtc-feedback 仍报告 WebRTC framesDecoded。

## 生命周期与资源约束

Expand Down
9 changes: 9 additions & 0 deletions docs/VALIDATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -557,3 +557,12 @@ run-1 捕获的第 12 个访问单元(索引 11)为:
- `npm run test:browser:media`:真实 Chromium 在生产 CSP 下通过 seek 能力切换、最后一次拖动位置(42.123 秒 → 42123 毫秒)、暂停状态保持、切歌后的旧 seek 回调隔离,以及既有画面/触控/重连检查。回调由测试脚本触发,未验证车机的实体按键或系统进度条 UI。
- `:mobile:lintDebug`:0 错误、18 警告;`git diff --check` 通过。
- 未安装或操作真实车机/iPhone。手机音乐应用是否执行跳转、进度回报及本地/浏览器输出的声音连续性仍需实机验收。本次复用现有 CarPlay 音频链路,未根据猜测注入 AirPlay 缓冲清空命令。

## Canvas WebGL 绘制(2026-11-15)

兼容 Canvas 与直接 Canvas 默认使用 Canvas 2D;连接页提供默认关闭的 WebGL 实验开关,偏好在当前浏览器保存,下次手动连接生效,自动重连沿用本次选择。原生 Video 下禁用开关。WebGL 不可用时使用 Canvas 2D,已取得 WebGL 后的失败沿用图片回退。为避免上下文类型冲突,2D 和 WebGL 实验使用独立的空画布。纹理、顶点缓冲及程序在会话内复用,停止时释放;保留新帧去重、回调停滞补绘、VideoFrame 释放和会话代次隔离。`wheelplayStats.presentation.renderBackend` 及 receiver 同名字段在采样后区分 webgl / 2d / native。

- `npm run check`、`npm test`:同步至最新 main 后通过,232 项 Node 测试。包含 GL 资源复用/释放、旋转、着色器失败、纹理尺寸限制、首次上传错误、上下文丢失与恢复许可、2D 回退,以及错误回调保帧和重启隔离;覆盖默认关闭、原生模式禁用、偏好存储失败、两个 Canvas 模式启用、同页开关和自动重连的选择隔离。
- `npm run test:browser:webgl`:真实 Chromium / ANGLE SwiftShader 验证四象限颜色与方向、横竖屏、跨动画帧保留画面、HTMLVideoElement 上传、真实 VideoFrame 上传与 close、同一画布切换模式、上下文丢失与恢复及真实 2D 回退;验证页面两个画布上的 2D → WebGL → 2D 切换、开关默认状态和启用/关闭后刷新页面的偏好恢复。输入为合成色块,轨道消费使用测试 reader;未验证手机 WebRTC 吞吐或硬件 GPU 帧率。
- `npm run test:browser:media`:同步至最新 main 后通过,包含图片回退、触控、重连、配对键盘、设置弹窗与 Media Session 回归。原生全屏未在当前浏览器环境进入,对应 OEM 全屏切换检查未执行。
- 未操作车机/iPhone;未测量目标设备帧率、功耗或上传耗时。`preserveDrawingBuffer=true` 为沿用断线保帧契约,额外缓冲开销应纳入设备对比;此前 Canvas 2D 的耗时数据不代表 WebGL 性能。
2 changes: 1 addition & 1 deletion docs/WEBRTC_RECOVERY.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,4 +68,4 @@ WebSocket 控制连接的心跳与重连规则独立于视频策略;整个网

首次成功绘制之前保持 JPEG,首帧等待 `max(10000ms, recoveryGraceMs)`。持续发送时分别检查解码和绘制进展,即使 framesDecoded 增长而画布不再更新,也会在所选容忍时间后回退。没有新输入的静态画面不触发渲染停滞;恢复输入时重新计时。连接短暂断开时仍保留最后一帧。

`presentation.fallbackReason` 区分 processor-unsupported、renderer-error、track-ended、first-frame-timeout、decode-stalled、render-stalled、stats-unavailable、connection-failed、codec-unsupported 等原因;server-stop 表示服务端停止本次媒体。选择保留;可恢复错误沿用上游有界退避重试,缺少 Processor、Canvas 2D 或明确的平台不支持错误停止当前配置的重试,重新连接或配置变化后再尝试。直接 Canvas 状态栏使用 renderedFps,原生 Video 与兼容 Canvas 继续使用 presentedFps / decodedFps。
`presentation.fallbackReason` 区分 processor-unsupported、renderer-error、track-ended、first-frame-timeout、decode-stalled、render-stalled、stats-unavailable、connection-failed、codec-unsupported 等原因;server-stop 表示服务端停止本次媒体。选择保留;可恢复错误沿用上游有界退避重试,缺少 Processor、可用 Canvas 绘制上下文或明确的平台不支持错误停止当前配置的重试,重新连接或配置变化后再尝试。直接 Canvas 状态栏使用 renderedFps,原生 Video 与兼容 Canvas 继续使用 presentedFps / decodedFps。
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
"demo": "node scripts/preview.mjs --demo",
"test": "node --test test/*.test.js",
"test:browser:media": "node scripts/test-media-presentation.mjs",
"test:browser:webgl": "node scripts/test-media-presentation.mjs --webgl-only",
"check": "node --check common/src/main/assets/web/app.js",
"android:build": "./gradlew :mobile:assembleDebug",
"android:test": "./gradlew :common:testDebugUnitTest"
Expand Down
Loading
Loading