HarmonyOS AVMetadataExtractor 媒体探针实战：元数据读取、封面帧获取与资源释放

本地视频列表第一次打开时，常见的卡顿并不一定来自图片解码，而是页面同时创建多个媒体解析器、重复打开同一个文件描述符，又在列表滚出屏幕后忘记释放封面 PixelMap。更隐蔽的问题是：开发阶段只拿一段标准 MP4 验证，到了用户设备上遇到没有封面、时长缺失或容器格式不支持的文件，整个列表便因为一次异常而中断。

AVMetadataExtractor 适合承担“读取媒体事实”的职责：标题、作者、时长、宽高、专辑封面以及指定时间的视频帧。它不是播放器，也不负责管理页面缓存。本文以“文件详情页生成媒体摘要”为例，把数据源所有权、异步读取、封面降级和资源释放串成一条可以迁移到项目中的闭环。

1. 先明确媒体探针解决什么，不解决什么

详情页需要的是一份轻量摘要，而不是把媒体完整播放一遍。探针层只回答以下问题：这个资源能否解析、有哪些可用字段、有没有可展示封面、使用结束后哪些对象必须归还。

export interface MediaSummary {
  sourceId: string;
  title: string;
  artist: string;
  durationMs: number;
  width: number;
  height: number;
  hasCover: boolean;
}

export type ProbeState = 'idle' | 'loading' | 'ready' | 'unsupported' | 'failed';

MediaSummary 不保存文件描述符，也不保存解析器实例。页面拿到的是可展示结果，底层资源仍由探针服务管理。这样列表缓存摘要时不会意外延长 FD 和原生解析器的生命周期。

2. 环境、接口版本与适用边界

本文示例以 Stage 模型、ArkTS、HarmonyOS SDK API 23 声明为基线，使用 @kit.MediaKit 的 media.AVMetadataExtractor。核心能力从 API 11 起可用；fetchFrameByTime() 与 setUrlSource() 从 API 20 起提供。项目若设置更低的 compatibleSdkVersion，应只保留元数据和音频专辑封面路径。

能力	接口	起始版本	这里的用途
创建解析器	createAVMetadataExtractor()	11	每次探针会话独立创建
本地资源	fdSrc	11	绑定 FD、偏移和长度
读取字段	fetchMetadata()	11	生成媒体摘要
音频封面	fetchAlbumCover()	11	读取内嵌专辑图
视频画面	fetchFrameByTime()	20	获取指定时间附近的帧
网络资源	setUrlSource()	20	绑定 HTTPS 媒体地址

模拟器、设备支持范围和具体容器格式应以目标 SDK 文档为准。文章中的示例不会假设所有媒体都存在标题、作者或封面。

3. FD 的所有权是第一道边界

把 FD 交给解析器后，不要再把同一个句柄同时交给播放器、转码器或另一个解析器。并发争用可能让读取位置互相干扰，最终表现为偶发空字段或解析失败。更稳的做法是由上层为一次探针操作提供独占 FD，并在解析器释放后再关闭它。

import { media } from '@kit.MediaKit';

export interface OwnedMediaSource {
  fd: number;
  offset: number;
  length: number;
  close: () => void;
}

function bindLocalSource(
  extractor: media.AVMetadataExtractor,
  source: OwnedMediaSource
): void {
  extractor.fdSrc = {
    fd: source.fd,
    offset: source.offset,
    length: source.length
  };
}

这里把 close() 一并交给会话，是为了让“谁打开、谁关闭”可追踪。offset 和 length 不能随意写成 0；当资源来自连续资产或文件片段时，应传入真实区间。

4. 一次完整解析必须形成资源闭环

正确顺序是：创建解析器、绑定唯一数据源、读取字段、按需获取图像、释放图像、释放解析器、关闭 FD。任何提前返回都应进入 finally，而不是依赖页面销毁时由系统兜底。

import { media } from '@kit.MediaKit';

export async function probeLocalMedia(
  sourceId: string,
  source: OwnedMediaSource
): Promise<MediaSummary> {
  const extractor = await media.createAVMetadataExtractor();
  try {
    bindLocalSource(extractor, source);
    const metadata = await extractor.fetchMetadata();
    return toSummary(sourceId, metadata);
  } finally {
    await extractor.release();
    source.close();
  }
}

finally 的价值不只是在成功路径释放。格式不支持、资源已损坏、业务取消请求时，它同样执行。注意释放顺序：先结束依赖 FD 的解析器，再关闭 FD。

5. 元数据字段要做缺省与数值归一

媒体字段多数是可选值。UI 直接渲染 metadata.title! 会把“测试文件恰好有标题”误当成接口保证。工程层应统一处理空字符串、无法转换的数值和异常时长。

import { media } from '@kit.MediaKit';

