Communitygithub.com

alecs5am/ralphy

HyperFrames CLI-Entwicklungszyklus – `npx hyperframes` für Grundgerüst (init), Validierung (lint, inspect), Vorschau, Rendering und Umgebungsfehlerbehebung (doctor, browser, info, upgrade).

Was ist ralphy?

Diese Fähigkeit („Skill“) steuert den vollständigen CLI-Entwicklungszyklus von HyperFrames über `npx hyperframes`. Sie ermöglicht das Erstellen von Videoprojekten (`init`), das Linten (`lint`) auf fehlende `data-composition-id`, überlappende Tracks oder nicht registrierte Zeitachsen sowie die visuelle Inspektion (`inspect`) des Layouts, bei der überlaufender Text oder beschnittene Container erkannt werden. Die Vorschau (`preview`) startet einen Hot-Reload-Server, und das Rendern (`render`) erzeugt MP4-, WebM- oder Docker-Reproduktionen mit parametrisierbaren Variablen. Die integrierte Fehlerbehebung (`doctor`, `browser`, `info`, `upgrade`) prüft die Umgebung (Node, FFmpeg, Chrome und Speicher). Für Asset-Vorverarbeitung wie TTS, Transkription und Hintergrundentfernung muss stattdessen der Skill `hyperframes-media` verwendet werden.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

HyperFrames CLI

Alles läuft über npx hyperframes. Erfordert Node.js >= 22 und FFmpeg.

Arbeitsablauf

  1. Grundgerüst erstellen — npx hyperframes init mein-video
  2. Schreiben — HTML-Komposition verfassen (siehe Skill hyperframes)
  3. Linten — npx hyperframes lint
  4. Visuell inspizieren — npx hyperframes inspect
  5. Vorschau — npx hyperframes preview
  6. Rendern — npx hyperframes render

Vor der Vorschau linten und inspizieren. lint erkennt fehlende data-composition-id, überlappende Tracks und nicht registrierte Zeitachsen. inspect öffnet die gerenderte Komposition in einem kopflosen Chrome, durchläuft die Zeitachse und meldet Text, der aus Sprechblasen/Containern oder über die Leinwand hinausragt.

Grundgerüst erstellen

npx hyperframes init mein-video                        # interaktiver Assistent
npx hyperframes init mein-video --example warm-grain   # Beispiel auswählen
npx hyperframes init mein-video --video clip.mp4        # mit Videodatei
npx hyperframes init mein-video --audio track.mp3       # mit Audiodatei
npx hyperframes init mein-video --example blank --tailwind # mit Tailwind v4 Browser-Laufzeit
npx hyperframes init mein-video --non-interactive       # Eingabeaufforderungen überspringen (CI/Agenten)

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

init erstellt die richtige Dateistruktur, kopiert Medien, transkribiert Audio mit Whisper und installiert KI-Coding-Fähigkeiten. Verwenden Sie es anstatt Dateien von Hand zu erstellen.

Bei Verwendung von --tailwind rufen Sie den Skill tailwind auf, bevor Sie Klassen oder Theme-Token bearbeiten. Das Grundgerüst verwendet Tailwind v4.2 über die Browser-Laufzeit, nicht die Tailwind-v3-Einrichtung von Studio.

Linten

npx hyperframes lint                  # aktuelles Verzeichnis
npx hyperframes lint ./mein-projekt   # bestimmtes Projekt
npx hyperframes lint --verbose        # Funde auf Info-Ebene
npx hyperframes lint --json           # maschinenlesbar

Lintet index.html und alle Dateien in compositions/. Meldet Fehler (müssen behoben werden), Warnungen (sollten behoben werden) und Informationen (mit --verbose).

Visuelle Inspektion

npx hyperframes inspect                 # gerendertes Layout über die Zeitachse inspizieren
npx hyperframes inspect ./mein-projekt  # bestimmtes Projekt
npx hyperframes inspect --json          # agentenlesbare Funde
npx hyperframes inspect --samples 15    # dichterer Zeitachsendurchlauf
npx hyperframes inspect --at 1.5,4,7.25 # explizite Heldenbild-Zeitstempel

Verwenden Sie dies nach lint und validate, insbesondere für Kompositionen mit Sprechblasen, Karten, Untertiteln oder enger Typografie. Es meldet:

  • Text, der außerhalb des nächsten visuellen Containers oder der Sprechblase liegt
  • Text, der durch eine eigene feste Breite/Höhe abgeschnitten wird
  • Text, der außerhalb der Kompositionsleinwand liegt
  • Kindelemente, die aus beschneidenden Containern entkommen

Fehler sollten vor dem Rendern behoben werden. Warnungen werden zur Überprüfung durch den Agenten ausgegeben; fügen Sie --strict hinzu, um auch bei Warnungen abzubrechen. Wiederholte statische Probleme werden standardmäßig zusammengefasst, sodass die JSON-Ausgabe für LLM-Kontextfenster kompakt bleibt. Wenn ein Überlauf für eine Ein-/Ausgangsanimation beabsichtigt ist, markieren Sie das Element oder den Vorfahren mit data-layout-allow-overflow. Wenn ein dekoratives Element niemals geprüft werden soll, markieren Sie es mit data-layout-ignore.

