Hyperframes

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

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

Источник	Опционально — установка: vibeos 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

к сведению

Ниже приведено полное определение навыка, которое VibeOS загружает при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навык активен.

HyperFrames

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

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

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

• Пользователь запрашивает готовое видео из текста, сценария или веб-сайта
• Анимированные титры, нижние трети или типографические интро
• Озвученное видео с субтитрами (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                     # предпросмотр в браузере с живой перезагрузкой (порт 3002)
npx hyperframes render --output final.mp4   # рендер в MP4
npx hyperframes doctor                      # диагностика проблем окружения

Флаги рендера: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (воспроизводимый) · --strict.

Полная справка по CLI: references/cli.md.

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

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

Скрипт:

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

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

Процедура

1. Планирование перед написанием HTML

Прежде чем касаться кода, сформулируйте на высоком уровне:

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

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

1. DESIGN.md в корне проекта? → Используйте его точные цвета, шрифты, правила движения и ограничения из раздела «Чего НЕ делать».

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

3. Ничего из вышеперечисленного? → Задайте 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 <имя> для выбора, --video clip.mp4 или --audio track.mp3 для начального наполнения медиа.

3. Макет перед анимацией

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

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

Смотрите references/composition.md для полной схемы атрибутов данных и правил композиции.

4. Анимация с GSAP

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

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

Смотрите references/gsap.md для основного API GSAP (твины, easing, stagger, временные шкалы).

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

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

1. Всегда используйте переход между сценами — никаких склеек.
2. Всегда используйте анимацию входа для каждого элемента сцены (gsap.from(...)).
3. Никогда не используйте анимацию выхода, кроме финальной сцены — переход И ЕСТЬ выход.
4. Финальная сцена может затухать.

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

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

• Аудио: всегда отдельный элемент <audio> (видео — muted playsinline).
• TTS: npx hyperframes tts "Текст сценария" --voice af_nova --output narration.wav. Список голосов: --list. Первая буква ID голоса кодирует язык (a/b=английский, e=испанский, f=французский, j=японский, z=мандарин и т.д.) — CLI автоматически определяет локаль фонемизатора; передавайте --lang только для переопределения. Неанглийская фонемизация требует системной установки espeak-ng.
• Субтитры: npx hyperframes transcribe narration.wav → транскрипция на уровне слов. Выберите стиль на основе тона транскрипции (хайп / корпоративный / обучающий / повествовательный / социальный — см. таблицу в references/features.md). Правило языка: никогда не используйте модели .en whisper, если аудио не подтверждено как английское — .en переводит неанглийское аудио вместо транскрибации. Каждая группа субтитров ДОЛЖНА иметь жёсткое завершение tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) после своего выходного твина — иначе группы будут «просвечивать» в последующие.
• Аудиореактивная графика: предварительно извлеките аудиодиапазоны (бас / средние / высокие) и дискретизируйте покадрово внутри временной шкалы с помощью цикла for из tl.call(draw, [], f / fps) — один длинный твин НЕ реагирует на аудио. Сопоставьте бас → scale (пульсация), высокие → textShadow/boxShadow (свечение), общую амплитуду → opacity/y/backgroundColor. Избегайте клише в виде эквалайзера — пусть контент направляет визуал, а аудио управляет его поведением.
• Выделение в стиле маркера: эффекты выделения, обводки, вспышки, зачёркивания, наброска для акцентирования текста являются детерминированными CSS+GSAP — см. references/features.md#marker-highlighting. Полностью доступны для поиска, без анимированных SVG-фильтров.
• Переходы между сценами: каждая многосценовая композиция ОБЯЗАНА использовать переходы (никаких склеек). Выбирайте из CSS-примитивов (толчок/сдвиг, размытое перекрестное затухание, зум через, ступенчатые блоки) или шейдерных переходов (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split и т.д.) через npx hyperframes add. Таблицы настроения и энергии находятся в references/features.md#transitions. Не смешивайте CSS и шейдерные переходы в одной композиции.

7. Линтинг, валидация, инспекция, предпросмотр, рендер

npx hyperframes lint              # выявляет отсутствие data-composition-id, перекрывающиеся дорожки, незарегистрированные временные шкалы
npx hyperframes validate          # аудит контрастности WCAG в 5 временных точках
npx hyperframes inspect           # аудит визуального макета — переполнение, элементы за кадром, скрытый текст
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 — компаньон для макета — запускает страницу в нескольких временных точках и отмечает проблемы, которые не видит статический линтер (субтитр, выходящий за безопасную зону только на 4.5с, карточка, переполняющаяся, когда её заголовок — самый длинный вариант, элемент, оказывающийся за шейдером перехода). Запускайте inspect особенно для композиций с облачками речи, карточками, субтитрами или плотной типографикой.

8. Веб-сайт в видео (если пользователь даёт URL)

Используйте 7-шаговый рабочий процесс захвата в видео из references/website-to-video.md: захват → DESIGN.md → SCRIPT.md → раскадровка → композиция → рендер → доставка.

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

• 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, чтобы текст переносился сам. Исключение: короткие заголовки, где каждое слово намеренно на отдельной строке.
• Анимация visibility или display — GSAP не может их твинить. Используйте autoAlpha (работает и с visibility, и с opacity).
• Вызов video.play() или audio.play() — фреймворк управляет воспроизведением. Никогда не вызывайте их сами.
• Асинхронное построение временных шкал — движок захвата читает window.__timelines синхронно после загрузки страницы. Никогда не оборачивайте построение временной шкалы в async, setTimeout или Promise.
• Автономный index.html, обёрнутый в <template> — скрывает всё содержимое от браузера. Только субкомпозиции, загружаемые через data-composition-src, используют <template>.
• Использование видео для аудио — всегда muted <video> + отдельный <audio>.

Верификация

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

1. Линтинг + валидация + инспекция пройдены: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (линтер выявляет структурные проблемы, валидация — контрастность, инспекция — визуальный макет/переполнение — см. troubleshooting.md, если появляются предупреждения).
2. Хореография анимации — для новых композиций или значительных изменений анимации запустите карту анимации. npx hyperframes init копирует скрипты навыка в проект, поэтому путь локальный для проекта:

   node skills/hyperframes/scripts/animation-map.mjs <директория-композиции> \
     --out <директория-композиции>/.hyperframes/anim-map

   Выводит один animation-map.json с сводками по каждому твину, ASCII-диаграммой Ганта, обнаружением stagger, мёртвыми зонами (>1с без анимации), жизненными циклами элементов и флагами (offscreen, collision, invisible, paced-fast <0.2с, paced-slow >2с). Просмотрите сводки и флаги — исправьте или обоснуйте каждый. Пропускайте при небольших правках.
3. Файл существует + не нулевой: ls -lh final.mp4.
4. Длительность соответствует data-duration: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
5. Визуальная проверка: извлеките кадр из середины композиции: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
6. Аудио присутствует, если ожидается: 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 — атрибуты данных, контракт временной шкалы, необсуждаемые правила, правила типографики/активов
• 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 — 7-шаговый рабочий процесс захвата в видео
• troubleshooting.md — исправление OpenClaw, переменные окружения, распространённые ошибки рендера