API ВЕГА

Обзор

Миграция видео-композиций Remotion, основанных на React, в HTML-формат HyperFrames с проверенной точностью кадров.

  • Переводит идиомы Remotion (Sequence, interpolate, spring, Audio, Video, Lottie, шрифты) в таймлайны GSAP HyperFrames через механическое маппинг API; ~80% типичных композиций переводятся без проблем.

  • Обнаруживает непереводимые паттерны (useState, побочные эффекты useEffect, асинхронный calculateMetadata, сторонние библиотеки React) и рекомендует использовать механизм интероперабельности среды выполнения вместо убыточного перевода.

  • Включает поэтапный тестовый набор (T1–T4) с порогами проверки SSIM для измерения точности перевода; отказывается выдавать результат без запуска инструмента оценки.

  • Выдаёт плоский HTML с встроенным таймлайном GSAP, раскладкой на CSS и data-* атрибутами на каждый экземпляр для пользовательских подкомпонентов; фиксирует любые пробелы в TRANSLATION_NOTES.md.

Сначала обновите этот skill — подтвердите у пользователя перед запуском: npx hyperframes skills update remotion-to-hyperframes. Если всё актуально — быстрый no-op; иначе он обновит этот skill и базовые доменные skills, от которых он зависит, прежде чем вы на них положитесь.

Remotion в HyperFrames

Основная точка входа — /hyperframes. Используйте этот skill только для того, чтобы перенести существующую композицию Remotion (React) в HyperFrames, в одном направлении. Создание новой композиции, воспроизведение на основе не-Remotion источника (After Effects, Framer Motion, чистый React / CSS — исходного Remotion кода для перевода нет), поверхностное упоминание Remotion или любые сомнения → сначала прочитайте /hyperframes: слой интентов владеет каждым решением о маршруте.

Обзор

Переводите видео-композиции Remotion (основанные на React) в композиции HyperFrames (HTML + GSAP). Большинство идиом Remotion имеют прямые эквиваленты в HyperFrames — для ~80% типичных композиций перевод выполняется механически. Этот skill кодирует маппинг и защищает от убыточных 20%, отказываясь переводить паттерны, которые не вписываются в модель навигации по кадрам HF, и рекомендуя вместо этого паттерн интероперабельности среды выполнения из PR #214.

Skill поставляется с поэтапным тестовым набором (T1–T4, всего 4 фикстуры), который оценивает переводы по измеренным порогам SSIM. Не переводите без запуска оценки — перевод, который «выглядит правильно», но рендерится на 0.05 SSIM ниже валидированного эталона, молча неверен.

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

Используйте этот skill ТОЛЬКО когда пользователь явно просит мигрировать с Remotion. Примеры триггерных фраз:

  • «перенеси мой Remotion-проект в HyperFrames»

  • «конвертируй этот Remotion-код в HyperFrames»

  • «мигрируй с Remotion»

  • «переведи эту Remotion-композицию»

  • «перепиши это как HyperFrames HTML»

НЕ используйте этот skill, когда:

  • (a) Пользователь создаёт новую композицию HyperFrames, даже если у него есть или он A/B-тестирует похожее видео на Remotion.

  • (b) Пользователь упоминает Remotion попутно, не прося о миграции.

  • (c) Пользователь делится кодом Remotion в качестве справочного материала, а не просит о переводе.

  • (d) Пользователь просит «такое же видео, как на моём Remotion», не прося явно о миграции исходного кода — рассматривайте это как новую сборку HyperFrames.

НЕ ПОДДЕРЖИВАЕТСЯ (откажите — это не то, что делает этот skill):

  • Обратное направление. Экспорт композиции HyperFrames в Remotion (или в любой другой фреймворк) — это не рабочий процесс; перевод выполняется только в направлении Remotion → HyperFrames. Скажите это прямо.

  • Не-Remotion источники. Проект After Effects (.aep), анимация Framer Motion / чистый React / CSS или исходный код любого другого инструмента — это не композиция Remotion; исходного Remotion кода для перевода нет. Воспроизведите его нативно через /general-video или откажитесь, если HyperFrames не может его представить.

