仓颉语言 Media Kit 媒体服务错误码全解析:5400101~5411011 错误原因与处理方案

  • 文档
  • 知识库
  • 教程
  • OpenHarmony

【免费下载链接】CangjieCorpus

本仓库为仓颉编程语言语料库,聚焦 仓颉编程语言 核心知识体系,整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源,经结构化处理与专业标注,构建为支持 RAG(检索增强生成)技术 的高质量知识基座,适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用,推动鸿蒙开发生态智能化升级!

项目地址: https://gitcode.com/Cangjie/CangjieCorpus
点击查看 免费下载

导读

本文基于开源仓颉语料库中 Media 错误码参考文档,系统梳理仓颉开发场景下 ohos.multimedia.media(媒体服务)模块特有的 18 个业务错误码,涵盖内存分配失败、状态机操作不允许、IO 异常、操作超时、播放服务死亡、音频焦点冲突以及网络链路、SSL 证书等一系列错误。读完本文,你将能对照错误码快速定位故障根因,并掌握"销毁实例—排查环境—重新创建"的标准处置方法论,同时理解这些错误码在 AVImageGenerator 等媒体 API 调用链中的具体抛出场景。

一、错误码机制概述:模块特有错误码与通用错误码

Media Kit(媒体服务)当前在 OpenHarmony 中为 Beta 特性,其仓颉 API 参考目录见 MediaKit 参考文档入口。在仓颉应用中调用媒体接口时,错误以 BusinessException 异常形式抛出,开发者可通过异常携带的 message 获取错误信息。

媒体模块遵循"模块特有错误码 + 通用错误码"的双层错误体系:

  • 模块特有错误码:即本文讲解的 5400101~5400107、5411001~5411011,仅针对 ohos.multimedia.media 媒体服务定义;
  • 通用错误码:适用于所有模块的公共错误,如 201(权限校验失败)、401(参数检查失败)、801(设备不支持该 API)等,详见通用错误码说明文档。

说明:原文档明确提示,以下仅介绍本模块特有错误码,通用错误码请参考通用错误码说明文档。排查媒体功能问题时,应先确认错误码是否属于本模块特有范围,若为 201/401/801 等通用码,需按通用错误码文档处理。

从错误码编号区间可以直观看出其归属:540010x 段为本地媒体处理类错误(内存、状态机、IO、超时、服务、格式、音频焦点),541100x~541101x 段为网络媒体相关错误(地址解析、连接、SSL、权限与资源)。这与媒体服务既处理本地资源、又支持网络流的架构特征一致。

二、本地媒体错误码(5400101~5400107)

本组错误码覆盖媒体实例的创建、状态流转、IO 交互、超时控制、服务生命周期、格式规格与音频焦点等本地处理链路,是媒体功能最常遇到的错误区间。

5400101 内存分配失败

项目内容
错误信息No memory.
错误描述分配内存失败。
可能原因① 实例数量超过 16 个;② new 或 malloc 流程失败导致空指针。
处理步骤销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

深入解读:该错误码意味着媒体服务侧内存资源耗尽或分配流程异常。原因①明确指出同一场景下媒体实例数量存在上限(16 个),开发者在长生命周期页面中若频繁创建 AVImageGenerator、AVPlayer 等实例而不及时释放,将触发该错误;原因②则指向底层 new/malloc 失败产生的空指针。从 API 参考 看,createAVImageGenerator() 与 release() 的异常表中均列出 5400101,印证了"创建与释放必须成对"的使用约束——调用 release() 及时释放资源是规避该错误码的关键手段。

5400102 当前状态机不支持此操作

项目内容
错误信息Operation not allowed.
错误描述当前操作不允许。
可能原因当前状态机不支持此操作。
处理步骤确认当前状态是否支持当前操作,把实例切换到正确的状态进行正确的操作。

