SwiftWhisper

在 Swift 中使用 Whisper 的最简单方式

轻松为您的应用或软件包添加转录功能。由 whisper.cpp 提供支持。

安装

Swift 包管理器

在您的 Package.swift 文件中将 SwiftWhisper 添加为依赖项：

let package = Package(
  ...
  dependencies: [
    // 将该包添加到您的依赖项中
    .package(url: "https://github.com/exPHAT/SwiftWhisper.git", branch: "master"),
  ],
  ...
  targets: [
    // 将 SwiftWhisper 作为依赖项添加到您希望使用它的任何目标中
    .target(name: "MyTarget",
            dependencies: [.byName(name: "SwiftWhisper")])
  ]
  ...
)

Xcode

在“Swift 包管理器”选项卡中添加 https://github.com/exPHAT/SwiftWhisper.git。查看文档

使用

API 文档。

import SwiftWhisper

let whisper = Whisper(fromFileURL: /* 模型文件 URL */)
let segments = try await whisper.transcribe(audioFrames: /* 16kHz PCM 音频帧 */)

print("转录后的音频:", segments.map(\.text).joined())

代理方法

您可以通过实现 WhisperDelegate 并设置 whisper.delegate = ... 来订阅分段、转录进度和错误信息。

protocol WhisperDelegate {
  // 进度更新，范围为 0 到 1 的百分比
  func whisper(_ aWhisper: Whisper, didUpdateProgress progress: Double)

  // 每当有新的文本分段被转录时
  func whisper(_ aWhisper: Whisper, didProcessNewSegments segments: [Segment], atIndex index: Int)
  
  // 转录完成，包含所有已转录的文本分段
  func whisper(_ aWhisper: Whisper, didCompleteWithSegments segments: [Segment])

  // 转录过程中出现错误
  func whisper(_ aWhisper: Whisper, didErrorWith error: Error)
}

其他

下载模型 :inbox_tray:

您可以在 这里 找到预训练模型并下载。

CoreML 支持 :brain:

要使用 CoreML，您需要包含一个后缀为 -encoder.mlmodelc 的 CoreML 模型文件，其名称与 Whisper 模型相同（例如：tiny.bin 旁边也会有一个 tiny-encoder.mlmodelc 文件）。除了额外的模型文件外，您还需要使用 Whisper(fromFileURL:) 初始化方法。您可以通过在转录过程中查看控制台输出来验证 CoreML 是否已启用。

将音频转换为 16kHz PCM :wrench:

将音频帧导入 SwiftWhisper 的最简单方法是使用 AudioKit。以下示例会读取输入音频文件，将其转换并重新采样，然后返回一个 16kHz PCM 浮点数数组。

import AudioKit

func convertAudioFileToPCMArray(fileURL: URL, completionHandler: @escaping (Result<[Float], Error>) -> Void) {
    var options = FormatConverter.Options()
    options.format = .wav
    options.sampleRate = 16000
    options.bitDepth = 16
    options.channels = 1
    options.isInterleaved = false

    let tempURL = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(UUID().uuidString)
    let converter = FormatConverter(inputURL: fileURL, outputURL: tempURL, options: options)
    converter.start { error in
        if let error {
            completionHandler(.failure(error))
            return
        }

        let data = try! Data(contentsOf: tempURL) // 在此处处理错误

        let floats = stride(from: 44, to: data.count, by: 2).map {
            return data[$0..<$0 + 2].withUnsafeBytes {
                let short = Int16(littleEndian: $0.load(as: Int16.self))
                return max(-1.0, min(Float(short) / 32767.0, 1.0))
            }
        }

        try? FileManager.default.removeItem(at: tempURL)

        completionHandler(.success(floats))
    }
}

开发速度提升 :rocket:

在为 Debug 构建配置编译应用程序时，您可能会发现转录性能较慢。这是因为编译器不会对 SwiftWhisper 进行完全优化，除非构建配置设置为 Release。

您可以通过安装使用 .unsafeFlags(["-O3"]) 强制进行最大优化的 SwiftWhisper 版本来解决这个问题。最简单的方法是使用 fast 分支上的最新提交。或者，您可以将方案配置为以 Release 配置进行构建。

  ...
  dependencies: [
    // 使用 `fast` 分支的最新提交哈希值：
    .package(url: "https://github.com/exPHAT/SwiftWhisper.git", revision: "deb1cb6a27256c7b01f5d3d2e7dc1dcc330b5d01"),
  ],
  ...

SwiftWhisper 快速上手指南

