Contents

william-weng/wwaudiostreamtranscription

English | 正體中文

✨ 功能特色

  • 串流式辨識：持續接收 PCM buffer 並即時轉寫為文字
  • 即時回呼：透過 onResult 回呼，即時取得部分與最終辨識結果
  • 錯誤處理：透過 onError 回呼，統一處理辨識過程中的錯誤
  • 多語言支援：可指定 Locale 進行不同語言的語音辨識
  • 輕量封裝：只暴露必要 API，方便整合進各種音訊管線

📦 安裝方式

使用 Swift Package Manager

在 Xcode 中選擇：

File → Add Package Dependencies...

接著輸入套件 repository URL，選擇要使用的版本，並將套件加入 App target。

如果這是本地套件，也可以在 Xcode 中使用：

File → Add Package Dependencies... → Add Local...

🧠 使用情境

  • 即時語音輸入：將麥克風輸入即時轉為文字
  • 通話錄音轉寫：搭配音訊擷取管線進行即時字幕
  • 語音指令辨識：在背景持續聆聽並辨識特定指令
  • 影片即時字幕：對即時音訊串流產生字幕

🏗️ 公開 API

| API | 說明 | | --- | --- | | requestAuthorization() | 請求語音辨識授權。 | | init(locale:shouldReportPartialResults:addsPunctuation:) | 建立 WWAudioStreamTranscription 實體。 | | append(buffer:) | 接收外部傳入的 PCM 音訊 buffer，並附加到辨識請求中。 | | start() | 啟動語音辨識 task。 | | finish() | 結束目前辨識，保留處理已經傳入的音訊機會。 | | cancel() | 立即取消目前辨識 |

📌 公開屬性

| 名稱 | 宣告 | 說明 | | --- | --- | --- | | onResult | onResult: (@Sendable (String, Bool) -> Void)? | 當有新的辨識結果時呼叫的回呼。 | | onError | onError: (@Sendable (Error) -> Void)? | 當發生錯誤時呼叫的回呼。 |

⚠️ 注意事項

  • 權限設定：使用前需請求 SFSpeechRecognizer 與麥克風權限
  • 語言支援：並非所有 Locale 都支援離線或線上辨識，請先確認
  • 執行緒安全：onResult 與 onError 可能在背景執行緒呼叫，若更新 UI 需派發到 MainActor
  • 單一任務：同一個 WWAudioStreamTranscription 實體同時只能有一個進行中的辨識任務

🧩 相關類型

  • WWAudioStreamTranscriptionResult：封裝辨識結果的文字與是否為最終結果
  • WWAudioStreamTranscriptionError：轉寫過程可能發生的錯誤類型

🧪 [簡單範例](https://github.com/William-Weng/RealTimeSpeechToText)

private extension SpeechViewModel {
    
    func createAudioPipeline() throws {
        
        let transcription = try WWAudioStreamTranscription(locale: locale)
        
        transcription.onResult = { [weak self] text, isFinal in
            
            Task { @MainActor in
                self?.text = text
                if isFinal { self?.isRecording = false }
            }
        }
        
        transcription.onError = { [weak self] error in
            
            Task { @MainActor in
                self?.errorMessage = error.localizedDescription
                self?.stop()
            }
        }
        
        let microphone = WWMicrophoneInput { [weak transcription] buffer in
            transcription?.append(buffer: buffer)
        }
        
        try microphone.configure()
        try transcription.start()
        try microphone.start()
        
        self.transcription = transcription
        self.microphoneInput = microphone
    }
}

Package Metadata

Repository: william-weng/wwaudiostreamtranscription

Default branch: main

README: README.md