深入解读:媒体组件(如播放器、录制器、缩略图生成器)内部按状态机运转,接口调用必须符合状态迁移顺序。以 AVImageGenerator 为例,其 fdSrc 属性设置与 fetchFrameByTime() 调用均可能抛出 5400102——在未正确设置数据源或实例已释放的状态下调用取帧接口,就会触发"操作不允许"。排查时需对照 API 文档确认实例所处状态与操作前置条件。

5400103 出现IO错误

项目内容
错误信息I/O error.
错误描述出现 IO 错误。
可能原因媒体与其他模块的数据交互发生问题(图形、音频、网络、HDI、相机)。
处理步骤确认网络是否通畅,并销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

深入解读:该错误是媒体子系统与外部模块数据交互失败的统称,原因横跨图形、音频、网络、HDI(硬件设备接口)、相机等多个数据通道。处理步骤中的"确认网络是否通畅"提示了网络流媒体场景下 IO 错误与网络状态的高度关联;若为本地资源场景,则需进一步检查文件描述符是否有效、资源是否被其他模块独占。

5400104 操作超时

项目内容
错误信息Operation timeout.
错误描述操作超时。
可能原因① 网络超时:默认网络超时时间为 15 秒,从开始缓存的事件上报后开始计时,超时后会上报该错误信息;② 访问其他模块超时。
处理步骤① 确认网络是否通畅;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

深入解读:这是本错误码文档中唯一明确给出时间参数的错误。网络超时默认 15 秒,且计时起点为"开始缓存的事件上报之后"——也就是说,从媒体服务开始缓存上报事件起,若 15 秒内相关操作未完成,即上报 Operation timeout.。开发者可据此在业务侧设置合理的超时等待窗口,避免在超时错误上报后仍对实例做无效操作。

5400105 播放服务死亡

项目内容
错误信息Service died.
错误描述播放服务死亡。
可能原因播放服务死亡。
处理步骤销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

深入解读:该错误码标识媒体播放服务进程异常退出,属于服务端生命周期类错误。一旦出现,当前实例已不可用,必须销毁重建。这种"服务死亡—重建实例"的处置模式在 5400101、5400103、5400104 等错误中反复出现,构成了媒体错误处理的通用动作模板。

5400106 不支持的规格

项目内容
错误信息Unsupported format.
错误描述不支持的规格。
可能原因不支持的文件或者格式。
处理步骤当前使用的格式规格不支持,用户需要切换为支持的格式规格。

深入解读:此错误由输入媒体文件或参数的格式规格超出能力范围导致。在 AVImageGenerator.fetchFrameByTime() 的异常表中明确列出 5400106,意味着当传入的 PixelMapParams 输出规格或视频源格式不被支持时即抛出该码。处理上只能由开发者切换到受支持的格式规格,无法通过重试解决。

5400107 音频焦点冲突

项目内容
错误信息Audio interrupted.
错误描述音频焦点冲突导致录制失败。
可能原因有其他进程占用了音频焦点,导致无法获取音频焦点。
处理步骤销毁当前实例,并确认当前是否有其他进程在进行录制;如果可以停止其他进程的占用,则可以重新创建。

深入解读:该错误码专门针对录音场景。OpenHarmony 的音频焦点机制保证同一时刻仅一个应用可持有录音焦点,当其他进程(如通话、其他录音应用)占用焦点时,本应用录制即失败并上报 Audio interrupted.。处置前必须先行确认并释放其他进程的焦点占用,单纯重建实例无法解决焦点被占的根本问题。

三、网络媒体错误码(5411001~5411011)

本组错误码对应网络流媒体场景,覆盖服务端地址解析、网络连接、SSL 证书校验、权限与资源等环节,从 5411001 到 5411011 构成了一条完整的"建连—校验—传输"排查链路。

5411001 解析或链接服务端地址错误

项目内容
错误信息Can not find host.
错误描述解析或链接服务端地址错误。
可能原因① 链接服务端地址错误;② 链接服务端地址解析失败。
处理步骤当前使用的链接服务端地址错误或无法被解析,需改用其他链接服务端地址。

