Hyperframes

Создавайте видеокомпозиции на HTML, анимированные титры, оверлеи для соцсетей, talking-head-ролики с субтитрами, аудиореактивные визуализации и шейдерные переходы с помощью HyperFrames. HTML — источник истины для видео. Используйте этот навык, когда пользователь хочет получить готовый MP4/WebM из HTML-композиции, анимировать текст, логотипы или графику поверх медиа, синхронизировать субтитры с аудио, добавить TTS-озвучку или превратить сайт в видео.

Метаданные навыка


Источник	Опциональный — установка командой `hermes skills install official/creative/hyperframes`
Путь	`optional-skills/creative/hyperframes`
Версия	`1.0.0`
Автор	heygen-com
Лицензия	Apache-2.0
Платформы	linux, macos, windows
Теги	`creative`, `video`, `animation`, `html`, `gsap`, `motion-graphics`
Связанные навыки	`manim-video`, `meme-generation`

Справочник: полный SKILL.md

инфо

Ниже — полное определение навыка, которое Hermes загружает при его срабатывании. Именно это агент видит как инструкции, пока навык активен.

HyperFrames

HTML — источник истины для видео. Композиция — это HTML-файл с атрибутами data-* для тайминга, GSAP-таймлайном для анимации и CSS для оформления. Движок HyperFrames снимает страницу кадр за кадром и кодирует в MP4/WebM через FFmpeg.

Дополнение к manim-video: для математических и геометрических роликов (уравнения, стиль 3B1B) берите manim-video. Для моушн-графики, talking-head с субтитрами, обзоров продукта, оверлеев для соцсетей, шейдерных переходов и всего, что строится на реальном видео или аудио, берите hyperframes.

Когда использовать

Пользователь просит готовое видео из текста, сценария или сайта
Анимированные титры, нижние плашки (lower thirds) или типографические интро
Видео с озвучкой и субтитрами (TTS + субтитры в синхрон с волновой формой)
Аудиореактивные визуализации (синхрон с битом, спектральные полосы, пульсирующее свечение)
Переходы между сценами (кроссфейд, вайп, шейдерное искажение, вспышка через белое)
Оверлеи для соцсетей (в стиле Instagram/TikTok/YouTube)
Конвейер «сайт → видео» (захват URL, выпуск промо-ролика)
Любая HTML/CSS/JS-анимация, которую нужно детерминированно отрендерить в видеофайл

Не применяйте этот навык для:

Чисто математической анимации и анимации уравнений (→ manim-video)
Генерации изображений или мемов (→ meme-generation, модели изображений)
Живых видеоконференций или стриминга

Краткий справочник

npx hyperframes init my-video               # создать проект
cd my-video
npx hyperframes lint                        # проверить перед предпросмотром/рендером
npx hyperframes preview                     # предпросмотр с live-reload (порт 3002)
npx hyperframes render --output final.mp4   # рендер в MP4
npx hyperframes doctor                      # диагностика окружения

Полный справочник по CLI: references/cli.md.

Настройка (однократно)

bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

Скрипт:

Проверяет, установлены ли Node.js >= 22 и FFmpeg (если нет — выводит инструкции по устранению).
Ставит CLI hyperframes глобально (npm install -g hyperframes@>=0.4.2).
Заранее кэширует chrome-headless-shell через Puppeteer — обязательно для рендера наивысшего качества через путь захвата HeadlessExperimental.beginFrame в Chrome.
Запускает npx hyperframes doctor и сообщает результат.

Если настройка не удалась, смотрите references/troubleshooting.md.

Процедура

1. Спланируйте до написания HTML

Прежде чем трогать код, сформулируйте в общих чертах:

Что — сюжетная дуга, ключевые моменты, эмоциональные акценты
Структура — композиции, дорожки (видео/аудио/оверлеи), длительности
Визуальная идентичность — цвета, шрифты, характер движения (взрывной / кинематографичный / текучий / технический)
Hero-кадр — для каждой сцены момент, когда одновременно видно больше всего элементов. Это статичная раскладка, которую собирают первой.

