使用指南

Voice Translation

概述

VAS 即時語音翻譯服務透過 WebSocket 提供低延遲的語音辨識（STT）與即時翻譯功能。完整流程為：

客戶端透過麥克風擷取音訊
將音訊串流傳送到 VAS 伺服器
伺服器進行語音辨識，回傳逐字稿
同步進行多語言翻譯並回傳結果
（選用）生成 TTS 語音合成播放翻譯結果

適用場景

場景	錄音類型（`type`）
會議記錄、訪談紀錄	`transcribe`
雙語即時互譯、跨語言對話	`conversation`
語音備忘、快速記錄	`record`
講座、演講、直播	`broadcast`（請參考廣播指南）

前置準備

1. 取得 API Key

確保您已擁有有效的 API Key（格式：vas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）。認證方式詳見認證機制。

2. 取得 Ticket

WebSocket 連線使用 Ticket 機制認證。先以 API Key 換取一次性 Ticket：

curl -X POST "https://vas-poc.vurbo.ai/api/v1/auth/ticket" \
  -H "X-API-Key: vas_your_api_key_here"

回應：

{
  "ticket": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "expires_in": 60
}

注意：Ticket 有效期為 60 秒，且僅能使用一次。

3. 建立 WebSocket 連線

將 Ticket 放入 Sec-WebSocket-Protocol，格式為 ticket.{TICKET_VALUE}：

const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

ws.onopen = () => {
  console.log('WebSocket 已連線');
};

4. 維持心跳

建議每 30 秒發送一次 ping，確保連線不會逾時：

{
  "type": "health",
  "data": { "action": "ping" }
}

伺服器會回應 pong。

開始語音翻譯

連線成功後，發送 start action 啟動語音翻譯工作階段。

基本請求

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "transcription_languages": ["zh-TW"],
    "translation_languages": ["en-US"],
    "type": "transcribe",
    "audio_format": "pcm",
    "summary_template": "meeting"
  }
}

核心參數說明

參數	類型	必填	說明
`transcription_languages`	string	是	語音辨識語言，最多 2 個（如 `["zh-TW"]`）
`translation_languages`	string	否	翻譯目標語言，空陣列或不傳代表不翻譯
`type`	string	是	錄音類型：`transcribe`、`conversation`、`record`、`broadcast`
`audio_format`	string	否	音訊格式：`pcm`（預設）或 `webm`
`summary_template`	string	條件	摘要模板（`transcribe` 類型必填，如 `meeting`、`interview`）
`realtime_translation`	boolean	否	即時翻譯模式（預設 `false`）
`recognition_mode`	string	否	`single`（單人，預設）或 `multi_speaker`（多人語者分離）；`multi_speaker` 下 `transcription_languages` 必須恰好 1 個，否則回傳 `diarization_multilang_conflict` 錯誤並拒絕開始
`name`	string	否	初始預設錄音名稱（最大 60 字，系統仍可覆蓋；未提供則自動生成如 `Transcription #1`）

含 TTS 的請求

若要啟用翻譯結果的語音合成，加入 TTS 相關參數：

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "transcription_languages": ["zh-TW"],
    "translation_languages": ["en-US"],
    "type": "transcribe",
    "audio_format": "pcm",
    "summary_template": "meeting",
    "tts_enabled": true,
    "tts_language": "en-US",
    "tts_voice": "en-US-JennyNeural",
    "tts_mode": "sync"
  }
}

TTS 參數	說明
`tts_enabled`	是否啟用 TTS（預設 `false`）
`tts_language`	TTS 輸出語言（需在 `translation_languages` 中）
`tts_voice`	TTS 語音名稱（如 `en-US-JennyNeural`）
`tts_mode`	`sync`（自動播放，預設）或 `async`（手動控制）

成功回應

啟動成功後，伺服器回傳 session_started 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "session_started",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "recording_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "recording_type": "transcribe",
    "recognition_mode": "single",
    "message": "語音辨識已開始"
  }
}

保存 session_id 和 recording_id，後續 API 操作會用到。

傳送音訊

Session 啟動後，持續傳送音訊資料給伺服器。

