FluidAudio - 使用 CoreML 模型进行转录、文本转语音、VAD 和说话人分离

FluidAudio 是一个适用于 Apple 设备的 Swift SDK，可在本地实现低延迟的音频 AI 处理，并将推理任务卸载到 Apple 神经引擎（ANE），从而减少内存占用并显著提升推理速度。

该 SDK 包含最先进的说话人分离、转录和语音活动检测功能，基于开源模型（MIT/Apache 2.0 许可）开发，只需几行代码即可轻松集成。这些模型针对后台处理、环境计算和始终在线的工作负载进行了优化，通过在 ANE 上运行推理来最大限度地降低 CPU 使用率，并完全避免使用 GPU/MPS。

如需定制用例、反馈、额外的模型支持或平台请求，请加入我们的 Discord 社区。我们还将推出用于设备端的视觉、语言和 TTS 模型，并会在那里分享最新进展。

以下是几款在 macOS 和 iOS 上使用 Fluid Audio 模型的优秀本地 AI 应用：

想转换您自己的模型吗？请查看 möbius。

亮点

• 自动语音识别 (ASR)：Parakeet TDT v3（0.6b）及其他 TDT/CTC 模型，支持批量转录，涵盖 25 种欧洲语言、日语和中文；Parakeet EOU（120m），用于流式 ASR 并具备话语结束检测功能（仅支持英语）。更多 ASR 模型请参阅 [Documentation/Models.md#asr-models]。
• 逆向文本规范化 (ITN)：对 ASR 输出进行后处理，将口语形式转换为书面形式（“two hundred” → “200”）。详情请参阅 text-processing-rs。
• 文本转语音 (TTS)：Kokoro（82m），支持 SSML 和发音控制，可并行合成 9 种语言（EN、ES、FR、HI、IT、JA、PT、ZH）；PocketTTS 则支持流式 TTS 及语音克隆功能（仅限英语）。
• 说话人分离（在线 + 离线）：能够从音频流中分离并识别不同说话人。提供实时处理的流式管道以及具备高级聚类功能的离线批处理管道。
• 说话人嵌入提取：生成说话人嵌入，用于语音比较和聚类，也可用于说话人身份识别。
• 语音活动检测 (VAD)：采用 Silero 模型进行语音活动检测。
• Apple 神经引擎：模型高效运行于 Apple 的 ANE 上，以最小的功耗实现最佳性能。
• 开源模型：所有模型均在 HuggingFace 上公开可用——由我们的团队转换并优化；采用宽松许可协议。完整模型目录请参阅 [Documentation/Models.md]。

视频演示

展示区

如果您希望将自己的应用加入展示列表，请提交 PR，并请按时间顺序排列。

安装

使用 Swift 包管理器将 FluidAudio 添加到您的项目中：

dependencies: [
    .package(url: "https://github.com/FluidInference/FluidAudio.git", from: "0.12.4"),
],

在 Xcode 中：

1. 将 FluidAudio 包添加到您的项目中。
2. 在“添加包”对话框中，选择 FluidAudio。
3. 将其添加到您的应用目标。

在 Package.swift 中：

.product(name: "FluidAudio", package: "FluidAudio")

CocoaPods： 我们建议使用 cocoapods-spm 以获得更好的 SPM 集成，但如有需要，您也可以使用我们的 podspec：pod 'FluidAudio', '~> 0.12.4'。

其他框架

如果您使用的是其他框架，请使用我们的官方封装库：

后处理工具

使用后处理工具增强 ASR 输出：

配置

快速参考

两者解决的是同一个问题：“我无法直接访问 HuggingFace。” 它们是不同的方法，您可以根据自己的设置选择适合的一种：

工作原理：

• 注册表 URL：应用程序从 your-mirror.com 而不是 huggingface.co 请求。
• 代理：应用程序仍然请求 huggingface.co，但流量通过代理路由以到达该地址。

在大多数情况下，您只需要其中一种。只有当您的镜像位于代理之后且没有代理无法访问时，才需要同时使用两者。

import FluidAudio

// 在使用任何管理器之前设置自定义注册表
ModelRegistry.baseURL = "https://your-mirror.example.com"

// 现在模型将从自定义注册表下载
let diarizer = DiarizerManager()

# 使用自定义注册表
export REGISTRY_URL=https://your-mirror.example.com
swift run fluidaudiocli transcribe audio.wav

# 或者使用 MODEL_REGISTRY_URL 别名
export MODEL_REGISTRY_URL=https://models.internal.corp
swift run fluidaudiocli diarization-benchmark --auto-download

export https_proxy=http://proxy.company.com:8080
# 或对于需要身份验证的代理：
export https_proxy=http://user:password@proxy.company.com:8080

swift run fluidaudiocli transcribe audio.wav

文档

DeepWiki 提供此仓库的自动生成文档。

文档索引

• 指南
  • 推理用音频转换
  • 手动下载和加载模型的选项：ASR、Diarizer、VAD
  • 如果需要通过代理路由 Hugging Face（或兼容）请求，请在运行下载助手之前设置 https_proxy（参见 Documentation/API.md）。
• 模型
  • 自动语音识别/转录
    • 入门指南
    • 最后片段处理
  • 说话人分离
    • 说话人分离指南
  • VAD：入门指南
    • 分割
    • 模型转换代码
• 基准测试
• API 参考
• 命令行指南

MCP 服务器

该仓库已编入 DeepWiki MCP 服务器索引，因此您的编码工具可以访问文档：

{
  "mcpServers": {
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/mcp"
    }
  }
}

