Metadata-Version: 2.1
Name: kairos-asr
Version: 0.6.3
Summary: High-performance Russian speech recognition library based on GigaAM-style RNN-T and ONNX.
Author: Alexey Shimokhin / Alenkar
License: MIT
Project-URL: Homepage, https://github.com/Alenkar/kairos-asr
Project-URL: Repository, https://github.com/Alenkar/kairos-asr
Project-URL: Issues, https://github.com/Alenkar/kairos-asr/issues
Keywords: asr,speech-recognition,russian,onnx,rnnt,gigaam,rnnt-asr
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: docs/THIRD_PARTY_LICENSES.md
Requires-Dist: huggingface-hub>=1.2.3
Requires-Dist: numpy>=1.23.5
Requires-Dist: torch>=2.6.0
Requires-Dist: torchaudio>=2.6.0
Requires-Dist: sentencepiece>=0.2.1
Requires-Dist: scipy>=1.15.3
Requires-Dist: onnxruntime>=1.19.2
Provides-Extra: all
Requires-Dist: sounddevice>=0.4.6; extra == "all"
Requires-Dist: onnxruntime-gpu>=1.19.2; extra == "all"
Provides-Extra: gpu
Requires-Dist: onnxruntime-gpu>=1.19.2; extra == "gpu"
Provides-Extra: realtime
Requires-Dist: sounddevice>=0.4.6; extra == "realtime"

![image](assets/logo.png)

# Kairos Automatic Speech Recognition

[![PyPI](https://img.shields.io/pypi/v/kairos-asr)](https://pypi.org/project/kairos-asr/)
[![Python](https://img.shields.io/pypi/pyversions/kairos-asr)](https://pypi.org/project/kairos-asr/)
[![Downloads](https://img.shields.io/pypi/dm/kairos-asr)](https://pypi.org/project/kairos-asr/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Hugging Face](https://img.shields.io/badge/HuggingFace-KairosASR-yellow?logo=huggingface)](https://huggingface.co/Alenkar/KairosASR)

---

**Kairos ASR** — высокопроизводительная библиотека распознавания русской речи на базе 
[**GigaAM-style RNN-T**](https://github.com/salute-developers/GigaAM) архитектуры и **ONNX**.

Проект сфокусирован на скорости, точности и удобстве интеграции в микросервисы и десктопные приложения.

## 📄 Описание

---

- Оптимизированный ONNX-инференс
- Работает на **CPU** и **GPU (CUDA, extra `[gpu]`)**
- Поддержка временных меток (**word-level**, **sentence-level**)
- Итеративная обработка с выводом прогресса и **ETA**
- Встроенный **Voice-Activity-Detection ([Silero VAD](https://github.com/snakers4/silero-vad))**
- Поддержка **длинных аудио**
- Простая установка и использование
- Поддержка **Windows** и **Linux**
## ⚡ TL;DR
- `pip install kairos-asr`
- Запустить: `kairos-asr transcribe example.wav` или см. Python сниппет ниже.
- Полное руководство: `docs/USAGE.md`.

## 📦 Установка

Веса доступны на Hugging Face: [Alenkar/KairosASR](https://huggingface.co/Alenkar/KairosASR)

## 🖥️ Системные требования
- `ffmpeg` должен быть доступен в `PATH` (используется для загрузки и ресемплинга аудио).
- Доступ в интернет. При первом запуске скачиваются веса моделей с Hugging Face и модель Silero VAD.
- Для ускорения скачиваний и избежания лимитов рекомендуется установить токен HF: `export HF_TOKEN=...` (или `huggingface-cli login`).

### Быстрый старт (CPU)

```bash
pip install kairos-asr
```

<details>
<summary>Другие способы установки</summary>

### Через GIT

```bash
pip install git+https://github.com/Alenkar/kairos-asr.git
# или
git clone https://github.com/Alenkar/kairos-asr.git
cd kairos-asr
pip install -e .
```
</details>

### Поддержка GPU (CUDA)

1) Пакет с GPU-опциями:
```bash
pip install "kairos-asr[gpu]"
```

2) Torch/Torchaudio под вашу версию CUDA:
```bash
# пример под CUDA 12.1/12.2 (cu121)
pip install torch==2.6.0 torchaudio==2.6.0 \
  --index-url https://download.pytorch.org/whl/cu121 --upgrade
```
Найдите свой индекс (cu118, cu121 и т.д.) на pytorch.org и подставьте в команду.

## 🚀 Использование (Python)

Минимальный пример:
```python
from kairos_asr import KairosASR

asr = KairosASR()  # авто-загрузка весов
result = asr.transcribe(wav_file="audio.wav")
print(result.full_text)
```

Требования к входному аудио:
- Файлы, поддерживаемые `ffmpeg`; автоматический ресемплинг до 16 kHz.
- Рекомендуется WAV PCM 16-bit, mono, 16 kHz; стерео приводится к моно.
- Длинные записи режутся Silero VAD на ~15–25 c (жёсткий лимит ~30 c) и объединяются.



## Использование (CLI)
Существует несколько команд для работы через терминал.

```bash
# Показать информацию
kairos-asr info

# Проверить окружение и вывести информацию
kairos-asr doctor

# Список моделей (показывает локальное наличие и путь)
kairos-asr list

# Скачать все модели
kairos-asr download

# Скачать только encoder
kairos-asr download encoder

# Перевести файл в текст
kairos-asr transcribe <wav_file>
```

## 🧠 Как работает

---

1. VAD делит аудио на сегменты (до 25 секунд).
2. Каждый сегмент преобразуется в Mel-spectrogram.
3. RNN-T модель (Encoder + Predictor + Joint).
4. Выравнивание слов по фреймам.
5. Объединение сегментов в финальную разметку.

Архитектура и общий пайплайн вдохновлены проектом **GigaAM**.

## 📜 Лицензия и происхождение

---

### Код
Часть исходного кода основана на проекте [**GigaAM**](https://github.com/salute-developers/GigaAM)
и используется в соответствии с условиями лицензии MIT.
Оригинальный [**проект GigaAM**](https://github.com/salute-developers/GigaAM):
* License: MIT
* Copyright (c) 2024 GigaChat Team

### Модели
Используемые веса моделей происходят из проекта **GigaAM**, но были:
* конвертированы в формат **ONNX**,
* оптимизированы для **CPU/GPU-inference**,
* адаптированы для использования в **Kairos ASR**,
* частично произведена тонкая настройка (**Lora**) на кастомных данных.

Права на исходные веса принадлежат правообладателям проекта **GigaAM**. 
Использование осуществляется в рамках лицензии MIT.

Если вы используете **KairosASR** в исследовательских или коммерческих целях — проверьте совместимость с лицензией
оригинальной модели (**GigaAM**).

## 📊 Планы развития

---

* [ ] Batch-inference.
* [ ] Realtime-inference (микрофон) и чанки с ndarray.
* [ ] Diarization (разделение спикеров).
* [ ] Тесты.
* [ ] Дальнейшее дообучение на специализированных данных.
* [ ] Скрипт для Lora finetune на своих данных.
* [ ] Увеличение Vocabulary.
* [x] Пакет для установки.
* [x] Веса на Hugging Face.

## 👤 Автор

---

Разработано и поддерживается: **([Alexey Shimokhin / Alenkar](https://github.com/Alenkar))**. \
Если вы используете **Kairos ASR** в своих проектах — ссылка или отзыв приветствуются.