音訊格式要求

PCM 格式（預設、推薦）：

項目	規格
取樣率	16000 Hz
位元深度	16-bit
聲道	Mono（單聲道）
位元組順序	Little-endian

WebM/Opus 格式： 任意取樣率與聲道，伺服器自動轉換。

傳送格式

音訊資料需經 Base64 編碼後，以 audio action 傳送：

{
  "type": "voice-translation",
  "data": {
    "action": "audio",
    "payload": "Base64 編碼的音訊資料..."
  }
}

前端擷取音訊範例

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const audioContext = new AudioContext({ sampleRate: 16000 });
const source = audioContext.createMediaStreamSource(stream);
const processor = audioContext.createScriptProcessor(4096, 1, 1);

processor.onaudioprocess = (e) => {
  const float32 = e.inputBuffer.getChannelData(0);
  // 轉換為 16-bit PCM
  const int16 = new Int16Array(float32.length);
  for (let i = 0; i < float32.length; i++) {
    int16[i] = Math.max(-32768, Math.min(32767, float32[i] * 32768));
  }
  // Base64 編碼後傳送
  const base64 = btoa(String.fromCharCode(...new Uint8Array(int16.buffer)));
  ws.send(JSON.stringify({
    type: 'voice-translation',
    data: { action: 'audio', payload: base64 }
  }));
};

source.connect(processor);
processor.connect(audioContext.destination);

接收辨識與翻譯結果

伺服器會透過 result 事件推送辨識與翻譯結果。

語音辨識結果（Origin）

{
  "type": "voice-translation",
  "data": {
    "action": "result",
    "origin": {
      "sid": 1,
      "language": "zh-TW",
      "text": "你好，很高興認識你",
      "is_final": true,
      "speaker_id": "0",
      "detected_language": "zh-TW",
      "start_time": "00:05"
    }
  }
}

欄位	說明
`sid`	句子編號，從 1 開始遞增
`text`	辨識出的文字
`is_final`	`false` 為中間結果（會被覆蓋），`true` 為最終結果
`speaker_id`	說話者 ID（多人模式下有意義）
`start_time`	句子開始時間（格式 `mm:ss`）

翻譯結果（Translations）

{
  "type": "voice-translation",
  "data": {
    "action": "result",
    "translations": {
      "en-US": {
        "sid": 1,
        "text": "Hello, nice to meet you",
        "is_final": true
      }
    }
  }
}

重點：origin 和 translations 可能在同一個 result 事件中，也可能分開推送。前端需根據 sid 做對應。

TTS 語音就緒（TTS Ready）

若啟用了 TTS，翻譯完成後會收到 tts_ready 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "tts_ready",
    "sid": 1,
    "language": "en-US",
    "text": "Hello, nice to meet you",
    "audio": "Base64EncodedMP3...",
    "format": "mp3",
    "duration_ms": 2500,
    "boundaries": [...]
  }
}

boundaries 陣列包含 Word Boundary 資訊，可用於實作卡拉 OK 同步高亮效果。

操作控制

暫停

暫時停止語音辨識處理：

{
  "type": "voice-translation",
  "data": { "action": "pause" }
}

恢復

恢復已暫停的語音辨識：

{
  "type": "voice-translation",
  "data": { "action": "resume" }
}

設定錄音名稱

有兩種方式設定錄音名稱：

方式一：在 start 時指定 name 參數（初始預設名稱）

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "transcription_languages": ["zh-TW"],
    "type": "transcribe",
    "summary_template": "meeting",
    "name": "產品規劃會議"
  }
}

此名稱為初始預設，Session 結束時系統仍可能根據逐字稿內容覆蓋。

方式二：在錄音進行中使用 set_name（固定名稱）

{
  "type": "voice-translation",
  "data": {
    "action": "set_name",
    "name": "產品規劃會議"
  }
}

使用 set_name 設定的名稱不會被系統覆蓋。

若未設定名稱，系統會自動使用「類型 + 流水號」格式（如 Transcription #1、Broadcast #3）。Session 結束後，系統會根據逐字稿內容嘗試自動生成更有意義的名稱（但不會覆蓋透過 set_name 設定的名稱）。

切換翻譯語言

在錄音進行中切換目標語言，系統會自動將已翻譯的句子重新翻譯：

{
  "type": "voice-translation",
  "data": {
    "action": "switch_language",
    "translation_languages": ["ja-JP"]
  }
}

系統會依序回傳 language_switch_start → 多個 batch_retranslation → language_switch_done 事件。

重新翻譯指定句子

修正辨識錯誤後，可對單句重新翻譯：

{
  "type": "voice-translation",
  "data": {
    "action": "retranslate",
    "sid": 1,
    "translation_languages": ["en-US"],
    "text": "修正後的原文"
  }
}

進階功能

多語言翻譯

在 translation_languages 中指定多個目標語言，即可同時翻譯為多種語言：

{
  "transcription_languages": ["zh-TW"],
  "translation_languages": ["en-US", "ja-JP", "ko-KR"]
}

翻譯結果會以語言代碼為 key 一起回傳。

說話者辨識（Multi Speaker）

設定 recognition_mode 為 multi_speaker 啟用說話者辨識：

{
  "recognition_mode": "multi_speaker"
}

注意：multi_speaker 模式下 transcription_languages 必須恰好 1 個。若提供多個語言會收到 diarization_multilang_conflict 錯誤並拒絕開始。

啟用後，辨識結果中的 speaker_id 會自動區分不同說話者（如 Guest-1、Guest-2）。可搭配以下操作管理說話者：

rename_speaker：全域重命名說話者（如 Guest-1 改為 王經理）
reassign_speaker：修改單句的說話者身份
merge_speakers：合併兩位說話者（將一方的所有句子歸到另一方）

TTS 播放控制

在 async 模式下，可手動控制 TTS 播放：

播放指定句子：

{
  "type": "voice-translation",
  "data": {
    "action": "tts_play",
    "sid": 5,
    "length": 3
  }
}

停止播放：

{
  "type": "voice-translation",
  "data": { "action": "tts_stop" }
}

切換播放模式：

{
  "type": "voice-translation",
  "data": {
    "action": "tts_mode",
    "tts_mode": "async"
  }
}

模式	行為
`sync`	自動播放最新的 `is_final=true` 翻譯，前一句播完才播下一句
`async`	手動透過 `tts_play` 控制播放

文字處理參數（Config）

可在 start 之前或錄音進行中，透過 config action 設定術語庫、模糊詞校正和翻譯字典：

{
  "type": "voice-translation",
  "data": {
    "action": "config",
    "terminology": {
      "zh-TW": [
        { "term": "語者分離", "boost": 1.5 },
        { "term": "CVD製程", "boost": 1.5 }
      ]
    },
    "translation_dict": [
      {
        "source": "語者分離",
        "translations": { "en-US": "Speaker Diarization" }
      }
    ]
  }
}

設定項目	說明
`terminology`	術語庫 -- 提升特定詞彙的辨識準確度（每語言最多 500 個）
`fuzzy_correction`	模糊詞校正 -- 自動修正同音字錯誤（通常不需手動設定，系統會從 terminology 自動生成）
`translation_dict`	翻譯字典 -- 確保專有名詞翻譯一致（建議不超過 50 條）

推薦做法：只設定 terminology，系統會自動為每個術語生成同音字、近音字、繁簡體變體的校正規則。

互譯模式

互譯模式讓兩個說不同語言的人透過單一 WebSocket 連線進行即時互譯對話。系統自動偵測每句話的語言，翻譯為對方語言，並以 TTS 語音回傳翻譯結果。語言偵測完全自動，不需手動切換。

開始互譯

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "conversation",
    "transcription_languages": ["zh-TW", "en-US"],
    "audio_format": "pcm",
    "realtime_translation": true,
    "tts_config": {
      "zh-TW": { "voice": "zh-TW-HsiaoChenNeural", "speaking_rate": 1.0 },
      "en-US": { "voice": "en-US-JennyNeural", "speaking_rate": 1.0 }
    }
  }
}

transcription_languages 必須恰好 2 個語言
active_language 可選，指定初始偏好語言（語言偵測仍為自動）
tts_config 可省略，系統自動使用預設語音
tts_enabled 預設 true，設為 false 則僅回傳文字翻譯

自動語言偵測

系統自動偵測每句話的語言。每句話的 origin.language 直接反映偵測到的語言，翻譯目標自動為兩個語言中的另一個。

注意：不需要手動呼叫 switch_language 切換語言，系統會自動偵測。switch_language 仍可使用，但僅更新內部偏好狀態。

途中切換 TTS 設定

在互譯進行中，可透過 set_tts 切換 TTS 開關或更新語音設定：

{
  "type": "voice-translation",
  "data": {
    "action": "set_tts",
    "tts_enabled": true,
    "tts_config": {
      "en-US": { "voice": "en-US-GuyNeural", "speaking_rate": 1.2 }
    }
  }
}

成功後收到 tts_updated 事件，包含更新後的完整設定。

完整互譯流程

1. start (conversation, zh-TW + en-US)
2. session_started
3. 傳送音訊 (Person A 說中文)
4. result (origin.language: "zh-TW", translations: en-US)  ← 自動偵測
5. tts_ready (en-US 語音 → 播出給 Person B)
6. 傳送音訊 (Person B 說英文，不需切換！)
7. result (origin.language: "en-US", translations: zh-TW)  ← 自動偵測
8. tts_ready (zh-TW 語音 → 播出給 Person A)
9. stop
10. task_complete

停止與摘要

停止錄音

發送 stop action 結束語音翻譯工作階段：

{
  "type": "voice-translation",
  "data": { "action": "stop" }
}

事件流程

停止後，系統會依序執行以下步驟並推送事件：

status -- 確認語音辨識已停止
（背景處理） -- 上傳音檔、儲存逐字稿
task_complete -- 任務處理完成，包含 task_id

{
  "type": "voice-translation",
  "data": {
    "action": "task_complete",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "任務處理完成"
  }
}

（若設定了摘要模板） -- 系統自動生成摘要

保存 task_id，後續可透過 Tasks API 查詢結果，或使用 SSE API 載入歷史紀錄。

完整流程圖

                    前置準備
                       │
        ┌──────────────┼──────────────┐
        │              │              │
   取得 API Key   取得 Ticket    建立 WebSocket
        │              │              │
        └──────────────┼──────────────┘
                       │
               ┌───────▼───────┐
               │  config（選用）│  設定術語庫 / 校正規則
               └───────┬───────┘
                       │
               ┌───────▼───────┐
               │     start     │  開始語音翻譯
               └───────┬───────┘
                       │
               session_started
                       │
          ┌────────────▼────────────┐
          │                         │
    ┌─────▼─────┐            ┌─────▼─────┐
    │   audio   │────────────│   result  │
    │  （持續）  │  傳送音訊   │  辨識結果  │
    └─────┬─────┘            └─────┬─────┘
          │                        │
          │    ┌───────────────────┤
          │    │                   │
          │  origin           translations
          │  （原文）          （翻譯結果）
          │                        │
          │               ┌────────▼────────┐
          │               │ tts_ready（選用）│
          │               └─────────────────┘
          │
    ┌─────▼─────┐    ┌──────────┐
    │  pause /  │◄──►│ resume   │  操作控制
    │  resume   │    └──────────┘
    └─────┬─────┘
          │
    ┌─────▼─────┐
    │   stop    │  停止翻譯
    └─────┬─────┘
          │
    ┌─────▼──────────┐
    │  task_complete  │  任務完成（含 task_id）
    └─────┬──────────┘
          │
    ┌─────▼─────┐
    │  summary  │  摘要生成（若有設定模板）
    └───────────┘

文件	說明
認證機制	API Key、Ticket 認證詳細說明
Voice Translation Reference	所有 action 的完整 API 規格
回應事件 Reference	所有回應事件格式參考
歷史紀錄與回放	停止後如何載入歷史紀錄
TTS 語音合成	TTS 功能完整指南
說話者管理	說話者重命名、重新指派、合併