# Модуль 1: STT (речь → текст)

Обёртка над **faster-whisper** с интерфейсом «провайдер»: если для ПК отца понадобится
другой распознаватель (vosk), он добавляется новым классом без изменения остального проекта.

## Файлы

| Файл | Назначение |
|---|---|
| `base.py` | Интерфейс `SttProvider`, результат `TranscriptResult` |
| `provider_faster_whisper.py` | Реализация на faster-whisper (CPU, int8) |
| `test_stt.py` | Тест-скрипт: файл / генерация фразы / микрофон |
| `samples/` | Тестовые аудио (создаются при запуске, в git не входят) |

## Использование из кода

```python
from modules.stt import get_provider

stt = get_provider("faster-whisper", model_size="small")  # tiny|base|small|medium
result = stt.transcribe("phrase.wav")          # путь к файлу (wav/mp3/flac)
result = stt.transcribe(np_array_float32_16k)  # или массив с микрофона
print(result.text, result.processing_sec)
```

## Что замеряет тест

- **processing_sec** — время распознавания (без загрузки модели);
- **RTF** (realtime factor) — обработка/длина аудио; RTF < 1 — быстрее реального времени;
- при `--repeat N` — лучший (минимальный) прогон.

## Критерии приёмки Модуля 1

1. Тестовая фраза распознаётся дословно (allow punctuation/case).
2. Фраза ~5 c обрабатывается за <= 3 c (RTF <= 0.6) на `small`/int8/CPU.
3. Если нет — пробуем `base`, фиксируем цифры; если и `base` медленный — добавляем Vosk-провайдер.

## Решение по скорости (замер 2026-09-10, Linux, фраза 8.9 c, edge-tts голос)

| Модель | Обработка | RTF | Точность |
|---|---|---|---|
| **small** | **1.17 c** | **0.13** | дословно ✅ |
| base | 0.54 c | 0.06 | 2 ошибки ("выпить чаю" → "выпечаю") |
| tiny | 0.39 c | 0.04 | 4 ошибки ("тестовы", "выпечаю") |

**Вердикт: faster-whisper `small` (int8, CPU, beam=1, VAD on)** — RTF 0.13 даёт запас ×3
даже на слабом ПК; качество base/tiny недостаточно для пожилого пользователя.
Загрузка модели при старте: ~2–5 c (после скачивания), кэш в `~/.cache/huggingface`.

Память по факту не замерена — при желании: `/usr/bin/time -v .venv/bin/python modules/stt/test_stt.py --make-sample`.

## Известные ограничения

- Первый запуск качает модель с HuggingFace (small ≈ 460 МБ). Если недоступно:
  `export HF_ENDPOINT=https://hf-mirror.com` перед запуском.
- Запись с микрофона идёт на 16 кГц: если запись звучит «с ускорением», у устройства
  проблемы с ресемплингом — сообщи, добавим ресемплинг явно.