对于 claude 代码：

claude mcp add -s user -t http deepwiki https://mcp.deepwiki.com/mcp

自动语音识别 (ASR) / 转录

• 模型：
  • FluidInference/parakeet-tdt-0.6b-v3-coreml（多语言，涵盖 25 种欧洲语言）
  • FluidInference/parakeet-tdt-0.6b-v2-coreml（仅英语，召回率最高）
• 处理模式：批量转录完整音频文件
• 实时因子：在 M4 Pro 上约为 190 倍（约 19 秒内处理 1 小时音频）
• 流式支持：通过 SlidingWindowAsrManager 支持实时流式处理和取消操作
• 后端：我们的后端 ASR 使用相同的 Parakeet TDT v3 模型。

ASR 快速入门

import FluidAudio

// 从音频文件进行批量转录
Task {
    // 1) 初始化 ASR 管理器并加载模型
    let models = try await AsrModels.downloadAndLoad(version: .v3)  // 切换到 .v2 以仅支持英语
    let asrManager = AsrManager(config: .default)
    try await asrManager.loadModels(models)

    // 3) 转录音频（已转换为 16Hz）
    let result = try await asrManager.transcribe(samples)

    // 3) 转录文件
    // let url = URL(fileURLWithPath: sample.audioPath)

    // 3) 转录 AVAudioPCMBuffer
    // let result = try await asrManager.transcribe(audioBuffer)
    print("转录结果：\(result.text)")
}

# 批量转录音频文件
swift run fluidaudiocli transcribe audio.wav

# 仅限英语且召回率更高的运行
swift run fluidaudiocli transcribe audio.wav --model-version v2

发言人区分

离线发言人区分流程

Pyannote Community-1 流程（幂集分割 + WeSpeaker + VBx）用于离线发言人区分。适用于大多数用例，基准测试请参阅 Benchmarks.md。

import FluidAudio

let config = OfflineDiarizerConfig()
let manager = OfflineDiarizerManager(config: config)
try await manager.prepareModels()  // 如果缺少 Core ML 包，则下载并编译

let samples = try AudioConverter().resampleAudioFile(path: "meeting.wav")
let result = try await manager.process(audio: samples)

for segment in result.segments {
    print("\(segment.speakerId) \(segment.startTimeSeconds)s → \(segment.endTimeSeconds)s")
}

对于音频文件处理，使用基于文件的 API，它会自动采用内存映射流式传输以提高效率：

let url = URL(fileURLWithPath: "meeting.wav")
let result = try await manager.process(url)

for segment in result.segments {
    print("\(segment.speakerId) \(segment.startTimeSeconds)s → \(segment.endTimeSeconds)s")
}

