猎豹

由位于加拿大温哥华的 Picovoice 制作。

猎豹是一款设备端流式语音转文本引擎。猎豹具有以下特点：

• 私密性：所有语音处理均在本地进行。
• 准确
• 紧凑且计算高效
• 跨平台支持：
  • Linux (x86_64)、macOS (x86_64、arm64) 和 Windows (x86_64、arm64)
  • Android 和 iOS
  • Chrome、Safari、Firefox 和 Edge
  • 树莓派 (3、4、5)

目录

• 猎豹
  • 目录
  • AccessKey
  • 语言支持
  • 演示
    • Python
    • C
    • iOS
    • Android
    • Flutter
    • React Native
    • Java
    • Node.js
    • .Net
    • Web
      • 原生 JavaScript 和 HTML
      • React
  • SDKs
    • Python
    • C
    • iOS
    • Android
    • Flutter
    • React Native
    • Node.js
    • Java
    • .Net
    • Web
      • 原生 JavaScript 和 HTML (ES Modules)
      • React
  • 发布

AccessKey

AccessKey 是您用于部署 Picovoice SDK（包括猎豹）的身份验证和授权令牌。任何使用 Picovoice 的人都需要有效的 AccessKey。请务必妥善保管您的 AccessKey。尽管语音识别完全离线运行，但您仍需互联网连接来通过 Picovoice 许可服务器验证您的 AccessKey。

AccessKey 还会验证您的使用是否在账户限制范围内。您可以在 Picovoice 控制台个人资料 中查看您的使用限制和实时使用情况。如需在试用期结束后继续使用 Picovoice，或续订并调整使用限制，请联系我们的 企业销售团队 或您现有的 Picovoice 联系人。

语言支持

• 猎豹流式语音转文本目前支持英语、法语、德语、意大利语、葡萄牙语和西班牙语。
• 对于商业客户，其他语言的支持可根据具体需求提供。

演示

Python 演示

安装演示包：

pip3 install pvcheetahdemo

cheetah_demo_mic --access_key ${ACCESS_KEY}

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台获取的 AccessKey。

C 演示

如果使用 SSH，克隆仓库时执行以下命令：

git clone --recurse-submodules git@github.com:Picovoice/cheetah.git

如果使用 HTTPS，克隆仓库时执行以下命令：

git clone --recurse-submodules https://github.com/Picovoice/cheetah.git

构建演示程序：

cmake -S demo/c/ -B demo/c/build && cmake --build demo/c/build

运行演示程序：

./demo/c/build/cheetah_demo_mic -a ${ACCESS_KEY} -m ${MODEL_PATH} -l ${LIBRARY_PATH}

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台获取的 AccessKey，${LIBRARY_PATH} 替换为指向 lib 目录下相应库文件的路径，${MODEL_PATH} 替换为指向 默认模型文件 的路径（或您自定义的模型文件）。

iOS 演示

要运行演示程序，请前往 demo/ios/CheetahDemo，然后执行以下命令：

pod install

将文件 ViewModel.swift 中的 let accessKey = "${YOUR_ACCESS_KEY_HERE}" 替换为您自己的 AccessKey。

随后，使用 Xcode 打开生成的 CheetahDemo.xcworkspace，并运行应用程序。

安卓演示

使用 Android Studio，将 demo/android/CheetahDemo 作为安卓项目打开，然后运行应用程序。

将文件 MainActivity.java 中的 "${YOUR_ACCESS_KEY_HERE}" 替换为您自己的 AccessKey。

Flutter 示例

要在 Android 或 iOS 上使用 Flutter 运行 Cheetah 示例，您必须在系统上安装 Flutter SDK。安装完成后，您可以运行 flutter doctor 来检查您的相关平台是否缺少其他必要依赖项。环境配置完成后，请启动模拟器或连接 Android/iOS 设备。

