Communitygithub.com

alecs5am/ralphy

Loop de desenvolvimento CLI do HyperFrames — `npx hyperframes` para scaffolding (init), validação (lint, inspect), pré-visualização, renderização e diagnóstico de ambiente (doctor, browser, info, upgrade). Use ao executar qualquer um desses comandos ou ao diagnosticar o ambiente de build/renderização do HyperFrames. Para comandos de pré-processamento de assets (`tts`, `transcribe`, `remove-background`), invoque a skill `hyperframes-media`.

O que é ralphy?

Esta skill oferece o loop de desenvolvimento completo da CLI do HyperFrames, centralizado no comando `npx hyperframes`. Ela guia o desenvolvedor por todas as etapas do fluxo de trabalho: desde a inicialização de projetos (`npx hyperframes init`) com templates prontos e suporte a Tailwind, até a validação com linting e inspeção visual, pré-visualização com hot-reload, renderização parametrizada e diagnóstico de ambiente. A skill é útil porque padroniza e automatiza o processo de criação de vídeos com composições HTML, garantindo que assets de mídia sejam corretamente processados, que o layout seja verificado antes da renderização (evitando erros como texto fora dos contêineres) e que a saída final seja reproduzível. Ela suporta Node.js >= 22, FFmpeg e Chrome headless, e pode ser usada tanto em ambientes interativos quanto em CI/agentes (com flags como `--non-interactive` e saída JSON). Para comandos de pré-processamento de assets (TTS, transcrição, remoção de fundo), a documentação recomenda invocar a skill `hyperframes-media` separadamente.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/alecs5am/ralphy/tree/HEAD/.agents/skills/hyperframes-cli

Perguntar na sua IA favorita

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

Documentação

CLI do HyperFrames

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

Fluxo de Trabalho

  1. Scaffold — npx hyperframes init meu-video
  2. Escreva — autorize a composição HTML (veja a skill hyperframes)
  3. Lint — npx hyperframes lint
  4. Inspeção visual — npx hyperframes inspect
  5. Pré-visualização — npx hyperframes preview
  6. Renderização — npx hyperframes render

Execute lint e inspeção antes da pré-visualização. O lint detecta data-composition-id ausente, trilhas sobrepostas e timelines não registradas. O inspect abre a composição renderizada no Chrome headless, percorre a timeline e relata texto vazando para fora de balões/contêineres ou do canvas.

Scaffolding

npx hyperframes init meu-video                        # assistente interativo
npx hyperframes init meu-video --example warm-grain   # escolha 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 --example blank --tailwind # com runtime do Tailwind v4 no navegador
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 mídias, transcreve áudio com Whisper e instala skills de codificação de IA. Use-o em vez de criar arquivos manualmente.

Ao usar --tailwind, invoque a skill tailwind antes de editar classes ou tokens de tema. O scaffold usa Tailwind v4.2 via o runtime do navegador, não a configuração Tailwind v3 do Studio.

Linting

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

Verifica index.html e 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 o layout renderizado na timeline
npx hyperframes inspect ./meu-projeto   # projeto específico
npx hyperframes inspect --json          # descobertas 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 hero-frame

Use após o lint e validate, especialmente para composições com balões de fala, cartões, legendas ou tipografia apertada. Ele relata:

  • Texto se estendendo para fora do contêiner visual ou balão mais próximo
  • Texto cortado pela própria caixa de largura/altura fixa
  • Texto se estendendo para fora do canvas da composição
  • Elementos filhos escapando de contêineres de recorte

Erros devem ser corrigidos antes da renderização. Avisos são exibidos para revisão do agente; adicione --strict para falhar também em avisos. Problemas estáticos repetidos são colapsados por padrão, para que a saída JSON permaneça 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 inspeção visual.

Pré-visualização

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 Studio no navegador automaticamente.

Ao entregar um projeto de volta ao usuário, use a URL do projeto no Studio, não o caminho da fonte index.html:

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

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

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

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                       # saída byte-idêntica
FlagOpçõesPadrãoNotas
--outputcaminhorenders/nome_timestamp.mp4Caminho de saída
--fps24, 30, 603060fps dobra o tempo de renderização
--qualitydraft, standard, highstandarddraft para iterar
--formatmp4, webmmp4WebM suporta transparência
--workers1-8 ou autoautoCada um inicia uma instância do Chrome
--dockerflagdesligadoSaída reproduzível
--gpuflagdesligadoCodificação acelerada por GPU
--strictflagdesligadoFalha em erros de lint
--strict-allflagdesligadoFalha em erros E avisos
--variablesobjeto JSON—Substitui valores de variáveis declaradas em data-composition-variables
--variables-filecaminho—Arquivo JSON com valores de variáveis (alternativa a --variables)
--strict-variablesflagdesligadoFalha na renderização em chaves não declaradas ou incompatibilidade de tipos em --variables

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

