speech-swift

环境要求

• Apple Silicon 设备（Mac 或 iOS），项目专为 Apple Silicon 打造
• Swift / Xcode 工具链，用于 Swift Package Manager 集成
• 首次使用需要联网，从 HuggingFace 下载模型权重
• （可选）国内网络环境需准备 HuggingFace 镜像地址

安装与启动步骤

1. 1确认设备与工具链

   speech-swift 面向 Mac 和 iOS，且只在 Apple Silicon 上本地运行。请确认使用 Apple Silicon 设备并已安装 Xcode / Swift 工具链。

2. 2添加 SPM 依赖

   在项目的 Package.swift 中把 speech-swift 以分支 main 的方式加进依赖列表。注意这里用 branch: "main"。

   .package(url: "https://github.com/soniqo/speech-swift", branch: "main")

   复制

3. 3声明所需模块

   每个模型都是独立的 SPM library，按需引入即可，不用的模块不会增加体积。下面以流式 ASR 和可选 UI 为例。

   .product(name: "ParakeetStreamingASR", package: "speech-swift"),
   .product(name: "SpeechUI",             package: "speech-swift"),  // optional SwiftUI views

   复制

4. 4三行代码转写音频

   导入模块后调用 fromPretrained() 加载模型，再用 transcribeAudio 把 16kHz 音频采样转成文本。

   import ParakeetStreamingASR
   
   let model = try await ParakeetStreamingASRModel.fromPretrained()
   let text = try model.transcribeAudio(audioSamples, sampleRate: 16000)

   复制

5. 5接入实时流式识别

   调用 transcribeStream 逐段获取识别结果，partial.isFinal 为 true 表示该句已最终确定，否则是临时结果。

   for await partial in model.transcribeStream(audio: samples, sampleRate: 16000) {
       print(partial.isFinal ? "FINAL: \(partial.text)" : "... \(partial.text)")
   }

   复制

6. 6配置国内镜像

   如果 huggingface.co 访问慢或被墙，设置 HF_ENDPOINT 环境变量改用镜像站点下载模型权重。

   export HF_ENDPOINT=https://hf-mirror.com

   复制

关键配置

如何确认成功

首次调用 fromPretrained() 会下载权重并缓存，随后 transcribeAudio 能返回识别文本且控制台无报错，即表示接入成功。

常见问题

注意事项

• README 的 Installation 章节为空，本文步骤基于 Quick start 与缓存配置章节，完整说明请查阅官网 soniqo.audio 与 docs/inference/cache-and-offline.md。
• 全部推理在设备端完成：无需云端、无需 API Key，音频数据不会离开设备。
• 代码示例中的音频变量（audioSamples / samples）需由你通过 AVFoundation 等自行采集，采样率按示例传 16000。
• iOS 沙盒容器中的缓存路径与 macOS 不同，详见 docs/inference/cache-and-offline.md。