ffmpeg-skill от kajisho5: 42 инструмента FFmpeg, которые дают кодинг-агенту локальный видеоредактор

Агент, который «знает FFmpeg», всё равно гадает: он предполагает частоту кадров по имени файла, выбирает кодек, который не помещается в контейнер, перекодирует файл, которому хватило бы копирования потоков, и отчитывается «готово», ни разу не открыв результат. Проект ffmpeg-skill от kajisho5 закрывает именно эту проблему. Это Agent Skill для Claude Code, Cursor, Codex и любого агента, читающего SKILL.md, который выдаёт кодинг-агенту полноценный локальный видеоредактор: 42 инструмента поверх ffmpeg и ffprobe, каждый со структурным интерфейсом, машиночитаемым контрактом и обязательной проверкой результата.

Всё работает локально: без облака, без API-ключей, только стандартная библиотека Python 3.10+ и сам FFmpeg на PATH. Для материалов, которые не хочется никуда загружать, — например, интервью или внутренние записи, — это принципиально. Проект распространяется как npm-пакет ffmpeg-skill, поддерживает FFmpeg версий 6.1–9 и лицензирован под MIT.

Как проект решает проблему «угадывания»

Каждая операция в скилле следует фиксированному рабочему процессу: сначала измерить файл, потом править без потерь, где возможно, затем проверить результат и убедиться в нём визуально.

• Сначала измерение. Любая задача начинается с probe.py: агент принимает решения по измеренным длительности, частоте кадров (с детекцией переменного FPS), разрешению, HDR-формату, включая Dolby Vision, и аудиодорожкам — а не по имени файла.
• Структурные инструменты вместо шелл-строк. Каждая операция — скрипт с типизированными аргументами. Ничего не выполняется через шелл, строка фильтров от вызывающей стороны не принимается вовсе.
• Контракт, который читает агент. Команда contract --json описывает для каждого инструмента вход, выход, нужные компоненты FFmpeg и способ проверки результата.
• Проверка после выполнения. Результат зондуется заново, сверяется со спецификацией целевой платформы, а если менялась картинка — просматривается как контактный лист кадров через look.py.

Ключевая честность проекта: скилл умеет только «руками». look.py лишь рендерит PNG — то, что агент потом осматривает этот лист своей мультимодальной моделью и выбирает точку кропа, остаётся на совести агента, а не кода.

Установка

sudo apt install ffmpeg      # один раз: сам FFmpeg

npx ffmpeg-skill             # установка для Claude Code (--cursor, --codex, --all)

npx ffmpeg-skill doctor      # ffmpeg, ffprobe и все нужные компоненты сборки

npx ffmpeg-skill contract --json   # машиночитаемый контракт для агентных фреймворков

doctor читает списки энкодеров, фильтров и битстрим-фильтров вашей сборки FFmpeg и по каждому инструменту отвечает, запустится ли он на этой машине — и чего именно не хватает, если нет. Отдельно проверяются шрифты для не-латинских алфавитов и даже свежие CVE самой FFmpeg: предупреждение печатается в stderr, но ошибкой не считается.

Опционально подключается локальная транскрибация для субтитров по речи — через faster-whisper, parakeet-mlx или openai-whisper. Аудио при этом никуда не уходит с машины; без движка всё остальное работает как раньше, а --transcribe просто отказывается с готовой строкой для установки.

После установки с агентом говорят обычным языком: «Возьми interview.mp4, оставь 0:45–3:10 и 5:00–6:30 и сделай ровно 60 секунд для Reels». Агент сам прогонит probe.py, cut.py --segments, fit.py --duration 60 --aspect 9:16 --fit crop, export.py --preset reels, check.py --platform reels и look.py, а в отчёте назовёт точную длительность, разрешение и частоту кадров вместе с контактным листом, который он осмотрел.

Что внутри: 42 инструмента

Все инструменты — скрипты на стандартной библиотеке Python с --help, --dry-run, --json и ненулевым кодом выхода с причиной на stderr при отказе. Группы:

Несколько деталей, которые обычно ломают самодельные FFmpeg-скрипты, здесь закрыты явно. cut.py сначала пытается отрезать поток копированием без перекодирования и переходит на перекодирование, только если это необходимо — при кадро-точном монтаже, фильтрах или смене формата. silence.py удаляет мёртвый воздух с запасом вокруг речи и предупреждает, где срез может попасть в дыхание или хвост слова. fit.py при кропе 16:9 → 9:16 по умолчанию берёт центр, но позволяет сместить точку, а решение, что именно оставить в кадре, принимает осматривающий агент. Никакой инструмент не перезаписывает исходник: выход всегда новый файл, и тесты после каждого прогона сверяют хеши входов.

Доставка под платформы из одной команды

Отдельная сильная сторона — шаблоны доставки. Команда:

python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt

заполняет готовый templates/tiktok.json: кроп 9:16, субтитры, всплывающие слово за словом над панелью описания TikTok и в стороне от колонки лайков, −14 LUFS, пресет экспорта tiktok и check.py --platform tiktok по записанному файлу. Шаблоны поставляются для tiktok, reels, shorts, youtube-shorts, youtube, x, linkedin, facebook, podcast и audiogram; а --template all рендерит все видеоплатформы из одного монтажа и пишет сводную таблицу. Безопасные зоны каждого интерфейса учтены заранее — субтитры и графика не попадают под чужие кнопки.

SPEC: контракт, который не может разойтись с кодом

Авторы назвали паттерн, на котором построен слой инструментов, SPEC — Self-Producing Execution Contract. Схема входа каждого инструмента никогда не пишется руками рядом с кодом: она генерируется во время работы из того же argparse-парсера, который и определяет CLI. Добавили флаг в скрипт — обновились input_schema в контракте и определение инструмента в MCP, без второй правки. А если документация или таблица метаданных отстанут от кода, сборку ломает CI-тест, который сверяет их на каждом прогоне.

MCP-сервер, идущий в комплекте, не хранит собственных описаний: tools/list переводится из контракта на старте. По умолчанию он отдаёт только ядро из 12 инструментов, чтобы не тратить контекст клиента на редкие схемы; переменная FFMPEG_SKILL_MCP_FULL=1 открывает все 42. Каждый инструмент доступен по имени через tools/call в любом случае.

Ценность как образец дисциплины

Помимо практической пользы, проект интересен как образец дисциплины проектирования под агентов: план до рендера (--dry-run, --plan с отпечатками входов), один статус в отчёте — Done: или Failed:, без «частично готово», отказ с внятной причиной вместо догадки, проверка сборки до запуска. Тот же подход — проверка после каждой операции, а не слепое доверие генерации — автор оформил в отдельную статью (DOI на Zenodo).

ffmpeg-skill — часть более широкой экосистемы видео-продакшена того же автора: он «руки», которые режут и экспортируют, тогда как выбор точек монтажа и утверждение результата остаются за агентом-«мозгом» (video-production-agent, AI-video-production-OS) или специализированными скиллами (remotion-ffmpeg-skill). Но сам по себе репозиторий самодостаточен: npx ffmpeg-skill — и у вашего агента есть видеоредактор. Подробный разбор демо с командами — в docs/demos.md, справочник по флагам каждого инструмента — в references/scripts.md, а коллекция готовых запросов к агенту — в examples/README.md.