first commit

2026-09-11 19:47:15 +03:00
commit 32754a1fe2
56 changed files with 3836 additions and 0 deletions
@@ -0,0 +1,57 @@
+# Модуль 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 кГц: если запись звучит «с ускорением», у устройства
+  проблемы с ресемплингом — сообщи, добавим ресемплинг явно.