При сомнениях по умолчанию создавайте нативную композицию HyperFrames через /general-video (общий процесс создания HyperFrames).

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

Шаг 1: Анализ исходного кода

Запустите scripts/lint_source.py на директории с исходным кодом Remotion. Анализ обнаруживает паттерны, которые нельзя перевести без проблем:

  • Блокеры (отказ + рекомендация интероперабельности): useState, useReducer, useEffect/useLayoutEffect с непустыми зависимостями, асинхронный calculateMetadata, сторонние UI-библиотеки React (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).

  • Предупреждения (перевод после удаления конструкции): конфигурация @remotion/lambda, delayRender, useCallback, useMemo, пользовательские хуки.

  • Информация (перевод с примечанием): staticFile, interpolateColors.

Если сработал хотя бы один блокер, остановитесь. Прочитайте references/escape-hatch.md и выведите рекомендацию. Предупреждения не останавливают перевод — удалите проблемную конструкцию на шаге 3 и зафиксируйте пробел в TRANSLATION_NOTES.md. Конфигурация @remotion/lambda — канонический случай предупреждения: skill удаляет импорт + вызовы renderMediaOnLambda(...), но переводит остальную часть композиции.

Шаг 2: Планирование перевода

Прочитайте references/api-map.md — индекс каждого API Remotion и его эквивалент HF или ссылку на тему. Определите, какие тематические ссылки вам понадобятся, на основе того, что использует исходный код:

Исходный код содержитЗагрузить справку
Composition, defaultProps, schema, calculateMetadataparameters.md
Sequence, Series, Loop, AbsoluteFill, Freezesequencing.md
useCurrentFrame, interpolate, spring, Easing, interpolateColorstiming.md
Audio, Video, Img, IFrame, staticFile, delayRendermedia.md
TransitionSeries, @remotion/transitionstransitions.md
@remotion/lottielottie.md
@remotion/google-fonts/<Family>, Font.loadFont, @font-facefonts.md

Не загружайте все — загружайте только то, что нужно для конкретного исходного кода.

Поищите в актуальном каталоге любой визуальный эффект, которого нет в таблице. Когда исходный код создаёт внешний вид без эквивалента HF API — оверлей сканлайнов/CNT-растр, глитч-эффект или хроматическая аберрация, шейдерный переход, зернистость плёнки — выполните npx hyperframes catalog --query "<the effect, in plain English>" --json перед тем, как вручную писать его на GSAP. Поиску ничего не нужно устанавливать: ни проекта, ни предварительного add, ни аккаунта. Он ранжирует весь размещённый реестр (~400 блоков и компонентов) из любой директории, а transitions.md уже использует этот подход для clockWipe() / iris() через npx hyperframes add sdf-iris. Настоящий компонент ближе к исходнику, чем ручная аппроксимация, поэтому он обычно повышает SSIM, а не понижает — но разница рендера на Шаге 4 всё равно остаётся арбитром. Напишите эффект вручную, если поиск не дал подходящего, и зафиксируйте замену в TRANSLATION_NOTES.md в любом случае.

Шаг 3: Генерация композиции HF

Сгенерируйте index.html с:

  • Корневым <div id="stage"> с атрибутами композиции: data-composition-id, data-start="0", data-duration (в секундах), data-fps, data-width, data-height, плюс один data-* на каждое скалярное свойство.

  • Одним хостовым <div> на каждую сцену с data-composition-src="compositions/<scene>.html" и data-start / data-duration / data-track-index. Корень не содержит вложенной раскладки.

  • Одним compositions/<scene>.html на каждую сцену (под-композиция <template>): её встроенный <style> для раскладки (CSS задаёт состояние from для каждого анимируемого свойства), её разметку и один остановленный gsap.timeline({paused: true}) в локальном времени сцены. Каждая производная от useCurrentFrame() в Remotion становится tween-анимацией на этом таймлайне со смещением внутри сцены.

  • window.__timelines["<scene-id>"] = tl; в каждом файле сцены и window.__timelines["<composition-id>"] для собственного (возможно, пустого) таймлайна корня.

