WhisperKit 是一个由 Argmax 开发的框架，用于在设备端部署最先进的语音转文本系统（例如 Whisper），并提供实时流式传输、词级时间戳、语音活动检测、说话人分离等高级功能。

[TestFlight 演示应用] [Python 工具] [基准测试与设备支持] [WhisperKit Android]

[!IMPORTANT] WhisperKit 非常适合开始使用设备端语音转文本功能。当您准备好通过实时转录和说话人分离来扩展设备端部署时，请启动您的 14 天试用，体验 Argmax Pro SDK，其中包含速度提升 9 倍且准确率更高的模型，如 Nvidia Parakeet V3、Nvidia Sortformer 流式说话人分离模型，以及兼容 Deepgram 的 WebSocket 本地服务器，便于集成到非 Swift 项目中。

目录

• 安装
  • Swift 包管理器
  • 先决条件
  • Xcode 步骤
  • Package.swift
  • Homebrew
• 快速入门
  • 快速示例
  • 模型选择
  • 生成模型
  • Swift CLI
  • WhisperKit 本地服务器
    • 构建服务器
    • 启动服务器
    • API 端点
    • 支持的参数
    • 客户端示例
    • 生成 API 规范
    • 客户端生成
    • API 限制
    • 完全支持的功能
• TTSKit
  • 快速示例
  • 模型选择
    • 自定义声音
    • 实时流式播放
  • 生成选项
    • 风格指令（仅限 1.7B 模型）
  • 保存音频
  • 进度回调
  • Swift CLI
  • 演示应用
• SpeakerKit
  • 快速示例
  • 分离选项
  • 与转录结合
  • RTTM 输出
  • Swift CLI
• 贡献与路线图
• 许可证
• 引用

安装

Swift 包管理器

WhisperKit、TTSKit 和 SpeakerKit 是同一个 Swift 包中的独立库产品。只需添加一次包，即可根据需要选择所需的产品。

先决条件

• macOS 14.0 或更高版本。
• Xcode 16.0 或更高版本。

Xcode 步骤

1. 在 Xcode 中打开您的 Swift 项目。
2. 导航至 File > Add Package Dependencies...。
3. 输入包仓库 URL：https://github.com/argmaxinc/whisperkit。
4. 选择版本范围或特定版本。
5. 当提示选择库产品时，选择 WhisperKit、TTSKit、SpeakerKit，或任意组合。

Package.swift

如果您将 WhisperKit、TTSKit 或 SpeakerKit 作为 Swift 包的一部分使用，可以在您的 Package.swift 依赖项中按如下方式添加：

dependencies: [
    .package(url: "https://github.com/argmaxinc/WhisperKit.git", from: "0.9.0"),
],

然后将所需的产品作为目标依赖项添加：

.target(
    name: "YourApp",
    dependencies: [
        "WhisperKit",   // 语音转文本
        "TTSKit",       // 文本转语音
        "SpeakerKit",   // 说话人分离
    ]
),

Homebrew

您可以使用 Homebrew 安装 WhisperKit 命令行应用程序，方法是运行以下命令：

brew install whisperkit-cli

快速入门

要开始使用 WhisperKit，您需要在项目中对其进行初始化。

快速示例

此示例演示如何转录本地音频文件：

import WhisperKit

// 使用默认设置初始化 WhisperKit
Task {
   let pipe = try? await WhisperKit()
   let transcription = try? await pipe!.transcribe(audioPath: "path/to/your/audio.{wav,mp3,m4a,flac}")?.text
    print(transcription)
}

模型选择

如果未指定，WhisperKit 会自动下载适用于当前设备的推荐模型。您也可以通过传递模型名称来选择特定模型：

let pipe = try? await WhisperKit(WhisperKitConfig(model: "large-v3"))

此方法还支持通配符搜索，因此您可以使用通配符来选择模型：

let pipe = try? await WhisperKit(WhisperKitConfig(model: "distil*large-v3"))

请注意，模型搜索必须从源仓库返回单个模型，否则将抛出错误。

有关可用模型的列表，请参阅我们的 HuggingFace 仓库。

生成模型

WhisperKit 还附带了一个支持性仓库 whisperkittools，它允许你创建并以 CoreML 格式将自己微调过的 Whisper 版本部署到 HuggingFace。一旦生成，只需将仓库名称更改为用于上传模型的那个即可加载：

let config = WhisperKitConfig(model: "large-v3", modelRepo: "username/your-model-repo")
let pipe = try? await WhisperKit(config)

Swift CLI