# 使用完整的 VBx 聚类处理会议
swift run fluidaudiocli process ~/FluidAudioDatasets/ami_official/sdm/ES2004a.Mix-Headset.wav \
  --mode offline --threshold 0.6 --output es2004a_offline.json

# 运行 AMI 单文件基准测试并自动下载
swift run fluidaudiocli diarization-benchmark --mode offline --auto-download \
  --single-file ES2004a --threshold 0.6 --output offline_results.json

offline_results.json 包含 DER/JER/RTFx 以及分割、嵌入提取和 VBx 聚类的时间分解。CI 现在会在每个 PR 上运行此工作流，以确保离线模型保持健康，并且 Hugging Face 资产始终可访问。

LS-EEND（长时流式端到端神经网络发言人区分）

使用 CoreML 推理的端到端流式发言人区分。是在线发言者区分的默认选择——单个模型，无需聚类流程，最多支持 10 名说话人，每 100 毫秒更新一次帧，并提供 900 毫秒的暂定预览。支持流式处理和完整缓冲区处理。详细信息请参阅 Documentation/Diarization/GettingStarted.md。

import FluidAudio

Task {
    let diarizer = LSEENDDiarizer()
    try await diarizer.initialize(variant: .dihard3)

    let samples = try await loadSamples16kMono(path: "path/to/meeting.wav")
    let timeline = try diarizer.processComplete(samples, sourceSampleRate: 16_000)

    for segment in timeline.segments {
        print("说话人 \(segment.speakerId): \(segment.startTimeSeconds)s - \(segment.endTimeSeconds)s")
    }
}

Sortformer（端到端神经网络发言人区分）

使用 NVIDIA 的 Sortformer 的端到端神经网络发言人区分。作为次要的流式发言人区分工具——虽然其说话人身份稳定性更好，参与者关注度更高，但相比 LS-EEND 在说话人容量和基准测试结果上有所牺牲。仅限 4 名说话人。无需单独的 VAD、分割或聚类。受 NVIDIA 开放模型许可证保护。

LS-EEND 和 Sortformer 都会以超低延迟更新的方式输出 DiarizerTimeline。使用方法及对比请参阅 Documentation/Diarization/Sortformer.md。

流式/在线发言人区分（Pyannote）

该流程使用分割加说话人嵌入，是继 LS-EEND 和 Sortformer 之后的第三选择。如果您特别需要经典的多阶段流程，它可以派上用场，但在实时发言人区分方面，它的速度远不及 LS-EEND 或 Sortformer。

为何使用 WeSpeaker/Pyannote 流程：

• 如果您希望分离分割和嵌入阶段，此流程更具模块化
• 当您需要集成外部说话人识别或聚类逻辑时，此流程更合适
• 说话人预先注册可靠
• 说话人数据库管理更加容易
• 清除或更新个别说话人非常简单
• 不建议在优先考虑低延迟实时发言人区分时使用

在大多数应用中：

• 将 LS-EEND 作为默认的在线发言人区分工具
• 当 Sortformer 更强的身份稳定性和参与者关注度比 4 名说话人的限制更重要时，将其作为第二选择
• 仅当您特别需要其模块化设计，即使会牺牲速度时，才使用 WeSpeaker/Pyannote 流程

权衡：

• 在推理时间和实际延迟方面都比 LS-EEND 或 Sortformer 慢
• 需要较大的数据块，通常至少需要 5 秒才能获得较好的结果
• 与 LS-EEND 和 Sortformer 不同，说话人状态更容易被显式操控

import FluidAudio

// 对音频文件进行发言人区分
Task {
    let models = try await DiarizerModels.downloadIfNeeded()
    let diarizer = DiarizerManager()
    diarizer.initialize(models: models)

    // 准备 16 kHz 单声道样本（参见：音频转换）
    let samples = try await loadSamples16kMono(path: "path/to/meeting.wav")

    // 进行发言人区分
    let result = try diarizer.performCompleteDiarization(samples)
    for segment in result.segments {
        print("说话人 \(segment.speakerId): \(segment.startTimeSeconds)s - \(segment.endTimeSeconds)s")
    }
}

关于流式发言人区分，请参阅 Documentation/Diarization/GettingStarted.md。

