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

# william-weng/wwaudiofiletranscription

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

## ✨ [功能特色](https://peterpanswift.github.io/iphone-bezels/)

- 支援將既有音訊檔案轉換成文字。 - 支援指定語言與地區設定，例如 `zh-TW`、`en-US`、`ja-JP`。 - 支援即時回傳暫時辨識結果。 - 支援以 `AsyncThrowingStream` 接收連續辨識結果。 - 支援自訂專有名詞與上下文詞彙。 - 支援 `SFSpeechRecognitionTaskHint` 指定辨識用途。 - 支援取消目前進行中的轉錄工作。 - 支援使用者從「檔案」App 選取的 security-scoped URL。

## 📦 安裝

### 使用 Swift Package Manager

在 Xcode 中選擇：

`File` → `Add Package Dependencies...`

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

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

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

## 🔐 權限設定

因為套件使用 Apple Speech framework 進行語音辨識，請在 App 的 `Info.plist` 加入以下設定：

```xml <key>NSSpeechRecognitionUsageDescription</key> <string>需要使用語音辨識將音訊檔案轉換成文字</string> ```

## 📌 公開屬性

| 名稱 | 型別 | 說明 | | --- | --- | --- | | `isTranscribing` | `Bool` | 指示目前是否正在進行音訊轉錄。 | | `authorizationStatus` | `Bool` | 目前的語音辨識授權狀態。 | | `isAuthorized` | `Bool` | 指示目前是否已取得語音辨識權限。 | | `locale` | `Locale` | 語音辨識器目前使用的語系。 |

## 🏗️ 公開 API

| API | 宣告 | 說明 | | --- | --- | --- | | `init(locale:)` | `init(locale: Locale)` | 建立音訊檔案轉錄器。 | | `requestAuthorization()` | `requestAuthorization() async` | 請求使用語音辨識的授權。 | | `transcribe(audioFileURL:shouldReportPartialResults:contextualStrings:taskHint:result:)` | `transcribe(audioFileURL: URL, shouldReportPartialResults: Bool = false, contextualStrings: [String] = [], taskHint: SFSpeechRecognitionTaskHint = .dictation, result: @escaping (Result<TranscriptResult, TranscriptError>) -> Void)` | 建立音訊檔案轉錄器。 | | `transcribe(audioFileURL:shouldReportPartialResults:contextualStrings:taskHint:)` | `transcribe(audioFileURL: URL, shouldReportPartialResults: Bool = false, contextualStrings: [String] = [], taskHint: SFSpeechRecognitionTaskHint = .dictation) -> AsyncThrowingStream<TranscriptResult, any Error>` | 建立音訊檔案轉錄器。 |

## 🚀 基本使用方式

### 建立轉錄器

```swift import Speech

let transcriber = WWAudioFileTranscription(     locale: Locale(identifier: "zh-TW") ) ```

### 請求語音辨識權限

```swift Task {     await transcriber.requestAuthorization()

guard transcriber.isAuthorized else {         print("尚未取得語音辨識權限")         return     } } ```

> `requestAuthorization()` 應該在開始轉錄前呼叫一次。授權狀態可以透過以下屬性查詢：

```swift transcriber.authorizationStatus transcriber.isAuthorized ```

## 🧠 自訂上下文詞彙

如果音訊中包含產品名稱、技術名詞、人名或其他專有名詞，可以傳入 `contextualStrings`：

```swift let contextualStrings = [     "SwiftUI",     "AVFoundation",     "SFSpeechRecognizer",     "Swift Package Manager",     "WWAudioFileTranscription" ]

transcriber.transcribe(     audioFileURL: audioURL,     shouldReportPartialResults: true,     contextualStrings: contextualStrings ) { result in     // 處理轉錄結果 } ```

> 這些詞彙會提供給 Speech framework 作為辨識時的上下文參考。

## 🌏 指定辨識語言

建立轉錄器時指定 `Locale`：

```swift let traditionalChineseTranscriber = WWAudioFileTranscription(     locale: Locale(identifier: "zh-TW") )

let englishTranscriber = WWAudioFileTranscription(     locale: Locale(identifier: "en-US") )

let japaneseTranscriber = WWAudioFileTranscription(     locale: Locale(identifier: "ja-JP") ) ```

> 請根據音訊內容選擇正確的語言，語言設定會直接影響辨識結果。

## 🧪 完整範例

```swift import UIKit import WWAudioFileTranscription

final class ViewController: UIViewController {          @IBOutlet weak var resultLabel: UILabel!          private let filename = "demo.wav"     private let transcriber: WWAudioFileTranscription = .init(locale: .init(identifier: "en-US"))          override func viewDidLoad() {         super.viewDidLoad()         Task { await transcriber.requestAuthorization() }     }          @IBAction func directTranscript(_ sender: UIButton) {                  let audioFileURL = Bundle.main.url(forResource: filename, withExtension: nil)!         resultLabel.text = ""                  transcriber.transcribe(audioFileURL: audioFileURL) { [weak self] (result) in             switch result {             case .success(let transcription): self?.resultLabel.text = transcription.transcript             case .failure(let error): self?.resultLabel.text = error.localizedDescription             }         }     }          @IBAction func liveTranscript(_ sender: UIButton) {                  let audioFileURL = Bundle.main.url(forResource: filename, withExtension: nil)!         resultLabel.text = ""

Task {             do {                 for try await result in transcriber.transcribe(audioFileURL: audioFileURL, shouldReportPartialResults: true) {                     resultLabel.text = result.transcript                 }             } catch {                 resultLabel.text = error.localizedDescription             }         }     } } ```

## ⚠️ 注意事項

- `WWAudioFileTranscription` 使用 `@MainActor`，請在主 actor 上建立與使用。 - 開始轉錄前必須先呼叫 `requestAuthorization()`。 - 轉錄器一次只處理一個音訊檔案。 - 音訊檔案必須存在，且格式必須是 Speech framework 支援的格式。 - `shouldReportPartialResults` 為 `true` 時，結果會多次回傳，請檢查 `isFinal`。 - 語音辨識能力與可用語言會依裝置、系統版本及 Apple Speech service 狀態而有所不同。 - Speech framework 的辨識處理可能涉及將音訊傳送至 Apple 的伺服器；請在 App 隱私權政策中清楚說明相關資料處理方式。 - 如果 App 需要完全離線的語音辨識，請另外評估裝置端辨識能力或其他離線模型方案。

## Package Metadata

Repository: william-weng/wwaudiofiletranscription

Default branch: main

README: README.md