it-healer-transcribe — транскрибация видео/аудио локальным ИИ

Скрипт рекурсивно проходит по папке с видео/аудио (или принимает один файл), извлекает аудиодорожку (ffmpeg) и транскрибирует её локально через mlx-whisper (без отправки данных куда-либо наружу). Результат — обычный текст или субтитры с таймкодами (.srt) — на выбор. По умолчанию также определяются говорящие (диаризация) — реплики размечаются как «Спикер 1» / «Спикер 2» и т.д. Проверка на побайтовые дубликаты по умолчанию отключена (включается флагом --dedupe).

Требования

• macOS на Apple Silicon (использует MLX/Metal-ускорение)
• Установленный ffmpeg (brew install ffmpeg)
• Python 3

Установка

Проще всего — из PyPI:

pip install it-healer-transcribe

Появится команда it-healer-transcribe в PATH. Дальше в примерах ниже .venv/bin/python3 transcribe.py можно заменить на it-healer-transcribe.

Установка из исходников (для разработки)

Выполняется в папке со скриптом:

python3 -m venv .venv
.venv/bin/pip install -e .

sherpa-onnx и soundfile (нужны только для определения говорящих — диаризации, включена по умолчанию) ставятся автоматически вместе с пакетом. Если диаризация не нужна, всегда можно запускать с --no-diarize.

Запуск

.venv/bin/python3 transcribe.py <источник> <папка_для_результата>
# или, если пакет установлен из PyPI:
it-healer-transcribe <источник> <папка_для_результата>

• <источник> — либо папка с видео/аудио (обходится рекурсивно, вместе со всеми вложенными подпапками), либо путь к одному файлу.
• <папка_для_результата> — куда складывать аудио и транскрипты. Может ещё не существовать — создастся автоматически.

Пример на папку:

.venv/bin/python3 transcribe.py ~/Movies/RawFootage ~/Movies/Transcribed

Пример на один файл:

.venv/bin/python3 transcribe.py ~/Documents/запись.wav ~/Downloads/Практикум

Структура результата (для папки-источника повторяет её вложенность; для одного файла — просто один файл в audio/ и один в transcripts/):

~/Movies/Transcribed/
  audio/
    trip2024/IMG_0001.wav
    trip2024/IMG_0002.wav
  transcripts/
    trip2024/IMG_0001.txt
    trip2024/IMG_0002.txt

Пример содержимого transcripts/.../IMG_0001.txt (с диаризацией, включена по умолчанию):

Спикер 1: Как вы себя чувствуете сегодня?

Спикер 2: В целом неплохо, но есть напряжение в плечах.

Спикер 1: Давайте с этим поработаем.

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

• видео: .mp4 .mov .mkv .avi .m4v .wmv .flv .webm
• аудио: .wav .mp3 .m4a .aac .flac .ogg

Дополнительные параметры

.venv/bin/python3 transcribe.py <источник> <результат> --language en --model mlx-community/whisper-medium-mlx --format srt --dedupe --speakers 3

• --language — язык речи (по умолчанию ru). Явное указание языка точнее и быстрее автоопределения.
• --model — модель whisper с Hugging Face (по умолчанию mlx-community/whisper-small-mlx). Варианты по возрастанию точности и требований к памяти/времени: whisper-tiny-mlx, whisper-base-mlx, whisper-small-mlx, whisper-medium-mlx, whisper-large-v3-mlx (полное имя репозитория — mlx-community/<название>).
• --format — формат результата: txt (сплошной текст, по умолчанию) или srt (субтитры с таймкодами, совместимые с плеерами и видеоредакторами).
• --dedupe — проверять файлы на побайтовые дубликаты (по умолчанию отключено). Включайте, если в источнике реально могут быть побайтово одинаковые копии — на локальном/быстром диске это почти бесплатно, но на сетевом/внешнем диске хеширование заметно замедляет старт.
• --no-diarize — отключить определение говорящих и вернуть старое поведение: сплошной текст/субтитры без меток «Спикер N». Полезно, если в записи один говорящий, или не установлены sherpa-onnx/soundfile.
• --speakers N — ожидаемое число говорящих (по умолчанию 2, т.к. это самый частый случай — ведущий/терапевт + клиент). Укажите точное число, если оно другое, либо -1 для автоопределения (менее надёжно).

При первом использовании новой модели она скачивается с Hugging Face (нужен интернет один раз, дальше берётся из кеша).

Определение говорящих (диаризация)

Включено по умолчанию. При первом запуске (без --no-diarize) скрипт скачивает две небольшие ONNX-модели проекта sherpa-onnx — сегментацию речи и голосовые эмбеддинги — в ~/.cache/transcribe-diarization/. Это открытый проект без torch и без Hugging Face аккаунта/токена — модели лежат обычными файлами на GitHub Releases.

Как это работает: whisper-сегменты сопоставляются со временными интервалами речи из диаризации (по максимальному перекрытию), и соседние сегменты одного говорящего объединяются в абзац с меткой Спикер N: (для .srt метка [Спикер N] добавляется в начало каждой субтитровой реплики, тайминги не меняются).

Ограничения:

• Метки «Спикер 1» / «Спикер 2» не связаны между разными файлами — это отдельная нумерация в каждом файле, не постоянная идентичность одного и того же человека. Определение конкретного человека по имени/голосу — отдельная, значительно более сложная задача (голосовые профили), в скрипте не реализована.
• Диаризация занимает дополнительное время на файл (иногда сравнимое с самой транскрибацией или больше).
• Если реальное число говорящих отличается от --speakers, качество разделения падает — подбирайте значение под конкретную запись.

Повторный запуск / докидывание новых файлов

Скрипт можно безопасно запускать повторно на той же паре папок:

• уже готовые транскрипты (transcripts/...) не перезаписываются — такие файлы пропускаются;
• если аудио уже извлечено (audio/...), но транскрипт не готов, повторное извлечение аудио пропускается;
• новые/недостающие файлы обрабатываются, остальные не трогаются.

Это удобно, если в исходную папку со временем добавляются новые видео/аудио — достаточно перезапустить ту же команду.

Дубликаты и ошибки

• Проверка на побайтовые дубликаты по умолчанию отключена — обрабатываются все файлы. Включается флагом --dedupe: тогда, если несколько файлов в разных подпапках побайтово идентичны, обрабатывается только один, остальные логируются как пропущенные дубликаты.
• Пустые/битые файлы (например, 0 байт) не считаются дубликатами «на глазок» — они честно пытаются обработаться и логируются как ошибка, если ffmpeg не может их прочитать. Обработка остальных файлов при этом продолжается.
• В конце работы выводится итог: сколько обработано, сколько дублей пропущено, сколько ошибок (с расшифровкой).

Запуск в фоне на много часов

Для больших папок (десятки/сотни гигабайт видео) обработка может занимать много часов. Запускайте через nohup, чтобы процесс продолжался и после закрытия терминала:

nohup .venv/bin/python3 transcribe.py <источник> <результат> > <результат>/transcribe.log 2>&1 &

Прогресс — по количеству файлов в <результат>/transcripts/ и по логу (tail -f <результат>/transcribe.log): лог пишется построчно в реальном времени, с отдельными отметками по этапам каждого файла (извлечение аудио, транскрибация, определение говорящих).

Лицензия

MIT — см. файл LICENSE.

Автор

IT Healer — it-healer.com · Telegram: @biodynamist