Шлюз визуальной идентичности (ЖЁСТКИЙ БАРЬЕР). Прежде чем писать ХОТЬ КАКОЙ-ТО HTML композиции, визуальная идентичность должна быть определена. НЕ пишите композиции с дефолтными или универсальными цветами (#333, #3b82f6, Roboto выдают, что шаг пропущен). Проверяйте по порядку:

Есть DESIGN.md в корне проекта? → Используйте его точные цвета, шрифты, правила движения и ограничения «What NOT to Do».
Пользователь назвал стиль (например, «Swiss Pulse», «тёмный и техничный», «люксовый бренд»)? → Сгенерируйте минимальный DESIGN.md с разделами ## Style Prompt, ## Colors (3–5 hex с ролями), ## Typography (1–2 семейства), ## What NOT to Do (3–5 антипаттернов).
Ничего из перечисленного? → Задайте 3 вопроса, прежде чем писать какой-либо HTML:
- Настроение? (взрывное / кинематографичное / текучее / техничное / хаотичное / тёплое)
- Светлый холст или тёмный?
- Есть фирменные цвета, шрифты или визуальные референсы?
Затем сгенерируйте DESIGN.md из ответов. Каждая композиция должна возводить свою палитру и типографику к DESIGN.md или явному указанию пользователя.

2. Создание проекта

npx hyperframes init my-video --non-interactive

Шаблоны: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Передайте --example <name>, чтобы выбрать один из них, и --video clip.mp4 или --audio track.mp3, чтобы засеять проект медиа.

3. Сначала раскладка, потом анимация

Напишите статичный HTML+CSS для hero-кадра первым делом — пока без GSAP. Контейнер .scene-content должен заполнять сцену (width:100%; height:100%; padding:Npx) с display:flex + gap. Сдвигайте содержимое внутрь через padding — никогда не ставьте position: absolute; top: Npx на контейнере содержимого (контент вылезет, если он выше оставшегося места).

Только когда hero-кадр выглядит правильно, добавляйте входы через gsap.from() (анимация к CSS-позиции) и выходы через gsap.to() (анимация от неё).

Полную схему data-атрибутов и правила композиции смотрите в references/composition.md.

4. Анимируйте через GSAP

Каждая композиция должна:

Регистрировать свой таймлайн: window.__timelines["<composition-id>"] = tl
Стартовать на паузе: gsap.timeline({ paused: true }) — воспроизведением управляет плеер
Использовать конечные значения repeat (никаких repeat: -1 — ломает движок захвата). Считайте: repeat: Math.ceil(duration / cycleDuration) - 1.
Быть детерминированной — никаких Math.random(), Date.now() или логики на системных часах. Если нужна псевдослучайность, берите PRNG с зерном.
Строиться синхронно — никаких async/await, setTimeout или промисов вокруг построения таймлайна.

Основной API GSAP (твины, easing, stagger, таймлайны) смотрите в references/gsap.md.

5. Переходы между сценами

Многосценовым композициям нужны переходы. Правила:

Всегда ставьте переход между сценами — никаких склеек встык.
Всегда используйте входные анимации на каждом элементе сцены (gsap.from(...)).
Никогда не используйте выходные анимации, кроме финальной сцены — переход и есть выход.
Финальная сцена может уйти в затемнение.

Чтобы установить шейдерные переходы (flash-through-white, liquid-wipe и т. д.), используйте npx hyperframes add <transition-name>. Полный список: npx hyperframes add --list.

6. Аудио, субтитры, TTS, аудиореактивность, подсветка

Аудио: всегда отдельный элемент <audio> (видео идёт как muted playsinline).
TTS: npx hyperframes tts "Script text" --voice af_nova --output narration.wav. Список голосов — через --list. Первая буква ID голоса кодирует язык (a/b=английский, e=испанский, f=французский, j=японский, z=мандаринский и т. д.) — CLI сам определяет локаль фонемизатора; передавайте --lang только для переопределения. Для неанглийской фонемизации нужен системно установленный espeak-ng.
Субтитры: npx hyperframes transcribe narration.wav → транскрипт на уровне слов. Стиль выбирайте по тону транскрипта (hype / corporate / tutorial / storytelling / social — см. таблицу в references/features.md). Правило языка: не используйте whisper-модели .en, пока не подтвердили, что аудио на английском, — .en неанглийское аудио переводит, а не транскрибирует. У каждой группы субтитров обязательно должен стоять жёсткий гасящий вызов tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) после её выходного твина, иначе группы протекут видимыми в следующие.
Аудиореактивные визуализации: заранее извлеките аудиополосы (бас / середина / верх) и сэмплируйте их покадрово внутри таймлайна циклом for из tl.call(draw, [], f / fps) — один длинный твин на аудио не реагирует. Маппинг: бас → scale (пульс), верх → textShadow/boxShadow (свечение), общая амплитуда → opacity/y/backgroundColor. Клише с полосами эквалайзера лучше обходить стороной — визуал ведёт содержимое, аудио задаёт его поведение.
Подсветка в стиле маркера: эффекты highlight, circle, burst, scribble, sketchout для акцента на тексте реализованы детерминированно на CSS+GSAP — см. references/features.md#marker-highlighting. Полностью перематываемы, без анимированных SVG-фильтров.
Переходы между сценами: в каждой многосценовой композиции переходы обязательны (никаких склеек встык). Выбирайте из CSS-примитивов (push slide, blur crossfade, zoom through, staggered blocks) или шейдерных переходов (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split и т. д.) через npx hyperframes add. Таблицы настроения и энергии лежат в references/features.md#transitions. Смешивать CSS- и шейдерные переходы в одной композиции нельзя.