Renderizações parametrizadas: a composição declara suas variáveis na raiz <html> com data-composition-variables — um array JSON de declarações ({id, type, label, default} por entrada) que define o esquema. Scripts internos leem os valores resolvidos via window.__hyperframes.getVariables(). A CLI **`--variables '{

Individual skills in this repo

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

alecs5am/ralphy

>- Composition and render craft — assembles scenario.json plus asset-manifest.json into a HyperFrames HTML composition and renders the mp4. Owns timing, transitions, captions, audio mix and ducking, the green zone, the render pipeline, and VO sync. Generates no media of its own. USE WHEN the user asks to "compose the video", "render", "preview", "fix the captions", "mix the audio", "tighten the transitions", "final cut", or edits HyperFrames composition code. TRIGGER (EN): "render it", "compose the video", "captions", "audio mix", "transitions", "final cut", "preview the composition".

alecs5am/ralphy

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

alecs5am/ralphy

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.

alecs5am/ralphy

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 dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

alecs5am/ralphy

>- How to make a vivid, character-driven brand POSTER — a single still image, not a video. A generalized overlay on the art-director step: supplies the poster-as-landing architecture (top banner → massive beveled wordmark → chest-up hero photo → scattered vinyl-sticker collage → copy block → thin footer strip), the parameterized slot set (brand, exclamation word, hero, product, palette, original blob glyph, aesthetic register), the model stack (gpt-5.4-image-2 for crisp typography, gemini fallback), and the niche's failure modes. Works for ANY brand and ANY aesthetic the user names — Y2K streetwear, vaporwave, grunge zine, clean DTC — the skill supplies the layout know-how, the user supplies the subject + vibe. USE WHEN the user asks for a poster / flyer / drop poster / "poster-as-landing-page" / brand key-art / album-cover-style still / hype graphic, with no specific existing poster to reproduce. This is a content-niche craft-overlay SKILL (generalized), loaded on top of a poster-format template match — n...

alecs5am/ralphy

>- Compatibility shim for the legacy `/ralphy-remotion` skill name. Use when a saved Claude Code command, old project note, or user request still mentions Ralphy Remotion; redirect the task to HyperFrames and the current Ralphy render playbooks instead of authoring new Remotion code.

alecs5am/ralphy

>- Compatibility shim for the legacy `/remotion-to-hyperframes` skill name. Use when an old project, note, or user request asks to migrate Ralphy Remotion work; translate the intent into the current HyperFrames composition model and follow the editor and HyperFrames playbooks.

alecs5am/ralphy

The full extract → classify → blueprint → de-dup → publish pipeline for a finished `.ralphy/workspaces/<ws>/projects/<id>/`. Reads its `units/*/unit.json` (#069) as the Unit source of truth, then factors the project into ALL FIVE entities — Unit + the four typed blocks Template (structure), Style (look), Recipe (effect/treatment), Asset (reusable media). Applies the recipe-vs-tag split (#082/#083): a candidate is a Recipe only if it carries an extractable artifact (ffmpeg filtergraph / HyperFram

alecs5am/ralphy

>- How to make a realistic AI UGC ad for a product — generalized niche know-how that looks real and doesn't feel AI. A domain overlay on the standard pipeline: supplies the shooting-script shape (timestamp | VO | shot | mannerism), the creator-persona build, the problem-mirror hook, the trust-through-mannerisms rule, and the 9:16 ~15s UGC format defaults. Works for ANY product the user names — their skincare line, a no-name app, a gadget. The skill supplies the know-how; the user supplies the product. USE WHEN the user asks for a UGC ad / creator-style product ad / "make an ad that looks like a real person reviewing my product" / testimonial-style or problem-solution short for TikTok / Reels / Shorts, with no specific existing video to reproduce. This is a niche SKILL (generalized), not a remix TEMPLATE. For "remix this exact ad but swap the product/person", use the remix path (docs/skills-vs-templates.md). For swapping the creator in an existing clip, see /ugc-model-swap.

alecs5am/ralphy

When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' 'ideas to grow,' 'what else can I try,' 'I don't know how to market this,' 'brainstorm marketing,' or 'what marketing should I do.' Use this as a starting point whenever someone is stuck or looking for inspiration on how to grow. For specific channel execution, see the relevant skill (paid-ads, social-content, email-sequence, etc.).

alecs5am/ralphy

Full end-to-end workflow for generating a realistic AI UGC ad for a product. 15-second format. Looks real. Doesn't feel AI.

Habilidades Relacionadas