Skip to content

docs(toolpkg): document WebView video codec support - #1509

Open
yoruuuchan wants to merge 1 commit into
AAswordman:devfrom
yoruuuchan:docs/webview-video-codecs
Open

yoruuuchan wants to merge 1 commit into
AAswordman:devfrom
yoruuuchan:docs/webview-video-codecs

Conversation

@yoruuuchan

Copy link
Copy Markdown
Contributor

变更说明 / 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

检查或命令:
git diff --check refs/remotes/upstream/dev..HEAD
python -B ci/script/check_markdown_links.py --base refs/remotes/upstream/dev --candidate HEAD
python -B ci/script/check_localizations.py --base refs/remotes/upstream/dev --candidate HEAD
python -B ci/script/check_repo_hygiene.py --base refs/remotes/upstream/dev --candidate HEAD

环境与变体:Windows 11,Python 3.12.10,分支基于 upstream/dev aeb569bf

结果:四项全部通过。Markdown 链接与本地化检查均为 errors=0 warnings=0,仓库卫生检查 errors=0 warnings=0。

未运行:Gradle 构建与 JVM 单测。本次没有改动 Kotlin、资源或构建配置,改动范围只有一份 Markdown 文档。

证据 / Evidence

N/A。纯文档改动,没有截图、日志或构建产物需要附上;新增小节的内容本身即验证对象,可直接对照 #1447 描述的现象核对。

检查清单 / Checklist

  • 我已记录可复现验证和未运行项原因 / Reproducible verification and reasons for unrun checks are recorded
  • 日常开发 PR 的目标分支为 dev;如目标为 main,我已说明这是维护者发布同步 / The target branch is dev for regular work; if it is main, I explained why this is a maintainer-led release sync
  • 我已确认 Candidate checks 覆盖改动范围,并会处理技术失败项 / Candidate checks covers the change scope and technical failures will be addressed
  • 最终 diff 无无关、临时、生成、二进制或敏感内容 / Final diff has no unrelated, temporary, generated, binary, or secret content
  • 已提供对应的回归、UI、文档/字符串或兼容性证据 / Relevant regression, UI, docs/strings, or compatibility evidence is provided

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.

@CATMIAOZHI CATMIAOZHI left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

审计结论:✅ 批准合并

改动(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 链接、本地化与仓库卫生检查且全部通过。
  • 无代码、安全、性能影响。

问题:

  1. [question] #1447 的期望第 2 条是「播放器侧加检测」(运行时在 loadedmetadata 后检查 videoWidth 并给出可读提示),本 PR 只做了文档(期望第 1 条)并给出了插件侧手动检测的示例代码,却以 Closes #1447 关闭整个 issue。是否确认用文档 + 手动检测示例代替运行时的内置检测?如需保留运行时检测的跟进项,建议改为不关闭 issue 或另开 issue 跟踪。

后续可跟进(不阻塞):无。

由 水晴喵的muse 审计

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants