> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skiesoft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 即時語音辨識使用指南

> WebSocket 即時語音串流辨識的實用整合指南和最佳實踐

## 使用指南

即時語音辨識 API 使用 WebSocket 協定提供低延遲的語音串流辨識服務。本指南將幫助您快速整合並優化即時語音辨識功能。

<Note>
  API 的詳細參數、請求格式和回應結構請參考自動生成的 API 文件。本頁面專注於實際使用指南和最佳實踐。
</Note>

## 快速整合

### 基本 WebSocket 連線

<CodeGroup>
  ```javascript Node.js theme={null}
  const WebSocket = require('ws');
  const fs = require('fs');

  const SERVER_URL = 'wss://api.skiesoft.com/asr';
  const WEBM_FILE_PATH = 'input.webm';
  const API_TOKEN = 'your-api-token-here';

  const ws = new WebSocket(SERVER_URL, {
      headers: { 'Authorization': `Bearer ${API_TOKEN}` }
  });

  ws.on('open', async () => {
      console.log('連接成功');

      const fileStream = fs.createReadStream(WEBM_FILE_PATH);

      fileStream.on('data', (data) => {
          ws.send(data);
      });

      fileStream.on('end', () => {
          ws.send(Buffer.alloc(0)); // 發送空 buffer 表示結束
          console.log('文件發送完成');
      });
  });

  ws.on('message', (message) => {
      const data = JSON.parse(message.toString());
      console.log('收到訊息:', data);
      if (data.type === 'ready_to_stop') {
          ws.close();
      }
  });
  ```

  ```javascript browser theme={null}
  const SERVER_URL = 'wss://api.skiesoft.com/asr';
  const API_TOKEN = 'your-api-token-here';

  const ws = new WebSocket(
      websocketUrl, 
      [
          'realtime', 
          'thiannuai-api-key.' + API_TOKEN
      ]
  );

  ws.on('open', async () => {
      console.log('連接成功');
  });

  ws.on('message', (message) => {
      const data = JSON.parse(message.toString());
      console.log('收到訊息:', data);
      if (data.type === 'ready_to_stop') {
          ws.close();
      }
  });
  ```
</CodeGroup>

## 最佳實踐

### 1. 連線管理和重連機制

穩健的 WebSocket 連線管理是確保即時語音辨識服務可靠性的關鍵：

**連線初始化**：

* 建立包含 URL、選項和狀態追蹤的連線管理類別
* 配置最大重連次數、重連間隔等參數
* 維護連線狀態和意圖關閉標記

**自動重連策略**：

* 實作指數退避演算法，避免頻繁重連造成伺服器負載
* 設定最大重連次數限制，防止無限重連
* 區分意圖關閉和異常斷線，只對異常斷線進行重連

**連線狀態監控**：

* 監聽所有 WebSocket 事件：開啟、訊息、關閉、錯誤
* 記錄連線狀態變化和錯誤資訊
* 提供狀態回調機制供上層應用處理

**錯誤處理機制**：

* 實作完整的錯誤處理流程
* 提供錯誤分類和對應的處理策略
* 支援錯誤回報和診斷功能

**資源管理**：

* 確保連線正確關閉，避免資源洩漏
* 實作連線池管理，支援多個並發連線
* 提供連線狀態查詢和統計功能

### 2. 音訊品質監控

實時監控音訊品質對於確保語音辨識準確性至關重要：

**音訊分析器設置**：

* 使用 Web Audio API 的 AnalyserNode 來分析音訊頻譜
* 設定適當的 FFT 大小（建議 256 或 512）來平衡效能和精度
* 建立音訊上下文和媒體串流源的連接

**即時品質評估**：

* 持續監控音量水平，確保音訊輸入在適當範圍內
* 分析頻率分布，檢測低頻、中頻、高頻的能量分布
* 計算整體音訊品質指標，包括信噪比和動態範圍

**品質指標計算**：

* 實作音量正規化演算法，將原始數據轉換為 0-1 範圍
* 分析不同頻段的能量分布，評估音訊完整性
* 提供即時品質回饋機制，供應用程式調整設定

**監控生命週期管理**：

* 實作開始和停止監控的完整流程
* 確保音訊上下文正確關閉，避免資源洩漏
* 提供品質更新事件處理機制

### 3. 緩衝區管理

有效的音訊緩衝區管理是確保即時語音辨識流暢運行的關鍵：

**緩衝區配置**：

* 根據應用需求設定適當的緩衝區大小（建議 4096 樣本）
* 配置正確的採樣率（建議 16kHz）和聲道數（單聲道）
* 建立緩衝區陣列來儲存音訊資料片段

**音訊處理流程**：

* 使用 ScriptProcessorNode 或 AudioWorklet 處理即時音訊
* 建立媒體串流源和音訊處理器的連接
* 實作音訊資料的複製和時間戳記錄

**緩衝區生命週期**：

* 持續收集音訊資料並加入時間戳
* 實作緩衝區大小限制，防止記憶體無限增長
* 提供最新緩衝區和時間範圍查詢功能

**資料管理策略**：

* 實作先進先出（FIFO）的緩衝區清理機制
* 提供緩衝區清空和停止功能
* 支援按時間範圍檢索歷史音訊資料

**事件處理機制**：

* 提供緩衝區就緒事件回調
* 支援自定義事件處理器
* 確保音訊處理的即時性和連續性

### 4. 延遲優化

最小化端到端延遲是即時語音辨識系統的核心要求：

**延遲測量機制**：

* 記錄音訊資料發送時間和接收辨識結果的時間
* 維護延遲測量歷史記錄，通常保留最近 100 次測量
* 設定目標延遲閾值（建議 200ms 以下）

**動態延遲分析**：

* 計算平均延遲、最大延遲和延遲變異性
* 識別延遲趨勢和異常值
* 提供延遲統計報告和警告機制

**自適應優化策略**：

* 根據當前延遲動態調整緩衝區大小
* 延遲過高時減少緩衝區大小（最小 1024 樣本）
* 延遲較低時適度增加緩衝區以提升品質（最大 8192 樣本）

**品質與延遲平衡**：

* 監控延遲是否超過目標值的兩倍
* 在延遲過高時觸發品質調整機制
* 實作延遲優先或品質優先的切換策略

**效能調優建議**：

* 使用較小的音訊塊大小減少處理延遲
* 優化網路傳輸和 WebSocket 配置
* 考慮使用音訊壓縮來減少傳輸時間

## 效能優化建議

### 1. 網路優化

* 使用 CDN 加速 WebSocket 連線
* 實作連線池管理
* 監控網路品質並動態調整

### 2. 音訊處理優化

* 使用 Web Workers 處理音訊資料
* 實作音訊壓縮以減少頻寬使用
* 動態調整音訊品質

### 3. 記憶體管理

* 定期清理音訊緩衝區
* 避免記憶體洩漏
* 監控記憶體使用量

## 故障排除

### 常見問題

1. **WebSocket 連線失敗**
   * 檢查 API 金鑰是否正確
   * 確認網路連線穩定
   * 檢查防火牆設定

2. **音訊品質差**
   * 檢查麥克風設定
   * 確認採樣率配置
   * 移除背景噪音

3. **延遲過高**
   * 減少緩衝區大小
   * 檢查網路延遲
   * 優化音訊處理流程

4. **辨識準確率低**
   * 改善音訊品質
   * 調整語言設定

***

需要更多協助？請查看我們的[即時 API 指南](/essentials/real-time-api)或[聯絡技術支援](mailto:support@skiesoft.com)。