Skip to content

feat(cli): 支持 PAGX 导出 MP4 - #3830

Open
jinwuwu001 wants to merge 91 commits into
mainfrom
feature/billyjin_pagx_mp4
Open

jinwuwu001 wants to merge 91 commits into
mainfrom
feature/billyjin_pagx_mp4

Conversation

@jinwuwu001

@jinwuwu001 jinwuwu001 commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

实现内容

  • 支持将动态和静态 PAGX 导出为 H.264 MP4。
  • 支持帧率、时长、缩放、编码参数配置及 GPU 尺寸上限处理。
  • 完善 ffmpeg 进程执行、参数校验、异常处理和输出文件发布。
  • npm 安装时下载并校验对应平台的 ffmpeg,支持缓存、PATH 和手动路径配置。
  • 增加相关回归测试,并在 native CI 中安装 ffmpeg 和 ffprobe。

Comment thread include/pagx/VideoExporter.h Outdated
* @param width receives the computed width on success.
* @param height receives the computed height on success.
*/
static bool ComputeOutputDimensions(float documentWidth, float documentHeight, float scale,

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.

【S2 严重】仅 CLI 使用的实体进入了永久公开 API

证据:ComputeOutputDimensions 的外部调用者只有 src/cli/CommandExport.cpp:363/395/439;VideoFrameRate::normalized()(:71)只被 src/cli/VideoEncoder.cpp:389 用于拼 -framerate;toString()(:79-80)只被 CommandExport/CommandRender 打印,文档还直接写 “suitable for ffmpeg”。宿主侧 width()/height() 已能给出最终尺寸,Make() 之后无需预计算。

影响:6 参数 + int* 出参的静态方法、以及 ffmpeg 风格的格式化方法成为公开契约,后续无法移除;与本文件 “Encoding and muxing are the host's responsibility” 的定位不一致。

建议:把 ComputeOutputDimensions、normalized()、toString() 移到 src/cli 内部头(CLI 已可依赖 src/ 私有头,如 CommandExport.cpp 已 include rendering/gpu/Devices.h);MIN_FRAME_RATE/MAX_FRAME_RATE 建议保留,它们描述 API 自身限制。

备注:若产品确实需要宿主侧预检/自行封装编码器,可讨论保留,但请在注释中补上宿主使用场景。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已按建议收敛公开 API,相关修改在 0af7bf32b:

  • 移除公开的 VideoExporter::ComputeOutputDimensions();
  • 移除 VideoFrameRate::normalized() 和 toString();
  • 尺寸计算移到库内部头 src/pagx/VideoExportInternal.h,供 VideoExporter 和 CLI 共用;
  • 帧率化简与格式化移到 cli/CliUtils;
  • 保留 MIN_FRAME_RATE/MAX_FRAME_RATE,因为它们描述公开采样选项自身的约束。

另外处理了评论中未列出的内部调用点:VideoExporter::Make() 的尺寸计算和参数错误中的帧率格式化也已切换到内部实现,没有保留公开兼容层。

Comment thread web/test/CMakeLists.txt
file(GLOB CLI_SOURCES CONFIGURE_DEPENDS ${ROOT}/src/cli/*.cpp)
list(FILTER CLI_SOURCES EXCLUDE REGEX "main\\.cpp$")
list(FILTER CLI_SOURCES EXCLUDE REGEX "CommandExport\\.cpp$")
list(FILTER CLI_SOURCES EXCLUDE REGEX "VideoEncoder\\.cpp$")

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.

【S3 严重】新增的平台进程文件未被排除,web 测试会编到依赖缺失的 TU

证据:这里排除了 VideoEncoder.cpp,但同一个 glob 仍收录 src/cli/VideoEncoderProcess_posix.cpp(仅 #ifndef _WIN32 守卫)与 VideoEncoderProcess_win.cpp。posix 文件调用 SetError(:52/:60/:95),而 SetError 只在被排除的 VideoEncoder.cpp:53 定义,VideoEncoderProcessInternal.h:30 只有声明。

影响:CI 的 web job(build.yml:242-253)只构建 web SDK 与 harness 单测,不构建 web/test 的 pag-test,因此 CI 绿不能作为证据。Release(-Oz) 下未引用的函数若被丢弃可能侥幸通过;Debug(-O0,见 web/test/package.json 的 build:debug / build:webgpu:debug) 会因未定义符号链接失败。

建议:与 VideoEncoder.cpp 一样排除 VideoEncoderProcess_(posix|win)\\.cpp,并同步 web/test/README.md 的排除清单。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已修改,相关修改在 0af7bf32b。

web/test/CMakeLists.txt 现在同时排除:

  • VideoEncoder.cpp
  • VideoEncoderProcess_posix.cpp
  • VideoEncoderProcess_win.cpp
  • VideoFrameSource.cpp

web/test/README.md 的排除清单也已同步更新。

同时确认 Web 测试入口没有引用 InitializeVideoEncoderProcess(),排除这些平台进程文件后不会留下该符号的引用。

access.grfInheritance = SUB_CONTAINERS_AND_OBJECTS_INHERIT;
BuildTrusteeWithSidW(&access.Trustee, static_cast<PSID>(tokenUser->User.Sid));
ACL* acl = nullptr;
auto aclResult = SetEntriesInAclW(1, &access, nullptr, &acl);

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.

【S4 严重,需 Windows 实测】发布后的 mp4 继承 staging 目录的“仅当前用户”DACL

证据:这里为 staging 目录构造只含当前用户 GENERIC_ALL(含 SUB_CONTAINERS_AND_OBJECTS_INHERIT)的 DACL,并在 :81 用 CreateDirectoryW 应用;part 文件在该目录内创建,因此继承该 DACL。finish() 用 MoveFileExW 同卷移动时,Windows 不会按目标目录重新计算继承 ACE,最终 .mp4 仍只有创建者可读。POSIX 侧 part 文件是 0666 & ~umask(通常 0644),两平台权限不一致。

影响:共享构建机 / CI 产物目录中,其他账号或服务读取产物会被拒绝;现有测试未断言文件 ACL,问题不会被发现。

建议:发布后对目标文件重新启用继承(SetNamedSecurityInfoW(dest, SE_FILE_OBJECT, DACL_SECURITY_INFORMATION, nullptr, nullptr, nullptr, nullptr)),或直接在输出目录内创建 part 文件以继承目标目录 DACL;并在 Windows 上用 icacls 验证一次实际权限。

@jinwuwu001 jinwuwu001 Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已修复,相关修改在 0af7bf32b,并已在 Windows 11 + VS2022(MSVC 19.44)上完成真实 MP4 导出验证。

修复方式是在 MoveFileExW 成功后调用 RestoreFileSecurityInheritance(),通过“空 ACL + UNPROTECTED_DACL_SECURITY_INFORMATION”清除 staging 带来的显式 ACE,并按输出目录重新建立继承。没有使用可能产生 NULL DACL 歧义的 pDacl = nullptr。

实测结果:

  • staging 目录和 part 文件均只有当前用户 ACE;
  • 不调用恢复逻辑时,MoveFileExW 后的产物仍只有当前用户 ACE,复现了评审指出的问题;
  • 修复后,真实导出的 car-app.pagx 产物权限为当前用户 (I)(F)、内置 Users 组 (I)(R),且 AreAccessRulesProtected = False。

结果与 icacls <file> /reset 一致,其他账号可以按照输出目录策略读取产物。权限恢复失败时,finish() 会明确返回错误,不会静默成功。

POSIX 侧继续保持 0666 & ~umask,采用各平台原生的权限策略,不强行对齐为固定 0644。

Comment thread src/pagx/VideoExporter.cpp Outdated
periodUs *= 2;
}
}
auto effectivePeriodUs = static_cast<double>(periodUs) + static_cast<double>(offsetUs);

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.

【S5 严重】evaluationOffset 被无条件计入播放周期,负偏移会截断默认时长

证据:此处 effectivePeriodUs = periodUs + offsetUs 对所有 loop 模式生效;但运行时语义不同(PAGAnimation.cpp:283-290):Once 是真正的延迟/跳过,Loop/PingPong 只做相位偏移(WrapTime 仅取模),周期本身不变。

影响:
(a) 负 offset 会让默认时长变短并被截断,例如 duration=333ms@60fps、evaluationOffset=-200ms 时导出 133ms ≈ 8 帧,而实际循环是 20 帧;
(b) 当 |offset| >= period 且这是唯一动态内容时,effectivePeriodUs <= 0,ResolveSampling 会误报 “the document's animations have no duration, pass a duration”,一个持续动画的文档无法导出;
(c) 正 offset 对 Loop/PingPong 只会多出重复帧。

旁证:include/pagx/nodes/AnimationTimeline.h:53-60 声明正偏移 “freezes at the first frame”,而 PAGAnimation 对 Loop/PingPong 会回绕到周期末尾——文档与运行时本身也不一致,exporter 按文档语义计算,二者必有一处错。

建议:仅 LoopMode::Once 累加 offset(负值截到 0),其余模式使用 playbackPeriod();文档/运行时的矛盾建议单独立项确认。测试建议补一条带 evaluationOffset 的嵌套时间线用例(当前 0 处覆盖)。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已修改,相关修改在 0af7bf32b。默认时长计算现在为:

  • Once:max(0, playbackPeriod + evaluationOffset),正偏移表示延迟,负偏移表示跳过;
  • Loop/PingPong:始终使用原 playbackPeriod,偏移只改变相位,不改变导出周期。

这修复了负偏移截断循环动画、正偏移产生额外重复帧,以及大偏移导致误报“动画没有时长”的问题。

同时更新了 VideoExportOptions.duration 和 AnimationTimeline.evaluationOffset 文档,并新增回归测试覆盖:

  • Loop 的正、负偏移及超过一个周期的偏移;
  • PingPong 偏移后的完整双程周期;
  • Once 正偏移增加时长、负偏移缩短时长。

@jinwuwu001 jinwuwu001 closed this Nov 16, 2026
IsExecutableFile() took const std::string&, but the managed ffmpeg cache path is assembled with std::filesystem::operator/, and on Windows path::string_type is std::wstring, so the resulting path cannot be converted to std::string. Take a std::filesystem::path instead; every existing caller still binds through the implicit conversion and POSIX behaviour is unchanged.
FallbackTypefaces() on Windows populated only fontFamily, leaving FontLocation::path empty. LayoutContext::ensureSystemFallbacks() builds each TypefaceHolder from that path, so every system fallback face failed to load: a document whose fontFamily is not installed (e.g. PingFang SC on Windows) shaped no glyphs at all instead of falling back to an installed font. Resolve each family's default face to its file path and face index the same way FindFont() does, skip families that cannot be resolved, and cache the list because a LayoutContext is rebuilt on every reshape.
@jinwuwu001 jinwuwu001 reopened this Nov 16, 2026
Comment thread src/pagx/VideoExporter.cpp Outdated
SetError(errorMsg, "failed to instantiate state machine '" + node->id + "'");
return false;
}
plan->timelines.emplace_back(std::move(stateMachine));

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.

【A6】重复 StateMachine id 会让同一实例每帧被推进两次

证据:ValidateDocumentAnimations(:63-80)只校验 NodeType::Animation 的 id,StateMachine 被跳过;这里对 document->animations 中每个 SM 节点都 emplace_back。而 PAGScene::getStateMachineTimeline(id)(PAGScene.cpp:475-509)按 id 只匹配第一个节点并返回缓存的同一个实例,因此两个同 id 的 SM 节点会得到同一个 shared_ptr 并两次进入 timelines。

影响:nextFrame() 的循环对每条 timeline 各调用一次 advanceAndApply,该状态机每帧被推进两次 → 2 倍速并且 apply 两次。文档本身虽带 "Duplicate node id" 错误但不会阻止加载,exporter 也不检查 document->errors,于是静默输出错误结果。

建议:plan->timelines 入栈前按实例指针去重;同时把 StateMachine 的 id 校验(非空 + 唯一)补进 ValidateDocumentAnimations,重复时直接报错而不是继续。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已修复,相关修改在 282b14b7a。

  • ValidateDocumentAnimations() 现在同时校验 Animation 和 StateMachine 的非空、唯一 id,同一集合也会阻止跨类型重复 id;
  • StateMachine 加入 plan->timelines 前按实例指针去重,避免缓存别名导致重复推进;
  • 公开 Make() 文档已同步说明两类节点的 id 约束;
  • 新增 MakeRejectsEmptyAndDuplicateStateMachineIds 回归测试。

相关单测已通过。

Comment thread include/pagx/VideoExporter.h Outdated
* `currentFrame() < frameCount()` to tell the two apart: a failure leaves the index
* unadvanced.
*/
bool nextFrame();

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.

【A1】nextFrame() 没有错误通道,失败原因对宿主不可见

证据:这里只返回 bool,文档让调用方用 currentFrame() < frameCount() 区分“结束”和“失败”。但失败原因是真实存在的:PAGScene::draw 在“surface 为空或没有内容”时返回 false(PAGScene.h:139),因此一个合法但内容为空的文档 Make() 成功之后,nextFrame() 会在第 0 帧永远失败;readPixels 失败同理。

影响:宿主只能上报“导出失败”,无法区分空文档 / GPU 读回失败 / 绘制失败,也无法给出可操作的提示;CLI 目前同样只能打印 failed to render frame 0。

建议:改为 bool nextFrame(std::string* errorMsg = nullptr) 或增加 lastError() const,并在注释中说明各类失败;至少对“无内容”这种可预期情形给出明确信息。若团队决定 v1 接受当前契约,请在类注释中写明“失败原因不可得”,避免宿主按错误假设接入。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已补充错误通道,相关修改在 282b14b7a 和 0b9fc8874。

nextFrame() 现在签名为 bool nextFrame(std::string* errorMsg = nullptr):

  • 正常结束返回 false,并清空旧错误;
  • 绘制失败返回具体帧号;
  • 像素回读失败返回具体帧号;
  • CLI 的 RunVideoFrames() 会输出该具体错误,只有错误为空时才回退到原来的通用提示。

另外实测确认,空文档当前可以正常输出透明帧,并不会触发 draw 失败,因此没有改变这一行为。绘制失败测试改为在有效文档上显式置空内部 surface,确定性覆盖错误传递路径。相关单测已通过。

Comment thread src/cli/CommandExport.cpp
@@ -131,6 +331,12 @@ static int ParseOptions(int argc, char* argv[], ExportOptions* options) {
options->pptBakeUnsupported = false;

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.

【B2】矢量/PPT 专属参数对 mp4 静默忽略,与反向校验不对称

证据:--svg-indent(:318)、--svg-no-xml-declaration(:326)、--text-to-path(:328)、--ppt-no-bake-unsupported(:330)、--ppt-ignore-glyphruns(:332)只写入 ExportOptions,均未调用 MarkVideoOnlyOption;ExportToMP4 / BuildVideoExportOptions 也从不读取它们。反方向已有校验:ResolveExportOptions(:282-286)会对非视频格式报 “ is only supported for video formats”。

影响:pagx export -o a.mp4 --text-to-path --svg-indent 4 退出码为 0,但两项都没有生效,用户会误以为文字已转曲、缩进已应用。

建议:与 firstVideoOnlyOption 对称,记录“仅矢量/PPT 格式”的选项,在选择 mp4 时明确报错;或在 help 中标注这些参数对 mp4 无效。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已修复,相关修改在 282b14b7a。

新增与视频参数校验对称的非视频参数记录,在输出 MP4 时明确拒绝:

  • --svg-indent
  • --svg-no-xml-declaration
  • --text-to-path
  • --ppt-no-bake-unsupported
  • --ppt-ignore-glyphruns

错误信息为 <option> is not supported for video formats (mp4),不再静默成功。已新增五个参数的 MP4 拒绝测试,相关单测已通过。

Comment thread CMakeLists.txt Outdated
set(PAG_BUILD_SHARED OFF)
endif ()

# VideoExporter is native-only in the current support matrix. Respect an explicit user override.

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.

【C1】注释与行为不符;PAG_BUILD_PAGX=OFF 时仍会注入 PAG_BUILD_VIDEO_EXPORTER 宏

证据:注释写 “Respect an explicit user override”,但 -DPAG_BUILD_VIDEO_EXPORTER=OFF 与 CLI/TESTS 同时出现时直接 FATAL_ERROR(:225-226),这是“拒绝”而不是“尊重”。另外 :229-231 只要该开关为真就向 PAG_DEFINES 追加宏,而 PAG_DEFINES 通过 target_compile_definitions(pag PUBLIC …)(:1043)导出;option(PAG_BUILD_VIDEO_EXPORTER … ON) 默认 ON,若 PAG_BUILD_PAGX=OFF,src/pagx/VideoExporter.cpp 根本不会被编译(:318-327),但宏仍会定义给所有 pag 消费者。

影响:(a) 注释误导用户以为可以关闭;(b) PAG_BUILD_PAGX=OFF 时出现“宏已定义但没有实现”的组合,消费者容易写出能编译、却在链接或运行期出问题的代码。

建议:把注释改为“CLI/TESTS 依赖该模块,显式关闭会报错”;并把宏注入条件收紧为 if (PAG_BUILD_PAGX AND PAG_BUILD_VIDEO_EXPORTER)。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已修复,相关修改在 282b14b7a。

  • 注释已改为明确说明 CLI/TESTS 依赖 VideoExporter,显式关闭会报错;
  • 宏注入条件已收紧为 if (PAG_BUILD_PAGX AND PAG_BUILD_VIDEO_EXPORTER)。

因此 PAG_BUILD_PAGX=OFF 时不会再向 pag 消费者传播没有对应实现的 PAG_BUILD_VIDEO_EXPORTER 宏。

Comment thread src/pagx/VideoExporter.cpp Outdated
if (width == nullptr || height == nullptr) {
return false;
}
return ComputeOutputDimension(documentWidth, scale, padToEvenSize, width) &&

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.

【A3】尺寸计算返回 false 时可能已写入 *width

证据:A && B 是短路求值,而 ComputeOutputDimension 成功时就会写 *dimension(:55-58)。宽度成功、高度失败时 *width 已被更新、*height 仍是旧值,与本函数“失败即结果无效”的隐含契约不符(Make() 的错误处理和 CLI 的调用方式都按全有或全无理解)。

影响:当前三个调用点在 false 时都会提前返回,暂无实际故障;但任何后续调用方若在失败后继续使用两个 out 参数,会读到半更新的尺寸,属于易被复用的内部 API 隐患。

建议:先算到局部变量,两者都成功后再一次性写出;或在 VideoExportInternal.h 注明“失败时 out 参数内容未定义”。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已修复,相关修改在 282b14b7a。

ComputeVideoOutputDimensions() 现在先计算到局部 computedWidth 和 computedHeight,两个维度都成功后才一次性写入调用方的 out 参数;任一维度失败时,两个输出值都保持不变。

新增 OutputDimensionsAreAllOrNothing 测试,使用宽度合法、高度非法且带初始值的 out 参数验证全有或全无语义。相关单测已通过。

matrix:
os:
- ubuntu-latest
- windows-latest

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.

【C4】新增的 windows-latest job 只跑下载器单测,仍未编译 pagx-cli

证据:这个 job(:196-229)只执行 npm run generate:ffmpeg-manifest 和 npm run test:ffmpeg;build.yml 的 win job(:444-484)构建的是 win/Win32Demo.sln,linux job(:485-534)走 linux/build_pag.sh + demo CMake,都不传 PAG_BUILD_CLI。因此本 PR 新增的 src/cli/VideoEncoderProcess_win.cpp、CliUtils 中的 UTF8ToWide/QuoteWindowsArg、以及 Advapi32 链接,在 CI 中从未被编译过。

影响:最近的 9491cafd1(MSVC C2664:IsExecutableFile 收到 std::filesystem::path)就是这类问题——只有在作者本地 Windows 构建时才被发现,否则会在发布阶段暴露。

建议:在 win / linux job 增加一次 cmake -DPAG_BUILD_CLI=ON 的构建(不必运行测试),把 Windows/POSIX 的 CLI 编译纳入门禁。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

已补充 CLI 编译门禁,相关修改在 2f38ebad2。

为控制 runner 和依赖拉取成本,没有新增独立 job,而是在 build.yml 现有的 Windows 和 Linux runner 中复用已完成的 checkout、depsync 和 third-party 缓存,追加发布流水线同款命令:

node build_pag pagx-cli -a x64 -i -DPAG_BUILD_CLI=ON -DPAG_BUILD_SHARED=OFF

Windows 在 Win32Demo 构建后执行,并分别检查两个原生命令的退出码;Linux 在现有 demo 构建前执行。任一侧 CLI 编译或链接失败都会使现有 build job 失败。

本次只增加 Windows/Linux 的 CLI 编译和链接验证,没有扩展完整单测车道;完整 native 单测仍由现有 macOS OpenGL/Metal 车道负责。

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

补充说明本次 tgfx 升级及 test/baseline/version.json 变化的原因。

Linux CLI 编译门禁启用后,GCC 15 在 tgfx TileCache.cpp 等文件中暴露出缺少 <cstdint> 的既有问题。为此将 tgfx 更新到 main 最新的 a3349d9a(提交 f1fb9737c),其中包含 Add missing cstdint includes to fix the GCC 15 build。

这次同步同时带入了上游 PR #1626 的高斯模糊优化:小核模糊使用数学等价的单 pass 二维卷积,减少中间 render target 和舍入。由此产生了精确的截图 MD5 差异,所以需要接受对应基线,而不是保留旧版本号让 CI 失败。

我已分别生成并审核 OpenGL SwiftShader 的 91 组和 Metal 的 28 组新旧截图:

  • OpenGL 最低 SSIM 为 0.999996,最低 PSNR 为 76.05 dB;
  • Metal 最低 SSIM 为 0.999997,最低 PSNR 为 81.97 dB;
  • Metal 最大通道差值仅为 2/255;
  • 未发现几何位置、内容、颜色、阴影方向或模糊范围的可见变化。

确认这些差异属于上游预期的中间精度变化后,已分别完成 OpenGL 和 Metal 的基线接受流程。version.json 的 100 项版本更新记录在提交 996a387b4,不是手工编辑;Metal 接受后没有新增 diff,是因为相关 key 已包含在这批版本更新中。

* the end with sensible defaults so that callers compiled against an older header continue to
* link and behave correctly. Reordering, removing, or changing the type of an existing field is
* a breaking change.
* This struct is part of the public API but does not promise binary ABI stability. Callers and

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.

没改代码,不需要修改注释吧

/** A rational sampling rate in frames per second. Zero numerator with denominator 1 means auto. */
struct VideoFrameRate {
/** Creates a frame rate from a numerator and denominator. */
constexpr VideoFrameRate(int64_t numeratorValue = 0, int64_t denominatorValue = 1)

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.

这个函数形参命名太过于抽象了,分子和分母,使用实际有意义的命名

int64_t numerator = 0;

/** Frame-rate denominator. Explicit rates must use a positive denominator. */
int64_t denominator = 1;

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.

注意下规范化这两个变量的命名

/** A rational sampling rate in frames per second. Zero numerator with denominator 1 means auto. */
struct VideoFrameRate {
/** Creates a frame rate from a numerator and denominator. */
constexpr VideoFrameRate(int64_t numeratorValue = 0, int64_t denominatorValue = 1)

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.

【API】隐式转换会把浮点帧率静默截断,与“拒绝取整”的设计目标矛盾

证据:这个构造函数非 explicit,参数是 int64_t,因此宿主写出下面这种最常见的写法时编译通过,但值被静默截断:

pagx::VideoExportOptions options;
options.frameRate = 29.97;      // 实际变成 {29, 1},不报错

我用最小复现片段在 clang(-std=c++17)上验证过:编译成功,仅有一条 -Wliteral-conversion 警告;MSVC 默认警告级别下不会有提示。这与 :84-88 的文档承诺直接冲突——“A non-integer document frame rate is rejected in this mode instead of being guessed or rounded”;正是因为要避免取整才引入有理数类型,却留了一个静默取整的赋值入口。

影响:从 ffprobe/WebCodecs/系统 API 拿到 double fps 的宿主几乎一定会这样赋值,结果是 29.97 → 29、23.976 → 23,导出视频时长与音画同步随之偏移,且 CLI 会把 -framerate 29 传给 ffmpeg,用户完全看不到警告。

建议(二选一):

  1. 加一个删除的重载,把错误前移到编译期,且不影响现有的 frameRate = {0, 1}:
VideoFrameRate(double) = delete;
  1. 或把构造函数改为 explicit,默认成员初始化改成 VideoFrameRate frameRate{0, 1};,文档给宿主示范 VideoFrameRate(30000, 1001)。

若希望支持宿主从浮点值初始化,可额外提供带校验的 static VideoFrameRate FromFramesPerSecond(double)(内部换算成近似分数或明确报错),而不是依赖隐式转换。

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.

3 participants