Communitygithub.com

alecs5am/ralphy

Bucle de desarrollo CLI de HyperFrames: `npx hyperframes` para inicialización (init), validación (lint, inspect), previsualización, renderizado y diagnóstico del entorno (doctor, browser, info, upgrade). Úsalo al ejecutar cualquiera de estos comandos o al solucionar problemas del entorno de compilación/renderizado de HyperFrames. Para comandos de preprocesamiento de activos (`tts`, `transcribe`, `remove-background`), invoca en su lugar el skill `hyperframes-media`.

¿Qué es ralphy?

Este skill proporciona acceso completo a la CLI de HyperFrames, una herramienta para crear y gestionar composiciones de vídeo programáticas. Esencial para desarrolladores que trabajan con HyperFrames, este skill centraliza todo el flujo de trabajo: desde el scaffolding inicial del proyecto con `npx hyperframes init`, pasando por la validación estática con `lint` y la inspección visual con `inspect` (que detecta texto fuera de contenedores o del canvas), hasta la previsualización con recarga en caliente y el renderizado final en múltiples formatos y calidades. Soporta renderizados parametrizados, lo que permite variar dinámicamente el contenido de una misma composición. El skill también incluye comandos para diagnosticar el entorno (`doctor`), gestionar Chrome integrado, obtener información de la versión y actualizar la herramienta. Está diseñado para ser usado en plataformas como Cursor, Windsurf, Claude Code y otros agentes que ejecuten comandos de shell, así como en entornos CI/CD. La documentación detallada del SKILL.md describe exhaustivamente cada comando, sus opciones (como `--docker` para resultados reproducibles, `--quality` para controlar la velocidad frente a la calidad, y `--variables` para composiciones parametrizadas), y las mejores prácticas para un flujo de trabajo eficiente.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

CLI de HyperFrames

Todo se ejecuta a través de npx hyperframes. Requiere Node.js >= 22 y FFmpeg.

Flujo de trabajo

  1. Andamio — npx hyperframes init my-video
  2. Escribir — redactar la composición HTML (ver el skill hyperframes)
  3. Lint — npx hyperframes lint
  4. Inspección visual — npx hyperframes inspect
  5. Previsualizar — npx hyperframes preview
  6. Renderizar — npx hyperframes render

Ejecuta lint e inspect antes de previsualizar. lint detecta data-composition-id faltantes, pistas superpuestas y líneas de tiempo no registradas. inspect abre la composición renderizada en Chrome sin cabeza, recorre la línea de tiempo e informa de texto que se sale de burbujas/contenedores o del canvas.

Andamio

npx hyperframes init my-video                        # asistente interactivo
npx hyperframes init my-video --example warm-grain   # elegir un ejemplo
npx hyperframes init my-video --video clip.mp4        # con archivo de vídeo
npx hyperframes init my-video --audio track.mp3       # con archivo de audio
npx hyperframes init my-video --example blank --tailwind # con Tailwind v4 en tiempo de ejecución del navegador
npx hyperframes init my-video --non-interactive       # saltar indicaciones (CI/agentes)

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

init crea la estructura de archivos correcta, copia los medios, transcribe el audio con Whisper e instala las habilidades de codificación de IA. Úsalo en lugar de crear archivos a mano.

Al usar --tailwind, invoca el skill tailwind antes de editar clases o tokens de tema. El andamio usa Tailwind v4.2 a través del tiempo de ejecución del navegador, no la configuración de Tailwind v3 de Studio.

Linting

npx hyperframes lint                  # directorio actual
npx hyperframes lint ./my-project     # proyecto específico
npx hyperframes lint --verbose        # hallazgos a nivel de información
npx hyperframes lint --json           # legible por máquina

Analiza index.html y todos los archivos en compositions/. Informa errores (deben corregirse), advertencias (deberían corregirse) e información (con --verbose).

Inspección visual

npx hyperframes inspect                 # inspeccionar el diseño renderizado a lo largo de la línea de tiempo
npx hyperframes inspect ./my-project    # proyecto específico
npx hyperframes inspect --json          # hallazgos legibles por el agente
npx hyperframes inspect --samples 15    # barrido más denso de la línea de tiempo
npx hyperframes inspect --at 1.5,4,7.25 # marcas de tiempo explícitas de fotogramas clave

Úsalo después de lint y validate, especialmente para composiciones con burbujas de diálogo, tarjetas, subtítulos o tipografía ajustada. Informa de:

  • Texto que se extiende fuera del contenedor visual o burbuja más cercana
  • Texto recortado por su propia caja de ancho/alto fijo
  • Texto que se extiende fuera del canvas de la composición
  • Elementos hijos que escapan de contenedores de recorte

