Transcribe Call

---
name: transcribe-call
description: "Локальная расшифровка аудиозаписи созвона/интервью в текст через faster-whisper на GPU. Используй, когда пользователь присылает путь к аудиофайлу (например записи Телемоста) и просит расшифровать, распознать речь, сделать транскрипт или конспект разговора."
---

# Локальная расшифровка звонков (faster-whisper)

Расшифровывает аудио в текст на локальной GPU, без отправки записи куда-либо наружу. Подходит
для личных созвонов, интервью, планёрок — всё остаётся на машине пользователя.

## ⛔ Сначала внеси встречу в тайм-трекер

Запись созвона со стороны заказчика — оплачиваемое время встречи, отдельное от времени разбора.
До запуска расшифровки: старт из имени файла (`... 24.09.26 20-02-02 ...` → 20:02:02 МСК),
длительность из `ffprobe`, затем `time_log` с `kind: "MEETING"`, `startedAt`/`endedAt`.
Полный порядок — [time-tracking.md § Запись задним числом](/.claude/rules/time-tracking.md).

## Быстрый старт

```powershell
python "C:\web\letar\.claude\skills\transcribe-call\transcribe.py" "<путь к аудио>"
```

Пишет `<имя>.txt` (только текст) и `<имя>.timed.txt` (с таймкодами) **рядом с аудиофайлом**, не в
репозитории. Если у разговора есть предметная терминология (имена, названия, профессиональный
жаргон) — передай её отдельно, это повышает точность распознавания редких слов:

```powershell
python transcribe.py "<путь к аудио>" --hotwords "прораб, техзадание, ретроспектива"
# или из файла, если словарь большой/меняется от случая к случаю:
python transcribe.py "<путь к аудио>" --hotwords-file "C:\Users\Kami\Documents\Телемост\hotwords.txt"
```

⚠️ **Не зашивай в этот скрипт термины конкретного клиента/проекта.** `letar` — публичный
репозиторий (см. `.claude/rules/public-repo-hygiene.md`) — доменные словари передаются аргументом
и живут вне репозитория (файл рядом с записями, или в приватной памяти пользователя), а не в коде
скилла.

## Что делает скрипт сам

- **Докрутка после падения.** Иногда процесс faster-whisper молча падает посреди длинной записи
  (exit code 9, без трассировки — известная особенность CTranslate2 на этой машине, см.
  `reference_local_audio_transcription_whisper.md` в памяти). `transcribe.py` — это
  супервизор: он запускает распознавание отдельным подпроцессом и, если тот упал, сам находит
  последний записанный таймкод и перезапускает распознавание с этого места (`--max-retries`,
  по умолчанию 5). В конце все куски склеиваются в один `<имя>.timed.txt`/`<имя>.txt` с
  правильными абсолютными таймкодами — вручную ничего докручивать не нужно.
- **Пометка известных галлюцинаций Whisper.** Модель иногда выдаёт на тишине/музыке фразы вида
  «Продолжение следует…», «Субтитры делал DimaTorzok», «Спасибо за просмотр». Скрипт не удаляет
  такие строки молча (это может быть настоящая речь, совпавшая по тексту случайно) — помечает
  префиксом `[ВОЗМОЖНАЯ ГАЛЛЮЦИНАЦИЯ WHISPER, ПРОВЕРИТЬ]`, дальше решает человек.
