whisper.rn

React Native 绑定 whisper.cpp。

whisper.cpp：高性能推理 OpenAI's Whisper 自动语音识别 (ASR) 模型。

截图

iOS：在 iPhone 13 Pro Max 上测试	Android：在 Pixel 6 上测试
(tiny.en，启用 Core ML，发布模式 + 归档)	(tiny.en，armv8.2-a+fp16，发布模式)

安装

npm install whisper.rn

iOS

请再次运行 npx pod-install。

默认情况下，whisper.rn 将使用预构建的 rnwhisper.xcframework 用于 iOS。如果您想从源代码构建，请在您的 Podfile 中将 RNWHISPER_BUILD_FROM_SOURCE 设置为 1。

如果您想使用 medium 或 large 模型，建议在 iOS 项目中启用 扩展虚拟地址空间 功能。

Android

如果项目中启用了 ProGuard，请在 android/app/proguard-rules.pro 中添加以下规则：

# whisper.rn
-keep class com.rnwhisper.** { *; }

对于 Apple Silicon Mac，建议在根项目构建配置中使用 ndkVersion = "24.0.8215888"（或更高版本）。否则，请参考此故障排除 问题。

Expo

您需要在使用之前预构建项目。有关更多详细信息，请参阅 Expo 指南。

技巧与窍门

技巧与窍门 文档收集了使用 whisper.rn 的一些技巧和窍门。

使用方法

import { initWhisper } from 'whisper.rn'

const whisperContext = await initWhisper({
  filePath: 'file://.../ggml-tiny.en.bin',
})

const sampleFilePath = 'file://.../sample.wav'
const options = { language: 'en' }
const { stop, promise } = whisperContext.transcribe(sampleFilePath, options)

const { result } = await promise
// result：（来自音频文件的推理文本结果）

语音活动检测 (VAD)

语音活动检测允许您使用 Silero VAD 模型检测音频数据中的语音片段。

初始化 VAD 上下文

import { initWhisperVad } from 'whisper.rn'

const vadContext = await initWhisperVad({
  filePath: require('./assets/ggml-silero-v6.2.0.bin'), // VAD 模型文件
  useGpu: true, // 使用 GPU 加速（仅限 iOS）
  nThreads: 4, // 处理线程数
})

检测语音片段

来自音频文件

// 检测音频文件中的语音（支持与转录相同的格式）
const segments = await vadContext.detectSpeech(require('./assets/audio.wav'), {
  threshold: 0.5, // 语音概率阈值（0.0-1.0）
  minSpeechDurationMs: 250, // 最小语音持续时间（毫秒）
  minSilenceDurationMs: 100, // 最小静音持续时间（毫秒）
  maxSpeechDurationS: 30, // 最大语音持续时间（秒）
  speechPadMs: 30, // 语音片段周围的填充时间（毫秒）
  samplesOverlap: 0.1, // 分析窗口之间的重叠比例
})

// 同样支持：
// - 文件路径：vadContext.detectSpeech('path/to/audio.wav', options)
// - HTTP URL：vadContext.detectSpeech('https://example.com/audio.wav', options)
// - Base64 WAV：vadContext.detectSpeech('data:audio/wav;base64,...', options)
// - 资源文件：vadContext.detectSpeech(require('./assets/audio.wav'), options)

来自原始音频数据

// 检测 base64 编码的 float32 PCM 数据中的语音
const segments = await vadContext.detectSpeechData(base64AudioData, {
  threshold: 0.5,
  minSpeechDurationMs: 250,
  minSilenceDurationMs: 100,
  maxSpeechDurationS: 30,
  speechPadMs: 30,
  samplesOverlap: 0.1,
})

处理结果

segments.forEach((segment, index) => {
  console.log(
    `第 ${index + 1} 段：${segment.t0.toFixed(2)} 秒 - ${segment.t1.toFixed(2)} 秒`,
  )
  console.log(`持续时间：${(segment.t1 - segment.t0).toFixed(2)} 秒`)
})

释放 VAD 上下文

await vadContext.release()
// 或者释放所有 VAD 上下文
await releaseAllWhisperVad()

实时转录

新的 RealtimeTranscriber 提供了增强的实时转录功能，包括语音活动检测 (VAD)、自动切片和内存管理等特性。

// 如果你的 RN 打包工具不支持 package exports，可以使用 whisper.rn/src/realtime-transcription
import { RealtimeTranscriber } from 'whisper.rn/realtime-transcription'
import { AudioPcmStreamAdapter } from 'whisper.rn/realtime-transcription/adapters'
import RNFS from 'react-native-fs' // 或任何兼容的文件系统

// 依赖项
const whisperContext = await initWhisper({
  /* ... */
})
const vadContext = await initWhisperVad({
  /* ... */
})
const audioStream = new AudioPcmStreamAdapter() // 需要 @fugood/react-native-audio-pcm-stream

