---
title: william-weng/wwaudiostreamtranscription
framework: Swift Package Catalog
role: article
path: packages/william-weng/wwaudiostreamtranscription
---

# william-weng/wwaudiostreamtranscription

[English](./README.en.md) | [正體中文](./README.md)

## ✨ 功能特色

- **串流式辨識**：持續接收 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)

```swift 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