语音转文字

大约 9 分钟

语音转文字

本文介绍如何使用 HarmonyOS SDK 将语音消息或本地语音文件转换为文字。

本功能从 SDK v1.13.0 版本开始支持。

功能说明

语音转文字功能支持将语音内容转换为文本，主要包括以下功能：

  • 语音消息转文字：将已发送成功的语音消息转换为文本。
  • 本地语音文件转文字：将本地语音文件转换为文本。
  • 语音参数配置：为无文件头的本地语音文件补充格式、采样率、采样位深和声道数等参数。
  • 读取转文字结果：转换成功后，可从语音消息体读取已持久化的文本结果。

语音消息转文字 与 本地语音文件转文字 支持的音频格式不完全相同。

文件格式语音消息转文字本地语音文件转文字
PCM❌ 不支持✅ 支持
AMR✅ 支持✅ 支持
MP3✅ 支持✅ 支持
WAV✅ 支持✅ 支持
M4A✅ 支持✅ 支持
AAC✅ 支持✅ 支持

为获得更优性能，推荐优先使用标准的 PCM 和 MP3 格式。

语音参数 audioParams 仅用于本地语音文件转文字。对于本地 PCM 文件，由于文件本身不包含完整音频头信息，必须传入 audioParams；其他格式通常可传 null。具体配置方式请参考 将本地语音文件转换为文本。

开通服务

使用该服务前，请联系环信商务进行开通。

使用限制

  • 本地语音文件大小不能超过 10 MB，音频时长不能超过 60 秒。
  • 单个 App Key 下，语音消息转文字和本地语音文件转文字两个接口的总调用频率上限为每秒 50 次。如需调整，请联系环信商务。

技术原理

语音转文字主要支持以下两种调用方式：

  • 语音消息转文字：客户端传入语音消息对象，SDK 校验消息类型后调用底层转换能力。转换成功后，结果会通过 Promise 返回，并写入 VoiceMessageBody。
  • 本地语音文件转文字：客户端传入本地语音文件路径。SDK 校验文件是否存在；若文件为 PCM 格式，则结合 语音参数 解析原始音频数据，再调用底层转换能力。

时序图如下所示：

img

处理流程如下：

语音消息转文字

  1. App 调用 voiceMessageToText(message) 发起语音消息转文字请求。
  2. IM SDK 校验 message 是否为空，以及消息类型是否为语音消息。
  3. 校验通过后，IM SDK 向 IM Server 发起语音消息转文字请求。
  4. IM Server 执行语音识别和文本转换，并将转换结果或错误信息返回给 IM SDK。
  5. IM SDK 在收到转换结果后，将文本写入 ChatMessage 对象对应的语音消息体。
  6. IM SDK 通过 Promise 返回转换结果或错误信息给 App。

本地语音文件转文字

  1. App 调用 voiceFileToText(filePath, audioParams) 发起本地语音文件转文字请求。
  2. IM SDK 校验 filePath 是否为空，并检查目标文件是否存在。
  3. 如果待转换文件为 PCM 格式，IM SDK 还会读取 audioParams 中的语音参数，用于识别原始音频数据。
  4. IM SDK 向 IM Server 发起本地语音文件转文字请求。
  5. IM Server 执行语音识别和文本转换，并将转换结果或错误信息返回给 IM SDK。
  6. IM SDK 通过 Promise 将转换结果或错误信息返回给 App。

前提条件

开始前，请确保满足以下条件：

将语音消息转换为文本

调用 ChatManager#voiceMessageToText 将单条发送成功的语音消息转换为文字。

为获得更优性能，推荐优先使用标准的 MP3 格式语音消息。

  try {
    const text = await ChatClient.getInstance().chatManager()!.voiceMessageToText(voiceMessage);
    console.info(`voiceMessageToText success: ${text}`);
  } catch (e) {
    console.error(`voiceMessageToText failed: ${JSON.stringify(e)}`);
  }

关键参数

参数类型是否必需描述
voiceMessageChatMessage是待转换的语音消息对象，消息体类型必须为 VoiceMessageBody。

注意事项

  • 该方法仅支持已发送成功的语音消息。
  • 传入的 ChatMessage 必须为语音消息，否则会返回 ChatError#MESSAGE_INVALID。可通过 ChatMessage#getType 判断消息类型。
  • 当前语音消息转文字支持 AMR、MP3、WAV、M4A 和 AAC 格式的语音消息，不支持直接对 PCM 格式的语音消息进行转换。
  • 如需转换 PCM 音频，请使用 本地语音文件转文字接口，并传入对应的 ChatAudioParams。
  • 转换成功后，可通过 VoiceMessageBody#getText 读取持久化的文本结果。

将本地语音文件转换为文本

调用 ChatManager#voiceFileToText 可将本地语音文件转换为文字。

调用前，必须确保应用具备访问目标文件的权限，且文件路径可被当前进程读取。为获得更优性能，推荐优先使用标准的 PCM 和 MP3 格式音频文件。

下面示例以本地 PCM 文件为例，展示如何配置 audioParams 并发起转换：

async function convertVoiceFileToText(filePath: string): Promise<void> {
  const audioParams = new ChatAudioParams();
  audioParams.setFormat(ChatAudioFormat.PCM);
  audioParams.setSampleRate(16000);
  audioParams.setBitsPerSample(16);
  audioParams.setChannels(1);

  try {
    const text = await ChatClient.getInstance()
      .chatManager()!
      .voiceFileToText(filePath, audioParams);
    console.info(`voiceFileToText success: ${text}`);
  } catch (e) {
    console.error(`voiceFileToText failed: ${JSON.stringify(e)}`);
  }
}