5411002 网络连接超时

项目内容
错误信息Connection time out.
错误描述网络连接超时。
可能原因网络异常。
处理步骤① 确认网络是否通畅;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

5411003 网络异常导致的数据或链路异常

项目内容
错误信息NetWork abnormal.
错误描述网络异常导致的数据或链路异常。
可能原因网络异常。
处理步骤销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

5411004 网络被禁用

项目内容
错误信息NetWork unavailable.
错误描述网络被禁用导致的错误。
可能原因网络被禁用。
处理步骤① 确认网络是否被禁用;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

5411005 无权限,访问被拒绝

项目内容
错误信息No permission.
错误描述无访问权限。
可能原因无访问权限。
处理步骤① 确认是否有访问权限;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

深入解读:5411005 与通用错误码 201(权限校验失败)容易混淆,需注意区分:201 是应用未申请 API 调用权限(如媒体服务所需的 ohos.permission.MICROPHONE),属通用码范畴;而 5411005 是媒体网络服务端的访问权限被拒,需确认对目标服务端地址是否具备访问权限。

5411006 客户端请求参数错误或超出处理能力

项目内容
错误信息Network access denied.
错误描述客户端请求参数错误或超出处理能力。
可能原因客户端请求参数错误或超出处理能力。
处理步骤① 确认请求参数是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

5411007 无可用资源

项目内容
错误信息Cannot find available network resources.
错误描述无可用网络资源。
可能原因链接服务端地址异常。
处理步骤① 确认链接服务端地址是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

5411008 服务端校验客户端证书失败

项目内容
错误信息SSL client cert needed.
错误描述SSL 客户端不可信,服务端校验客户端证书失败。
可能原因未携带证书、证书不合法、证书过期。
处理步骤① 确认 SSL 证书是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

5411009 SSL连接失败

项目内容
错误信息SSL connection failed.
错误描述SSL 链接失败。
可能原因SSL 链接失败。
处理步骤① 确认 SSL 链接是否已失效;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

5411010 客户端校验服务端证书失败

项目内容
错误信息SSL server cert needed.
错误描述SSL 服务端不可信,客户端校验服务端证书失败。
可能原因未携带证书、证书不合法、证书过期。
处理步骤① 确认 SSL 证书是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

深入解读:5411008 与 5411010 构成 SSL 双向校验的两端视角:前者是服务端校验客户端证书(SSL client cert needed.),后者是客户端校验服务端证书(SSL server cert needed.),两者的可能原因均为"未携带证书、证书不合法、证书过期"。HTTPS 网络流媒体场景下,开发者应优先核对证书链是否完整、是否在有效期内,再执行实例重建流程。

5411011 网络协议的原因导致请求不受支持

项目内容
错误信息Unsupportted request.
错误描述客户端请求参数错误或超出处理能力。
可能原因客户端请求参数错误或超出处理能力。
处理步骤① 确认客户端请求参数是否正常;② 销毁当前实例,并重新创建;如果重新创建失败,则停止相关操作。

注意:该错误码的"错误描述"与"可能原因"原文均写为"客户端请求参数错误或超出处理能力"(与 5411006 相同),但从错误信息 Unsupportted request.(原文拼写)与标题"网络协议的原因导致请求不受支持"看,其本质是请求因协议原因不被服务端支持。实际排查时应以错误信息与标题为准,重点核查请求是否符合服务端协议要求。

四、错误码与媒体 API 的对应关系

了解"哪个接口可能抛哪个错误码",能显著缩小排查范围。在 ohos.multimedia.media API 参考 中,各接口均通过异常表声明其可抛出的 Media 错误码,以当前 Beta 版提供的 AVImageGenerator(视频缩略图获取)能力为例:

API可抛出的 Media 错误码
createAVImageGenerator()5400101(No memory.)
prop fdSrc(设置数据源)5400101、5400102
fetchFrameByTime()(获取指定时间图像)5400101、5400102、5400106
release()(释放资源)5400101

