Metadata-Version: 2.3
Name: fasr-asr-paraformer
Version: 0.5.2
Summary: paraformer asr model for fasr
Author: osc
Author-email: osc <790990241@qq.com>
Requires-Dist: fasr
Requires-Dist: funasr
Requires-Dist: torchaudio
Requires-Python: >=3.10, <3.13
Description-Content-Type: text/markdown

# fasr-asr-paraformer

[Chinese documentation](README_ZH.md)

Paraformer speech recognition for fasr. The offline models return timestamped
tokens, and `seaco_paraformer` adds hotword support.

## Install

```bash
pip install fasr-asr-paraformer
```

## Registered Models

| Registry name | Class | Best for |
|---|---|---|
| `paraformer` | `Paraformer` | Offline ASR with token timestamps |
| `seaco_paraformer` | `SeacoParaformer` | Offline ASR with hotword biasing |
| `paraformer_online` | `ParaformerOnline` | Streaming Paraformer ASR |

## Pipeline Usage

```python
from fasr import AudioPipeline

pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe(
        "recognizer",
        model="paraformer",
        batch_size=64,
        disable_log=True,
    )
    .add_pipe("sentencizer", model="ct_transformer")
)
```

For hotwords, use `seaco_paraformer`:

```python
pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="fsmn")
    .add_pipe("recognizer", model="seaco_paraformer")
    .add_pipe("sentencizer", model="ct_transformer")
)

audio = pipeline.run("meeting.wav", hotwords=["Paraformer", "fasr"])[0]
```

## Confection Config

```toml
[asr_model]
@asr_models = "paraformer"
batch_size = 64
device = "cuda:0"
disable_update = true
disable_log = true
disable_pbar = true
```

Inside a pipeline:

```toml
[pipeline]
@pipelines = "AudioPipeline.v1"
pipe_order = ["recognizer"]

[pipeline.pipes]

[pipeline.pipes.recognizer]
@pipes = "thread_pipe"
batch_size = 4

[pipeline.pipes.recognizer.component]
@components = "recognizer"

[pipeline.pipes.recognizer.component.model]
@asr_models = "paraformer"
batch_size = 64
device = "cuda:0"
disable_log = true
disable_pbar = true
```

## Direct Model Usage

```python
from fasr.config import registry

model = registry.asr_models.get("paraformer")(batch_size=64)
spans = model.transcribe(audio_spans)
for span in spans:
    print(span.text)
    for token in span.tokens or []:
        print(token.text, token.start_ms, token.end_ms)
```

Use local weights:

```python
model.load_checkpoint("/path/to/paraformer")
```

## Parameters

| Parameter | Type / range | Default | Higher / true | Lower / false | Change when |
|---|---|---|---|---|---|
| `batch_size` | `int >= 1` | `10000` | More throughput, more memory | Lower memory, lower throughput | Batch size is too memory-heavy or too slow |
| `device` | `str \| null` | `null` | Explicit device selection such as `cuda:0` or `cpu` | Auto-selects `cuda:0` when CUDA is available, otherwise `cpu` | You want to override the automatic device choice |
| `disable_update` | `bool` | `True` | Skips FunASR update checks | Allows update checks | Reproducible startup or update discovery |
| `disable_log` | `bool` | `True` | Suppresses backend logs | Shows backend logs | Debugging loading or inference |
| `disable_pbar` | `bool` | `True` | Hides progress bars | Shows progress bars | Interactive scripts |
| `compile_model` | `bool`, online only | `False` | Uses `torch.compile`, slower warm-up but faster steady state | No compile warm-up | Long-running streaming service |
| `chunk_size_ms` | `int`, online only | `600` | Fewer streaming calls, later output | More responsive, more overhead | Streaming latency/throughput tuning |

Generic checkpoint fields such as `checkpoint`, `cache_dir`, `endpoint`,
`revision`, and `force_download` are inherited from the base model.

## Output

- `paraformer` and `seaco_paraformer` populate `span.raw_text`.
- When timestamps are available, `span.tokens` contains absolute
  `start_ms` / `end_ms` values on the channel timeline.
- If `device` is omitted, the model auto-selects `cuda:0` when CUDA is
  available, otherwise it falls back to `cpu` and logs a warning.
- `seaco_paraformer` accepts `hotwords` through the pipeline run call or
  `transcribe(..., hotwords=[...])`.

## Dependencies

- `fasr`
- `funasr`
- Python 3.10-3.12
