文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载导读ohos.multimedia.media媒体服务是 OpenHarmony 媒体子系统的核心仓颉 API 模块为开发者提供一套简单且易于理解的接口方便应用接入系统媒体资源。本指南聚焦其中与视频缩略图获取强相关的能力——AVImageGenerator视频缩略图生成器系统讲解从创建实例、描述媒体文件、按时间点抓帧到释放资源的完整调用链并结合 CangjieCorpus 仓库中的错误码文档与关联 Kit 源码帮助读者在仓颉模板工程中快速落地从任意时间点截取视频帧的实战方案。一、模块概览媒体子系统与 AVImageGenerator 的定位媒体子系统包含音视频相关媒体业务ohos.multimedia.media模块为开发者提供接入系统媒体资源的能力。在仓颉侧该模块当前以Beta 特性形式提供见 Media Kit 模块说明其中与本文主题直接相关的常用功能是获取视频缩略图AVImageGeneratorAVImageGenerator是一个典型的同步抓帧器开发者向它描述一段媒体文件文件句柄 偏移量 长度指定目标时间点与取帧策略即可获得对应的PixelMap缩略图。这一能力在视频列表封面、视频剪辑预览、短视频应用等场景中非常实用。二、开发前置准备2.1 导入模块在仓颉代码中通过 Kit 导入方式引入媒体能力import kit.MediaKit.*Kit 封装了同一 Kit 下各接口模块开发者通过导入MediaKit即可使用AVImageGenerator、AVFileDescriptor、PixelMapParams、AVImageQueryOptions等接口关于 Kit 导入机制的说明可参考 开发说明。2.2 权限列表调用本模块接口需要申请权限ohos.permission.MICROPHONE需要在应用配置文件如module.json5中声明该权限并遵守应用运行时权限申请流程。2.3 示例工程使用说明文档中的 API 示例代码遵循以下约定详见仓颉示例代码说明若示例代码首行有// index.cj注释表示该示例可在仓颉模板工程的index.cj文件中直接编译运行若示例需获取 Context 应用上下文需在仓颉模板工程中的main_ability.cj文件中进行配置获取当前应用沙箱所在路径可通过 UIAbilityContext.filesDir 获取。三、核心调用链总览视频缩略图获取的完整生命周期包含四个步骤创建实例调用createAVImageGenerator()构建AVImageGenerator描述数据源构造AVFileDescriptor并赋给generator.fdSrc按时间抓帧调用fetchFrameByTime()获取PixelMap缩略图释放资源调用release()释放底层资源。下面逐一展开。四、创建实例func createAVImageGenerator()public func createAVImageGenerator(): AVImageGenerator功能创建AVImageGenerator实例。系统能力SystemCapability.Multimedia.Media.AVImageGenerator起始版本22返回值类型说明AVImageGenerator返回AVImageGenerator实例。异常BusinessException对应错误码如下表详见 Media 错误码。错误码 ID错误信息5400101No memory.示例可在 index.cj 中编译运行// index.cj import kit.MediaKit.* import kit.PerformanceAnalysisKit.* import ohos.business_exception.BusinessException try { let generator createAVImageGenerator() } catch (e: BusinessException) { Hilog.error(0, AppLogCj, e.message) }五、描述媒体数据源class AVFileDescriptorAVFileDescriptor是音视频文件资源描述类型对应一种特殊资源的播放方式当应用中的音频/视频资源被连续存储在同一个文件中时需要根据偏移量和长度进行播放或抓帧。public class AVFileDescriptor { public var fd: Int32 public var offset: Int64 public var length: Int64 public init( fd: Int32, offset!: Int64 0, length!: Int64 -1 ) }系统能力SystemCapability.Multimedia.Media.Core起始版本225.1 var fd资源句柄public var fd: Int32功能资源句柄。类型Int32读写能力可读写该句柄有两种典型获取方式通过 getRawFd 获取 HAP 内置 rawfile 资源的文件描述符返回 RawFileDescriptor其包含fd、offset、length三个字段通过 open 打开应用沙箱内的文件获得句柄默认以OpenMode.READ_ONLY只读方式打开。5.2 var offset资源偏移量public var offset: Int64功能资源偏移量默认值为0。类型Int64读写能力可读写需要基于预置资源的信息输入非法值会造成音视频资源解析错误。5.3 var length资源长度public var length: Int64功能资源长度默认值为文件中从偏移量开始的剩余字节。类型Int64读写能力可读写需要基于预置资源的信息输入非法值会造成音视频资源解析错误。5.4 init(Int32, Int64, Int64)public init( fd: Int32, offset!: Int64 0, length!: Int64 -1 )参数说明参数名类型必填默认值说明fdInt32是-资源句柄通过 getRawFd 获取也可以通过 open 获取。offsetInt64否0命名参数。资源偏移量需要基于预置资源的信息输入非法值会造成音视频资源解析错误。lengthInt64否-1命名参数。资源长度默认值为文件中从偏移量开始的剩余字节需要基于预置资源的信息输入非法值会造成音视频资源解析错误。六、抓帧核心类class AVImageGeneratorpublic class AVImageGenerator {}功能视频缩略图获取类用于从视频资源中获取缩略图。在调用AVImageGenerator的方法前需要先通过 createAVImageGenerator() 构建一个AVImageGenerator实例。系统能力SystemCapability.Multimedia.Media.AVImageGenerator起始版本226.1 prop fdSrc媒体文件描述public mut prop fdSrc: AVFileDescriptor功能媒体文件描述通过该属性设置数据源。类型AVFileDescriptor读写能力可读写系统能力SystemCapability.Multimedia.Media.AVMetadataExtractor使用示例假设一个连续存储的媒体文件地址偏移为 0、字节长度为 100则其文件描述为AVFileDescriptor { fd 资源句柄; offset 0; length 100; }说明重要将资源句柄fd传递给AVImageGenerator实例之后不允许通过该资源句柄再执行其他读写操作包括但不限于将同一个资源句柄传递给多个AVPlayer/AVMetadataExtractor/AVImageGenerator/AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系将导致视频缩略图数据获取异常。异常BusinessException错误码如下表。错误码 ID错误信息5400101No memory.5400102Operation not allowed.6.2 func fetchFrameByTime(Int64, AVImageQueryOptions, PixelMapParams)public func fetchFrameByTime(timeUs: Int64, options: AVImageQueryOptions, param: PixelMapParams): PixelMap功能获取视频缩略图。系统能力SystemCapability.Multimedia.Media.AVImageGenerator起始版本22参数说明参数名类型必填默认值说明timeUsInt64是-需要获取的缩略图在视频中的时间点单位为微秒μs。optionsAVImageQueryOptions是-需要获取的缩略图时间点与视频帧的对应关系。paramPixelMapParams是-需要获取的缩略图的格式参数。返回值类型说明PixelMap视频缩略图。返回的 PixelMap 是图像像素类可用于读取或写入图像数据以及获取图像信息例如进一步交给 Image Kit 进行编码保存注意其序列化大小存在上限见 Image Kit 文档说明。异常BusinessException错误码如下表。错误码 ID错误信息5400101No memory.5400102Operation not allowed.5400106Unsupported format.完整示例可在 index.cj 中编译运行// index.cj import kit.MediaKit.* import kit.LocalizationKit.* import ohos.business_exception.BusinessException import kit.PerformanceAnalysisKit.Hilog try { let timeUs 0 let queryOption AVImageQueryOptions.AvImageQueryNextSync let param PixelMapParams(width: 300, height: 300) let generator createAVImageGenerator() let abilityContext Global.abilityContext // 此处需手动配置模板获取Context上下文。上下文获取方式请参见使用说明。 let rawFd abilityContext.resourceManager.getRawFd(trailer.mp4) // 请替换您的资源路径获取文件路径参考本文使用说明 generator.fdSrc AVFileDescriptor(rawFd.fd, offset: rawFd.offset, length: rawFd.length) let pic generator.fetchFrameByTime(timeUs, queryOption, param) generator.release() } catch (e: BusinessException) { Hilog.info(0, test, ${e.message}) }6.3 func release()public func release(): Unit功能释放资源。系统能力SystemCapability.Multimedia.Media.AVImageGenerator起始版本22异常BusinessException错误码如下表。错误码 ID错误信息5400101No memory.示例可在 index.cj 中编译运行// index.cj import kit.MediaKit.* import kit.LocalizationKit.* import kit.PerformanceAnalysisKit.* import ohos.business_exception.BusinessException try { let timeUs 0 let queryOption AVImageQueryOptions.AvImageQueryNextSync let param PixelMapParams(width: 300, height: 300) let generator createAVImageGenerator() let abilityContext Global.abilityContext // 此处需手动配置模板获取Context上下文。上下文获取方式请参见使用说明。 let rawFd abilityContext.resourceManager.getRawFd(trailer.mp4) generator.fdSrc AVFileDescriptor(rawFd.fd, offset:rawFd.offset, length:rawFd.length) let pic generator.fetchFrameByTime(timeUs, queryOption, param) generator.release() } catch (e: BusinessException) { Hilog.error(0, AppLogCj, e.message) }release()是实例生命周期的收尾动作与createAVImageGenerator()成对使用尤其在反复创建实例、频繁抓帧的场景下及时释放可避免句柄与内存资源占用。七、输出格式参数class PixelMapParamsPixelMapParams用于描述获取视频缩略图时输出缩略图的格式参数。public class PixelMapParams { public var width: Int32 public var height: Int32 public init(width!: Int32 -1, height!: Int32 -1) }系统能力SystemCapability.Multimedia.Media.AVImageGenerator起始版本227.1 var width / var heightpublic var width: Int32 public var height: Int32功能width输出的缩略图宽度应保证大于 0 且不大于原始视频宽度否则返回的缩略图不会进行缩放height输出的缩略图高度应保证大于 0 且不大于原始视频高度否则返回的缩略图不会进行缩放。类型Int32读写能力可读写7.2 init(Int32, Int32)public init(width!: Int32 -1, height!: Int32 -1)参数说明参数名类型必填默认值说明widthInt32否-1命名参数。输出的缩略图宽度。应保证大于 0 且不大于原始视频宽度否则返回的缩略图不会进行缩放。heightInt32否-1命名参数。输出的缩略图高度。应保证大于 0 且不大于原始视频高度否则返回的缩略图不会进行缩放。八、取帧策略枚举enum AVImageQueryOptions在获取视频缩略图时传入的时间点与实际取得的视频帧所在时间点不一定相等因此需要指定传入时间点与实际取得的视频帧的时间关系。AVImageQueryOptions即用于描述这一对应关系。public enum AVImageQueryOptions : EquatableAVImageQueryOptions ToString { | AvImageQueryNextSync | AvImageQueryPreviousSync | AvImageQueryClosestSync | AvImageQueryClosest | ... }系统能力SystemCapability.Multimedia.Media.AVImageGenerator起始版本22父类型EquatableAVImageQueryOptionsToString8.1 枚举取值语义取值功能AvImageQueryClosest表示选取离传入时间点最近的帧该帧不一定是关键帧。AvImageQueryClosestSync表示选取离传入时间点最近的关键帧。AvImageQueryNextSync表示选取传入时间点或之后的关键帧。AvImageQueryPreviousSync表示选取传入时间点或之前的关键帧。实际应用中若追求又快又稳的封面图通常选用AvImageQueryNextSync或AvImageQueryClosestSync只取关键帧解码开销小、成功率高若对时间点精度要求高、需要逐帧呈现画面内容则可选用AvImageQueryClosest。8.2 运算符与字符串化枚举通过实现EquatableAVImageQueryOptions与ToString提供了三个成员方法public operator func (other: AVImageQueryOptions): Bool public operator func !(other: AVImageQueryOptions): Bool public func toString(): String(other)比较两个AVImageQueryOptions是否相等相等返回true否则返回false!(other)比较两个AVImageQueryOptions是否不等不等返回true否则返回falsetoString()返回AVImageQueryOptions的字符串表示便于日志输出与调试。九、异常与错误码速查ohos.multimedia.media相关接口抛出的BusinessException对应 Media 特有错误码完整定义见 Media 错误码。其中与 AVImageGenerator 直接相关的错误码如下9.1 5400101 内存分配失败No memory.可能原因① 实例数量超过 16 个②new或malloc流程失败导致空指针。处理步骤销毁当前实例并重新创建如果重新创建失败则停止相关操作。9.2 5400102 当前状态机不支持此操作Operation not allowed.可能原因当前状态机不支持该操作。处理步骤确认当前状态是否支持当前操作把实例切换到正确的状态后再执行正确操作。9.3 5400106 不支持的规格Unsupported format.可能原因不支持的文件或格式。处理步骤当前使用的格式规格不支持需切换为支持的规格。除上述特有错误码外通用错误码请参考通用错误码说明文档。十、数据源获取路径深入rawfile 与沙箱文件前文示例通过abilityContext.resourceManager.getRawFd(trailer.mp4)获取内置资源的句柄这是最常用的数据源获取方式。围绕这一环节仓库中相关 Kit 提供了两类路径方式一rawfile 内置资源getRawFd(String)获取resources/rawfile目录下 rawfile 文件所在 HAP 的文件描述符返回 RawFileDescriptor含fd、offset、length三字段恰好与AVFileDescriptor一一对应可直接透传注意getRawFd获取的 fd 使用完毕后需调用closeRawFd关闭避免资源泄露。方式二应用沙箱文件先通过 UIAbilityContext.filesDir 取得应用沙箱目录路径再通过 open(path, mode) 打开文件获取File对象及对应句柄之后填充AVFileDescriptor的fd、offset、length字段。十一、实战要点汇总生命周期完整createAVImageGenerator()→ 设置fdSrc→fetchFrameByTime()→release()四步缺一不可时间单位fetchFrameByTime的timeUs单位为微秒如取视频开头帧传入0即可输出尺寸PixelMapParams的宽高需大于 0 且不超过原始视频宽高否则不缩放示例中width: 300, height: 300即为典型的封面缩略图尺寸fd 独占性句柄传给AVImageGenerator后不得再用于其他读写或传给其他媒体组件否则可能因竞争导致缩略图数据异常异常兜底所有调用均建议使用try/catch捕获BusinessException并按错误码5400101/5400102/5400106执行销毁重建或规格切换策略工程落地示例代码需放入仓颉模板工程的index.cj涉及Global.abilityContext的需在main_ability.cj中配置Context上下文具体可参考仓颉示例代码说明。通过以上步骤开发者即可在仓颉应用中稳定获取视频任意时间点的缩略图为视频列表封面、预览封面等功能提供统一的实现范式。赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉媒体服务 Media KitBeta开发指南AVImageGenerator 视频缩略图获取 API 全解析仓颉媒体服务 Media KitBeta开发指南AVImageGenerator 视频缩略图获取 API 全解析 Media Kit媒体服务是 Ope文档知识库教程OpenHarmonyzlib4cj仓颉语言 zlib / DEFLATE / gzip 压缩解压库实战指南zlib4cj仓颉语言 zlib / DEFLATE / gzip 压缩解压库实战指南 导读 zlib4cj 是为仓颉Cangjie语言打造的三方库支持后端仓颉语言位置服务开发全指南深入解析 ohos.geo_location_manager 模块仓颉语言位置服务开发全指南深入解析 ohos.geo_location_manager 模块 导读 本文以 cj apis geo_location_mana文档知识库教程OpenHarmony上一篇高效MATLAB到Python代码转换matlab2python实战指南下一篇Navicat Mac版无限试用终极指南三种简单方法免费使用Navicat Premium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考