对应关系印证了错误码的实际触发场景:

  • 5400101 贯穿实例创建到释放的完整生命周期,与"实例数量上限 16"和资源释放不及时直接相关;
  • 5400102 出现在设置数据源与取帧阶段,对应状态机校验(如未设置 fdSrc 就调用 fetchFrameByTime());
  • 5400106 仅在取帧时出现,与视频源格式或 PixelMapParams 输出规格不支持相关。

仓颉侧的系统能力声明可见于 SysCap 能力列表,其中 SystemCapability.Multimedia.Media.AVImageGenerator、SystemCapability.Multimedia.Media.AVPlayer、SystemCapability.Multimedia.Media.AVRecorder、SystemCapability.Multimedia.Media.AVMetadataExtractor、SystemCapability.Multimedia.Media.AVTranscoder 等即对应媒体服务各能力点;若设备不具备相应能力(通用错误码 801),接口将不可用。

五、错误处理实战:仓颉代码中的捕获与处置

5.1 基础捕获模式

仓颉中媒体接口以 BusinessException 抛出错误,标准捕获写法如下(源自 API 参考示例):

// 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)
}

其中 Hilog 用于输出错误信息到日志,便于对照本文错误码表定位问题。需要说明的是,媒体接口的错误码通过 BusinessException 的 message 字段携带,5400101~5411011 各码对应的英文错误信息即为 message 的内容,可据此在日志中快速匹配。

5.2 按错误码分流的处置模板

综合前文各错误码的处理步骤,可提炼出如下统一处置逻辑:

// 伪代码示例:按错误码选择处置动作
try {
    // 媒体操作
} catch (e: BusinessException) {
    match (e.code) {
        // 内存/IO/超时/服务死亡类:销毁重建
        case 5400101 | 5400103 | 5400104 | 5400105 =>
            generator.release()          // 销毁当前实例
            // 重新创建实例并重试;若重建失败则停止相关操作
        // 状态机类:调整操作顺序或实例状态
        case 5400102 =>
            // 确认当前状态是否支持该操作,切换实例到正确状态
        // 格式规格类:切换资源或参数规格
        case 5400106 =>
            // 切换为支持的格式规格
        // 音频焦点类:确认并释放其他进程占用
        case 5400107 =>
            // 确认是否有其他进程在录制,停止占用后重建
        // 网络类:先确认网络/证书/地址,再重建实例
        case 5411001 | 5411002 | ... | 5411011 =>
            // 确认网络、服务端地址、SSL 证书、权限后重建实例
        _ => ()
    }
}

注意:上例中 e.code 为示意性写法,具体获取错误码的字段名请以所使用 SDK 的 BusinessException 定义为准。处置原则与官方文档一致:凡涉及实例异常(内存、IO、超时、服务死亡、网络)的错误,统一走"销毁实例 → 确认环境(网络/证书/地址/权限/焦点)→ 重新创建,重建失败则停止相关操作"的流程。

5.3 完整调用流程中的错误预防

结合使用 AVImageGenerator 提取视频指定时间图像(仓颉)开发指导,媒体功能的完整生命周期为"创建实例 → 设置资源 → 获取数据 → 释放资源",在各环节落实预防措施可显著降低上述错误码的触发概率:

  1. 创建实例:调用 createAVImageGenerator() 创建,注意实例总数不超过 16 个,用完即 release();
  2. 设置资源:通过 ResourceManager.getRawFd 或应用沙箱路径取得文件描述符后赋值给 fdSrc;不同 AVImageGenerator/AVMetadataExtractor 实例操作同一资源时需多次打开文件描述符,不要共用同一 fd,且 fd 传给实例后不得再用于其他读写操作,否则将引发资源竞争(对应 5400102 状态机错误与 IO 类异常);
  3. 获取数据:fetchFrameByTime(timeUs, queryOption, param) 中 timeUs 为时间点(微秒)、queryOption 决定与关键帧的时间对应关系、param 为输出缩略图格式参数(width/height 应大于 0 且不大于原始视频尺寸,否则不缩放),参数不合法可触发 5400106;
  4. 释放资源:release() 销毁实例。

