transcribe

name

transcribe

description

Транскрибирование видео и аудио файлов. Используй когда пользователь просит транскрибировать, расшифровать запись, сделать конспект встречи, извлечь речь из видео или аудио, преобразовать речь в текст. Для аудио (m4a/mp3/wav/ogg/flac/aac/wma) по умолчанию локальный faster-whisper + диаризация с автодетектом числа спикеров (pyannote community-1 GPU; с явным --num-speakers N - sherpa-onnx, быстрее). Для видео (mp4/mkv/webm/avi/mov) - Gemini API (разбор экрана + скриншоты) либо полностью локально (--engine local: whisper + локальная VLM). Разделение по спикерам с распознаванием имен по голосу между встречами (голосовая база) и по репликам.

/transcribe - Транскрибация видео и аудио

Два движка:

• Локальный (default для аудио): faster-whisper (CUDA) + опц. диаризация. Движок диаризации выбирается сам: без --num-speakers — pyannote community-1 (GPU, корректный автодетект числа спикеров, RTF ~0.064); с явным --num-speakers N — sherpa-onnx GPU (pyannote-segmentation-3.0 + eres2net, RTF ~0.24, точное N). Нет затрат, не уходит наружу. ВИДЕО тоже можно разобрать полностью локально - --engine local (разбор экрана локальной VLM + спикеры по голосу, см. ниже).
• Gemini (default для видео и --analyze-ui): облачный API, ~$0.10/час. Нужен интернет и квота. Стартовая модель gemini-2.5-flash (пин конкретной версии, дешевая); при перегрузке (503/429) переходит на gemini-2.5-flash-lite. Дорогие 3.5/pro сознательно исключены.

Выбор движка по умолчанию

Тип файла	Движок	Причина
Аудио (m4a, mp3, wav, ogg, flac, aac, wma)	local	Быстро, бесплатно, диаризация
Видео (mp4, mkv, webm, avi, mov)	gemini	Быстро, облако. Приватный вариант - --engine local (см. ниже)
Видео + --engine local	local	Разбор экрана БЕЗ облака: whisper + локальная VLM (LM Studio) + спикеры по голосу
Любой + --analyze-ui	gemini	Детальный разбор интерфейсов в облаке
Любой + --engine gemini	gemini	Явный override на облако
Аудио + --engine local	local	Явный override (аудио)

При 503/429 Gemini-движок сначала сам перебирает пул моделей (см. раздел "Авто-fallback по моделям Gemini"). Если весь пул недоступен и это аудио - можно вручную переключиться на local (--engine local).

Режимы

Локальный (аудио + faster-whisper + опц. pyannote)

Выходные файлы:

• <имя> - транскрипция.md — таймкоды + текст
• <имя> - транскрипция.txt — plain text
• <имя> - со спикерами.md — реплики с метками [SPEAKER_XX, MM:SS] (только при --diarize)

Gemini generic

Выходные файлы:

• <имя> - транскрипция.md — речь с таймкодами + спикеры (если различимы)
• <имя> - саммари.md — протокол встречи (с флагом --with-summary); строится из текста транскрипции в 2 прохода (экстрактор всех фактов -> протокол) для полноты задач/решений

Gemini analyze-ui (только видео)

Анализ видеозаписи с разбором экранного интерфейса + скриншоты. Детальный лог и транскрипция пишутся по частям сразу (инкрементально): сбой на поздней части длинного видео не теряет ранние. Саммари строится в конце из полной транскрипции (2 прохода) - это протокол задач/решений; разбор показанных интерфейсов - в детальном логе.

Выходные файлы:

• <имя> - саммари.md
• <имя> - детальный.md
• <имя> - транскрипция.md
• screenshots/ - PNG-кадры

Локальный разбор видео (--engine local, только видео)

Полностью локальный разбор экрана + речи БЕЗ облака (подробности в "Инструкция" ниже). Спикеры распознаются по голосу (голосовая база) и по репликам - см. "Спикеры и голосовая база".

Выходные файлы:

• <имя> - транскрипция.md / .txt
• <имя> - со спикерами.md (при --diarize)
• <имя> - детальный.md - дословный лог: описание экрана по кадрам + реплики за интервал
• <имя> - связный.md - связный нарратив экран+речь (если не --no-coherent)
• <имя> - саммари.md - протокол задач/решений (если не --no-summary)
• <имя>.voiceprints.json - отпечатки голоса кластеров
• screenshots/ - ВСЕ scene-кадры

Аргументы

