---
name: funasr-subtitle
description: Extract subtitles from video or audio files using Fun-ASR-Nano model. Supports outputting SRT and TXT formats. Use when users need to generate subtitles, transcribe videos, or extract text from audio content using the FunASR Nano model.
---

# FunASR Subtitle Extractor

## Overview

This skill provides a tool to automatically extract subtitles from video or audio files using the high-performance Fun-ASR-Nano model. It handles audio extraction (using ffmpeg) and speech-to-text transcription, generating both standard SRT subtitle files and plain text transcripts.

## Capabilities

1.  **Audio Extraction**: Automatically extracts audio from video files (MP4, MKV, etc.) using ffmpeg.
2.  **Speech Recognition**: Uses Fun-ASR-Nano (2512 version) for accurate multi-lingual speech recognition.
3.  **Subtitle Generation**: Outputs timestamped SRT files suitable for video players.
4.  **Transcript Generation**: Outputs plain text files for reading.

## Installation & Setup

### 1. Install Dependencies

You can run the provided PowerShell script to install Python dependencies:

```powershell
./scripts/install_deps.ps1
```

Or install manually:

```bash
pip install funasr modelscope torch torchaudio ffmpeg-python
```

### 2. System Requirements

*   **FFmpeg**: Must be installed and added to the system PATH.
    *   Verify with: `ffmpeg -version`
*   **CUDA (Optional)**: For faster inference, ensure you have a CUDA-compatible GPU and PyTorch installed with CUDA support. The script will automatically fallback to CPU if CUDA is unavailable.

## Usage

### Extract Subtitles

To extract subtitles from a file, use the provided Python script `scripts/extract_subtitles.py`.

```bash
python scripts/extract_subtitles.py <input_file_path>
```

**Arguments:**
- `input_file_path`: Path to the video or audio file (e.g., `.mp4`, `.mp3`, `.wav`).

**Output:**
The script generates two files in the same directory as the input:
- `<filename>.srt`: Subtitle file with timestamps.
- `<filename>.txt`: Plain text transcript.
- It also returns a JSON object with the paths and full text content.

### Example

```python
# In a python script or shell
python scripts/extract_subtitles.py "C:/Videos/lecture.mp4"
```

## Known Issues & Troubleshooting

### 1. `FunASRNano` Registration Error (ImportError)

**Issue:**
In `funasr` version 1.3.1 (and possibly others), you may encounter an error like:
`AssertionError: FunASRNano is not registered` or `ModuleNotFoundError: No module named 'model'`.

**Cause:**
The `Fun-ASR-Nano` model code in the library uses relative imports that fail when the model directory is not in the Python path.

**Solution (Already applied in `extract_subtitles.py`):**
The script includes a workaround that explicitly adds the model directory to `sys.path` and imports the model module to force registration.

```python
# Workaround logic in extract_subtitles.py
funasr_path = os.path.dirname(funasr.__file__)
fun_asr_nano_path = os.path.join(funasr_path, "models", "fun_asr_nano")
if os.path.exists(fun_asr_nano_path):
    sys.path.append(fun_asr_nano_path)
try:
    import funasr.models.fun_asr_nano.model
except ImportError:
    pass
```

### 2. VAD (Voice Activity Detection) Compatibility

**Issue:**
Using `vad_model="fsmn-vad"` with `Fun-ASR-Nano` may cause runtime errors (e.g., `KeyError: 0` in `inference_with_vad`).

**Solution:**
The VAD model is currently disabled in the script (`vad_model` commented out). The Nano model handles the transcription directly. If you need VAD, check for updates to `funasr` or enable it cautiously in the `FunASRSkill` class.

### 3. Model Download

**Issue:**
The model download might be slow or fail on unstable connections.

**Solution:**
The script uses `modelscope` to download `FunAudioLLM/Fun-ASR-Nano-2512` automatically. It is configured to `trust_remote_code=True`. If download fails, check your network or try setting a mirror for ModelScope.
