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

原创2026-10-15 13:23:141,398 阅读
文章标签:文档知识库

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

导读

本文基于开源仓颉语料库中 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 模块特有错误码汇总如下:

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

登录后查看全文
CangjieCorpus