Communitygithub.com

HyperFrames CLI

Ferramenta de linha de comando para criar, lintar, inspecionar, visualizar, renderizar, transcrever, gerar TTS e diagnosticar projetos HyperFrames.

O que é HyperFrames CLI?

O HyperFrames CLI é um utilitário de linha de comando para desenvolvedores que trabalham com composições de vídeo baseadas em HTML. Ele suporta todo o ciclo de vida do projeto: scaffolding inicial com `init`, linting para validar estrutura e atributos obrigatórios, inspeção visual headless para detectar texto que transborda de contêineres ou da tela, preview no estúdio com hot-reload, renderização em MP4 ou WebM com controle de qualidade e FPS, transcrição de áudio com Whisper, geração de texto-para-fala (TTS), e diagnóstico do ambiente com `doctor`. Projetado para ser usado em ambientes de desenvolvimento, CI/CD e agentes de IA, o CLI integra-se perfeitamente com Node.js >= 22 e FFmpeg. Comandos adicionais como `compositions`, `docs`, `benchmark` e `upgrade` completam a ferramenta, tornando-a essencial para qualquer fluxo de trabalho de produção de vídeo com HyperFrames.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/govindgoel2001/video-editing-toolkit/tree/HEAD/vendor/hyperframes-skills/hyperframes-cli

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

CLI HyperFrames

Tudo é executado através de npx hyperframes. Requer Node.js >= 22 e FFmpeg.

Fluxo de trabalho

  1. Scaffolding — npx hyperframes init meu-video
  2. Escrever — criar composição HTML (consulte a skill hyperframes)
  3. Lint — npx hyperframes lint
  4. Inspeção visual — npx hyperframes inspect
  5. Preview — npx hyperframes preview
  6. Renderizar — npx hyperframes render

Execute lint e inspect antes do preview. O lint detecta data-composition-id ausentes, faixas sobrepostas e timelines não registradas. O inspect abre a composição renderizada no Chrome headless, navega pela timeline e relata texto saindo de balões/contêineres ou da tela.

Scaffolding

npx hyperframes init meu-video                        # wizard interativo
npx hyperframes init meu-video --example warm-grain   # escolher um exemplo
npx hyperframes init meu-video --video clip.mp4        # com arquivo de vídeo
npx hyperframes init meu-video --audio track.mp3       # com arquivo de áudio
npx hyperframes init meu-video --non-interactive       # pular prompts (CI/agentes)

Templates: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.

O init cria a estrutura de arquivos correta, copia a mídia, transcreve o áudio com Whisper e instala skills de codificação de IA. Use-o em vez de criar arquivos manualmente.

Linting

npx hyperframes lint                  # diretório atual
npx hyperframes lint ./meu-projeto    # projeto específico
npx hyperframes lint --verbose        # achados em nível informativo
npx hyperframes lint --json           # legível por máquina

Faz lint de index.html e de todos os arquivos em compositions/. Relata erros (devem ser corrigidos), avisos (devem ser corrigidos) e informações (com --verbose).

Inspeção Visual

npx hyperframes inspect                 # inspeciona layout renderizado na timeline
npx hyperframes inspect ./meu-projeto    # projeto específico
npx hyperframes inspect --json          # achados legíveis por agente
npx hyperframes inspect --samples 15    # varredura mais densa da timeline
npx hyperframes inspect --at 1.5,4,7.25 # timestamps explícitos de quadros-chave

Use após lint e validate, especialmente em composições com balões de fala, cartões, legendas ou tipografia ajustada. Relata:

  • Texto que se estende para fora do contêiner visual ou balão mais próximo
  • Texto cortado por sua própria caixa de largura/altura fixa
  • Texto que se estende para fora da tela da composição
  • Filhos escapando de contêineres de recorte

Erros devem ser corrigidos antes da renderização. Avisos são exibidos para revisão pelo agente; adicione --strict para falhar também em avisos. Problemas estáticos repetidos são colapsados por padrão, mantendo a saída JSON compacta para janelas de contexto LLM. Se o transbordamento for intencional para uma animação de entrada/saída, marque o elemento ou ancestral com data-layout-allow-overflow. Se um elemento decorativo nunca deve ser auditado, marque-o com data-layout-ignore.

npx hyperframes layout permanece disponível como um alias de compatibilidade para a mesma passagem de inspeção visual.

Preview

npx hyperframes preview                   # serve o diretório atual
npx hyperframes preview --port 4567       # porta personalizada (padrão 3002)

Recarrega automaticamente em alterações de arquivo. Abre o estúdio no navegador automaticamente.

Ao devolver um projeto ao usuário, use a URL do projeto no Estúdio, não o caminho do arquivo index.html de origem:

http://localhost:<porta>/#project/<nome-do-projeto>

Use a porta real da saída do preview e o nome do diretório do projeto. Por exemplo, após npx hyperframes preview --port 3017 em codex-openai-video, informe http://localhost:3017/#project/codex-openai-video.

Trate index.html apenas como contexto do código-fonte. É aceitável vinculá-lo como um arquivo de implementação, mas não o rotule como o projeto ou superfície de preview.

Renderização

npx hyperframes render                                # MP4 padrão
npx hyperframes render --output final.mp4             # saída nomeada
npx hyperframes render --quality draft                # iteração rápida
npx hyperframes render --fps 60 --quality high        # entrega final
npx hyperframes render --format webm                  # WebM transparente
npx hyperframes render --docker                       # byte-idêntico
FlagOpçõesPadrãoNotas
--outputcaminhorenders/nome_timestamp.mp4Caminho de saída
--fps24, 30, 603060fps dobra o tempo de render
--qualitydraft, standard, highstandarddraft para iteração
--formatmp4, webmmp4WebM suporta transparência
--workers1-8 ou autoautoCada um inicia um Chrome
--dockerflagdesligadoSaída reproduzível
--gpuflagdesligadoCodificação acelerada por GPU
--strictflagdesligadoFalha em erros de lint
--strict-allflagdesligadoFalha em erros E avisos

Orientação de qualidade: draft durante iteração, standard para revisão, high para entrega final.

Transcrição

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt   # importar existente
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

Texto-para-Fala (TTS)

npx hyperframes tts "Texto aqui" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list  # mostrar todas as vozes

Diagnóstico de Problemas

npx hyperframes doctor       # verificar ambiente (Chrome, FFmpeg, Node, memória)
npx hyperframes browser      # gerenciar Chrome empacotado
npx hyperframes info         # versão e detalhes do ambiente
npx hyperframes upgrade      # verificar atualizações

Execute doctor primeiro se a renderização falhar. Problemas comuns: FFmpeg ausente, Chrome ausente, pouca memória.

Outros

npx hyperframes compositions   # listar composições no projeto
npx hyperframes docs           # abrir documentação
npx hyperframes benchmark .    # benchmark de desempenho de renderização

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

govindgoel2001/video-editing-toolkit

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

govindgoel2001/video-editing-toolkit

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

govindgoel2001/video-editing-toolkit

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.

govindgoel2001/video-editing-toolkit

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

govindgoel2001/video-editing-toolkit

Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.

govindgoel2001/video-editing-toolkit

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

Habilidades Relacionadas