function positiveInt(value: number | undefined): number {
  if (value === undefined || !Number.isFinite(value) || value < 0) return 0;
  return Math.round(value);
}

function toSummary(sourceId: string, data: media.AVMetadata): MediaSummary {
  return {
    sourceId,
    title: data.title?.trim() || '未命名媒体',
    artist: data.artist?.trim() || '未知作者',
    durationMs: positiveInt(data.duration),
    width: positiveInt(data.videoWidth),
    height: positiveInt(data.videoHeight),
    hasCover: false
  };
}

字段单位以当前 SDK 声明为准，升级 SDK 时应重新核对。不要通过“数值看起来像秒还是毫秒”来猜单位，也不要把缺失值伪装成业务上的真实 0 后参与统计。

6. 音频封面缺失属于正常分支

fetchAlbumCover() 返回 PixelMap，但音频没有内嵌封面、封面编码不受支持时可能失败。详情页不应因此把整份元数据显示为失败；更合理的策略是保留摘要，封面位置显示业务占位图。

import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

export async function withAlbumCover<T>(
  extractor: media.AVMetadataExtractor,
  render: (cover: image.PixelMap) => Promise<T>
): Promise<T | undefined> {
  let cover: image.PixelMap | undefined;
  try {
    cover = await extractor.fetchAlbumCover();
    return await render(cover);
  } catch (error) {
    console.info(`album cover unavailable: ${JSON.stringify(error)}`);
    return undefined;
  } finally {
    if (cover !== undefined) await cover.release();
  }
}

示例把封面的使用范围限制在回调里，避免调用方把已经释放的对象存进全局状态。若页面确实需要长期展示，应在释放前转换为项目自己的缓存格式，并明确缓存淘汰策略。

7. 视频缩略图应选择“足够代表内容”的时间点

视频第 0 微秒常常是黑帧、片头或尚未完成解码的关键帧。可以根据时长选择 10% 附近，同时限制最大时间，避免长视频把取帧位置推得过远。AV_IMAGE_QUERY_CLOSEST_SYNC 通常比强求任意最近帧更适合列表缩略图，因为关键帧路径开销更可控。

import { image } from '@kit.ImageKit';
import { media } from '@kit.MediaKit';

export async function fetchPreviewFrame(
  extractor: media.AVMetadataExtractor,
  durationMs: number
): Promise<image.PixelMap> {
  const targetMs = Math.min(Math.max(durationMs * 0.1, 1000), 30_000);
  return extractor.fetchFrameByTime(
    Math.round(targetMs * 1000),
    media.AVImageQueryOptions.AV_IMAGE_QUERY_CLOSEST_SYNC,
    { width: 640, height: 360 }
  );
}

接口的时间参数是微秒，因此毫秒需要乘以 1000。输出宽高不能超过原视频尺寸；对于竖屏视频，固定 640 × 360 还可能破坏比例，生产项目应先读取宽高后按比例计算目标尺寸。

8. 解析层与页面层不要共享原生对象

业务页面负责发起选择与展示状态；数据源层负责打开独占句柄；解析层负责绑定、读取和释放；图像结果在展示或编码完成后立即释放。页面只长期持有 MediaSummary 与缓存键，不长期持有 AVMetadataExtractor。

export interface ProbeResult {
  summary: MediaSummary;
  coverCacheKey?: string;
}

export interface MediaProbeRepository {
  probe(sourceId: string): Promise<ProbeResult>;
  cancel(sourceId: string): void;
}

这个接口刻意没有暴露 FD、解析器和 PixelMap。上层可以替换数据源实现，也可以在列表滚动时取消尚未开始的任务，而不会跨层操作原生资源。

9. 列表并发不能等于文件数量

一次性对 200 个视频调用 Promise.all() 会同时占用大量 FD、解析器和图像内存。缩略图列表更适合使用小并发队列，并优先处理可见项。下面的队列只演示并发上限，实际项目还应加入滚动取消和缓存命中。

class ProbeLimiter {
  private running: number = 0;
  private readonly waiters: Array<() => void> = [];

  constructor(private readonly limit: number = 2) {}

  async run<T>(task: () => Promise<T>): Promise<T> {
    if (this.running >= this.limit) {
      await new Promise<void>((resolve) => this.waiters.push(resolve));
    }
    this.running += 1;
    try {
      return await task();
    } finally {
      this.running -= 1;
      this.waiters.shift()?.();
    }
  }
}

限制值应通过真机内存与滚动体验决定，而不是越大越快。对于同一 sourceId，还应合并重复请求，避免列表重组时重复解析。

10. 网络媒体必须单独处理安全与失败语义

API 20 起可以通过 setUrlSource() 绑定网络媒体，并可传请求头。在线资源存在超时、重定向、鉴权过期和明文 HTTP 限制，不应和本地 FD 分支共用同一错误提示。