从 demo/flutter 运行 prepare_demo 脚本，并指定语言代码以将示例设置为您选择的语言（例如 de 表示德语，ko 表示韩语）。要查看可用语言列表，请不带语言代码运行 prepare_demo。

dart scripts/prepare_demo.dart ${LANGUAGE}

将文件 main.dart 中的 "${YOUR_ACCESS_KEY_HERE}" 替换为您的 AccessKey。

从 demo/flutter 运行以下命令以构建并将示例部署到您的设备：

flutter run

React Native 示例

要运行 React Native Cheetah 示例应用，您首先需要设置 React Native 环境。为此，请参阅 React Native 官方文档。环境设置完成后，导航到 demo/react-native/CheetahDemo，运行以下命令：

对于 Android：

yarn android-install          # 设置环境
yarn android-run ${LANGUAGE}  # 构建并部署到 Android

对于 iOS：

yarn ios-install              # 设置环境
yarn ios-run ${LANGUAGE}      # 构建并部署到 iOS

Node.js 示例

安装示例包：

yarn global add @picovoice/cheetah-node-demo

确保您的设备已连接正常工作的麦克风，然后在终端中运行以下命令：

cheetah-mic-demo --access_key ${ACCESS_KEY}

有关 Node.js 示例的更多信息，请访问 demo/nodejs。

Java 示例

Cheetah Java 示例 是一个命令行应用程序，允许您选择在音频文件上或实时麦克风输入上运行 Cheetah。

要试用实时演示，请确保您的设备已连接正常工作的麦克风。然后从终端调用以下命令：

cd demo/java
./gradlew build
cd build/libs
java -jar cheetah-mic-demo.jar -a ${ACCESS_KEY}

有关 Java 示例的更多信息，请访问 demo/java。

.NET 示例

Cheetah .NET 示例 是一个命令行应用程序，允许您选择在音频文件上或实时麦克风输入上运行 Cheetah。

请确保您的设备已连接正常工作的麦克风。从 demo/dotnet/CheetahDemo 在终端中运行以下命令：

dotnet run -c MicDemo.Release -- --access_key ${ACCESS_KEY}

将 ${ACCESS_KEY} 替换为您的 Picovoice AccessKey。

有关 .NET 示例的更多信息，请访问 demo/dotnet。

Web 示例

原生 JavaScript 和 HTML

从 demo/web 在终端中运行以下命令：

yarn
yarn start

（或者）

npm install
npm run start

在浏览器中打开 http://localhost:5000 即可试用该示例。

React 示例

从 demo/react 在终端中运行以下命令：

yarn
yarn start

（或者）

npm install
npm run start

在浏览器中打开 http://localhost:3000 即可试用该示例。

SDK

Python

安装 Python SDK：

pip3 install pvcheetah

创建引擎实例并实时转录音频：

import pvcheetah

handle = pvcheetah.create(access_key='${ACCESS_KEY}')

def get_next_audio_frame():
    pass

while True:
    partial_transcript, is_endpoint = handle.process(get_next_audio_frame())
    if is_endpoint:
        final_transcript = handle.flush()

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台获取的密钥。

C

创建引擎实例并实时转录音频：

#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>

#include "pv_cheetah.h"

pv_cheetah_t *handle = NULL;
const pv_status_t status = pv_cheetah_init("${ACCESS_KEY}", "${MODEL_PATH}", "${DEVICE}", 0.f, false, false, &handle);
if (status != PV_STATUS_SUCCESS) {
    // 错误处理逻辑
}

extern const int16_t *get_next_audio_frame(void);

while (true) {
    char *partial_transcript = NULL;
    bool is_endpoint = false;
    const pv_status_t status = pv_cheetah_process(
            handle,
            get_next_audio_frame(),
            &partial_transcript,
            &is_endpoint);
    if (status != PV_STATUS_SUCCESS) {
        // 错误处理逻辑
    }
    // 处理转录内容
    free(partial_transcript);
    if (is_endpoint) {
        char *final_transcript = NULL;
        const pv_status_t status = pv_cheetah_flush(handle, &final_transcript);
        if (status != PV_STATUS_SUCCESS) {
            // 错误处理逻辑
        }
        // 处理最终转录内容
        free(final_transcript);
    }
}

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台获取的密钥，将 ${MODEL_PATH} 替换为 默认模型文件 的路径（或您自定义的模型路径）。最后，在完成操作后，请务必使用 pv_cheetah_delete(handle) 释放资源。