swift run fluidaudiocli diarization-benchmark --single-file ES2004a \
  --chunk-seconds 3 --overlap-seconds 2

CLI

# 处理单个文件并保存 JSON
swift run fluidaudiocli process meeting.wav --output results.json --threshold 0.6

语音活动检测（VAD）

Silero VAD 为我们设备上的检测器提供支持。最新版本沿用了上游 PyTorch 实现中的相同时间戳提取和流式启发式方法。如果您需要针对您的环境调整设置，请在 Discord 上联系我们。

VAD 快速入门（离线分割）

简单调用，每 256 毫秒跳动一次返回分块级别的概率：

let results = try await manager.process(samples)
for (index, chunk) in results.enumerated() {
    print(
        String(
            format: "分块 %02d: 概率=%.3f, 推理时间=%.4fs",
            index,
            chunk.probability,
            chunk.processingTime
        )
    )
}

以下是更适合与其他系统集成的高级 API：

import FluidAudio

Task {
    let manager = try await VadManager(
        config: VadConfig(defaultThreshold: 0.75)
    )

    let audioURL = URL(fileURLWithPath: "path/to/audio.wav")
    let samples = try AudioConverter().resampleAudioFile(audioURL)

    var segmentation = VadSegmentationConfig.default
    segmentation.minSpeechDuration = 0.25
    segmentation.minSilenceDuration = 0.4

    let segments = try await manager.segmentSpeech(samples, config: segmentation)
    for segment in segments {
        print(
            String(format: "语音 %.2f–%.2fs", segment.startTime, segment.endTime)
        )
    }
}

流式处理

import FluidAudio

Task {
    let manager = try await VadManager()
    var state = await manager.makeStreamState()

    for chunk in microphoneChunks {
        let result = try await manager.processStreamingChunk(
            chunk,
            state: state,
            config: .default,
            returnSeconds: true,
            timeResolution: 2
        )

        state = result.state

        // 访问原始概率（0.0-1.0）以用于自定义逻辑
        print(String(format: "概率: %.3f", result.probability))

        if let event = result.event {
            let label = event.kind == .speechStart ? "开始" : "结束"
            print("\(label) @ \(event.time ?? 0)s")
        }
    }
}

命令行界面

从通用的 process 命令开始，该命令会端到端地对单个文件运行说话人分离管道（因此也包括 VAD）：

swift run fluidaudiocli process path/to/audio.wav

一旦你需要直接试验与 VAD 相关的参数，可以使用以下命令：

# 检查离线分割结果（默认模式）
swift run fluidaudiocli vad-analyze path/to/audio.wav

# 仅进行流式模拟（默认按秒打印时间戳）
swift run fluidaudiocli vad-analyze path/to/audio.wav --streaming

# 基准测试准确率与精度之间的权衡
swift run fluidaudiocli vad-benchmark --num-files 50 --threshold 0.3

swift run fluidaudiocli vad-analyze --help 列出了所有可调参数，包括负阈值覆盖、最大语音分割、填充以及分块大小。离线模式还会根据模型的每分块处理时间报告 RTFx。

文本转语音（TTS）

⚠️ 测试版： TTS 目前仅支持美式英语。计划增加更多语言支持。

FluidAudio 提供两种 TTS 后端：

PocketTTS

适合流式传输的 TTS，支持从短音频样本中进行语音克隆。

import FluidAudio

Task {
    let manager = try await PocketTtsManager()
    let audioData = try await manager.synthesize("Hello from FluidAudio.")
    try audioData.write(to: URL(fileURLWithPath: "out.wav"))
}

# 使用默认语音合成
swift run fluidaudiocli tts "Hello from FluidAudio." --output out.wav --backend pocket

# 从音频样本克隆语音
swift run fluidaudiocli tts "Hello world." --output out.wav --backend pocket --clone-voice speaker.wav

Kokoro

高质量并行 TTS，支持 SSML 和音素级发音控制。对于未收录在词汇表中的单词，使用 CoreML G2P（字素到音素）模型——无需外部依赖。

import FluidAudio