import { media } from '@kit.MediaKit';

async function probeRemote(url: string, token: string): Promise<media.AVMetadata> {
  const extractor = await media.createAVMetadataExtractor();
  try {
    extractor.setUrlSource(url, { Authorization: `Bearer ${token}` });
    return await extractor.fetchMetadata();
  } finally {
    await extractor.release();
  }
}

请求头不要输出到日志。若接口返回明文流量不允许，应修正资源地址和网络安全策略，而不是在代码里忽略错误。媒体 URL 有有效期时，缓存键也不应直接使用完整带签名地址。

11. 页面取消不是强行销毁正在使用的对象

用户快速离开页面时，可以阻止结果回写，但不要在另一个异步任务仍执行 fetchMetadata() 时并发调用 release()。简单可靠的方式是会话内串行拥有解析器，完成后统一释放；取消标记只控制是否继续生成图像和是否提交 UI。

class ProbeSession {
  private cancelled: boolean = false;

  cancel(): void {
    this.cancelled = true;
  }

  canContinue(): boolean {
    return !this.cancelled;
  }
}

若目标 API 提供专门取消接口，应优先使用接口语义。没有取消接口时，不要用并发释放模拟取消，否则容易制造悬空引用。

12. 错误要映射成用户能理解的状态

建议区分“资源不支持”“文件不可访问”“请求已取消”“内部失败”。底层错误码保留在受控日志中，UI 不直接展示原始异常对象。

页面状态	典型原因	页面策略	排查入口
unsupported	容器或编码不受支持	展示通用媒体图标	核对格式与设备能力
failed	FD 无效、文件截断	允许用户重试	核对 offset、length 与文件状态
ready 无封面	资源未内嵌图片	使用占位图	不视为整条任务失败
idle	任务被滚动取消	不显示错误弹窗	查看可见项调度

失败处理的目标是保留可用信息。封面失败不应抹掉时长，作者缺失也不应阻止视频宽高展示。

13. 真机验证要覆盖“坏文件”和快速滚动

只验证一份标准资源不足以说明闭环稳定。至少准备以下样本：有内嵌封面的音频、无封面的音频、横屏视频、竖屏视频、被截断文件、不支持格式、较长视频和在线 HTTPS 资源。

操作：连续进入并退出详情页 30 次
预期：FD 数量回落，内存不持续增长，页面无旧结果回写

操作：列表快速滑过 100 个媒体项
预期：只处理可见任务，并发不超过设定上限

操作：打开无封面音频
预期：摘要仍显示，封面使用占位图

操作：打开损坏文件
预期：单项进入失败状态，其余列表继续工作

还应在真机上观察应用前后台切换。后台期间如果页面不再需要缩略图，应暂停新任务，而不是继续消耗解码资源。

14. 常见故障的定位顺序

现象	优先查看	修正方式
偶发字段为空	同一 FD 是否被多对象复用	每次会话独占打开句柄
列表越滑越卡	PixelMap 与解析器是否释放	将释放放进 finally
视频缩略图全黑	是否固定取第 0 微秒	选择非零时间并靠近关键帧
竖屏缩略图变形	输出尺寸是否固定横屏比例	按原始宽高计算目标尺寸
在线资源始终失败	URL、鉴权头与明文流量策略	使用 HTTPS 并保护请求头
页面退出后闪回旧图	结果是否带会话标识	提交 UI 前核对当前请求

先查所有权和释放，再查媒体内容本身。很多“格式问题”最终是 FD 被复用或对象没有及时归还。

15. 完成前验收清单与资料索引

[ ] 每次探针会话拥有独立数据源句柄
[ ] offset 与 length 来自真实资源区间
[ ] 可选元数据统一做缺省和数值归一
[ ] 音频无封面不会导致摘要整体失败
[ ] 视频取帧使用微秒，并保持原始宽高比
[ ] PixelMap、AVMetadataExtractor 和 FD 均在 finally 中释放
[ ] 列表解析有并发上限、重复请求合并和取消策略
[ ] 网络地址使用 HTTPS，鉴权头不写日志
[ ] 真机覆盖损坏资源、快速滚动和前后台切换

资料来源：

• 华为开发者文档：使用 AVMetadataExtractor 提取音视频元数据信息
• 华为开发者文档中心：Media Kit API
• 本机 D:/harmonyos/SDK/23/ets/api/@ohos.multimedia.media.d.ts，用于核对 API 23 的接口签名与起始版本。

媒体探针真正困难的部分不是调用一次 fetchMetadata()，而是让句柄、解析器、图像结果和页面状态具有清晰所有权。把这些对象限制在一次会话内，缺失字段按正常分支处理，再给列表加上并发与取消边界，媒体摘要才能从演示代码变成可长期运行的工程能力。