Los errores deben corregirse antes de renderizar. Las advertencias se muestran para revisión del agente; añade --strict para fallar también con advertencias. Los problemas estáticos repetidos se colapsan por defecto para que la salida JSON se mantenga compacta para las ventanas de contexto de los LLM. Si el desbordamiento es intencional para una animación de entrada/salida, marca el elemento o ancestro con data-layout-allow-overflow. Si un elemento decorativo nunca debe ser auditado, márcalo con data-layout-ignore.

npx hyperframes layout sigue estando disponible como alias de compatibilidad para la misma pasada de inspección visual.

Previsualización

npx hyperframes preview                   # servir el directorio actual
npx hyperframes preview --port 4567       # puerto personalizado (por defecto 3002)

Recarga en caliente con los cambios de archivo. Abre el estudio en tu navegador automáticamente.

Al devolver un proyecto al usuario, usa la URL del proyecto de Studio, no la ruta index.html fuente:

http://localhost:<puerto>/#project/<nombre-del-proyecto>

Usa el puerto real de la salida de previsualización y el nombre del directorio del proyecto. Por ejemplo, después de npx hyperframes preview --port 3017 en codex-openai-video, informa http://localhost:3017/#project/codex-openai-video.

Trata index.html solo como contexto de código fuente. Está bien enlazarlo como un archivo de implementación, pero no lo etiquetes como el proyecto o la superficie de previsualización.

Renderizado

npx hyperframes render                                # MP4 estándar
npx hyperframes render --output final.mp4             # salida con nombre
npx hyperframes render --quality draft                # iteración rápida
npx hyperframes render --fps 60 --quality high        # entrega final
npx hyperframes render --format webm                  # WebM transparente
npx hyperframes render --docker                       # salida byte-idéntica
IndicadorOpcionesPor defectoNotas
--outputrutarenders/nombre_timestamp.mp4Ruta de salida
--fps24, 30, 603060fps duplica el tiempo de renderizado
--qualitydraft, standard, highstandarddraft para iterar
--formatmp4, webmmp4WebM admite transparencia
--workers1-8 o autoautoCada uno inicia Chrome
--dockerindicadoroffSalida reproducible
--gpuindicadoroffCodificación acelerada por GPU
--strictindicadoroffFallar en errores de lint
--strict-allindicadoroffFallar en errores Y advertencias
--variablesobjeto JSON—Sobrescribir valores de variables declaradas en data-composition-variables
--variables-fileruta—Archivo JSON con valores de variables (alternativa a --variables)
--strict-variablesindicadoroffFallar el renderizado en claves no declaradas o discrepancias de tipo en --variables

Guía de calidad: draft mientras iteras, standard para revisión, high para entrega final.

Renderizados parametrizados: la composición declara sus variables en la raíz <html> con data-composition-variables — un array de declaraciones JSON ({id, type, label, default} por entrada) que define el esquema. Los scripts internos leen los valores resueltos mediante window.__hyperframes.getVariables(). La CLI --variables '{"title":"Q4 Report"}' es un objeto JSON indexado por id que sobrescribe esos valores predeterminados declarados para un renderizado; las claves faltantes se mantienen, por lo que la misma composición se ejecuta sin cambios en la vista previa de desarrollo y en producción. (Los hosts de sub-composición también pueden sobrescribir por instancia con data-variable-values — misma forma de objeto, con alcance en una sola montura de la sub-composición. Consulta el skill hyperframes para el patrón completo).

Preprocesamiento de activos

npx hyperframes tts, transcribe y remove-background producen activos (audio de narración, transcripciones a nivel de palabra, vídeo transparente) que se colocan en una composición. Cada uno descarga su propio modelo en la primera ejecución. Para la selección de voz, las reglas del modelo whisper (la trampa de que .en traduce no-inglés), la elección del formato de salida (VP9 alpha WebM vs ProRes) y la cadena TTS → transcribir → subtítulos, invoca el skill hyperframes-media.

Solución de problemas

npx hyperframes doctor       # comprobar el entorno (Chrome, FFmpeg, Node, memoria)
npx hyperframes browser      # gestionar Chrome integrado
npx hyperframes info         # detalles de versión y entorno
npx hyperframes upgrade      # comprobar actualizaciones

Ejecuta doctor primero si falla el renderizado. Problemas comunes: falta FFmpeg, falta Chrome, poca memoria.

Otros

npx hyperframes compositions   # listar composiciones en el proyecto
npx hyperframes docs           # abrir documentación
npx hyperframes benchmark .    # evaluar rendimiento de renderizado

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.

Skills relacionados