Skip to main content

​
使用指南

即時語音辨識 API 使用 WebSocket 協定提供低延遲的語音串流辨識服務。本指南將幫助您快速整合並優化即時語音辨識功能。
API 的詳細參數、請求格式和回應結構請參考自動生成的 API 文件。本頁面專注於實際使用指南和最佳實踐。

​
快速整合

​
基本 WebSocket 連線

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();
    }
});

​
最佳實踐

​
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 指南或聯絡技術支援。