Параметр	Обязательный	По умолчанию	Описание
FilePath	да	—	Путь к аудио/видеофайлу
--output-dir	нет	<каталог>/Транскрипция/<имя>/	Каталог результатов
--engine	нет	auto (local для аудио, gemini для видео)	local или gemini
--diarize	нет	выкл	Локальный движок: разделение по спикерам
--num-speakers N	нет	автодетект (pyannote community-1)	Точное число спикеров; с ним движок переключается на sherpa-onnx (быстрее)
--min-speakers N / --max-speakers N	нет	—	Границы автодетекта (движок pyannote)
--diarize-engine	нет	авто: без N — pyannote, с N — sherpa-onnx	НЕ запускать sherpa-onnx без --num-speakers: его пороговый автодетект пересегментирует (16.07.26: 242 кластера на ~7 человек)
--analyze-ui	нет	выкл	Gemini: анализ интерфейсов (только видео)
--with-summary	нет	выкл	Gemini: добавить саммари
--format	нет	md	Формат: md или txt
--model	нет	gemini-2.5-flash	Gemini: стартовая модель (или env GEMINI_MODEL)
--fallback-models	нет	встроенный пул	Gemini: цепочка fallback через запятую (или env GEMINI_FALLBACK_MODELS)
--no-fallback	нет	выкл	Gemini: только стартовая модель, без перебора
--project NAME	нет	-	local видео: пометить встречу в голосовой базе (провенанс)
--voiceprint-db PATH	нет	voiceprints/db.json скилла	local видео: путь к голосовой базе
--no-voiceprints	нет	выкл	local видео: не использовать и не пополнять голосовую базу
--no-coherent	нет	выкл	local видео: не строить связный лог (быстрее)
--no-summary	нет	выкл	local видео: не строить саммари
--speaker-model M	нет	qwen2.5-32b	local видео: LLM для маппинга спикеров -> имена
--reuse-transcript	нет	выкл	local видео: не гонять whisper заново, если транскрипция уже есть

Поддерживаемые форматы

• Видео: mp4, mkv, webm, avi, mov
• Аудио: mp3, wav, ogg, m4a, flac, aac, wma

Зависимости

Локальный движок:

• venv whisper (отдельный, изоляция CUDA-DLL): путь в env WHISPER_PYTHON; дефолт ~/.claude/skills/transcribe/venv-whisper (faster-whisper, ctranslate2-CUDA, ffmpeg)
• Для --diarize БЕЗ --num-speakers (default): движок pyannote с чекпойнтом pyannote/speaker-diarization-community-1 — корректный автодетект числа спикеров (16.07.26: 8 при истине ~7, RTF 0.064). Нужны torch + pyannote.audio>=4 в whisper-venv, HF_TOKEN в .env (read-токен с принятыми условиями pyannote/speaker-diarization-community-1; для старых чекпойнтов также speaker-diarization-3.1, segmentation-3.0). Отпечатки голоса при этом считает venv-sherpa по готовым turns (diarize_sherpa.py --from-turns) — то же eres2net-пространство, что и голосовая база.
• Для --diarize С --num-speakers N (default): движок sherpa-onnx GPU CUDA, ~/.claude/skills/transcribe/venv-sherpa с GPU-сборкой sherpa_onnx 1.13.0+cuda12.cudnn9 от k2-fsa maintainer (HuggingFace csukuangfj2/sherpa-onnx-wheels). pyannote-segmentation-3.0 + 3D-Speaker eres2net эмбеддинги в ONNX. RTF ~0.24, никаких HF gated моделей. ВНИМАНИЕ: пороговый автодетект sherpa (без N) СЛОМАН — пересегментирует (эксперимент 04.07: пороги 0.5-0.8 давали 21-45 спикеров при истине 4; прогон 16.07: 242 кластера на ~7 человек). Слабое звено — эмбеддер eres2net-zh-cn (EER 5.3 в бенчмарке Шмырева против 1.1-1.6 у топов).
• CUDA GPU обязателен для обоих движков

Gemini движок:

• Python-пакеты: google-genai, python-dotenv
• Системные: ffmpeg, ffprobe в PATH
• API-ключ в ~/.claude/skills/transcribe/.env: GEMINI_API_KEY=...

Установка и настройка (для агента)

НЕ проверяй сервер/venv/модели вручную ПЕРЕД запуском. Скрипты сами читают .env и делают свой префлайт (печатают [0/5] проверка сервера ... + какие модели резолвятся). Просто ЗАПУСТИ нужный скрипт (см. «Инструкция») и читай ЕГО вывод.

Что где (скрипт берет из .env сам, тебе знать не обязательно, руками НЕ проверяй):