Swift CLI 允许在 Xcode 项目之外快速进行测试和调试。要安装它，请运行以下命令：

git clone https://github.com/argmaxinc/whisperkit.git
cd whisperkit

然后设置环境并下载你想要的模型。

make setup
make download-model MODEL=large-v3

注意：

1. 这只会下载由 MODEL 指定的模型（请参阅我们 HuggingFace 仓库 中可用的模型，我们在那里使用前缀 openai_whisper-{MODEL}）。
2. 在运行 download-model 之前，请确保已安装 git-lfs。

如果你想将所有可用模型下载到本地文件夹，可以使用以下命令代替：

make download-models

之后，你可以通过 CLI 运行它们：

swift run whisperkit-cli transcribe --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" --audio-path "path/to/your/audio.{wav,mp3,m4a,flac}"

这应该会打印出音频文件的转录内容。如果你希望直接从麦克风流式传输音频，可以使用：

swift run whisperkit-cli transcribe --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" --stream

WhisperKit 本地服务器

WhisperKit 包含一个实现了 OpenAI 音频 API 的本地服务器，允许你使用现有的 OpenAI SDK 客户端或生成新的客户端。该服务器支持转录和翻译，并具备 输出流式传输 功能（即在生成转录结果时实时显示）。

[!NOTE] 对于具有全双工流式传输功能的实时转录服务器，请查看 WhisperKit Pro 本地服务器，它为需要连续音频处理的应用程序提供实时音频流和转录功能。

构建服务器

# 带服务器支持的构建
make build-local-server

# 或者手动使用构建标志
BUILD_ALL=1 swift build --product whisperkit-cli

启动服务器

# 使用默认设置启动服务器
BUILD_ALL=1 swift run whisperkit-cli serve

# 自定义主机和端口
BUILD_ALL=1 swift run whisperkit-cli serve --host 0.0.0.0 --port 8080

# 使用特定模型并启用详细日志记录
BUILD_ALL=1 swift run whisperkit-cli serve --model tiny --verbose

# 查看所有可配置参数
BUILD_ALL=1 swift run whisperkit-cli serve --help

API 端点

• POST /v1/audio/transcriptions - 将音频转录为文本
• POST /v1/audio/translations - 将音频翻译成英语

支持的参数

参数	描述	默认值
file	音频文件（wav、mp3、m4a、flac）	必需
model	模型标识符	服务器默认
language	源语言代码	自动检测
prompt	用于指导转录的文本	无
response_format	输出格式（json、verbose_json）	verbose_json
temperature	采样温度（0.0–1.0）	0.0
timestamp_granularities[]	时间精度（词、片段）	片段
stream	启用流式传输	false

客户端示例

Python 客户端（OpenAI SDK）

cd Examples/ServeCLIClient/Python
uv sync
python whisperkit_client.py transcribe --file audio.wav --language en
python whisperkit_client.py translate --file audio.wav

快速 Python 示例：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:50060/v1")
result = client.audio.transcriptions.create(
    file=open("audio.wav", "rb"),
    model="tiny"  # 模型参数是必需的
)
print(result.text)

Swift 客户端（根据 OpenAPI 规范生成，详见 ServeCLIClient/Swift/updateClient.sh）

cd Examples/ServeCLIClient/Swift
swift run whisperkit-client transcribe audio.wav --language en
swift run whisperkit-client translate audio.wav

Curl 客户端（Shell 脚本）

cd Examples/ServeCLIClient/Curl
chmod +x *.sh
./transcribe.sh audio.wav --language en
./translate.sh audio.wav --language es
./test.sh  # 运行全面的测试套件

生成 API 规范

服务器的 OpenAPI 规范和代码是从官方 OpenAI API 生成的：

# 生成最新的规范和服务器代码
make generate-server

客户端生成

你可以使用 OpenAPI 规范为任何语言生成客户端，例如：

# 生成 Python 客户端
swift run swift-openapi-generator generate scripts/specs/localserver_openapi.yaml \
  --output-directory python-client \
  --mode client \
  --mode types

# 生成 TypeScript 客户端
npx @openapitools/openapi-generator-cli generate \
  -i scripts/specs/localserver_openapi.yaml \
  -g typescript-fetch \
  -o typescript-client

API 的局限性

与官方 OpenAI API 相比，本地服务器存在以下限制：

• 响应格式：仅支持 json 和 verbose_json（不支持纯文本、SRT、VTT 格式）。
• 模型选择：客户端必须通过 --model 标志指定所需的模型来启动服务器。

完全支持的功能