iOS

Cheetah 的 iOS 绑定可通过 CocoaPods 获取。要将其导入您的 iOS 项目中，请在 Podfile 中添加以下行并运行 pod install：

pod 'Cheetah-iOS'

创建引擎实例并实时转录音频：

import Cheetah

let modelPath = Bundle(for: type(of: self)).path(
        forResource: "${MODEL_FILE}", // Cheetah 模型文件名
        ofType: "pv")!

let cheetah = Cheetah(accessKey: "${ACCESS_KEY}", modelPath: modelPath)

func getNextAudioFrame() -> [Int16] {
  // .. 获取音频帧
  return audioFrame;
}

while true {
  do {
    let partialTranscript, isEndpoint = try cheetah.process(getNetAudioFrame())
    if isEndpoint {
      let finalTranscript = try cheetah.flush()
    }
  } catch let error as CheetahError {
      // 处理错误
  } catch { }
}

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台获取的密钥，将 ${MODEL_FILE} 替换为通过 Picovoice 控制台 或 默认模型 训练的自定义模型。

Android

要将该软件包包含到您的 Android 项目中，请确保在项目的顶级 build.gradle 文件中已添加 mavenCentral()，然后将以下内容添加到应用的 build.gradle 文件中：

dependencies {
    implementation 'ai.picovoice:cheetah-android:${LATEST_VERSION}'
}

创建引擎实例并实时转录音频：

import ai.picovoice.cheetah.*;

final String accessKey = "${ACCESS_KEY}"; // 从 Picovoice 控制台获取的 AccessKey (https://console.picovoice.ai/)
final String modelPath = "${MODEL_FILE}";

short[] getNextAudioFrame() {
    // .. 获取音频帧
    return audioFrame;
}

try {
    Cheetah cheetah = new Cheetah.Builder().setAccessKey(accessKey).setModelPath(modelPath).build(appContext);

    String transcript = "";

    while (true) {
        CheetahTranscript transcriptObj = cheetah.process(getNextAudioFrame());
        transcript += transcriptObj.getTranscript();

        if (transcriptObj.getIsEndpoint()) {
            CheetahTranscript finalTranscriptObj = cheetah.flush();
            transcript += finalTranscriptObj.getTranscript();
        }
    };

} catch (CheetahException ex) { }

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台获取的 AccessKey，并将 ${MODEL_FILE} 替换为来自 控制台 的默认模型或自定义训练模型。

Flutter

将 Cheetah Flutter 插件 添加到您的 pubspec.yaml 文件中。

dependencies:
  cheetah_flutter: ^<version>

创建引擎实例并实时转录音频：

import 'package:cheetah_flutter/cheetah.dart';

const accessKey = "{ACCESS_KEY}"  // 从 Picovoice 控制台获取的 AccessKey (https://console.picovoice.ai/)

List<int> buffer = getAudioFrame();

try{
    Cheetah _cheetah = await Cheetah.create(accessKey, '{CHEETAH_MODEL_PATH}');

    String transcript = "";

    while (true) {
        CheetahTranscript partialResult = await _cheetah.process(getAudioFrame());
        transcript += partialResult.transcript;

        if (partialResult.isEndpoint) {
            CheetahTranscript finalResult = await _cheetah.flush();
            transcript += finalResult.transcript;
        }
    }

    _cheetah.delete()

} on CheetahException catch (err) { }

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台 获取的 AccessKey，并将 ${CHEETAH_MODEL_PATH} 替换为来自 Picovoice 控制台 的自定义训练模型路径，或使用 默认模型。