• Локальный сервер VLM - из LOCAL_150_BASE в .env (может быть удаленный хост, НЕ обязательно localhost). НЕ проверяй localhost:1234.
• Python для whisper - из WHISPER_PYTHON в .env (может быть внешний venv, НЕ обязательно skill-овый venv-whisper). НЕ проверяй skill-venv.

Ставить/чинить - ТОЛЬКО если скрипт при запуске сам сообщил, что сервер/модель/whisper недоступны:

• установка: python ~/.claude/skills/transcribe/scripts/setup.py (ДОЛГО ~20-30 мин, фоном; флаги --skip-gemini/--skip-sherpa/--with-pyannote/--allow-cpu), проверка verify.py --full;
• для --engine local (видео) нужен запущенный LM Studio (адрес из LOCAL_150_BASE) с моделями (VLM qwen3-vl-30b-a3b-instruct или qwen3-vl-8b, gemma-4-26b, qwen2.5-32b) + Pillow/numpy в python запуска. Пошагово - в README.

.env (~/.claude/skills/transcribe/.env, gitignore, НЕ коммить): GEMINI_API_KEY, HF_TOKEN (если pyannote), WHISPER_PYTHON, LOCAL_150_BASE, LOCAL_VLM_MODEL.

Инструкция

«Локально» / «без облака» = ТОЛЬКО локальный движок (--engine local / analyze_video_local.py). Если пользователь просит локально - НЕ запускай Gemini и НЕ старый analyze_video.py. Локаль-скрипт сам конфигурится из .env (сервер + whisper) - просто запусти его. Если локальный сервер/модели недоступны - ОСТАНОВИСЬ и скажи пользователю; НЕ сваливайся в облако (данные встреч могут быть конфиденциальные).

1. Определи FilePath и флаги. По расширению файла и флагам выбери движок (см. таблицу выше).

2. Если расширение — аудио, и нет --engine gemini, и нет --analyze-ui → запускай локальный:

PYTHONUNBUFFERED=1 PYTHONIOENCODING=utf-8 \
 ~/.claude/skills/transcribe/venv-whisper/Scripts/python.exe \
 ~/.claude/skills/transcribe/scripts/transcribe_local.py \
 "<FilePath>" [--output-dir "<OutputDir>"] [--diarize] [--num-speakers N] [--min-speakers N] [--max-speakers N]

Локальный пайплайн:

• Транскрипция и диаризация запускаются в отдельных subprocess параллельно (изоляция CUDA-DLL ctranslate2 vs torch).
• 27-мин аудио = ~10 мин общего времени (RTF ~0.4).
• Часовое аудио = ~25 мин общего времени.
• Диаризация — только при --diarize. Без неё ~1.5-2 мин на 27-мин файл.

3. Если это ВИДЕО и указан --engine local → запускай ПОЛНОСТЬЮ ЛОКАЛЬНЫЙ разбор экрана (без облака):

PYTHONUNBUFFERED=1 PYTHONIOENCODING=utf-8 python ~/.claude/skills/transcribe/scripts/analyze_video_local.py "<FilePath>" [--output-dir "<OutputDir>"] [--diarize] [--num-speakers N] [--project NAME] [--voiceprint-db PATH] [--no-voiceprints] [--no-coherent] [--no-summary]