// 创建转录器
const transcriber = new RealtimeTranscriber(
  { whisperContext, vadContext, audioStream, fs: RNFS },
  {
    audioSliceSec: 30,
    vadPreset: 'default',
    autoSliceOnSpeechEnd: true,
    transcribeOptions: { language: 'en' },
  },
  {
    onTranscribe: (event) => console.log('转录:', event.data?.result),
    onVad: (event) => console.log('VAD:', event.type, event.confidence),
    onStatusChange: (isActive) =>
      console.log('状态:', isActive ? 'ACTIVE' : 'INACTIVE'),
    onError: (error) => console.error('错误:', error),
  },
)

// 开始/停止转录
await transcriber.start()
await transcriber.stop()

依赖项：

• @fugood/react-native-audio-pcm-stream 用于 AudioPcmStreamAdapter
• 兼容的文件系统模块（例如 react-native-fs）。请参阅 文件系统接口 获取 TypeScript 定义。

自定义音频适配器： 你可以通过实现 AudioStreamInterface 来创建自定义音频流适配器。这允许与不同的音频源或自定义音频处理管道集成。

示例： 请参阅 完整示例 以获取包括文件模拟和 UI 的完整实现。

更多详细信息请访问 文档。

使用资源文件

你也可以从资源文件中使用模型文件或音频文件：

import { initWhisper } from 'whisper.rn'

const whisperContext = await initWhisper({
  filePath: require('../assets/ggml-tiny.en.bin'),
})

const { stop, promise } = whisperContext.transcribe(
  require('../assets/sample.wav'),
  options,
)

// ...

这需要编辑 metro.config.js 以支持资源文件：

// ...
const defaultAssetExts = require('metro-config/src/defaults/defaults').assetExts

module.exports = {
  // ...
  resolver: {
    // ...
    assetExts: [
      ...defaultAssetExts,
      'bin', // whisper.rn：ggml 模型二进制文件
      'mil', // whisper.rn：CoreML 模型资源文件
    ],
  },
}

请注意：

• 这会显著增加发布模式下的应用大小。
• RN 打包工具不允许超过 2GB 的文件大小，因此无法使用原始 f16 large 模型（2.9GB），建议使用量化后的模型。

Core ML 支持

平台：iOS 15.0+，tvOS 15.0+

要在 iOS 上使用 Core ML，你需要 Core ML 模型文件。

.mlmodelc 模型文件的加载依赖于 ggml 模型文件路径。例如，如果你的 ggml 模型路径是 ggml-tiny.en.bin, 那么对应的 Core ML 模型路径将是 ggml-tiny.en-encoder.mlmodelc。请注意，ggml 模型仍然需要作为解码器或编码器的备用方案。

Core ML 模型托管在：https://huggingface.co/ggerganov/whisper.cpp/tree/main

如果你想在运行时下载模型，并且模型文件是压缩包形式，你需要先解压才能获得 .mlmodelc 目录。可以使用类似 react-native-zip-archive 的库，或者将这些单独的文件托管起来供自己下载。

.mlmodelc 是一个目录，通常包含 5 个文件（其中 3 个是必需的）：

[
  'model.mil',
  'coremldata.bin',
  'weights/weight.bin',
  // 非必需：
  // 'metadata.json', 'analytics/coremldata.bin',
]

或者直接使用 require 将其打包到你的应用中，就像示例应用那样，但这会显著增加应用大小。

const whisperContext = await initWhisper({
  filePath: require('../assets/ggml-tiny.en.bin')
  coreMLModelAsset:
    Platform.OS === 'ios'
      ? {
          filename: 'ggml-tiny.en-encoder.mlmodelc',
          assets: [
            require('../assets/ggml-tiny.en-encoder.mlmodelc/weights/weight.bin'),
            require('../assets/ggml-tiny.en-encoder.mlmodelc/model.mil'),
            require('../assets/ggml-tiny.en-encoder.mlmodelc/coremldata.bin'),
          ],
        }
      : undefined,
})

在实际开发中，我们建议将资源导入拆分到另一个平台特定的文件中（例如 context-opts.ios.js），以避免这些未使用的文件被打包到 Android 应用中。

运行示例

示例应用提供了一个简单的界面来测试各项功能。

使用的 Whisper 模型：https://huggingface.co/ggerganov/whisper.cpp 中的 tiny.en
示例文件：https://github.com/ggerganov/whisper.cpp/tree/master/samples 中的 jfk.wav

请按照贡献指南中的开发流程部分来运行示例应用。

模拟 whisper.rn

我们提供了一个用于测试的 whisper.rn 模拟版本，可以在 Jest 中使用：

jest.mock('whisper.rn', () => require('whisper.rn/jest-mock'))

使用 whisper.rn 的应用

• BRICKS：我们的产品，用于以简单方式构建交互式标牌。我们提供 LLM 功能作为生成式 LLM/助手。
• ...（欢迎任何贡献）