React Native

Cheetah 的 React Native 绑定可通过 NPM 获取。通过以下命令将其添加：

yarn add @picovoice/cheetah-react-native

创建引擎实例并转录音频文件：

import {Cheetah, CheetahErrors} from '@picovoice/cheetah-react-native';

const getAudioFrame = () => {
  // 获取音频帧
}

try {
  while (1) {
    const cheetah = await Cheetah.create("${ACCESS_KEY}", "${MODEL_FILE}")
    const {transcript, isEndpoint} = await cheetah.process(getAudioFrame())
    if (isEndpoint) {
      const {transcript} = await cheetah.flush()
    }
  }
} catch (err: any) {
  if (err instanceof CheetahErrors) {
    // 处理错误
  }
}

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台获取的 AccessKey，并将 ${MODEL_FILE} 替换为来自 控制台 的默认模型或自定义训练模型。完成操作后，请务必使用 cheetah.delete() 显式释放资源。

Node.js

安装 Node.js SDK：

yarn add @picovoice/cheetah-node

创建 Cheetah 类的实例：

const Cheetah = require("@picovoice/cheetah-node");

const accessKey = "${ACCESS_KEY}"; // 从 Picovoice 控制台获取 (https://console.picovoice.ai/)
const endpointDurationSec = 0.2;
const handle = new Cheetah(accessKey);

function getNextAudioFrame() {
  // ...
  return audioFrame;
}

while (true) {
  const audioFrame = getNextAudioFrame();
  const [partialTranscript, isEndpoint] = handle.process(audioFrame);
  if (isEndpoint) {
    finalTranscript = handle.flush()
  }
}

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台 获取的 AccessKey。

完成操作后，请务必使用 release() 释放资源：

handle.release();

Java

使用 Cheetah Builder 类创建引擎实例，并实时转录音频：

import ai.picovoice.cheetah.*;

final String accessKey = "..."; // Picovoice 控制台提供的 AccessKey (https://console.picovoice.ai/)

short[] getNextAudioFrame() {
    // .. 获取音频帧
    return audioFrame;
}

String transcript = "";

try {
    Cheetah cheetah = new Cheetah.Builder().setAccessKey(accessKey).build();

    while (true) {
        CheetahTranscript transcriptObj = cheetah.process(getNextAudioFrame());
        transcript += transcriptObj.getTranscript();

        if (transcriptObj.getIsEndpoint()) {
            CheetahTranscript finalTranscriptObj = cheetah.flush();
            transcript += finalTranscriptObj.getTranscript();
        }
    }

    cheetah.delete();

} catch (CheetahException ex) { }

.NET

使用 NuGet 或 dotnet CLI 安装 .NET SDK：

dotnet add package Cheetah

该 SDK 提供了一个工厂方法来创建引擎实例，如下所示：

using Pv;

const string accessKey = "${ACCESS_KEY}";

Cheetah handle = Cheetah.Create(accessKey);

将 ${ACCESS_KEY} 替换为您从 Picovoice 控制台 获取的 AccessKey。

初始化后，有效的采样率由 handle.SampleRate 给出。预期的帧长度（输入数组中的音频样本数量）为 handle.FrameLength。该引擎接受 16 位线性编码的 PCM 格式，并且仅处理单声道音频。

short[] GetNextAudioFrame()
{
    // .. 获取音频帧
    return audioFrame;
}

string transcript = "";

while(true)
{
    CheetahTranscript transcriptObj = handle.Process(GetNextAudioFrame());
    transcript += transcriptObj.Transcript;

        if (transcriptObj.IsEndpoint) {
        CheetahTranscript finalTranscriptObj = handle.Flush();
        transcript += finalTranscriptObj.Transcript;
    }
}

Cheetah 的资源将由垃圾回收器自动释放，但若希望在使用完毕后立即释放资源，可以使用 using 语句：

using(Cheetah handle = Cheetah.Create(accessKey))
{
    // .. 在此处使用 Cheetah
}

