Whisper Skill — локальная транскрибация без OpenAI API

Этот скилл учит Claude правильно ставить и использовать Whisper локально — на ноуте, маке, серваке, без всякого OpenAI API. Поддерживает все ~99 языков (Whisper мультиязычен из коробки), все ОС, и автоматически подбирает оптимальный путь под конкретное железо.

💰 Сколько экономим: OpenAI Whisper API стоит $0.006/мин. Если транскрибируешь 5 часов в день — это $108/мес. Локальная установка — $0 после первой загрузки модели (~3 GB).

Как пользоваться

Шаг 0 — Самый простой путь: интерактивный мастер

Если пользователь не хочет читать документацию — запусти мастер, он спросит что хочешь делать и сам всё поставит:

python wizard.py

Мастер задаёт 3 вопроса (что делать / какая ОС / поставить?) и автоматически:

• определяет железо
• ставит ffmpeg + нужный whisper-бэкенд + модель
• настраивает выбранную фичу (диктовка / сабы / транскрибация / подкасты)
• прогоняет smoke-test

Идеален для не-технарей или быстрого старта.

Шаг 1 — Если хочешь руками: определи железо

python scripts/detect_env.py

Скрипт сам:

• определит ОС (macOS / Linux / Windows / WSL)
• определит CPU (Apple Silicon / x86_64 / ARM)
• найдёт GPU (NVIDIA CUDA / AMD ROCm / Apple Metal / нет)
• посмотрит сколько RAM / VRAM
• подберёт оптимальный бэкенд + модель + выдаст команды установки

Дальше работаешь с тем что он рекомендовал. Не угадывай — всегда запускай детектор первым.

Шаг 2 — поставь рекомендованный бэкенд

Открой соответствующую карточку в backends/ и следуй инструкции. Вкратце:

Шаг 3 — выбери модель под задачу

Whisper моделей много, не запускай large если можно turbo. Открой models/README.md — там таблица «задача → модель → vram → скорость → качество».

Быстрая шпаргалка:

• TikTok/Reels транскрибация (15-60 сек) → large-v3-turbo (8x быстрее, потеря качества <2%)
• Подкасты (1-3 ч) с RU + EN → large-v3
• Long-form, многоязычка с редкими языками → large-v3 (turbo плохо работает с редкими)
• Слабое железо, ноут без GPU → base или small (компромисс)

Шаг 4 — запусти готовый пример

Под типовые сценарии есть рабочие скрипты в examples/:

# === ОСНОВНЫЕ ===
# Один файл → SRT/VTT/TXT
python -m examples.transcribe_one input.mp3

# Папка с видео → пакетная обработка
python -m examples.batch_folder ./videos/

# Из URL (TikTok/YouTube/Reels) → транскрибат через yt-dlp
python -m examples.from_url "https://www.tiktok.com/@user/video/123..."

# Подкаст с двумя дикторами (Speaker A / Speaker B)
python -m examples.podcast_diarize podcast.mp3

# === KILLER FEATURES ===
# 🎤 Push-to-talk диктовка (заменяет Superwhisper / Wispr Flow за $0)
python -m examples.voice_dictation

# 🎬 Вшить сабы в MP4 (CapCut-стиль с подсветкой текущего слова)
python -m examples.bake_subs input.mp4 --style tiktok --output ready.mp4

Все примеры используют общую обвязку examples/common.py: автовыбор устройства, кэш, совместимость со всеми бэкендами.

Killer features подробно

Подробнее:

• docs/voice-dictation.md — push-to-talk диктовка во любое поле
• docs/subtitle-baker.md — стилизованные сабы в видео

Общие правила

Язык — авто-детект, но указывай если знаешь

Whisper умеет автоопределять язык, но это дорого (5-10% времени) и иногда ошибается на коротких клипах. Если знаешь — указывай явно (language="ru"). Это и быстрее, и точнее.

Препроцессинг аудио

• Whisper нативно работает с 16 kHz mono. Если у тебя 48 kHz stereo — он сам ресемплит, но это лишнее время. Лучше прогнать через ffmpeg один раз: ffmpeg -i input.mp4 -ar 16000 -ac 1 output.wav
• Тихие места и пустоты — ставь VAD (Voice Activity Detection) фильтр: vad_filter=True в faster-whisper. Это критически ускоряет на видео с длинными паузами или фоном без речи.
• Музыка / шум — Whisper плохо транскрибирует на фоне громкой музыки. Если поджимает — прогоняй через Demucs или Spleaker для отделения вокала.

Word-level timestamps — для авто-сабов в стиле CapCut

Если делаешь видео с пословными субтитрами (как TikTok/CapCut стиль), нужны точные метки на каждое слово, а не на сегмент. Это умеют:

• whisperx — встроено (по дефолту align_model от wav2vec2)
• faster-whisper — флаг word_timestamps=True
• mlx-whisper — флаг word_timestamps=True
• whisper.cpp — --max-len 1 или JSON-режим

См. docs/word-level-subs.md.

Длинное аудио — chunking

Whisper максимум обрабатывает 30-секундные окна. Все нормальные бэкенды (faster-whisper, whisperx) сами разбивают длинные файлы на чанки и склеивают результат. Не пытайся вручную нарезать.

Качество RU vs EN

• На английском Whisper лучшее что есть. Качество 90-95% как у профессионального стенографиста.
• На русском — large-v3 ставит хорошо (85-90%). turbo хуже на русском чем large-v3 (~3-5% потери). На редких языках (казахский, узбекский, татарский) — только large-v3, остальные модели падают.
• Бенчмарки по языкам — в methodology/quality-vs-speed.md.

Speaker diarization (только если 2+ человек в записи)

Diarization = «кто-что-сказал». Для подкастов / интервью / совещаний.

• Не нужна для одного спикера (подавляющее большинство TikTok/Reels) — пропускай.
• Нужна для подкастов / интервью / Zoom-записей.
• Включается через whisperx (diarize=True) или docs/diarization.md.
• Требует бесплатного Hugging Face токена (для модели pyannote/speaker-diarization-3.1).

Под-документы