whisper-skill

name

whisper-skill

description

Используй этот скилл когда пользователю нужна локальная транскрибация аудио/видео через Whisper, голосовой ввод (диктовка вместо клавиатуры, push-to-talk hotkey), или вшивание субтитров в MP4 в стиле CapCut. Активируй при задачах "транскрибируй файл/папку/TikTok/YouTube/подкаст", "сабы для shorts/reels/тиктока", "speech-to-text локально", "speaker diarization", "диктовка голосом", "Superwhisper alternative", "Wispr Flow alternative", "voice dictation". Скилл автоматически определяет ОС/CPU/GPU и подбирает оптимальный бэкенд (faster-whisper / whisper.cpp / whisperx / mlx-whisper / openvino) и модель под железо пользователя. Для Intel Core Ultra / Intel Arc — openvino задействует iGPU+NPU. Включает interactive wizard (wizard.py) который ставит всё одной командой. Все языки, бесплатно после установки, никаких API.

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/ и следуй инструкции. Вкратце:

Железо	Рекомендованный бэкенд	Карточка
Mac M1/M2/M3/M4	mlx-whisper (нативный Metal)	backends/mlx-whisper.md
Linux + NVIDIA GPU	faster-whisper (CUDA)	backends/faster-whisper.md
Windows + NVIDIA GPU	faster-whisper через WSL2	backends/faster-whisper.md
Intel Core Ultra (Meteor Lake+) / Intel Arc	openvino (нативный iGPU + NPU)	backends/openvino.md
Любая ОС, нет GPU, не Mac, не Intel Ultra	whisper.cpp (CPU-оптимизированный)	backends/whisper-cpp.md
Нужны спикеры (diarization)	whisperx (faster-whisper + pyannote)	backends/whisperx.md

Шаг 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 подробно

Feature	Команда	Что заменяет	Сколько экономит
Voice Dictation	python -m examples.voice_dictation	Superwhisper, Wispr Flow, Aqua Voice	$8-12/мес
Subtitle Baker	python -m examples.bake_subs	CapCut Pro, Adobe Premiere	$10-50/мес
Interactive Wizard	python wizard.py	—	прости́т 30 минут гугления

Подробнее:

• 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).

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

Файл	Когда читать
wizard.py	Самый простой старт — интерактивный мастер настройки
scripts/detect_env.py	Авто-определение железа + рекомендации
backends/faster-whisper.md	Linux/Windows + (GPU или нет)
backends/whisper-cpp.md	Без Python / минимум зависимостей
backends/whisperx.md	Нужна diarization или word-timestamps
backends/mlx-whisper.md	Mac M1+
backends/openvino.md	Intel Core Ultra / Intel Arc — задействует iGPU + NPU
models/README.md	Выбор модели под задачу
docs/installation-mac.md	Установка под Mac
docs/installation-linux.md	Установка под Linux
docs/installation-windows.md	Установка под Windows
docs/voice-dictation.md	🎤 Push-to-talk диктовка во любое поле
docs/subtitle-baker.md	🎬 Сабы прямо в MP4 (CapCut-style)
docs/diarization.md	Разметка спикеров
docs/speed-tuning.md	Ускорить инференс
docs/cost-comparison.md	«А зачем мне локально если есть API?»
docs/known-issues.md	Грабли
methodology/quality-vs-speed.md	Бенчмарки и tradeoff'ы

Типичные ошибки и как их чинить

RuntimeError: CUDA out of memory

Модель слишком большая для VRAM. Варианты:

1. Перейти на меньшую модель (large-v3 → medium или large-v3-turbo)
2. Уменьшить batch_size (с 16 до 8 или 4)
3. Использовать compute_type="int8_float16" (4x экономия VRAM, минус 1-2% качества)

Detected language: en для русского текста

Whisper иногда «слышит» русский как английский на коротких клипах. Решение:

1. Указывать язык явно: model.transcribe(audio, language="ru")
2. Или: брать модель large-v3 (она лучше определяет язык чем turbo)

Плохое качество на TikTok/Reels с громкой музыкой

Whisper не выделяет голос из музыки. Перед транскрибацией прогоняй через Demucs:

demucs --two-stems=vocals input.mp3
# → выходит no_vocals.wav и vocals.wav, дальше только vocals.wav в Whisper

Странные галлюцинации в тишине ("Спасибо за просмотр", "Подписывайтесь")

Whisper в тишине придумывает текст из тренировочных данных. Решение — VAD-фильтр (Voice Activity Detection):

• В faster-whisper: vad_filter=True
• В whisperx: встроено
• В whisper.cpp: --vad

Текст без точек и заглавных букв

large-v3 обычно ставит пунктуацию хорошо. Если нет:

• Попробуй condition_on_previous_text=True
• Или прогоняй после-обработку через methodology/post-processing.md (punctuator-модели или LLM для расстановки)

Установка падает с Pytorch not found / cuda mismatch

Самая частая боль на Linux/Windows. Решение пошагово в docs/installation-linux.md или docs/installation-windows.md. Главное — не ставь PyTorch и CUDA отдельно — пусть менеджер пакетов сделает это сам через правильную команду.

pip install whisper ставит не то

pip install whisper ставит другой пакет (старый репозиторий). Правильно:

• Faster-whisper: pip install faster-whisper
• Original OpenAI: pip install openai-whisper (но faster-whisper в 4-12x быстрее, original не нужен)
• whisperx: pip install whisperx
• mlx-whisper: pip install mlx-whisper

После транскрибации — что дальше?

Whisper отдаёт текст. Дальше типовые next steps:

1. Переписать текст / суммаризовать — отдельная задача (LLM поверх транскрибата).
2. Сабы в видео — через ffmpeg + SRT-файл из Whisper. См. examples/burn_subs.py (если делал).
3. Сохранить в БД / Notion / Sheets — стандартный pipeline, в examples/ есть шаблоны.
4. Перевод на другой язык — Whisper умеет переводить только в английский (флаг task="translate"). Для перевода RU → DE — отдельный шаг через LLM или DeepL.

Что вне скоупа

• TTS / Voice cloning — это другая история (ElevenLabs, Coqui XTTS) — отдельный скилл если будет
• Дообучение Whisper на свой домен — теоретически возможно, но 99% задач решает выбор правильной модели
• Перевод на любой язык — Whisper умеет только → EN. Для остального LLM/DeepL
• Lip-sync / dubbing — отдельная тема (Sync.so, Wav2Lip)