本地服务器完全支持以下 OpenAI API 功能：

• 包含参数：logprobs 参数可用于获取详细的标记级对数概率。
• 流式响应：使用服务器发送事件（SSE）实现实时转录。
• 时间戳粒度：支持词级和片段级时间戳。
• 语言检测：自动检测语言或手动指定。
• 温度控制：用于控制转录随机性的采样温度。
• 提示文本：用于指导转录风格和上下文的文本。

TTSKit

TTSKit 是一个基于 Core ML 的设备端文本到语音框架。它在 Apple 芯片上完全运行 Qwen3 TTS 模型，支持实时流式播放，无需服务器。

• macOS 15.0 或更高版本。
• iOS 18.0 或更高版本。

快速示例

此示例演示如何从文本生成语音：

import TTSKit

Task {
    let tts = try await TTSKit()
    let result = try await tts.generate(text: "Hello from TTSKit!")
    print("生成了 \(result.audioDuration)s 的音频，采样率为 \(result.sampleRate)Hz")
}

TTSKit() 会在首次运行时自动下载默认的 0.6B 模型。分词器和 CoreML 模型会在首次调用 generate() 时按需加载。

模型选择

TTSKit 提供两种模型尺寸。您可以通过将变体传递给 TTSKitConfig 来选择模型：

// 速度快，可在所有平台上运行（约 1 GB 下载）
let tts = try await TTSKit(TTSKitConfig(model: .qwen3TTS_0_6b))

// 质量更高，仅限 macOS 平台（约 2.2 GB 下载，支持风格指令）
let tts = try await TTSKit(TTSKitConfig(model: .qwen3TTS_1_7b))

模型托管在 HuggingFace 上，并在首次下载后缓存到本地。

自定义语音

您可以从 9 种内置语音和 10 种语言中进行选择：

let result = try await tts.generate(
    text: "こんにちは世界",
    speaker: .onoAnna,
    language: .japanese
)

语音： .ryan、.aiden、.onoAnna（"ono-anna"）、.sohee、.eric、.dylan、.serena、.vivian、.uncleFu（"uncle-fu"）

语言： .english、.chinese、.japanese、.korean、.german、.french、.russian、.portuguese、.spanish、.italian

实时流式播放

play 会在音频生成的同时逐帧流式传输到设备扬声器：

try await tts.play(text: "这会在生成完成之前就开始播放。")

您可以控制在开始播放之前缓冲的音频量。默认的 .auto 策略会测量第一个生成步骤，并预缓冲刚好足以避免欠载的音频：

try await tts.play(
    text: "长段文字...",
    playbackStrategy: .auto
)

其他策略包括 .stream（立即播放，无缓冲）、.buffered(seconds:)（固定预缓冲）和 .generateFirst（先生成所有音频，再播放）。

生成选项

您可以通过 GenerationOptions 自定义采样、分块和并发设置：

// Qwen 推荐的默认值
var options = GenerationOptions()
options.temperature = 0.9
options.topK = 50
options.repetitionPenalty = 1.05
options.maxNewTokens = 245

// 长文本会自动按句号分割
options.chunkingStrategy = .sentence
options.concurrentWorkerCount = nil  // nil 表示所有分块同时运行，为当前设备提供一个良好的默认值

let result = try await tts.generate(text: longArticle, options: options)

风格指令（仅 1.7B 模型）

1.7B 模型接受自然语言风格指令来控制韵律：

var options = GenerationOptions()
options.instruction = "像说书人一样缓慢而温暖地说话。"

let result = try await tts.generate(
    text: "从前有……",
    speaker: .ryan,
    options: options
)

保存音频

生成的音频可以保存为 WAV 或 M4A 格式：

let result = try await tts.generate(text: "救救我！")
let outputDir = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]

// 可保存为 .wav 或 .m4a（AAC）
try await AudioOutput.saveAudio(result.audio, toFolder: outputDir, filename: "output", format: .m4a)

进度回调

您可以在生成过程中接收每一步的音频。如果回调返回 false，则会提前取消生成：

let result = try await tts.generate(text: "你好！") { progress in
    print("音频片段：\(progress.audio.count) 个样本")
    if let stepTime = progress.stepTime {
        print("第一步耗时 \(stepTime) 秒")
    }
    return true  // 返回 false 取消
}

Swift 命令行工具

TTS 命令可通过相同的 whisperkit-cli 工具使用。您可以生成语音，并可选择实时播放：

