Repository navigation
docs(toolpkg): document WebView video codec support - #1509
Open
yoruuuchan wants to merge 1 commit into
Open
yoruuuchan wants to merge 1 commit into
yoruuuchan wants to merge 1 commit into
Conversation
Playback inside UI.WebView runs through the system WebView media pipeline, so the set of playable codecs depends on the device and WebView version. MPEG-4 Part 2 (mp4v) is outside that set: the audio track keeps playing while videoWidth and videoHeight stay at zero and no error event fires, which leaves plugin authors with a silent black frame and no usable failure signal. Document the H.264/AAC baseline, the mp4v symptom, and the loadedmetadata videoWidth check that detects an unsupported codec.
2 tasks done
CATMIAOZHI
self-requested a review
November 16, 2026 07:35
CATMIAOZHI
approved these changes
Nov 16, 2026
CATMIAOZHI
left a comment
Collaborator
There was a problem hiding this comment.
审计结论:✅ 批准合并
改动(1 个文件,+24/−0):在 ToolPkg 开发者文档 compose_dsl.md 的 WebView 一节下新增「媒体播放与编码」小节,说明 <video> 的编码支持范围与 mp4v 静默失败现象及 videoWidth 自检方法。纯文档改动,不涉及运行时代码。
通过的检查:
- 目标分支为
dev,符合规范。 - 新增内容与 #1447 报告的现象逐项一致:
videoWidth/videoHeight为 0、画面全黑、error事件不触发、play()正常 resolve、readyState继续推进、系统播放器可正常播放、转 H.264 后恢复正常。 - 宿主默认配置与代码一致:
ToolPkgComposeDslWebView.kt中allowFileAccess/allowContentAccess默认true,mediaPlaybackRequiresUserGesture默认false。 - FFmpeg 模块引用无误:
../04_modules/ffmpeg.md存在;Tools.FFmpeg.convert的video_codec: 'h264'、audio_codec: 'aac'均为该文档列出的合法字面量;mpeg4也在FFmpegVideoCodec字面量列表中。 - 转码命令
ffmpeg -i input.mp4 -c:v libx264 -pix_fmt yuv420p -c:a aac output.mp4正确,且文档已注明libx264需要 ffmpeg 构建包含(与 #1447 中内置构建缺少 libx264 的情况呼应)。 - 标题层级正确(
###位于## WebView之下),链接目标存在;作者已运行 Markdown 链接、本地化与仓库卫生检查且全部通过。 - 无代码、安全、性能影响。
问题:
- [question] #1447 的期望第 2 条是「播放器侧加检测」(运行时在
loadedmetadata后检查videoWidth并给出可读提示),本 PR 只做了文档(期望第 1 条)并给出了插件侧手动检测的示例代码,却以Closes #1447关闭整个 issue。是否确认用文档 + 手动检测示例代替运行时的内置检测?如需保留运行时检测的跟进项,建议改为不关闭 issue 或另开 issue 跟踪。
后续可跟进(不阻塞):无。
由 水晴喵的muse 审计
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
变更说明 / Description
背景与动机 / Context and motivation
ToolPkg 的
UI.WebView支持在页面里用<video>播放视频,但文档没有说明它能播哪些容器和编码组合。插件作者沿用「mp4 都能播」的常识转码时,会拿到有声音、无画面的静默失败:videoWidth为0,error事件不触发,控制台也没有报错。相关内容见 #1447。改动范围 / Changes
docs/doc-src/toolpkg_developer_documentation/06_ui_and_compose/compose_dsl.md的 WebView 一节后补「媒体播放与编码」小节:播放由系统 WebView 的媒体管线负责,可播编码随设备与 WebView 版本变化;H.264 + AAC 是通用组合;mp4v这类不受支持的编码只播音频且不报错;用videoWidth自检。兼容性与风险 / Compatibility and risks
N/A。纯文档改动,不影响用户行为、数据、API、配置、性能或安全。
关联 Issue / Related issue
Closes #1447
验证方式 / Verification
证据 / Evidence
N/A。纯文档改动,没有截图、日志或构建产物需要附上;新增小节的内容本身即验证对象,可直接对照 #1447 描述的现象核对。
检查清单 / Checklist
dev;如目标为main,我已说明这是维护者发布同步 / The target branch isdevfor regular work; if it ismain, I explained why this is a maintainer-led release syncCandidate checks覆盖改动范围,并会处理技术失败项 /Candidate checkscovers the change scope and technical failures will be addressed