网页

原生 JavaScript 和 HTML（ES 模块）

使用 yarn 安装 Web SDK：

yarn add @picovoice/cheetah-web

或者使用 npm：

npm install --save @picovoice/cheetah-web

使用 CheetahWorker 创建引擎实例，并转录音频文件：

import { CheetahWorker } from "@picovoice/cheetah-web";
import cheetahParams from "${PATH_TO_BASE64_CHEETAH_PARAMS}";

let transcript = "";

function transcriptCallback(cheetahTranscript: CheetahTranscript) {
  transcript += cheetahTranscript.transcript;
  if (cheetahTranscript.isEndpoint) {
    transcript += "\n";
  }
}

function getAudioData(): Int16Array {
  // ... 获取音频数据的函数
  return new Int16Array();
}

const cheetah = await CheetahWorker.create(
  "${ACCESS_KEY}",
  transcriptCallback,
  { base64: cheetahParams }
);

for (;;) {
  cheetah.process(getAudioData());
  // 在满足某些条件时退出循环
}
cheetah.flush(); // 对剩余数据调用 transcriptionCallback。

将 ${ACCESS_KEY} 替换为你从 Picovoice 控制台 获取的密钥。最后，完成操作后使用 cheetah.release() 释放资源。

React

yarn add @picovoice/cheetah-react @picovoice/web-voice-processor

（或）

npm install @picovoice/cheetah-react @picovoice/web-voice-processor

import { useCheetah } from "@picovoice/cheetah-react";

function App(props) {
  const {
    result,
    isLoaded,
    isListening,
    error,
    init,
    start,
    stop,
    release,
  } = useCheetah();

  const initEngine = async () => {
    await init(
      "${ACCESS_KEY}",
      cheetahModel,
    );
  };

  const toggleRecord = async () => {
    if (isListening) {
      await stop();
    } else {
      await start();
    }
  };

  useEffect(() => {
    if (result !== null) {
      console.log(result.transcript);
      console.log(result.isComplete);
    }
  }, [result])
}

版本发布

v4.0.0 - 2026年3月19日

• 提升了引擎性能和降低延迟
• 新增文本归一化功能

v3.0.0 - 2025年12月17日

• 进一步优化了引擎性能
• 支持在 GPU 或多核 CPU 上运行
• Node.js 最低版本提升至 Node 18
• iOS 最低版本提升至 iOS 16
• Flutter 最低版本提升至 3.10
• React Native 最低版本提升至 0.73

v2.3.0 - 2025年8月29日

• 新增支持低延迟的 Cheetah Fast 模型
• 提高了引擎的准确性

v2.2.0 - 2025年7月3日

• 改进了自动标点符号插入功能

v2.1.0 - 2024年12月10日

• 新增对法语、德语、意大利语、葡萄牙语和西班牙语的支持
• 修复了多个 bug 并提升了性能

v2.0.0 - 2023年11月27日

• 改进了错误报告机制
• 升级了授权与认证系统
• 提高了引擎的准确性
• 修复了多个 bug 并进行了多项改进
• Node.js 最低支持版本提升至 Node 16
• iOS 最低支持版本提升至 iOS 13 及以上
• 修复了 .NET 的兼容性问题

v1.1.0 - 2022年8月11日

• 转录结果默认启用大小写正确化
• 新增自动标点符号插入选项
• 发布 Cheetah Web SDK

v1.0.0 - 2022年1月25日

• 初始版本发布

Cheetah 快速上手指南

Cheetah 是由 Picovoice 开发的本地流式语音转文本（Speech-to-Text）引擎。它完全在设备端运行，无需联网即可进行语音识别，具有高精度、低延迟和跨平台支持的特点。

环境准备

系统要求

Cheetah 支持以下平台和架构：

• 桌面端: Linux (x86_64), macOS (x86_64, arm64), Windows (x86_64, arm64)
• 移动端: Android, iOS
• Web 端: Chrome, Safari, Firefox, Edge
• 嵌入式: Raspberry Pi (3, 4, 5)