关键参数

参数类型是否必需描述
filePathstring是本地语音文件路径。必须确保应用具备读取该路径的权限。
audioParamsChatAudioParams否语音参数。PCM 文件必须传入；MP3、AMR、WAV、M4A 和 AAC 文件通常可传 null。

audioParams 仅用于将本地语音文件转换为文本，用于描述本地语音文件的基础属性，包括格式、采样率、位深和声道数，有助于 SDK 准确解析语音内容。

  • 对于 PCM 文件，必须传入 ChatAudioParams，以便 SDK 正确解析原始音频数据。
  • 对于 MP3、AMR、WAV、M4A 和 AAC 文件，通常无需显式配置该对象，调用接口时可传 null。
  • 如果语音参数与原始文件不匹配，可能导致转换失败或结果异常。

ChatAudioParams 的关键成员如下：

成员说明
ChatAudioFormat语音格式。仅支持配置 PCM、MP3 和 AMR 格式。对于 WAV、M4A 和 AAC，服务端会直接解析处理，SDK 仅透传文件数据，因此无需通过 ChatAudioFormat 配置格式参数。
getFormat/setFormat获取或设置语音文件格式。
getSampleRate/setSampleRate获取或设置采样率，单位为 Hz，建议设置为 8000 或 16000。
getBitsPerSample/setBitsPerSample获取或设置采样位深，单位为 bit，例如 16。
getChannels/setChannels获取或设置声道数，例如 1 表示单声道。

读取语音消息的转换结果

调用成功后，可直接通过返回值获取转换文本。语音消息转换完成后，结果也会持久化到消息体中。

  • 仅当语音消息成功完成转换后，才能读取到有效文本。
  • 如果消息尚未转换，或当前没有转换结果，则返回空字符串。
  • 该方式适用于展示已识别结果，避免重复发起转换请求。
function readVoiceText(message: ChatMessage): string {
  if (message.getType() === ContentType.VOICE) {
    return (message.getBody() as VoiceMessageBody).getText();
  }
  return '';
}

注意事项

  • voiceMessageToText 和 voiceFileToText 均为异步接口，转换结果通过 Promise 返回。
  • 转换本地语音文件前，建议先校验文件是否存在且可读，避免无效调用。
  • 如果本地语音文件来自外部存储或第三方路径，请确保应用具备读取权限。
  • 如果本地文件大小超过 10 MB、时长超过 60 秒，或语音参数与实际文件不匹配，可能导致识别失败。
  • PCM 音频不支持通过 语音消息转文字接口 直接转换，需要调用 本地文件转文字接口，并且传入 ChatAudioParams 参数。

常见错误与排查

常见错误码

错误码常量说明常见原因处理建议
4ChatError#EXCEED_SERVICE_LIMIT服务使用量超限。测试版语音转文字服务用量超过限制。检查当前服务配额或联系商务开通正式服务。
104ChatError#INVALID_TOKEN鉴权失败。当前登录状态失效，或 token 无效、已过期。重新登录并确保鉴权状态有效。
110ChatError#INVALID_PARAM请求参数错误。请求参数缺失或非法，例如消息缺少可用的语音附件标识。检查消息对象、文件路径和请求参数是否合法。
400ChatError#FILE_NOT_FOUND语音文件不存在。服务端未找到消息关联的语音文件，或本地文件路径无效。检查消息附件是否可用，或确认本地文件路径是否正确。
401ChatError#FILE_INVALID语音文件无效或格式不支持。语音文件格式不支持，或文件内容异常。检查文件格式、可读性和文件内容是否完整。
403ChatError#FILE_DOWNLOAD_FAILED语音文件下载失败。服务端拉取消息语音文件失败。检查网络状态和服务端附件可用性。
408ChatError#FILE_DURATION_TOO_LONG待转换语音文件时长超过限制。语音时长超出 60 秒限制。缩短语音时长后重试。
409ChatError#FILE_VOICE_TO_TEXT_FAILED语音文件转文字失败。语音内容识别失败，或底层转换服务调用失败。检查语音内容质量、格式和参数配置是否匹配。
500ChatError#MESSAGE_INVALID消息不合法。传入 message 为 null，消息类型不是语音消息，或当前消息不是已发送成功的语音消息。确保传入的是已发送成功的语音消息。
505ChatError#SERVICE_NOT_ENABLED服务未开通。当前应用未开通语音转文字服务。开通语音转文字服务后再调用。

常见问题

  1. 为什么 voiceMessageToText 返回 MESSAGE_INVALID？

通常有以下原因：

  • 传入的 message 为 null；
  • 传入的消息类型不是语音消息；
  • 当前消息不是已发送成功的语音消息；
  1. 为什么本地文件转换返回 FILE_NOT_FOUND？

通常有以下原因：

  • filePath 为空；
  • 文件路径错误；
  • 目标文件不存在；
  • 应用对该路径没有读取权限。
  1. 为什么 PCM 文件转换失败？

常见原因包括：

  • 未正确传入 ChatAudioParams；
  • sampleRate、bitsPerSample 或 channels 与原始语音不匹配；
  • 实际文件并非 PCM 原始流格式。
  1. 为什么 ChatAudioFormat 不支持 WAV、M4A 和 AAC，但语音转文字功能仍支持这些格式？

WAV、M4A 和 AAC 格式由服务端直接识别和处理，SDK 仅负责将文件数据透传至服务端，不进行本地解析或参数校验。因此，在调用 voiceFileToText 时，对于这些格式的文件，audioParams 参数通常可传 null。

上次编辑于:
环信 IM 文档
© 环信 2026