7. Lint, проверка, инспекция, превью, рендер

npx hyperframes lint              # проверяет отсутствующие data-composition-id, пересечения дорожек, незарегистрированные таймлайны
npx hyperframes validate          # аудит контрастности WCAG в 5 временных точках
npx hyperframes inspect           # визуальный аудит раскладки — overflow, элементы вне кадра, перекрытый текст
npx hyperframes preview           # предпросмотр в браузере
npx hyperframes render --quality draft --output draft.mp4    # быстрая итерация
npx hyperframes render --quality high --output final.mp4     # финальный рендер

hyperframes validate сэмплирует пиксели фона за каждым текстовым элементом и предупреждает о контрастности ниже 4.5:1 (или 3:1 для крупного текста). hyperframes inspect — его напарник со стороны раскладки: гоняет страницу на нескольких отметках времени и ловит то, что статический lint не видит (субтитр, переносящийся за безопасную зону только на 4.5 с; карточка, вылезающая, когда её заголовок оказывается самым длинным вариантом; элемент, оказавшийся за шейдером перехода). Запускайте inspect особенно на композициях с речевыми облачками, карточками, субтитрами или плотной типографикой.

8. Сайт в видео (если пользователь дал URL)

Используйте семишаговый процесс «захват → видео» из references/website-to-video.md: capture → DESIGN.md → SCRIPT.md → storyboard → composition → render → deliver.

Подводные камни

HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ убрал этот протокол. Убедитесь, что у вас hyperframes@>=0.4.2 (он сам это обнаруживает и откатывается в режим скриншотов). Аварийный выход: export PRODUCER_FORCE_SCREENSHOT=true. См. hyperframes#294 и references/troubleshooting.md.
Системный Chrome (а не chrome-headless-shell) — рендер виснет на 120 с и падает по таймауту. Запустите npx puppeteer browsers install chrome-headless-shell (setup.sh делает это сам). hyperframes doctor сообщает, какой бинарник будет использован.
repeat: -1 где угодно — ломает движок захвата. Всегда вычисляйте конечное число повторов.
gsap.set() на элементах клипа, которые появляются позже — элемента нет на момент загрузки страницы. Используйте tl.set(selector, vars, timePosition) внутри таймлайна, на отметке data-start клипа или после неё.
<br> внутри текста содержимого — принудительные переносы не знают отрисованной ширины шрифта, поэтому естественный перенос + <br> дают двойной разрыв. Дайте тексту переноситься через max-width. Исключение: короткие display-заголовки, где каждое слово намеренно на своей строке.
Анимация visibility или display — GSAP не умеет твинить эти свойства. Используйте autoAlpha (он закрывает и visibility, и opacity).
Вызов video.play() или audio.play() — воспроизведением владеет фреймворк. Вызывать их самостоятельно нельзя.
Асинхронное построение таймлайнов — движок захвата читает window.__timelines синхронно после загрузки страницы. Никогда не оборачивайте построение таймлайна в async, setTimeout или промис.
Отдельный index.html, обёрнутый в <template> — прячет всё содержимое от браузера. <template> используют только под-композиции, загружаемые через data-composition-src.
Использование видео ради аудио — всегда <video> с muted + отдельный <audio>.

Проверка

До и после рендера:

Проходят lint + validate + inspect: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint ловит структурные проблемы, validate — контраст, inspect — проблемы визуальной раскладки и переполнения; если появились предупреждения, см. troubleshooting.md).
Хореография анимации — для новых композиций или существенных изменений анимации прогоните карту анимации. npx hyperframes init копирует скрипты навыка в проект, поэтому путь локален для проекта:
```
node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map
```
На выходе один animation-map.json со сводками по каждому твину, ASCII Gantt-диаграммой таймлайна, обнаружением stagger, мёртвыми зонами (>1 с без анимации), жизненными циклами элементов и флагами (offscreen, collision, invisible, paced-fast <0.2 с, paced-slow >2 с). Просмотрите сводки и флаги — каждый либо исправьте, либо обоснуйте. На мелких правках пропускайте.
Файл существует и не нулевой: ls -lh final.mp4.
Длительность совпадает с data-duration: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
Визуальная проверка: извлеките кадр из середины композиции: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
Аудио на месте, если ожидается: ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.

Если hyperframes render падает, запустите npx hyperframes doctor и приложите его вывод к отчёту о проблеме.

Справочные материалы

composition.md — data-атрибуты, контракт таймлайна, непреложные правила, правила типографики и ассетов
cli.md — каждая команда CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
gsap.md — основной API GSAP для HyperFrames (твины, easing, stagger, таймлайны, matchMedia)
features.md — субтитры, TTS, аудиореактивность, маркерная подсветка, переходы (загружается по запросу)
website-to-video.md — семишаговый процесс «захват → видео»
troubleshooting.md — фикс OpenClaw, переменные окружения, частые ошибки рендера