Task {
    let manager = KokoroTtsManager()
    try await manager.initialize()
    let data = try await manager.synthesize(text: "Hello from FluidAudio.")
    try data.write(to: URL(fileURLWithPath: "out.wav"))
}

swift run fluidaudiocli tts "Hello from FluidAudio." --auto-download --output out.wav

词典和模型资产会缓存在 ~/.cache/fluidaudio/Models/kokoro 下。

持续集成

• tests.yml：默认构建矩阵，涵盖 SwiftPM 测试和 iOS 归档冒烟测试。
• diarizer-benchmark.yml：在 ES2004a 上运行流式说话人分离基准测试，用于跟踪回归。
• offline-pipeline.yml：端到端执行 VBx 离线管道（fluidaudio diarization-benchmark --mode offline），如果 DER/JER 超出限制或模型下载失败，则构建失败。可将此工作流作为在您自己的 CI 中预置模型缓存的参考。

其他信息

常见问题解答

• 命令行界面仅适用于 macOS。对于 iOS，请以编程方式使用库。
• 模型会在首次使用时自动下载。如果您的网络限制了对 Hugging Face 的访问，请设置 HTTPS 代理：export https_proxy=http://127.0.0.1:7890。
• Windows 替代方案正在开发中：fluid-server。
• 如果您想在 Mac 上获取系统音频，可以参考这个仓库 AudioCap。

许可证

Apache 2.0 — 详情请参阅 LICENSE 文件。

致谢

本项目基于 sherpa-onnx 项目的优秀工作，该团队在说话人分离算法和技术方面做出了卓越贡献。

Pyannote：https://github.com/pyannote/pyannote-audio

WeSpeaker：https://github.com/wenet-e2e/wespeaker

Parakeet-mlx：https://github.com/senstella/parakeet-mlx

silero-vad：https://github.com/snakers4/silero-vad

Kokoro-82M：https://huggingface.co/hexgrad/Kokoro-82M

引用

如果您在工作中使用了 FluidAudio，请引用以下内容：

FluidInference 团队. (2025). FluidAudio：适用于 Apple 平台的本地说话人分离、ASR 和 VAD（版本 0.12.4）[计算机软件]. GitHub. https://github.com/FluidInference/FluidAudio