前置依赖

1. AccessKey (访问密钥):
   • 所有 Picovoice SDK 均需有效的 AccessKey 进行授权。
   • 请访问 Picovoice Console 注册并获取密钥。
   • 注意: 虽然语音识别过程完全离线，但初始化时需要网络连接以验证 AccessKey 的有效性。
2. 语言支持:
   • 目前支持：英语、法语、德语、意大利语、葡萄牙语、西班牙语。
3. 开发环境:
   • 根据所选语言安装对应运行时（如 Python 3, Node.js, JDK, .NET SDK 等）。
   • 确保麦克风硬件工作正常（用于实时演示）。

安装步骤

以下以最常用的 Python 和 Node.js 为例，其他语言请参考官方文档对应的 SDK 部分。

Python 安装

使用 pip 安装核心库：

pip3 install pvcheetah

若需运行官方提供的麦克风演示程序：

pip3 install pvcheetahdemo

Node.js 安装

使用 npm 或 yarn 安装核心库：

npm install @picovoice/cheetah-node
# 或
yarn add @picovoice/cheetah-node

若需运行官方演示程序：

yarn global add @picovoice/cheetah-node-demo

其他平台简述

• Java/Android: 通过 Maven Central 引入 ai.picovoice:cheetah-java 或 cheetah-android。
• iOS: 通过 CocoaPods 安装 Cheetah-iOS。
• .NET: 通过 NuGet 安装 Picovoice.Cheetah。
• Flutter/React Native/Web: 均有对应的 npm/pub 包，详见 README "SDKs" 章节。

基本使用

以下示例展示如何初始化引擎并处理实时音频流。请将 ${ACCESS_KEY} 替换为你从控制台获取的真实密钥。

Python 示例

import pvcheetah

# 1. 创建引擎实例
handle = pvcheetah.create(access_key='${ACCESS_KEY}')

def get_next_audio_frame():
    # 此处应替换为实际获取 16kHz 单声道 PCM 音频帧的逻辑
    # 每帧长度通常为 512 个采样点
    pass

try:
    while True:
        # 2. 处理音频帧
        partial_transcript, is_endpoint = handle.process(get_next_audio_frame())
        
        # 输出部分识别结果
        if partial_transcript:
            print(partial_transcript, end=' ')
            
        # 3. 检测语句结束并获取最终结果
        if is_endpoint:
            final_transcript = handle.flush()
            if final_transcript:
                print(f"\nFinal: {final_transcript}")
finally:
    # 4. 释放资源
    handle.delete()

Node.js 示例

const Cheetah = require('@picovoice/cheetah-node');

async function run() {
    // 1. 创建引擎实例
    const handle = await Cheetah.create('${ACCESS_KEY}');

    // 模拟获取音频帧的函数 (需返回 Int16Array)
    function getNextAudioFrame() {
        // 此处填入实际音频采集逻辑
        return new Int16Array(512); 
    }

    try {
        while (true) {
            // 2. 处理音频帧
            const { partialTranscript, isEndpoint } = handle.process(getNextAudioFrame());

            if (partialTranscript) {
                process.stdout.write(partialTranscript + ' ');
            }

            // 3. 检测语句结束
            if (isEndpoint) {
                const finalTranscript = handle.flush();
                if (finalTranscript) {
                    console.log(`\nFinal: ${finalTranscript}`);
                }
            }
        }
    } finally {
        // 4. 释放资源
        handle.release();
    }
}

run().catch(console.error);

运行演示程序 (最快体验方式)

如果你已安装 pvcheetahdemo (Python) 或 @picovoice/cheetah-node-demo (Node.js)，可直接运行命令行工具测试麦克风：

Python:

cheetah_demo_mic --access_key ${ACCESS_KEY}

Node.js:

cheetah-mic-demo --access_key ${ACCESS_KEY}