- **Перераспознавание помеченного.** Такие сегменты часто стоят **на месте речи**, а не тишины
  (30-секундное окно, соседние строки идут вплотную) — под ними теряется реальный текст. После
  склейки скрипт вырезает окно ±5 с вокруг каждого помеченного сегмента и прогоняет его заново,
  до первой удачной попытки:
  1. с теми же hotwords, но `temperature` от 0.2 — на нуле уверенная галлюцинация проходит
     пороги, и fallback не включается;
  2. без hotwords — faster-whisper кладёт их в prompt каждого окна, а prompt провоцирует
     «субтитровые» галлюцинации (на реальной записи окно с hotwords снова дало «Субтитры
     сделал…», без них — нормальный текст);
  3. без VAD.

  Попытка засчитывается, если текст не пуст, не содержит известных галлюцинаций и не зациклен.
  Из окна берутся только слова самого сегмента (по пословным таймкодам), повторы краёв соседних
  строк срезаются. Удалось — строка получает префикс `[ПЕРЕРАСПОЗНАНО]`, иначе остаётся прежняя
  пометка. ⚠️ Это всё ещё текст под проверку: на стыке может остаться дубль или потеряться слово,
  а с `temperature > 0` результат от запуска к запуску немного разный. Отключить —
  `--no-retry-hallucinations`.

## Параметры

| Флаг                        | По умолчанию | Смысл                                                                            |
| --------------------------- | ------------ | -------------------------------------------------------------------------------- |
| `--compute-type`            | `float32`    | `float32` — макс. качество (~8 ГБ VRAM); `int8_float16` быстрее, если не влезает |
| `--hotwords`                | пусто        | строка терминов через запятую — подсказка модели                                 |
| `--hotwords-file`           | —            | то же самое, но из текстового файла (не коммитить в репо)                        |
| `--start-sec`               | `0`          | ручной старт с секунды — для докрутки конкретного отрезка вручную                |
| `--max-retries`             | `5`          | сколько раз подряд перезапускать воркер после падений                            |
| `--no-retry-hallucinations` | выкл.        | не перераспознавать помеченные сегменты                                          |
| `--retry-only`              | выкл.        | только перераспознать помеченное в готовом `<имя>.timed.txt` (см. ниже)          |

**Уже расшифрованная запись с пометками** (сделана до появления перераспознавания или с
`--no-retry-hallucinations`) — полный прогон не нужен, хватит минуты:

```powershell
python transcribe.py "<путь к аудио>" --retry-only --hotwords-file "<тот же словарь>"
```

Файл `.timed.txt` перезаписывается на месте, строки без пометки не меняются. Уже
`[ПЕРЕРАСПОЗНАНО]` повторно не трогаются.

## Что нужно на машине

Python 3.14 (`C:\Python314`), `faster-whisper`, `nvidia-cublas-cu12`, `nvidia-cudnn-cu12>=9,<10` —
уже установлены на этой машине (Kami). Модель `large-v3` кешируется HuggingFace при первом
запуске. Подробности среды, версии и история граблей — в памяти:
`C:\Users\Kami\.claude\projects\C--web-letar\memory\reference_local_audio_transcription_whisper.md`.

Если запускаешь на другой машине без этого окружения — установка описана там же.

## ⛔ Что нельзя коммитить

- Сами расшифровки (`.txt`, `.timed.txt`) — это личные разговоры пользователя. Оставляй их
  рядом с аудиофайлом (обычно `C:\Users\Kami\Documents\Телемост\`), не переноси в репозиторий
  ни в каком виде.
- Файлы с доменными hotwords конкретного клиента/проекта — та же причина
  (`.claude/rules/public-repo-hygiene.md`): в публичном `letar` не должно быть имён клиентов,
  их доменов и деталей бизнеса.
- В документы проекта (PLAN.md, заметки) переносить только **извлечённые выводы и решения** из
  разговора — не сырой текст расшифровки целиком.

## Проверка, что всё работает

Быстрый тест на первых ~60 секундах любой записи (не гонять полный файл, если просто проверяешь
окружение):

```powershell
python transcribe.py "<путь к короткому фрагменту или полной записи>" --max-retries 0
```

Если нужно проверить именно короткий отрезок длинной записи — обрежь исходный файл заранее
(`ffmpeg -i in.aac -t 60 out.aac`) либо просто прерви процесс через минуту: часть уже будет
записана в `.timed.txt`.