> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-pr-4892.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# FunASR

> Speech-to-text service implementation using locally-downloaded FunASR models

## Overview

`FunASRSTTService` provides offline speech recognition using FunASR's SenseVoice models running locally on CPU or GPU. SenseVoice is a multilingual model with strong Chinese accuracy, supporting Chinese, Cantonese, English, Japanese, Korean, and other languages. The non-autoregressive architecture enables fast inference, making it a strong fully-local STT option for voice agents. No API key needed - models download once on first use and are cached locally for privacy-focused transcription.

<CardGroup cols={2}>
  <Card title="FunASR STT API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.funasr.stt.html">
    Pipecat's API methods for FunASR STT integration
  </Card>

  <Card title="FunASR Example" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-funasr.py">
    Complete example with FunASR STT
  </Card>

  <Card title="FunASR Documentation" icon="book" href="https://github.com/modelscope/FunASR">
    FunASR model details and research
  </Card>

  <Card title="SenseVoice Model" icon="microphone" href="https://github.com/FunAudioLLM/SenseVoice">
    SenseVoice multilingual ASR model
  </Card>
</CardGroup>

## Installation

```bash theme={null}
uv add "pipecat-ai[funasr]"
```

## Prerequisites

### Local Model Setup

Before using FunASR STT service, you need:

1. **Model Selection**: Choose an appropriate FunASR model (default: `iic/SenseVoiceSmall`)
2. **Storage Space**: Ensure sufficient disk space for model downloads (models are cached after first use)
3. **CPU or GPU Resources**: FunASR can run on CPU or GPU (CUDA)

### Configuration Options

* **Model Selection**: Default is `iic/SenseVoiceSmall`, but other FunASR models are supported
* **Language Support**: SenseVoice natively supports Chinese (`zh`), Cantonese (`yue`), English (`en`), Japanese (`ja`), and Korean (`ko`) with automatic language detection for other languages
* **Device Selection**: Choose `"cpu"` or `"cuda"` based on your hardware
* **No API Key**: Runs entirely locally for complete privacy

<Tip>
  No API keys required - FunASR runs entirely locally for complete privacy. Can run on CPU or GPU.
</Tip>

## Configuration

<ParamField path="device" type="str" default="&#x22;cpu&#x22;">
  Inference device. Use `"cpu"` or `"cuda"` for GPU acceleration.
</ParamField>

<ParamField path="settings" type="FunASRSTTService.Settings" default="None">
  Runtime-configurable settings for the STT service. See [FunASRSTTSettings](#funasrsttsettings) below.
</ParamField>

## FunASRSTTSettings

Runtime-configurable settings passed via the `settings` constructor argument using `FunASRSTTService.Settings(...)`. These can be updated mid-conversation with `STTUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default                 | Description                                                                                                                                                                                                                  |
| ---------- | ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`    | `str`             | `"iic/SenseVoiceSmall"` | FunASR model identifier. Default is SenseVoiceSmall. *(Inherited from base STT settings.)*                                                                                                                                   |
| `language` | `Language \| str` | `Language.EN`           | Language for transcription. Natively supports Chinese (`zh`), Cantonese (`yue`), English (`en`), Japanese (`ja`), and Korean (`ko`). Falls back to auto-detection for other languages. *(Inherited from base STT settings.)* |
| `use_itn`  | `bool`            | `True`                  | Apply inverse text normalization (e.g., converts spoken numbers like "nine" to numerals "9").                                                                                                                                |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.funasr.stt import FunASRSTTService

stt = FunASRSTTService()
```

### With GPU Acceleration

```python theme={null}
from pipecat.services.funasr.stt import FunASRSTTService

stt = FunASRSTTService(device="cuda")
```

### With Custom Language

```python theme={null}
from pipecat.services.funasr.stt import FunASRSTTService
from pipecat.transcriptions.language import Language

stt = FunASRSTTService(
    settings=FunASRSTTService.Settings(
        language=Language.ZH,  # Chinese
    ),
)
```

### With Inverse Text Normalization Disabled

```python theme={null}
from pipecat.services.funasr.stt import FunASRSTTService

stt = FunASRSTTService(
    settings=FunASRSTTService.Settings(
        use_itn=False,
    ),
)
```

### With Custom Model

```python theme={null}
from pipecat.services.funasr.stt import FunASRSTTService

stt = FunASRSTTService(
    settings=FunASRSTTService.Settings(
        model="iic/SenseVoiceSmall",  # or another FunASR model identifier
    ),
)
```

## Notes

* **First run downloads**: The selected model downloads from the ModelScope hub on first use and is cached locally. Later runs load it from the cache.
* **Segmented transcription**: `FunASRSTTService` extends `SegmentedSTTService`, meaning it processes complete audio segments after VAD detects the user has stopped speaking.
* **CPU and GPU support**: FunASR can run on CPU or GPU (CUDA). Use the `device` parameter to choose.
* **Audio format**: Expects 16-bit mono PCM audio at 16 kHz sample rate.
* **Multilingual support**: SenseVoice natively supports Chinese, Cantonese, English, Japanese, and Korean. For other languages, it falls back to automatic language detection.
* **No external dependencies**: Unlike API-based STT services, FunASR requires no API keys or network connectivity after the initial model download.
* **Inverse text normalization**: By default, `use_itn=True` converts spoken numbers to numerals (e.g., "nine" → "9"). Disable this with `use_itn=False` if you need the raw transcription.
* **Non-autoregressive inference**: SenseVoice uses non-autoregressive architecture for fast inference, making it suitable for real-time voice agents.