动图魔方 HarmonyOS 方案（21）：视频抽帧到 PixelMap 的管线边界
一、抽帧质量由采样契约决定
视频转 GIF 的第一步不是循环调用取帧接口，而是把“用户想要的时间范围”翻译成可执行的采样计划。源视频可能是可变帧率、超高分辨率或只有少量关键帧；如果直接用duration × fps生成全部时间点，会同时放大耗时、内存和重复帧问题。
本方案把抽帧管线分为探测、计划、获取、交接和清理五个阶段。输出是受所有权约束的PixelMap帧流，不包含调色板量化、LZW 编码和文件保存。运行证据需要在真机上验证，因此文章保持方案定位，不用静态代码替代性能结论。
| 输入约束 | 归一化规则 | 目的 |
|---|---|---|
| fps | 限制在 1–30 | 避免无意义的高频采样 |
| duration | 限制在有效媒体范围 | 不请求越界时间点 |
| frameCount | 同时受时长和硬上限约束 | 控制内存与等待时间 |
| targetMaxEdge | 按画质档限制长边 | 避免保留原始超大帧 |
| startSec | 不小于 0 | 支持裁剪后的局部抽帧 |
二、探测阶段只保留尺寸信息
管线先获取一张探测帧，用来读取源尺寸和确认媒体源可解码。探测帧完成使命后立即释放，不能和正式帧一起保留。随后依据长边上限计算目标宽高，保持原始宽高比，并把最终尺寸写入采样计划。
export interface VideoProbe { sourceWidth: number sourceHeight: number targetWidth: number targetHeight: number durationUs: number } export async function probeVideo( generator: VideoImageGenerator, startUs: number, maxEdge: number ): Promise<VideoProbe> { const frame = await generator.fetchFrame(startUs, {}) try { const info = await frame.getImageInfo() const target = fitWithin(info.width, info.height, maxEdge) return { ...target, durationUs: generator.durationUs } } finally { await frame.release() } }探测失败时不进入正式循环。文件句柄和生成器由外层生命周期统一释放，错误转换为“文件不可读取”“视频格式不支持”或“媒体元数据异常”等稳定类型，页面不展示底层异常字符串。
三、采样计划是可测试的纯数据
采样点用整数微秒表示，避免浮点误差在长视频中逐步累积。计划生成器先裁剪用户区间，再根据帧数上限计算步长。最后一个时间点必须小于区间结束位置，防止请求刚好落在媒体尾部之外。
export interface FrameSamplePlan { startUs: number endUs: number stepUs: number timestampsUs: number[] } export function buildSamplePlan( startSec: number, durationSec: number, fps: number, maxFrames: number ): FrameSamplePlan { const startUs = Math.max(0, Math.round(startSec * 1_000_000)) const durationUs = Math.max(100_000, Math.round(durationSec * 1_000_000)) const expected = Math.max(1, Math.round(durationSec * fps)) const count = Math.min(expected, maxFrames) const stepUs = Math.max(1, Math.floor(durationUs / count)) const timestampsUs = Array.from( { length: count }, (_, index) => startUs + index * stepUs ) return { startUs, endUs: startUs + durationUs, stepUs, timestampsUs } }这段逻辑可以独立测试 0.1 秒片段、三十秒上限、低帧率视频和用户裁剪区间。可变帧率素材仍可能在邻近时间点返回相同画面，去重属于后续优化，不能通过减少时间点掩盖。
四、逐帧获取需要背压而不是无界数组
一次返回全部PixelMap[]简单，却把内存峰值交给调用方。更稳妥的契约是生产者每取到一帧就交给消费者处理；消费者确认完成后生产者才继续。若现阶段必须使用数组，也要以帧数、尺寸和估算字节数三重上限限制。
export interface OwnedFrame { index: number timeUs: number pixelMap: PixelMap width: number height: number } export interface FrameConsumer { consume(frame: OwnedFrame): Promise<void> } export async function extractWithBackpressure( plan: FrameSamplePlan, generator: VideoImageGenerator, consumer: FrameConsumer, signal: ExportSignal ): Promise<void> { for (let index = 0; index < plan.timestampsUs.length; index++) { signal.checkCancelled() const pixelMap = await generator.fetchFrame(plan.timestampsUs[index]) const info = await pixelMap.getImageInfo() await consumer.consume({ index, timeUs: plan.timestampsUs[index], pixelMap, width: info.width, height: info.height }) signal.report(index + 1, plan.timestampsUs.length, '抽取视频帧') await yieldToUi() } }这里的关键是所有权约定：consume()接收帧后负责释放；若交接前发生异常，生产者负责释放。接口文档必须写清楚责任，否则两边都释放会导致无效对象，两边都不释放则会持续抬高内存。
五、用资源作用域封住文件和生成器
视频文件句柄、图像生成器与单帧对象的生命周期不同。外层作用域负责文件和生成器，内层作用域负责尚未成功交接的帧。取消、坏帧或消费者失败都必须进入finally。
export async function runVideoExtraction( filePath: string, task: (generator: VideoImageGenerator) => Promise<void> ): Promise<void> { const file = openReadOnly(filePath) const generator = await createVideoImageGenerator() try { generator.setFdSource(file.fd) await task(generator) } finally { try { await generator.release() } finally { closeFile(file) } } } export async function handoffFrame( frame: PixelMap, consumer: FrameConsumer, owned: OwnedFrame ): Promise<void> { let transferred = false try { await consumer.consume(owned) transferred = true } finally { if (!transferred) await frame.release() } }六、坏帧策略必须区分跳过和终止
某个时间点取帧失败不一定意味着整段视频不可用。允许连续跳过少量坏帧，但需要设置最大失败次数和最小成功帧数；若第一帧就失败、连续失败超过阈值或最终没有帧，任务终止。成功帧不足时页面提示降低帧率或缩短区间，而不是悄悄输出与预期差异巨大的 GIF。
| 失败类型 | 默认策略 | 任务结果 | 可恢复建议 |
|---|---|---|---|
| 文件无法打开 | 立即终止 | 无输出 | 重新选择文件 |
| 探测帧失败 | 立即终止 | 无输出 | 检查格式或权限 |
| 单个时间点失败 | 记录并跳过 | 继续 | 保留失败时间点 |
| 连续三帧失败 | 终止 | 释放已持有帧 | 降低 fps 或缩短区间 |
| 用户取消 | 立即停止新请求 | 清理资源 | 保留编辑参数 |
| 成功帧少于两帧 | 不进入编码 | 无输出 | 调整采样范围 |
七、进度和取消属于管线协议
进度不能只报告循环索引，还要带阶段：探测、抽帧、处理和编码。页面据此显示“正在读取视频”或“正在处理第 N 帧”，取消按钮则共享同一个ExportSignal。每帧后让出事件循环，避免长循环阻塞状态刷新；但让出不等于并行，多任务同时抽帧仍需全局并发限制。
取消后消费者释放当前帧，生产者停止请求下一帧，外层关闭生成器和文件。若已经进入编码阶段，抽帧器不再拥有帧资源，取消责任随所有权一起交给处理器。清晰的阶段交接能避免“按钮显示已取消，后台仍继续占用内存”。
八、验收指标必须在真机采集
实施顺序是先落地采样计划与资源作用域，再接入逐帧消费者，随后加入坏帧阈值和取消，最后优化去重与并发。构建通过只能证明接口可编译，不能证明帧尺寸、耗时或内存峰值。
后续证据计划包含：三种分辨率、三种时长和两种帧率的真机矩阵；每个样本记录目标帧数、成功帧数、首尾尺寸、总耗时和峰值内存；取消后确认文件句柄与生成器释放；损坏视频验证错误页。图像与媒体处理的官方能力入口可参考华为 HarmonyOS 开发文档。
九、总结
稳定的视频抽帧管线依赖三个边界：纯数据的采样计划、带背压的帧交接、覆盖所有退出路径的资源作用域。把这三点建立起来，后续的裁剪、滤镜、量化和 GIF 编码才能在可控的帧数、尺寸与内存预算上继续工作。