hyperframes-html-to-video

HyperFrames — HTML → видео (HeyGen)

Ссылка: https://github.com/HeyGen-com/hyperframes · Apache-2.0 · 40k★, активная разработка (HeyGen за спиной, не одиночка). npm-пакет hyperframes, Node ≥22, TypeScript monorepo.

Что это

Превращает HTML + CSS + медиа + seekable-анимации → детерминированный MP4 (один HTML = идентичный ролик, воспроизводимо). Локальный рендер бесплатен, без HeyGen-кредитов. Три режима: CLI, из AI-агента через skills (19 штук, готовые .claude/skills/ — учат агента циклу: план → HTML → анимации → медиа → lint → preview → render; работает с Claude Code/Cursor/Codex), или как рендер-ядро (есть Dockerfile.render, gcp-cloud-run, aws-lambda, k8s-jobs).

CLI: npx hyperframes init my-video (шаблон-проект) → npx hyperframes render -c ./comp.html -o out.mp4. Также doctor/browser (chromium), lint, preview, benchmark.

Зачем Сергею — оживить видео-автопостинг

Пайплайн: n8n (триггер/данные) → готовим HTML-шаблон (Claude Code skill /hyperframes или n8n) → hyperframes render → MP4 → Telegram-нода → пост в @technologiprivat. Детерминированность → годится для конвейера.

Где рендерить — НЕ на forge

Рендер тяжёлый (headless chromium + ffmpeg, CPU/RAM). Forge под давлением по RAM (боты/n8n/RAG/своп) → задушит. Рендерим на periscope (4 ядра/6G, есть место) или отдельной ноде, по требованию. Hosted-вариант (hyperframes.heygen.com) — облако HeyGen, оплата = РФ-проблема; self-host бесплатен.

Тест на periscope (10.08)

• Установлено: Node 22.23.2 + ffmpeg 6.1.1 на periscope (194.34.238.184).
• РЕЗУЛЬТАТ (11.08): ✅ РАБОТАЕТ. Тестовый ролик отрендерился: 1920×1080, H.264, 30fps, 10с, 300 кадров, 1м20с на 4 ядрах (1 worker, screenshot-capture). Файл 25.6KB (простой blank-шаблон).
• Грабли развёртывания (все в окружении, НЕ в инструменте):
  1. Локальный chromium (hyperframes browser ensure) — Chrome Headless Shell НЕ качается с periscope (puppeteer-download виснет на Google-источнике, 12K за 10 мин).
  2. Docker-режим (--docker) — образ собирается (1.28GB), но у HyperFrames внутренний таймаут на сборку (spawnSync docker ETIMEDOUT), в который медленный диск periscope не укладывается на unpacking (78-273с). Плюс npx каждый запуск тянет новую версию (0.7.105→106) и пересобирает с нуля.
  3. СРАБОТАЛО: apt install chromium (пришёл как snap /snap/bin/chromium) на хост + глобальный npm i -g hyperframes + запуск PRODUCER_HEADLESS_SHELL_PATH=/snap/bin/chromium hyperframes render -o out.mp4 — минуя и puppeteer-download, и docker.
• Рабочий рецепт для конвейера: Node22 + ffmpeg + системный chromium + PRODUCER_HEADLESS_SHELL_PATH → hyperframes render. 1080p/10с ≈ 80с CPU — ок для периодического постинга, не для потока. Node/ffmpeg/chromium/образ уже стоят на periscope (/opt/hyperframes-test/).
• Формат композиции (контракт HyperFrames): root-элемент с id="master-root" data-composition-id="master" data-start="0" data-duration="10" data-width/height; анимация = GSAP timeline paused, зарегистрированная в window.__timelines["master"]; рендерер перематывает её по кадрам (seekable). Пример valid custom-HTML написан и компилируется (шрифты Google подтягиваются и кэшируются детерминированно).
• ⚠️ ВАЖНЫЙ УРОК (11.08): тяжёлый рендер OOM-убивает ShadowBroker на periscope. Кастомная композиция с filter: blur(90px) на 3 больших блобах = дорогая компоновка каждого из 300 кадров → RAM в потолок (6G машины) → OOM-killer дважды прибил uvicorn (backend ShadowBroker). ShadowBroker сам поднялся (restart: unless-stopped), фронт 200 OK, но это реальный удар по рабочему сервису. Вывод: тяжёлый видеорендер и ShadowBroker НЕ уживаются на одной 6G-ноде. Простые ролики (swiss/текст, ~2 мин) — ок. Для тяжёлой графики: либо облегчить композицию (убрать blur → готовый градиент-картинкой), либо временно docker compose stop ShadowBroker (освобождает ~4G), либо отдельная нода под рендер в реальном конвейере.

Связано: n8n-automation, savereelsbot, shadowbroker.