六、错误码速查总表与排查优先级

为便于日常开发快速查阅,将全部 18 个 Media 模块特有错误码汇总如下:

错误码错误信息一句话定位核心处置动作
5400101No memory.内存分配失败,实例超 16 个或 malloc/new 失败销毁重建,失败则停止
5400102Operation not allowed.状态机不支持当前操作切换实例到正确状态
5400103I/O error.媒体与图形/音频/网络/HDI/相机交互异常确认网络后销毁重建
5400104Operation timeout.操作超时(网络默认 15 秒)确认网络后销毁重建
5400105Service died.播放服务死亡销毁重建,失败则停止
5400106Unsupported format.文件或格式规格不支持切换为支持的规格
5400107Audio interrupted.音频焦点被其他进程占用停止占用后重建
5411001Can not find host.服务端地址错误或解析失败更换链接地址
5411002Connection time out.网络连接超时确认网络后销毁重建
5411003NetWork abnormal.网络异常致数据/链路异常销毁重建,失败则停止
5411004NetWork unavailable.网络被禁用确认网络后销毁重建
5411005No permission.服务端访问权限被拒确认权限后销毁重建
5411006Network access denied.请求参数错误或超出能力确认参数后销毁重建
5411007Cannot find available network resources.服务端地址异常无可用资源确认地址后销毁重建
5411008SSL client cert needed.服务端校验客户端证书失败确认证书后销毁重建
5411009SSL connection failed.SSL 链接失败确认链接后销毁重建
5411010SSL server cert needed.客户端校验服务端证书失败确认证书后销毁重建
5411011Unsupportted request.请求因网络协议原因不受支持确认请求参数后销毁重建

排查优先级建议:遇到媒体错误时,建议按下述顺序定位:

  1. 先判断错误码是否属于本模块特有码(5400101~5400107、5411001~5411011),否则转到通用错误码说明文档处理(如 201 权限、401 参数、801 能力不支持);
  2. 对网络类错误(5411001~5411011),先确认服务端地址、网络连通性、SSL 证书与访问权限,再执行实例销毁重建;
  3. 对本地类错误(5400101~5400107),先确认实例数量、调用顺序、资源描述符与音频焦点占用情况,再执行实例销毁重建;
  4. 无论哪类错误,都遵循统一原则:销毁当前实例并重新创建,若重新创建失败则停止相关操作,避免在失效实例上持续重试导致资源泄漏。

总结

Media 错误码文档以"错误信息—错误描述—可能原因—处理步骤"四要素结构,系统定义了媒体服务的 18 个特有错误码。理解这组错误码的关键在于两点:一是按编号区间区分本地媒体错误(540010x,内存、状态机、IO、超时、服务、规格、音频焦点)与网络媒体错误(541100x~541101x,地址、连接、SSL、权限、资源);二是掌握贯穿始终的通用处置方法论——先确认环境因素(网络、证书、地址、权限、焦点、实例数量),再销毁重建实例,重建失败即停止相关操作。结合 AVImageGenerator 等 API 参考 中各接口声明的错误码异常表,开发者即可在仓颉应用中实现精准的错误捕获、日志定位与故障恢复。

  • 文档
  • 知识库
  • 教程
  • OpenHarmony

【免费下载链接】CangjieCorpus

本仓库为仓颉编程语言语料库,聚焦 仓颉编程语言 核心知识体系,整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源,经结构化处理与专业标注,构建为支持 RAG(检索增强生成)技术 的高质量知识基座,适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用,推动鸿蒙开发生态智能化升级!

项目地址: https://gitcode.com/Cangjie/CangjieCorpus
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值