npx hyperframes layout bleibt als Kompatibilitätsalias für denselben visuellen Inspektionsdurchlauf verfügbar.

Vorschau

npx hyperframes preview                   # aktuelles Verzeichnis bereitstellen
npx hyperframes preview --port 4567       # benutzerdefinierter Port (Standard 3002)

Aktualisiert bei Dateiänderungen automatisch neu. Öffnet das Studio automatisch im Browser.

Wenn Sie ein Projekt an den Benutzer zurückgeben, verwenden Sie die Studio-Projekt-URL, nicht den Quellpfad index.html:

http://localhost:<port>/#project/<projektname>

Verwenden Sie den tatsächlichen Port aus der Vorschauausgabe und den Projektverzeichnisnamen. Beispiel: Nach npx hyperframes preview --port 3017 in codex-openai-video melden Sie http://localhost:3017/#project/codex-openai-video.

Behandeln Sie index.html nur als Quellcode-Kontext. Es ist in Ordnung, es als Implementierungsdatei zu verlinken, aber bezeichnen Sie es nicht als Projekt oder Vorschauoberfläche.

Rendern

npx hyperframes render                                # Standard-MP4
npx hyperframes render --output endgueltig.mp4        # benannte Ausgabe
npx hyperframes render --quality draft                # schnelle Iteration
npx hyperframes render --fps 60 --quality high        # endgültige Auslieferung
npx hyperframes render --format webm                  # transparentes WebM
npx hyperframes render --docker                       # byteidentisch
FlaggeOptionenStandardHinweise
--outputPfadrenders/name_timestamp.mp4Ausgabepfad
--fps24, 30, 603060 fps verdoppelt die Renderzeit
--qualitydraft, standard, highstandarddraft für Iteration
--formatmp4, webmmp4WebM unterstützt Transparenz
--workers1-8 oder autoautoJeder startet Chrome
--dockerFlaggeausReproduzierbare Ausgabe
--gpuFlaggeausGPU-beschleunigte Kodierung
--strictFlaggeausBei Lint-Fehlern abbrechen
--strict-allFlaggeausBei Fehlern UND Warnungen abbrechen
--variablesJSON-Objekt—Überschreibt in data-composition-variables deklarierte Variablen
--variables-filePfad—JSON-Datei mit Variablenwerten (Alternative zu --variables)
--strict-variablesFlaggeausRendern bei nicht deklarierten Schlüsseln oder Typenkonflikten abbrechen

Qualitätsrichtlinie: draft während der Iteration, standard zur Überprüfung, high für die endgültige Auslieferung.

Parametrisierte Renderings: Die Komposition deklariert ihre Variablen auf dem <html>-Root-Element mit data-composition-variables – einem JSON-Array von Deklarationen ({id, type, label, default} pro Eintrag), das das Schema definiert. Skripte im Inneren lesen die aufgelösten Werte über window.__hyperframes.getVariables(). Die CLI --variables '{"title":"Q4-Bericht"}' ist ein JSON-Objekt, das nach id schlüsselt und die deklarierten Standardwerte für einen Rendervorgang überschreibt; fehlende Schlüssel fallen durch, sodass dieselbe Komposition unverändert in der Entwicklungsvorschau und in der Produktion läuft. (Sub-Comp-Hosts können auch pro Instanz mit data-variable-values überschreiben – gleiche Objektform, begrenzt auf eine Einbindung der Unterkomposition. Das vollständige Muster finden Sie im Skill hyperframes.)

Asset-Vorverarbeitung

npx hyperframes tts, transcribe und remove-background erzeugen Assets (Erzähl-Audio, Wort-für-Wort-Transkripte, transparentes Video), die in eine Komposition eingefügt werden. Jeder Befehl lädt sein eigenes Modell beim ersten Ausführen herunter. Für Sprachauswahl, Whisper-Modellregeln (die .en-übersetzt-nicht-Englisch-Falle), Ausgabeformatwahl (VP9-Alpha-WebM vs. ProRes) und die Kette TTS → Transkription → Untertitel rufen Sie den Skill hyperframes-media auf.

Fehlerbehebung

npx hyperframes doctor       # Umgebung prüfen (Chrome, FFmpeg, Node, Speicher)
npx hyperframes browser      # gebündeltes Chrome verwalten
npx hyperframes info         # Versions- und Umgebungsdetails
npx hyperframes upgrade      # nach Updates suchen

Führen Sie zuerst doctor aus, wenn das Rendern fehlschlägt. Häufige Probleme: fehlendes FFmpeg, fehlendes Chrome, zu wenig Speicher.

Sonstiges

npx hyperframes compositions   # Kompositionen im Projekt auflisten
npx hyperframes docs           # Dokumentation öffnen
npx hyperframes benchmark .    # Renderleistung benchmarken

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.

Verwandte Skills