Node.js 绑定

• whisper.node：whisper.cpp 的另一个 Node.js 绑定，但其 API 与 whisper.rn 相同。

贡献

请参阅 贡献指南 了解如何为仓库做出贡献以及开发流程。

故障排除

如果在使用 whisper.rn 时遇到任何问题，请参阅 故障排除。

许可证

MIT

---

由 create-react-native-library 制作

---

由 BRICKS 构建并维护。

whisper.rn 快速上手指南

whisper.rn 是 whisper.cpp 的 React Native 绑定库，允许你在 iOS 和 Android 端高性能运行 OpenAI 的 Whisper 语音识别模型。

环境准备

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

• 系统要求：
  • iOS: 15.0+ (若使用 Core ML 加速)
  • Android: 支持 armv8.2-a+fp16 的设备
• 前置依赖：
  • Node.js & npm/yarn
  • React Native 项目环境
  • iOS: CocoaPods (pod 命令)
  • Android: NDK (推荐版本 24.0.8215888 或更高，特别是在 Apple Silicon Mac 上)
  • Expo 用户: 必须使用 expo prebuild 进行原生构建，不支持纯 Expo Go。

安装步骤

1. 安装依赖包

在项目根目录执行：

npm install whisper.rn

2. iOS 配置

安装完成后，重新安装 CocoaPods 依赖：

cd ios && pod-install && cd ..
# 或者
cd ios && pod install && cd ..

• 可选配置：默认使用预编译的 rnwhisper.xcframework。如需从源码构建，请在 Podfile 中设置 RNWHISPER_BUILD_FROM_SOURCE=1。
• 大模型支持：若使用 medium 或 large 模型，建议在 Xcode 项目中启用 Extended Virtual Addressing 能力。

3. Android 配置

如果项目启用了 ProGuard/R8，请在 android/app/proguard-rules.pro 中添加以下规则以防代码混淆：

# whisper.rn
-keep class com.rnwhisper.** { *; }

• NDK 版本：确保 android/build.gradle 中指定了兼容的 NDK 版本：

  buildToolsVersion = "..."
  ndkVersion = "24.0.8215888" // 推荐
  

4. 资源文件配置 (可选)

如果你打算将模型文件 (.bin) 或音频文件打包进应用（通过 require 引入），需要修改 metro.config.js 以支持二进制扩展名：

const defaultAssetExts = require('metro-config/src/defaults/defaults').assetExts

module.exports = {
  // ...
  resolver: {
    assetExts: [
      ...defaultAssetExts,
      'bin', // whisper 模型文件
      'mil', // CoreML 模型文件
    ],
  },
}

注意：打包大模型会显著增加应用体积。Whisper large 模型原始文件超过 2GB，无法直接通过 RN 打包，建议使用量化版本（如 ggml-large-v3-q5_0.bin）。

基本使用

1. 准备模型文件

你需要下载 .bin 格式的 GGML 模型文件。可以从 Hugging Face 获取。 示例使用 tiny.en 模型。

2. 代码示例

以下是最基础的转录流程：初始化上下文 -> 执行转录 -> 获取结果。

import { initWhisper } from 'whisper.rn'

// 1. 初始化 Whisper 上下文
// filePath 可以是本地绝对路径 ('file://...') 或通过 require 引入的资产
const whisperContext = await initWhisper({
  filePath: 'file://.../ggml-tiny.en.bin', 
  // 如果使用 iOS Core ML 加速，可在此处配置 coreMLModelAsset
})

// 2. 准备音频文件路径
const sampleFilePath = 'file://.../sample.wav'
const options = { language: 'en' } // 指定语言

// 3. 执行转录
const { stop, promise } = whisperContext.transcribe(sampleFilePath, options)

// 4. 等待结果
const { result } = await promise

console.log('识别结果:', result)

// 如需中途停止，调用 stop()
// stop()

3. 使用资产文件 (Assets)

如果你已将模型和音频文件放入项目 assets 目录：

import { initWhisper } from 'whisper.rn'

const whisperContext = await initWhisper({
  filePath: require('../assets/ggml-tiny.en.bin'),
})

const { stop, promise } = whisperContext.transcribe(
  require('../assets/sample.wav'),
  { language: 'en' }
)

const { result } = await promise
console.log(result)

进阶功能提示

• 语音活动检测 (VAD)：库内置了 Silero VAD 模型，可用于检测音频中的有效语音片段，减少无效转录。使用 initWhisperVad 初始化。
• 实时转录：对于流式音频输入，可使用 RealtimeTranscriber 类，它集成了 VAD、自动切片和内存管理功能。需配合 @fugood/react-native-audio-pcm-stream 使用。
• 模型选择：生产环境建议根据设备性能选择模型。tiny 和 base 适合移动端实时场景；small 及以上模型在移动端推理速度较慢，建议仅在离线高算力场景或配合服务器使用。