Речь - локальный whisper; разбор экрана - qwen3-vl-8b-instruct на локальном сервере LM Studio; связный лог и саммари - google/gemma-4-26b-a4b; маппинг спикеров по репликам - qwen2.5-32b. Кадры обрабатываются параллельно (число слотов выводится из контекста VLM под unified KV cache). Клиентские кадры НЕ уходят в облако. Спикеры распознаются слоями: по ГОЛОСУ (голосовая база, узнает людей между встречами) и по репликам - см. "Спикеры и голосовая база". Предусловия: сервер LM Studio доступен (по умолчанию http://localhost:1234, env LOCAL_150_BASE), модели qwen3-vl-8b-instruct + google/gemma-4-26b-a4b + qwen2.5-32b-instruct загружены (скрипт проверяет и внятно сообщает, если модели нет). Выход: транскрипция / со спикерами / детальный / связный / саммари / voiceprints.json / screenshots/ (ВСЕ scene-кадры). ВНИМАНИЕ: локальное зрение НЕ гарантирует посимвольную точность (в отличие от облака) - финансовые цифры сверять с экраном. Env-переопределения: LOCAL_150_BASE, LOCAL_VLM_MODEL, LOCAL_SUMMARY_MODEL, LOCAL_SPEAKER_MODEL, SCENE_THRESHOLD, FRAME_FLOOR_SEC, FRAME_CAP, WHISPER_PYTHON.

4. Иначе (видео без --engine local, или явный --engine gemini, или --analyze-ui) — запускай Gemini:

PYTHONUNBUFFERED=1 python ~/.claude/skills/transcribe/scripts/transcribe.py "<FilePath>" [--output-dir "<OutputDir>"] [--analyze-ui] [--with-summary] [--format md|txt] [--model MODEL] [--fallback-models "m1,m2"] [--no-fallback]

Скрипт долгий (5-15 мин), файлы >1 ч разбиваются автоматически.

4. Fallback при перегрузке Gemini (503 / 429): скрипт сам перебирает пул моделей (см. "Авто-fallback по моделям Gemini"), доп. действий не требуется. Если весь пул недоступен и это аудио - крайний случай: локальный движок (см. шаг 2).

5. После завершения покажи пользователю пути к файлам и прочитай начало транскрипции / саммари.

ВАЖНО: PYTHONUNBUFFERED=1 обязательно для прогресса.

Спикеры и голосовая база

В локальном разборе видео (--engine local) имена спикеров определяются ДВУМЯ слоями (голос приоритетнее):

1. По голосу (голосовая база). Диаризация считает отпечаток голоса каждого спикера (eres2net-эмбеддинг). Отпечаток сверяется с накопительной базой voiceprints/db.json по косинусной близости - так узнаются даже неназванные люди и ОДИН человек между разными встречами. Это больше, чем делает облако (оно вяжет имена только внутри одной записи).
2. По репликам (текст). LLM (qwen2.5-32b) читает транскрипт и вяжет имена по обращениям ("Иван, что скажешь?"), самопредставлениям, ссылкам. Голос приоритетнее текста.

Авто-пополнение (бутстрап): если человек назван текстом, но в базе его еще нет - его отпечаток заносится в базу, и на будущих встречах он узнается уже по голосу. Неоднозначные имена (одно имя на нескольких спикеров в одной записи) НЕ заносятся.

Провенанс: --project NAME помечает, в каком проекте/встрече встречался человек (полезно при пересечении людей между проектами).

Управление: --no-voiceprints (не трогать базу), --voiceprint-db PATH (своя база), --speaker-model (модель текстового слоя). Голоса - чувствительные данные: база хранится ЛОКАЛЬНО и не коммитится.

Просмотр / ручной enroll базы:

python ~/.claude/skills/transcribe/scripts/voiceprints.py list
python ~/.claude/skills/transcribe/scripts/voiceprints.py match --prints "<имя>.voiceprints.json"

Авто-fallback по моделям Gemini

При 503 (перегрузка серверов Google) или 429 (лимит) скрипт автоматически переходит к следующей модели из пула, пока одна не ответит. Ретрай одной модели делает SDK, смену модели - скрипт.

Дефолтная цепочка (только дешевые модели 2.5): gemini-2.5-flash -> gemini-2.5-flash-lite.

Дорогие модели (gemini-3.5-flash, *-pro, плавающие *-latest) сознательно НЕ в цепочке: плавающий gemini-flash-latest дрейфовал в gemini-3.5-flash и дал 96% счета за июнь 2026 (видео-вход в 5x дороже 2.5-flash). Нужна максимальная надежность любой ценой - добавить их через --fallback-models.

Управление:

• --model MODEL - стартовая модель (или env GEMINI_MODEL).
• --fallback-models "m1,m2,..." - переопределить цепочку (или env GEMINI_FALLBACK_MODELS).
• --no-fallback - только стартовая модель, без перебора.

503 - серверная перегрузка Gemini, она НЕ зависит от тарифа (платный тариф не помогает). Перебор моделей - официально рекомендованный обход. По умолчанию перебор идет только по дешевым 2.5-моделям.

Стоимость

• Локальный движок: бесплатно (только электричество).
• Gemini: flash-класс ~$0.10-0.30 за 1 час записи. По умолчанию перебор только по дешевым 2.5-моделям (дорогие 3.5/pro исключены).

Ограничения

• Локальный АУДИО-движок (whisper) сам по себе не делает анализ интерфейсов. Для локального разбора ЭКРАНА видео есть отдельный путь --engine local (analyze_video_local.py: whisper + локальная VLM на LM Studio + спикеры по голосу) - требует доступный сервер LM Studio и загруженные модели; посимвольная точность зрения не гарантирована.
• Локальный движок требует CUDA GPU.
• Pyannote 4.x (диаризация) — модели gated, нужны принятые условия + HF-токен.
• Кириллические имена файлов: скриптом обрабатываются.
• Точность таймкодов +/- несколько секунд.
• --analyze-ui с аудиофайлом → fallback на Gemini generic + саммари.