SwiftWhisper 是在 Swift 项目中使用 Whisper 语音识别模型的最简便方式，基于 whisper.cpp 构建，可轻松为 App 添加语音转文字功能。

环境准备

• 系统要求：macOS 12.0+、iOS 15.0+、watchOS 8.0+、tvOS 15.0+
• 开发工具：Xcode 14.0+
• 前置依赖：
  • 无需额外安装底层依赖（内部已集成 whisper.cpp）
  • 若需处理音频文件，推荐使用 AudioKit 进行格式转换（见下文示例）
  • 需自行下载预训练模型文件（.bin 格式），下载地址：Hugging Face - whisper.cpp models

💡 提示：国内开发者访问 Hugging Face 可能较慢，建议使用镜像站如 ModelScope 搜索 "whisper.cpp" 获取加速下载。

安装步骤

方式一：Swift Package Manager（推荐）

在项目的 Package.swift 文件中添加依赖：

let package = Package(
  ...
  dependencies: [
    .package(url: "https://github.com/exPHAT/SwiftWhisper.git", branch: "master"),
  ],
  ...
  targets: [
    .target(name: "MyTarget",
            dependencies: [.byName(name: "SwiftWhisper")])
  ]
  ...
)

方式二：Xcode 图形界面

1. 打开 Xcode 项目
2. 点击菜单栏 File → Add Packages...
3. 输入仓库地址：https://github.com/exPHAT/SwiftWhisper.git
4. 选择分支 master 并添加

⚡ 性能优化建议：Debug 模式下转录速度可能较慢。如需提升开发体验，可改用 fast 分支（强制开启 -O3 优化）：

.package(url: "https://github.com/exPHAT/SwiftWhisper.git", revision: "deb1cb6a27256c7b01f5d3d2e7dc1dcc330b5d01")

基本使用

1. 导入模块并初始化

确保已将模型文件（如 tiny.bin）添加到项目中，并获取其 URL：

import SwiftWhisper

let modelURL = Bundle.main.url(forResource: "tiny", withExtension: "bin")!
let whisper = Whisper(fromFileURL: modelURL)

2. 执行转录

传入 16kHz 单声道 PCM 音频数据（Float 数组）：

let segments = try await whisper.transcribe(audioFrames: audioFrames)

print("转录结果:", segments.map(\.text).joined())

3. （可选）监听进度与结果

实现 WhisperDelegate 协议以实时获取转录进度和片段：

class MyDelegate: WhisperDelegate {
    func whisper(_ aWhisper: Whisper, didUpdateProgress progress: Double) {
        print("进度: \(progress * 100)%")
    }
    
    func whisper(_ aWhisper: Whisper, didProcessNewSegments segments: [Segment], atIndex index: Int) {
        print("新片段: \(segments.map(\.text))")
    }
    
    func whisper(_ aWhisper: Whisper, didCompleteWithSegments segments: [Segment]) {
        print("完成：\(segments.map(\.text).joined())")
    }
    
    func whisper(_ aWhisper: Whisper, didErrorWith error: Error) {
        print("错误: \(error)")
    }
}

whisper.delegate = MyDelegate()

附：音频格式转换示例（使用 AudioKit）

若原始音频非 16kHz PCM，需先转换：

import AudioKit

func convertAudioFileToPCMArray(fileURL: URL, completionHandler: @escaping (Result<[Float], Error>) -> Void) {
    var options = FormatConverter.Options()
    options.format = .wav
    options.sampleRate = 16000
    options.bitDepth = 16
    options.channels = 1
    options.isInterleaved = false

    let tempURL = URL(fileURLWithPath: NSTemporaryDirectory()).appendingPathComponent(UUID().uuidString)
    let converter = FormatConverter(inputURL: fileURL, outputURL: tempURL, options: options)
    converter.start { error in
        if let error {
            completionHandler(.failure(error))
            return
        }

        let data = try! Data(contentsOf: tempURL)
        let floats = stride(from: 44, to: data.count, by: 2).map {
            return data[$0..<$0 + 2].withUnsafeBytes {
                let short = Int16(littleEndian: $0.load(as: Int16.self))
                return max(-1.0, min(Float(short) / 32767.0, 1.0))
            }
        }

        try? FileManager.default.removeItem(at: tempURL)
        completionHandler(.success(floats))
    }
}

🧠 CoreML 加速：如需启用 CoreML 加速，请同时提供同名 -encoder.mlmodelc 模型文件（如 tiny-encoder.mlmodelc），并使用相同初始化方法。转录时控制台会显示 CoreML 是否激活。