swift run whisperkit-cli tts --text "命令行问候语" --play
swift run whisperkit-cli tts --text "保存到文件" --output-path output.wav
swift run whisperkit-cli tts --text "日本語テスト" --speaker ono-anna --language japanese
swift run whisperkit-cli tts --text-file article.txt --model 1.7b --instruction "欢快地朗读"
swift run whisperkit-cli tts --help

示例应用

TTSKitExample 示例应用展示了实时流式传输、模型管理、波形可视化以及 macOS 和 iOS 上的生成历史记录。请参阅 TTSKitExample README 以获取构建说明。

SpeakerKit

SpeakerKit 是一个基于 Core ML 的设备端说话人分离框架。它在 Apple 芯片上运行 Pyannote v4 (community-1) 分割和嵌入模型，用于识别和标记音频中的说话人。有关架构细节和基准测试，请参阅博客文章。

• macOS 13.0 或更高版本。
• iOS 16.0 或更高版本。

快速示例

此示例演示如何对音频文件进行说话人分离：

import SpeakerKit

Task {
    let speakerKit = try await SpeakerKit()

    let audioArray = try AudioProcessor.loadAudioAsFloatArray(fromPath: "audio.wav")
    let result = try await speakerKit.diarize(audioArray: audioArray)

    print("检测到 \(result.speakerCount) 位说话人")
    for segment in result.segments {
        print(segment)
    }
}

SpeakerKit() 使用 PyannoteConfig() 的默认设置，在首次运行时会自动从 HuggingFace 下载模型。分段器和嵌入器的 CoreML 模型会在首次调用 diarize() 时延迟加载（除非在配置中设置了 load）。

说话人分离选项

您可以通过 PyannoteDiarizationOptions 控制说话人检测：

let audioArray = try AudioProcessor.loadAudioAsFloatArray(fromPath: "audio.wav")
let options = PyannoteDiarizationOptions(
    numberOfSpeakers: 2,               // nil 表示自动检测
    clusterDistanceThreshold: 0.6,     // 聚类阈值
    useExclusiveReconciliation: false   // 每帧只分配一位说话人
)
let result = try await speakerKit.diarize(audioArray: audioArray, options: options)

如果使用本地模型，则可跳过下载步骤：

let config = PyannoteConfig(modelFolder: "/path/to/models")
let speakerKit = try await SpeakerKit(config)

与转录结合

SpeakerKit 可以将说话人分离结果与 WhisperKit 转录合并，生成带有说话人信息的片段：

import WhisperKit
import SpeakerKit

let whisperKit = try await WhisperKit()
let speakerKit = try await SpeakerKit()

let audioArray = try AudioProcessor.loadAudioAsFloatArray(fromPath: "audio.wav")
let transcription = try await whisperKit.transcribe(audioArray: audioArray)
let diarization = try await speakerKit.diarize(audioArray: audioArray)

let speakerSegments = diarization.addSpeakerInfo(to: transcription)

for group in speakerSegments {
    for segment in group {
        print("\(segment.speaker): \(segment.text)")
    }
}

有两种策略可用于将说话人与转录匹配：

• .subsegment（默认）—— 在词间断处分割片段，然后分配说话人
• .segment—— 将一位说话人分配给整个转录片段

RTTM 输出

生成 RTTM 输出：

let speakerKit = try await SpeakerKit()

let audioArray = try AudioProcessor.loadAudioAsFloatArray(fromPath: "meeting.wav")
let diarization = try await speakerKit.diarize(audioArray: audioArray)

let rttmLines = SpeakerKit.generateRTTM(from: diarization, fileName: "meeting")
for line in rttmLines {
    print(line)
}

Swift 命令行工具

说话人分离命令可通过 whisperkit-cli 工具使用：

# 独立的说话人分离
swift run whisperkit-cli diarize --audio-path audio.wav --verbose

# 保存 RTTM 输出
swift run whisperkit-cli diarize --audio-path audio.wav --rttm-path output.rttm

# 指定说话人数
swift run whisperkit-cli diarize --audio-path audio.wav --num-speakers 3

# 带有说话人分离的转录
swift run whisperkit-cli transcribe --audio-path audio.wav --diarization

# 查看所有选项
swift run whisperkit-cli diarize --help

贡献与路线图

我们的目标是不断改进 WhisperKit，非常欢迎您的帮助！只需在代码中搜索“TODO”，即可找到许多尚未实现的功能。请参阅我们的贡献指南，了解如何提交问题、拉取请求以及编码规范；我们也在其中公开了未来计划实现的功能路线图。

许可证

WhisperKit 采用 MIT 许可证发布。更多详情请参阅 LICENSE 文件。

