Tutorial: 实时语音转录和翻译

功能描述

本文主要介绍如何使用实时传译插件来启动实时语音转文字（ASR）和翻译能力。该插件可以将房间内用户的语音实时转换为文字，并支持翻译成多种语言。

前提条件

• TRTC Web SDK 版本 >= 5.15.0

实现流程

引入并注册插件

import TRTC from 'trtc-sdk-v5';
import RealtimeTranscriber from 'trtc-sdk-v5/plugins/realtime-transcriber';
const trtc = TRTC.create({ plugins: [RealtimeTranscriber] });

启动插件

启动插件后会返回一个 transcriberRobotId，用于后续停止该转录任务。

const transcriberRobotId = await trtc.startPlugin('RealtimeTranscriber', {
  sourceLanguage: 'zh',
  translationLanguages: ['en', 'ja'],
  userIdsToTranscribe: 'all',
});

监听转录消息

通过监听 REALTIME_TRANSCRIBER_MESSAGE 事件来获取转录结果。

trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE, (event) => {
  console.log(`${event.speakerUserId}: ${event.sourceText}`);
  if (event.translationTexts) {
    Object.entries(event.translationTexts).forEach(([lang, text]) => {
      console.log(`  ${lang}: ${text}`);
    });
  }
});

监听状态变化

通过监听 REALTIME_TRANSCRIBER_STATE_CHANGED 事件来获取转录任务的状态变化。

trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_STATE_CHANGED, (event) => {
  console.log(`转录任务状态: ${event.state}, robotId: ${event.transcriberRobotId}`);
});

停止插件

await trtc.stopPlugin('RealtimeTranscriber', { transcriberRobotId });

使用示例

ASR 场景：转录房间内的音频为文字

// 启动转录任务
const robotId = await trtc.startPlugin('RealtimeTranscriber', {
  sourceLanguage: 'zh'
});
// 监听转录消息
trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE, (data) => {
  console.log(data.speakerUserId + ' says: ' + data.sourceText);
});

翻译场景：将指定用户的语音翻译成多种语言

// 启动转录任务，转录 userA 的语音并翻译成法语和英语
const robotId = await trtc.startPlugin('RealtimeTranscriber', {
  sourceLanguage: 'zh',
  translationLanguages: ['fr', 'en'],
  userIdsToTranscribe: 'userA'
});
// 监听转录消息
trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE, (data) => {
  console.log(`👤 ${data.speakerUserId}:`);
  console.log(`  原文: ${data.sourceText}`);
  if (data.translationTexts) {
    Object.entries(data.translationTexts).forEach(([lang, text]) => {
      console.log(`  ${lang.toUpperCase()}: ${text}`);
    });
  }
});

转录多个指定用户

const robotId = await trtc.startPlugin('RealtimeTranscriber', {
  sourceLanguage: 'en',
  translationLanguages: ['zh', 'ja'],
  userIdsToTranscribe: ['userA', 'userB', 'userC']
});

API 说明

trtc.startPlugin('RealtimeTranscriber', options)

用于启动实时转录任务。

options: RealtimeTranscriberStartOptions

Returns: Promise<string>

返回转录任务的 transcriberRobotId，用于后续停止任务。

Example:

const robotId = await trtc.startPlugin('RealtimeTranscriber', {
  sourceLanguage: 'zh',
  translationLanguages: ['en', 'ja'],
  userIdsToTranscribe: 'all',
});

trtc.stopPlugin('RealtimeTranscriber', options)

用于停止实时转录任务。

options

Example:

await trtc.stopPlugin('RealtimeTranscriber', { transcriberRobotId: robotId });

事件说明

TRTC.EVENT.REALTIME_TRANSCRIBER_STATE_CHANGED

转录任务状态变化事件。

RealtimeTranscriberStateEvent

Example:

trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_STATE_CHANGED, (event) => {
  if (event.state === 'started') {
    console.log('转录任务已启动');
  } else if (event.state === 'stopped') {
    console.log('转录任务已停止');
  }
});

后台资源受限通知

当后台 AI 服务（ASR/翻译）资源受限时，SDK 会通过 TRTC.EVENT.ERROR 事件主动通知（后台限频每分钟下发一次，资源恢复正常后停止下发）。此时：

• error.code 固定为 5400（SERVER_ERROR，表示服务器处理请求失败）
• error.extraCode 为降级事件码，见下表
• error.data 携带 { roomId, transcriberRobotId, taskId, resourceType }，用于定位受影响的转录任务

业务侧收到后应及时回退或降级相关 AI 能力，避免影响线上业务。

trtc.on(TRTC.EVENT.ERROR, (error) => {
  if (error.code === 5400 && error.extraCode === 5001) {
    // 例如 error.message: 'The ASR/Translate concurrent usage has exceeded the limit. ...'
    // error.data: { roomId, transcriberRobotId, taskId, resourceType }
    console.warn(`转录服务资源受限，robotId: ${error.data.transcriberRobotId}, ${error.message}`);
    // 业务侧自行决定降级或关闭相关 AI 能力
  }
});

TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE

转录消息事件，当有新的转录结果时触发。

RealtimeTranscriberMessageEvent

Example:

trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE, (event) => {
  const { speakerUserId, sourceText, translationTexts, isCompleted } = event;
  // 显示实时转录结果
  console.log(`[${isCompleted ? '完成' : '进行中'}] ${speakerUserId}: ${sourceText}`);
  // 显示翻译结果
  if (translationTexts) {
    translationTexts.forEach(({ language, text }) => {
      console.log(`  ${language}: ${text}`);
    });
  }
});
// 取消监听
trtc.off(TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE, handler);

支持的语言

ASR 源语言

翻译目标语言

常见问题

1. 如何区分中间结果和最终结果？

通过 REALTIME_TRANSCRIBER_MESSAGE 事件中的 isCompleted 字段判断。当 isCompleted 为 false 时，表示当前是实时更新的中间结果；当 isCompleted 为 true 时，表示该语音片段已完成，返回最终结果。

trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE, (event) => {
  if (event.isCompleted) {
    // 最终结果，可以存储或展示
    saveSubtitle(event);
  } else {
    // 中间结果，可以实时更新 UI
    updateLiveCaption(event);
  }
});

2. 如何根据 segmentId 合并字幕？

每个连续的语音片段会有相同的 segmentId，可以根据此 ID 进行字幕的更新和合并：

const subtitleMap = new Map();
trtc.on(TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE, (event) => {
  subtitleMap.set(event.segmentId, event);
  if (event.isCompleted) {
    // 语音片段完成，可以归档
    archiveSubtitle(subtitleMap.get(event.segmentId));
  }
});

3. 如何节省带宽？

当不需要接收转录消息时，移除 REALTIME_TRANSCRIBER_MESSAGE 事件的所有监听器，插件会自动暂停接收消息以节省带宽。当重新添加监听器时，会自动恢复接收消息。