Пользовательские подкомпоненты React инлайнятся как повторяющийся HTML с использованием интерфейса свойств в качестве шаблона (см. parameters.md для паттерна data-* на каждый экземпляр).

Шаг 4: Валидация

Запустите инструмент оценки — references/eval.md для полного руководства. Быстрый путь:

Рендер эталона Remotion (после npm install в фикстуре)

cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

Рендер перевода HF

cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4

SSIM diff

../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff


Порог: ~0.02 ниже `p05` комплексности источника (см. таблицу валидированных порогов в `eval.md`). Если разница не проходит, запустите [scripts/frame_strip.sh](https://github.com/heygen-com/hyperframes/blob/HEAD/skills/remotion-to-hyperframes/scripts/frame_strip.sh), чтобы увидеть, *какие* кадры разошлись, затем перечитайте соответствующую справку по timing/sequencing/media.

**Важно**: оба рендера должны использовать совпадающий пиксельный формат. Установите `Config.setVideoImageFormat("png")` + `Config.setColorSpace("bt709")` в `remotion.config.ts` исходного кода Remotion — иначе разница измеряет различия кодировщика (~0.05 SSIM), а не точность перевода.

### Шаг 5: Фиксация пробелов

Всё, что не перевелось без проблем (убранные volume ramps, приближённые пользовательские presentation, подставленные шрифты), фиксируется в `TRANSLATION_NOTES.md`, который создаётся рядом с выводом HF. Формат см. в [references/limitations.md](https://github.com/heygen-com/hyperframes/blob/HEAD/skills/remotion-to-hyperframes/references/limitations.md).

## Что этот skill ЯВНО НЕ делает

- **Не переводит машины состояний React.** Композиции, которые управляют анимацией через `useState` + `useEffect`, не являются детерминированными целями захвата кадров в модели навигации по кадрам HyperFrames. Рекомендуйте паттерн интероперабельности среды выполнения.

- **Не запускает пайплайн рендера Remotion параллельно с HyperFrames.** Это паттерн интероперабельности среды выполнения из [PR #214](https://github.com/heygen-com/hyperframes/pull/214) — отдельное решение для композиций, которые не проходят линт этого skill.

(`@remotion/lambda` — *не* блокер — конфигурация Lambda — это деплой, а не анимация. Skill удаляет её как предупреждение и переводит остальное. См. [references/escape-hatch.md](https://github.com/heygen-com/hyperframes/blob/HEAD/skills/remotion-to-hyperframes/references/escape-hatch.md).)

## Как оценить собственный перевод

Запустите оркестратор тестового набора:

./assets/test-corpus/run.sh


Он выполняет T1, T2, T3 (рендер + diff) и T4 (валидация линта), выводит таблицу прохождения по каждому уровню и генерирует агрегированный JSON-отчёт. Используйте это для проверки, что skill работает end-to-end на чистой копии — и как регрессионную проверку после редактирования любой справки.

Валидированный эталон (на 2026-04-27):

| Уровень | Форма композиции | Средний SSIM | Порог |
| --- | --- | --- | --- |
| T1 | fade-in одного элемента | 0.974 | 0.95 |
| T2 | мульти-сцена + spring + audio + image | 0.985 | 0.95 |
| T3 | data-driven, пользовательские подкомпоненты, count-up | 0.953 | 0.90 |
| T4 | escape-hatch (8 случаев линта) | 8/8 пройдено | n/a |

Установка

npx skills add https://github.com/heygen-com/hyperframes --skill remotion-to-hyperframes