@software{FluidInferenceTeam_FluidAudio_2025,
  author = {{FluidInference Team}},
  title = {{FluidAudio: 本地说话人分离、ASR 和 VAD，适用于 Apple 平台}},
  year = {2025},
  month = {3},
  version = {0.12.4},
  url = {https://github.com/FluidInference/FluidAudio},
  note = {计算机软件}
}

表达您的支持

通过在您的项目中添加“由 Fluid Inference 提供支持”徽章，帮助 Fluid Inference 社区发展壮大吧！

将以下提示复制并粘贴到您托管主页的代码代理中：

在页脚中添加一个居中的“由 Fluid Inference 提供支持”徽章，链接至 fluidinference.com。图片地址：https://oss.gittoolsai.com/images/FluidInference_FluidAudio_readme_84a39d3f1e87.png。请在您的框架配置中将该图片的主机名加入白名单。

或者使用以下代码片段之一：

<div className="flex justify-center py-8">
  <a href="https://fluidinference.com">
    <img
      src="https.//assets.inference.plus/fi-badge.png"
      alt="由 Fluid Inference 提供支持"
      height={80}
    />
  </a>
</div>

<div style="text-align: center; padding: 20px;">
  <a href="https://fluidinference.com">
    <img src="https://oss.gittoolsai.com/images/FluidInference_FluidAudio_readme_84a39d3f1e87.png" alt="由 Fluid Inference 提供支持" height="80">
  </a>
</div>

<p align="center">
  <a href="https://fluidinference.com">
    <img src="https://oss.gittoolsai.com/images/FluidInference_FluidAudio_readme_84a39d3f1e87.png" alt="由 Fluid Inference 提供支持" height="80">
  </a>
</p>

FluidAudio 快速上手指南

FluidAudio 是一个专为 Apple 设备（macOS/iOS）设计的 Swift SDK，支持完全本地化、低延迟的音频 AI 处理。它利用 Apple Neural Engine (ANE) 进行推理加速，提供语音识别 (ASR)、说话人分离 (Diarization)、语音活动检测 (VAD) 和文本转语音 (TTS) 等功能。

环境准备

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

• 操作系统：macOS 14.0+ 或 iOS 17.0+
• 开发工具：Xcode 15.0+ (包含 Swift 6.0+)
• 硬件要求：配备 Apple Silicon 芯片 (M1/M2/M3 等) 的设备，以利用 ANE 加速。
• 依赖管理：推荐使用 Swift Package Manager (SPM)。

注意：本项目主要针对 Apple 生态优化，不支持 Windows 或 Linux 服务器环境。目前暂无官方国内镜像源，若访问 Hugging Face 下载模型受阻，请自行配置网络代理或使用国内 Hugging Face 镜像站。

安装步骤

1. 通过 Swift Package Manager 集成

在 Xcode 项目中添加 FluidAudio：

1. 打开 Xcode 项目，点击菜单栏 File > Add Package Dependencies...。
2. 输入仓库地址：

   https://github.com/FluidInference/FluidAudio
   

3. 选择版本规则（建议 Up to Next Major Version），点击 Add Package。

或者，直接在 Package.swift 文件中添加依赖：

dependencies: [
    .package(url: "https://github.com/FluidInference/FluidAudio", from: "1.0.0")
]

然后在目标依赖中添加 "FluidAudio"。

2. 下载模型

FluidAudio 的模型托管在 Hugging Face 上。首次运行时，SDK 通常会自动下载所需模型到本地缓存。如需手动预下载或自定义模型路径，请访问 FluidInference Hugging Face Organization。

常用模型包括：

• ASR: parakeet-tdt-v3 (批量转录), parakeet-eou (流式转录)
• TTS: kokoro, PocketTTS
• Diarization: pyannote, sortformer

基本使用

以下示例展示如何使用 FluidAudio 进行最简单的语音转文字 (ASR) 和 说话人分离。

1. 导入模块

import FluidAudio
import AVFoundation

2. 初始化引擎

配置并启动音频处理引擎。默认情况下，FluidAudio 会自动尝试将计算任务卸载到 ANE。

// 创建配置
var config = FluidAudioConfig()
config.device = .ane // 强制使用 Apple Neural Engine

// 初始化引擎
let engine = try await FluidAudioEngine(configuration: config)

3. 执行批量语音转录 (ASR)

假设你有一个本地的音频文件 URL：

let audioURL = URL(fileURLWithPath: "/path/to/your/audio.m4a")

do {
    // 执行转录
    let result = try await engine.transcribe(
        url: audioURL,
        model: .parakeetTDTv3 // 指定使用 Parakeet TDT v3 模型
    )
    
    // 输出结果
    print("转录文本：\(result.text)")
    
    // 如果启用了说话人分离，可以遍历片段
    for segment in result.segments {
        print("说话人 \(segment.speakerID ?? "未知"): \(segment.text)")
    }
} catch {
    print("转录失败：\(error)")
}

4. 流式转录 (实时监听)

对于实时麦克风输入，可以使用流式管道：

// 设置流式处理器
let streamer = engine.createStreamingTranscriber(model: .parakeetEOU)

// 开始监听 (需配合 AVAudioEngine 或类似音频输入源)
try streamer.start()

// 设置回调处理实时结果
streamer.onResult = { partialResult in
    print("实时识别：\(partialResult.text) [结束标记：\(partialResult.isFinal)]")
}

// 停止监听
// try streamer.stop()

5. 文本转语音 (TTS)

使用 Kokoro 模型生成语音：

let text = "你好，这是 FluidAudio 的测试声音。"
let outputURL = URL(fileURLWithPath: "/tmp/output.wav")

do {
    try await engine.synthesize(
        text: text,
        outputURL: outputURL,
        model: .kokoro,
        language: .zh // 指定语言
    )
    print("语音生成完毕：\(outputURL.path)")
} catch {
    print("TTS 失败：\(error)")
}

提示：更多高级功能（如自定义说话人嵌入提取、SSML 控制、逆文本标准化 ITN）请参考官方文档 docs.fluidinference.com。