hyperframes-cliCLI для HyperFrames видео

heygen-com/hyperframes

Полный dev-цикл для HyperFrames: init с 9 стартовыми шаблонами, lint для ошибок композиций, inspect и финальный рендер видеопроектов.

HyperFrames CLI HeyGen видео разработка шаблоны рендер

Установка

npx -y skills add heygen-com/hyperframes --skill hyperframes-cli --agent claude-code

HyperFrames CLI

Всё запускается через npx hyperframes, если инструкции проекта не указывают локальный wrapper. Требуется Node.js >= 22 и FFmpeg.

Рабочий процесс

Скаффолдинг — npx hyperframes init my-video (или capture по URL). init также проверяет установленные скиллы относительно последних на GitHub и обновляет их при необходимости.
Написание — создать HTML-композицию (см. скилл hyperframes-core)
Lint — npx hyperframes lint
Validate — npx hyperframes validate (ошибки рантайма + контраст)
Визуальная инспекция — npx hyperframes inspect
Preview — npx hyperframes preview открывает Studio — редактор таймлайна, где пользователь может редактировать что угодно. Просмотрите там, затем спросите перед рендерингом.
Render — выберите вариант:
- Итерация: npx hyperframes render --quality draft
- Финальный: npx hyperframes render --quality high --output out.mp4
- CI: npx hyperframes render --docker --strict --output out.mp4
- Облако (долгие/большие): npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait

Запускайте lint, validate и inspect до preview. lint находит отсутствующие data-composition-id, пересекающиеся треки и незарегистрированные таймлайны. validate загружает композицию в headless Chrome и сообщает об ошибках рантайма и проблемах контраста WCAG. inspect перемещается по таймлайну и сообщает о тексте, вышедшем за пределы контейнеров или холста.

Соглашения агента

--json доступен для всех команд кроме render, preview и play. Используйте для агентных/CI-вызовов.
doctor --json всегда завершается с кодом 0, даже при сломанной среде. Проверяйте поле ok: npx hyperframes doctor --json | jq -e '.ok' > /dev/null
Нон-TTY режим определяется автоматически. В CI/агентах/pipe CLI переключается в неинтерактивный режим; init тогда требует --example. Принудительно: --non-interactive.
CI-гейты при рендеринге: --strict завершается при lint-ошибках, --strict-all — и при предупреждениях, --strict-variables — при незадекларированных ключах --variables.
Рендер под контролем пользователя. Никогда не запускайте рендер автоматически после прохождения проверок. Остановитесь на preview, сообщите что видео редактируется в Studio, и рендерите только после одобрения.
Проверка после рендера: после завершения render с кодом 0 убедитесь, что файл существует: [ -s "$OUTPUT" ] || echo "render produced no output"

Таблица маршрутизации

Задача	Справочник
Скаффолдинг (`init`, `capture`, `skills`)	`references/init-and-scaffold.md`
Проверка корректности (`lint`, `validate`, `inspect`, `snapshot`)	`references/lint-validate-inspect.md`
Preview и рендер (`preview`, `play`, `render`, `publish`)	`references/preview-render.md`
Диагностика среды (`doctor`, `browser`)	`references/doctor-browser.md`
Облачный рендер на AWS Lambda	`references/lambda.md`
Прочее (`info`, `upgrade`, `compositions`, `docs`, препроцессинг ассетов)	`references/upgrade-info-misc.md`

Передача между скиллами

Tailwind-проекты (init --tailwind) → используйте hyperframes-core перед редактированием классов или токенов темы.
Registry-блоки/компоненты (hyperframes add, hyperframes catalog) → используйте hyperframes-registry.
Препроцессинг ассетов (tts, transcribe, remove-background) → используйте hyperframes-media.
Параметризованные рендеры (--variables) → задекларируйте через data-composition-variables на <html>; см. hyperframes-core.

Lambda (облачный рендер)

hyperframes lambda развёртывает распределённый рендеринг на AWS Lambda. Три команды от начала до конца:

npx hyperframes lambda deploy                                             # Развернуть SAM-стек
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # Удалить стек (S3-бакет сохраняется)

Используйте Lambda когда рендер слишком долгий/большой для одной машины (многоминутные видео, 4K, большие параллельные пакеты) и настроены AWS-учётные данные.

Минимальные гейты завершения

Статические гейты

npx hyperframes lint
npx hyperframes validate

Добавьте inspect для работы, чувствительной к layout, и render --strict в CI.

Визуальный smoke-тест — обязателен при суб-композициях

lint / validate / inspect оценивают каждую композицию изолированно. Они никогда не загружают index.html и не монтируют суб-композиции, поэтому не могут поймать ошибки кросс-файлового монтирования. Единственный гейт — тот, который фактически загружает index.html.

Используйте hyperframes snapshot:

# Захватить кадр в середине каждой суб-композиции
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Или равномерное распределение
npx hyperframes snapshot --frames 9

Результат сохраняется в snapshots/frame-NN-at-Xs.png. Проверяйте каждый кадр визуально.

Красные флаги на кадрах

Что видно	Причина
Текст мелкий и без стилей в левом верхнем углу	Блок `<style>` в `<head>` вне `<template>` — CSS не достиг live DOM
SVG/иконки раздуты до размера холста	Та же причина — нет ограничений width/height
Основной элемент сцены отсутствует; только фон и watermark	Host-id ≠ template id — таймлайн не запустился
Команда snapshot выводит «Sub-composition timelines not registered after 45000ms»	Прямое подтверждение ошибки host/template