Tutorial: 42-advanced-realtime-transcriber

42-advanced-realtime-transcriber

功能描述

本文主要介绍如何使用实时传译插件来启动实时语音转文字（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

Name Type Required Description
sourceLanguage string 必填 源语言代码，目前仅支持 'zh'、'en'
translationLanguages string | string[] 选填 翻译目标语言，支持单个语言或语言数组，如 'en' 或 ['en', 'ja']
userIdsToTranscribe string | string[] 选填 要转录的用户 ID，默认为 'all' 转录所有用户，也可指定单个或多个用户 ID
transcriberRobotId string 选填 自定义转录机器人 ID，不传则自动生成

Returns: Promise<string>

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

Example:

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

trtc.stopPlugin('RealtimeTranscriber', options)

用于停止实时转录任务。

options

Name Type Required Description
transcriberRobotId string 必填 启动时返回的转录机器人 ID

Example:

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

事件说明

TRTC.EVENT.REALTIME_TRANSCRIBER_STATE_CHANGED

转录任务状态变化事件。

RealtimeTranscriberStateEvent

Name Type Description
state 'started' | 'stopped' 转录任务状态
roomId string | number 房间 ID
transcriberRobotId string 转录机器人 ID
sourceLanguage string 源语言（可选）
error number 错误码（可选）
errorMessage string 错误信息（可选）

Example:

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

TRTC.EVENT.REALTIME_TRANSCRIBER_MESSAGE

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

RealtimeTranscriberMessageEvent

Name Type Description
segmentId string 语音片段 ID，用于标识一段连续的语音
speakerUserId string 说话人的用户 ID
sourceText string 转录的原文文本
translationTexts Array<{ language: string, text: string }> 翻译文本数组，如 [{ language: 'en', text: 'hello' }, { language: 'ja', text: 'こんにちは' }]
timestamp number 时间戳
isCompleted boolean 该语音片段是否已完成。false 表示中间结果（实时更新），true 表示最终结果
robotId string 转录机器人 ID

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 源语言

语言 代码
中文 zh
英语 en

翻译目标语言

语言 代码
中文 zh
英语 en
越南语 vi
日语 ja
韩语 ko
印度尼西亚语 id
泰语 th
葡萄牙语 pt
阿拉伯语 ar
西班牙语 es
法语 fr
马来语 ms
德语 de
意大利语 it
俄语 ru

常见问题

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 事件的所有监听器，插件会自动暂停接收消息以节省带宽。当重新添加监听器时，会自动恢复接收消息。