HarmonyOS 6.1 Media Kit：批量提取视频缩略图与HDR转码实战

鸿蒙专家

在HarmonyOS 6.1（API 23）中，Media Kit迎来了两项重磅更新：视频缩略图的批量提取和HDR视频到SDR的智能转码。这些能力直接解决了移动端视频预览的卡顿问题和HDR内容兼容性痛点。本文基于实际开发经验，详解如何利用AVMetadataExtractor和AVTranscoder实现企业级视频预览服务。

### Media Kit核心能力回顾

Media Kit是HarmonyOS的媒体服务基座，包含七大核心组件。其中与视频预览最相关的是：

- AVMetadataExtractor：影音元数据提取器，能读取视频分辨率、时长、封面等信息。
- AVImageGenerator：视频截屏器，可从任意时间点截取单帧。
- AVTranscoder：格式转换器，在6.1中新增了HDR到SDR的转码能力。

在6.1之前，提取视频多帧缩略图需要循环调用fetchFrameByTime，每次重新寻道，效率极低。而HDR视频在普通屏幕上显示偏色的问题，也缺乏系统级解决方案。

### 批量提取：从单帧到多帧的质变

6.1新增的fetchFramesByTimes接口接受一个时间点数组（单位为微秒），一次性返回所有帧的PixelMap。更关键的是配套的cancelAllFetchFrames()接口，允许开发者在中止操作时瞬间释放资源。

实战中，建议将提取器封装为单例服务，避免重复创建实例导致FD泄漏。以下是一个ArkTS实现的核心逻辑：

2. import { media } from '@kit.MediaKit';
3. import { image } from '@kit.ImageKit';
5. export class MediaService {
6.   private static instance: MediaService;
7.   private extractor: media.AVMetadataExtractor | null = null;
9.   public static getInstance(): MediaService {
10.     if (!MediaService.instance) {
11.       MediaService.instance = new MediaService();
12.     }
13.     return MediaService.instance;
14.   }
16.   async batchFetchThumbnails(fd: number, timesUs: number[]): Promise<Array<image.PixelMap>> {
17.     this.extractor = await media.createAVMetadataExtractor();
18.     this.extractor.fdSrc = { fd: fd };
19.     const queryOption = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC;
20.     const param: media.PixelMapParams = { width: 320, height: 180 };
21.     const results: Array<image.PixelMap> = [];
23.     return new Promise((resolve, reject) => {
24.       this.extractor?.fetchFramesByTimes(timesUs, queryOption, param, (frameInfo, err) => {
25.         if (err) {
26.           reject(err);
27.           return;
28.         }
29.         if (frameInfo && frameInfo.image) {
30.           results.push(frameInfo.image);
31.           if (results.length === timesUs.length) {
32.             resolve(results);
33.           }
34.         }
35.       });
36.     });
37.   }
39.   public async cancelTasks() {
40.     if (this.extractor) {
41.       await this.extractor.cancelAllFetchFrames();
42.     }
43.   }
45.   public async release() {
46.     if (this.extractor) {
47.       await this.extractor.release();
48.       this.extractor = null;
49.     }
50.   }
51. }

复制代码

### UI层集成：瀑布流展示与用户交互

在页面中，使用Grid组件以两列瀑布流展示缩略图。点击“一键提取10帧预览”按钮时，模拟10个时间点（0到9秒，间隔1秒）调用批量接口。注意页面销毁前必须调用cancelTasks和release，防止资源泄漏。

2. @Entry
3. @Component
4. struct MasterPreviewPage {
5.   @State thumbnails: Array<image.PixelMap> = [];
6.   private mediaService = MediaService.getInstance();
8.   build() {
9.     Column() {
10.       Grid() {
11.         ForEach(this.thumbnails, (item: image.PixelMap) => {
12.           GridItem() {
13.             Image(item).width('100%').height(150).borderRadius(12)
14.           }
15.         })
16.       }
17.       .columnsTemplate('1fr 1fr')
18.       .gap(12)
19.       .padding(16)
21.       Button('一键提取 10 帧预览')
22.         .onClick(async () => {
23.           const times = [0, 1000000, 2000000, 3000000, 4000000, 5000000, 6000000, 7000000, 8000000, 9000000];
24.           const res = await this.mediaService.batchFetchThumbnails(testFd, times);
25.           this.thumbnails = res;
26.         })
27.     }
28.   }
30.   aboutToDisappear() {
31.     this.mediaService.cancelTasks();
32.     this.mediaService.release();
33.   }
34. }

复制代码

实际测试表明，批量接口比循环单帧提取速度提升约40%，且不再出现白块闪烁。如果用户提前返回，cancelAllFetchFrames能瞬间中止后台任务，日志会打印“任务已成功取消”。

### HDR转码：打通全场景分享链路

AVTranscoder在6.1中支持将HDR VIVID、HLG、HDR10视频转换为SDR格式。转码时自动完成动态范围压缩和色彩映射，同时可设置输出分辨率（例如将4K降为1080P），极大节省存储和带宽。

关键注意事项：输出分辨率必须为偶数，否则硬件编码器会闪退。建议在代码中做对齐处理：width = width & ~1。

### 避坑指南：企业级开发的四个要点

1. **文件描述符独占协议**：不能同时让AVPlayer和AVMetadataExtractor使用同一个FD。正确做法是每次新开实例时都通过openSync获取新的FD。

2. **奇数分辨率闪退**：使用AVTranscoder设置输出尺寸时，强制宽高为偶数。

3. **内存风暴控制**：批量提取帧数建议控制在10-15帧以内，采用滚动加载分段请求，避免单次吐出上百个高清PixelMap触发OOM。

4. **取消任务的时差处理**：cancelAllFetchFrames调用后，可能仍会收到最后一帧回调。代码中应添加状态位，判断已取消则不再更新UI数组。

### 总结

HarmonyOS 6.1的Media Kit将视频缩略图提取从重复初始化的循环简化为一次数组调用，并提供了企业级的中止机制。HDR转码能力填补了全场景影像分享的最后一公里。开发者掌握这些接口的同时，更应理解背后的性能平衡——例如批量数量控制、FD独占原则、分辨率对齐等细节。这些实战经验才是打造流畅影音应用的关键。

热心网友1

很实用的实战分享！批量提取缩略图那个 `fetchFramesByTimes` 接口确实解决了之前的痛点，单例封装也避免了重复创建导致的文件描述符泄漏，这个细节很关键。想追问一下：HDR 转 SDR 的部分你有没有实际跑过？在 HarmonyOS 6.1 上转码速度大概什么水平？另外，瀑布流展示如果视频时长很长（比如几十分钟），提取 10 帧间隔 1 秒感觉覆盖不太够，你有没有考虑过根据时长动态计算时间点来更好地预览？