引用

如果您使用 WhisperKit 完成了很棒的工作，或者只是觉得它很有用，请发送邮件至 info@argmaxinc.com 告诉我们！

如果您在学术研究中使用 WhisperKit，可以使用以下 BibTeX 格式：

@misc{whisperkit-argmax,
   title = {WhisperKit},
   author = {Argmax, Inc.},
   year = {2024},
   URL = {https://github.com/argmaxinc/WhisperKit}
}

WhisperKit 快速上手指南

WhisperKit 是由 Argmax 开发的框架，专为在 Apple 设备端（On-Device）部署先进的语音转文本（Speech-to-Text）系统而设计。它支持实时流式转录、单词级时间戳、语音活动检测（VAD）及说话人分离等功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：macOS 14.0 (Sonoma) 或更高版本。
• 开发工具：Xcode 16.0 或更高版本。
• 依赖工具（仅 CLI 模式需要）：
  • Git LFS：用于下载大型模型文件。
  • Homebrew（可选）：用于快速安装命令行工具。

安装步骤

您可以选择将 WhisperKit 作为 Swift 包集成到项目中，或直接安装命令行工具。

方式一：Swift Package Manager (推荐用于 App 开发)

1. 在 Xcode 中打开您的 Swift 项目。
2. 点击菜单栏 File > Add Package Dependencies...。
3. 输入仓库地址：https://github.com/argmaxinc/whisperkit。
4. 选择版本范围。
5. 在产品选择界面，勾选您需要的模块：
   • WhisperKit (语音转文本)
   • TTSKit (文本转语音)
   • SpeakerKit (说话人分离)

或在 Package.swift 中手动配置：

dependencies: [
    .package(url: "https://github.com/argmaxinc/WhisperKit.git", from: "0.9.0"),
],
.target(
    name: "YourApp",
    dependencies: [
        "WhisperKit",   // 语音转文本
        "TTSKit",       // 文本转语音
        "SpeakerKit",   // 说话人分离
    ]
),

方式二：Homebrew (推荐用于命令行测试)

如果您只想快速体验或进行脚本测试，可以使用 Homebrew 安装 CLI 工具：

brew install whisperkit-cli

方式三：源码安装 CLI (用于调试或自定义构建)

git clone https://github.com/argmaxinc/whisperkit.git
cd whisperkit

# 初始化环境并下载指定模型 (例如 large-v3)
make setup
make download-model MODEL=large-v3

# 或者下载所有可用模型
# make download-models

基本使用

1. Swift 代码集成 (App 开发)

以下是最简单的转录本地音频文件的示例：

import WhisperKit

// 初始化 WhisperKit (默认会自动下载适合当前设备的模型)
Task {
   let pipe = try? await WhisperKit()
   
   // 转录音频文件 (支持 wav, mp3, m4a, flac)
   let transcription = try? await pipe!.transcribe(audioPath: "path/to/your/audio.wav")?.text
   
   print(transcription)
}

指定模型： 您也可以手动指定模型名称（支持通配符）：

let pipe = try? await WhisperKit(WhisperKitConfig(model: "large-v3"))
// 或使用通配符匹配
// let pipe = try? await WhisperKit(WhisperKitConfig(model: "distil*large-v3"))

2. 命令行使用 (CLI)

如果您通过源码安装了 CLI，可以使用以下命令进行转录：

转录本地文件：

swift run whisperkit-cli transcribe --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" --audio-path "path/to/your/audio.wav"

麦克风实时流式转录：

swift run whisperkit-cli transcribe --model-path "Models/whisperkit-coreml/openai_whisper-large-v3" --stream

3. 启动本地服务器 (Local Server)

WhisperKit 包含一个兼容 OpenAI Audio API 的本地服务器，允许您使用现有的 OpenAI SDK 客户端调用本地模型。

启动服务器：

# 使用默认设置启动
BUILD_ALL=1 swift run whisperkit-cli serve

# 自定义端口和模型
BUILD_ALL=1 swift run whisperkit-cli serve --host 0.0.0.0 --port 8080 --model tiny

Python 客户端调用示例：

from openai import OpenAI

# 指向本地服务器
client = OpenAI(base_url="http://localhost:50060/v1")

result = client.audio.transcriptions.create(
    file=open("audio.wav", "rb"),
    model="tiny"  # 必须指定模型参数
)
print(result.text)

提示：对于生产环境或需要更高性能（如 Nvidia Parakeet 模型）的场景，可以参考 Argmax Pro SDK 获取更高级的本地服务器解决方案。