Communitygithub.com

alecs5am/ralphy

Prétraitement de médias pour les compositions HyperFrames — synthèse vocale (Kokoro), transcription audio/vidéo (Whisper) et suppression d'arrière-plan pour les incrustations transparentes (u2net).

Qu'est-ce que ralphy ?

Ce skill regroupe trois commandes CLI (`tts`, `transcribe`, `remove-background`) conçues pour préparer des assets multimédia destinés aux compositions HyperFrames. Il permet de générer un voiceover à partir d'un texte, de transcrire une piste audio en un fichier de sous-titres horodatés, et de supprimer l'arrière-plan d'une vidéo ou d'une image pour l'utiliser comme incrustation transparente. Chaque commande télécharge son modèle d'IA localement au premier lancement (Kokoro-82M pour la synthèse vocale, Whisper pour la transcription, u2net pour la suppression d'arrière-plan) et met en cache les fichiers dans `~/.cache/hyperframes/`. Le skill propose une sélection de 54 voix multilingues, un choix de tailles de modèle Whisper (de `tiny` à `large-v3`) pour équilibrer vitesse et qualité, et une option de séparation des couches (`--background-output`) pour placer du texte ou des graphiques entre le sujet et son arrière-plan d'origine. Il est destiné aux développeurs qui créent des compositions HTML5 interactives avec HyperFrames et qui ont besoin d'assets multimédia générés localement, sans clé API externe.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Aperçu

Depuis le README du skill

Documentation

Prétraitement des médias HyperFrames

Trois commandes CLI qui produisent des assets pour les compositions : tts (parole), transcribe (horodatage) et remove-background (vidéo transparente). Chacune télécharge un modèle au premier lancement et le met en cache sous ~/.cache/hyperframes/. Placez la sortie dans le projet, puis référencez-la depuis le HTML de la composition — voir le skill hyperframes pour les conventions relatives aux éléments audio/vidéo.

Synthèse vocale (tts)

Générez de la parole localement avec Kokoro-82M. Aucune clé API nécessaire.

npx hyperframes tts "Texte ici" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list                       # les 54 voix, liste complète

Sélection de la voix

Adaptez la voix au contenu. La voix par défaut est af_heart.

Type de contenuVoixPourquoi
Démo produitaf_heart/af_novaChaleureuse, professionnelle
Tutoriel / guideam_adam/bf_emmaNeutre, facile à suivre
Marketing / promotionaf_sky/am_michaelÉnergique ou autoritaire
Documentationbf_emma/bm_georgeAnglais britannique clair, formel
Décontracté / réseauxaf_heart/af_skyAccessible, naturel

Multilingue

Les identifiants de voix encodent la langue dans la première lettre : a=anglais américain, b=anglais britannique, e=espagnol, f=français, h=hindi, i=italien, j=japonais, p=portugais brésilien, z=mandarin. La CLI détecte automatiquement la locale du phonémiseur à partir du préfixe — pas besoin de --lang quand la voix correspond au texte.

npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
npx hyperframes tts "今日はいい天気ですね" --voice jf_alpha --output ja.wav

Utilisez --lang uniquement pour forcer la détection automatique (accents stylisés). Codes valides : en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. La phonémisation pour les langues non anglaises nécessite espeak-ng au niveau système (brew install espeak-ng / apt-get install espeak-ng).

Vitesse

  • 0.7-0.8 — tutoriel, contenu complexe, accessibilité
  • 1.0 — rythme naturel (par défaut)
  • 1.1-1.2 — introductions, transitions, contenu dynamique
  • 1.5+ — rarement approprié ; testez avec soin

Scripts longs

Pour plus de quelques paragraphes, écrivez dans un fichier .txt et passez le chemin. Les entrées de plus de ~5 minutes de parole peuvent bénéficier d'un découpage en segments.

Prérequis

Python 3.8+ avec kokoro-onnx et soundfile (pip install kokoro-onnx soundfile). Le modèle se télécharge lors de la première utilisation (~311 Mo + ~27 Mo de voix, mis en cache dans ~/.cache/hyperframes/tts/).

Transcription (transcribe)

Produisez un fichier transcript.json normalisé avec horodatage mot par mot.

npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model small --language es
npx hyperframes transcribe subtitles.srt          # importer un fichier existant
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json

Règle de langue (non négociable)

N'utilisez jamais les modèles .en sauf si l'utilisateur précise explicitement que l'audio est en anglais. Les modèles .en (small.en, medium.en) traduisent l'audio non anglais en anglais au lieu de le transcrire. Cela détruit silencieusement la langue d'origine.

  1. Langue connue et non anglaise → --model small --language <code> (pas de suffixe .en)
  2. Langue connue et anglaise → --model small.en
  3. Langue inconnue → --model small (pas de .en, pas de --language) — Whisper détecte automatiquement

Le modèle par défaut est small, pas small.en.

Tailles de modèle

ModèleTailleVitesseQuand l'utiliser
tiny75 MoTrès rapideAperçus rapides, tests de pipeline
base142 MoRapidePetits extraits, audio clair
small466 MoModéréePar défaut — la plupart des contenus
medium1.5 GoLenteContenu important, audio bruité, musique
large-v33.1 GoTrès lenteQualité production

Musique avec voix : commencez au minimum par medium ; les pistes produites nécessitent souvent une importation manuelle SRT/VTT. Pour les vérifications de qualité des sous-titres (obligatoires après chaque transcription), le script de nettoyage JS, les règles de réessai et le chemin d'importation via l'API OpenAI/Groq, consultez hyperframes/references/transcript-guide.md.

Format de sortie

Les compositions consomment un tableau plat d'objets mot. Le champ id (w0, w1, ...) est ajouté lors de la normalisation pour des références stables dans les surcharges de sous-titres ; il est facultatif pour la rétrocompatibilité.

[
  { "id": "w0", "text": "Bonjour", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "le monde.", "start": 0.6, "end": 1.2 }
]

Suppression d'arrière-plan (remove-background)

Supprimez l'arrière-plan d'une vidéo ou d'une image afin que le sujet (généralement une personne — avatar, présentateur, tête parlante) apparaisse comme une incrustation transparente dans une composition.

npx hyperframes remove-background sujet.mp4 -o transparent.webm  # par défaut : VP9 alpha WebM
npx hyperframes remove-background sujet.mp4 -o transparent.mov   # ProRes 4444 (montage)
npx hyperframes remove-background portrait.jpg -o decoupe.png    # découpe d'une seule image
npx hyperframes remove-background sujet.mp4 -o sujet.webm \
  --background-output fond.webm                                  # les deux couches en une seule passe
npx hyperframes remove-background sujet.mp4 -o transparent.webm --device cpu
npx hyperframes remove-background --info                         # fournisseurs détectés

Utilise u2net_human_seg (MIT). Le premier lancement télécharge ~168 Mo de poids dans ~/.cache/hyperframes/background-removal/models/.

N'utilisez PAS u2net pour les autocollants détourés avec un contour blanc

remove-background (u2net) est une segmentation d'objet saillant — il segmente le corps du sujet et coupe le contour blanc de la découpe, car le trait blanc autour de la figure n'est pas « l'objet ». Pour les autocollants de messagerie transparents (Telegram, etc.) rendus avec un contour blanc sur un arrière-plan plat de couleur connue, incrustez l'arrière-plan au lieu de segmenter le sujet :

  • Remplissage par diffusion de l'arrière-plan plat. ImageDraw.floodfill de PIL amorcé à partir de points le long des quatre bords (pas ~24px), marquez les pixels remplis → alpha 0, tout le reste opaque. Cela préserve le contour blanc ET les accessoires intérieurs de même couleur ET les îlots déconnectés (une tasse volante séparée du corps garde son propre contour). Nécessite que le prompt de génération place le sujet sur un arrière-plan plat et uniforme et demande explicitement le contour blanc de la découpe.
  • Variante sans contour (plus propre qu'un retrait de contour intégré) : exécutez à nouveau chaque image par image-to-image — passez le rendu final comme --ref et invitez « recréer pose/propriétés identiques mais SUPPRIMER le contour blanc et placer sur un fond vert pur chroma-key (#00b140) », puis incrustez le vert avec une incrustation chroma douce, jamais un masque binaire (alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1), LOW≈30 HIGH≈95, plus déversement global G = min(G, max(R,B))). Un remplissage par diffusion binaire + érosion produit des bords en escalier / crénelés — floutez l'alpha binaire (GaussianBlur(0.8)) pour un bord lisse au lieu d'éroder.
  • Dimensionnement pour les autocollants de messagerie : rognez sur la boîte englobante alpha pleine et redimensionnez le côté long exactement à la cible (par exemple 512) — ne remplissez pas pour obtenir un carré de 512² (cela laisse le sujet petit avec de l'espace vide autour).

Ne s'applique PAS à : les découpes humaines pour incrustations vidéo (u2net est correct ici) ; les œuvres sans contour de découpe ; les sujets sur un arrière-plan non uniforme / chargé (le remplissage par diffusion nécessite une couleur clé plate).

Séparation des couches (--background-output)

Passez --background-output (ou -b) pour émettre une deuxième vidéo transparente en parallèle de la découpe : même source RVB, alpha est 255 − masque au lieu de masque. La découpe est le sujet avec un fond transparent ; le fond est l'environnement d'origine avec un trou transparent là où se trouvait le sujet.

FichierAlpha est…Utilisation
-o sujet.webmLe masque — sujet opaque, arrière-plan transparentCouche de premier plan, à placer par-dessus
--background-output fond.webmInverse — environnement opaque, région du sujet transparenteCouche de fond ; placez du texte ou des graphiques entre ceci et le sujet

Les deux sorties partagent le même préréglage --quality et sont issues d'une seule passe d'inférence — le coût de codage double environ, le coût de segmentation reste le même. Valide uniquement pour les entrées vidéo et les sorties .webm/.mov.

Fond troué, pas un fond nettoyé par inpainting. La région du sujet dans fond.webm est entièrement transparente — composez quelque chose d'opaque en dessous pour remplir le trou. Le seul test pour savoir si --background-output est l'outil approprié : est-ce que quoi que ce soit sera visible à travers la silhouette du sujet là où le sujet se trouvait ?

Cas d'utilisationOutil approprié
Texte/graphiques entre la découpe et le fond (raison d'être de cette commande)Trou (--background-output)
Sujet sur une scène sans rapportJuste sujet.webm ; ignorez le fond
Montrer la pièce sans la personne, seule, sans autre contenuFond nettoyé — nécessite un inpaintor (LaMa, ProPainter, E2FGVI). Pas cette commande.
Remplacer le sujet par un sujet différentFond nettoyé — idem ci-dessus

Si un utilisateur demande « la pièce sans la personne » et a l'intention de l'afficher seule, n'utilisez pas --background-output. Dites-lui qu'il a besoin d'un inpaintor.

Composition superposée typique (le cas d'utilisation canonique du trou) :

<!-- z=1 le fond alpha inversé remplit tout sauf la région du sujet -->
<video
  src="fond.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<!-- z=2 graphiques / texte entre les deux couches -->
<h1 id="headline" style="z-index:2; ...">FAITES-LE DANS HYPERFRAMES</h1>

<!-- z=3 la découpe replace le sujet par-dessus le titre -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
  <video
    src="sujet.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

Cela est fonctionnellement équivalent au motif texte-derrière-le-sujet ci-dessous, mais vous n'avez pas besoin du fichier presentateur.mp4 original dans le projet — le fond le remplace. Utile lorsque vous souhaitez fournir uniquement les deux couches transparentes et laisser l'utilisateur placer du contenu arbitraire entre elles.

Format de sortie

FormatQuand
.webm (VP9 + alpha)Par défaut. Les compositions le lisent directement via <video>.
.mov (ProRes 4444)Montage dans DaVinci/Premiere/FCP. Fichiers volumineux.
.pngDécoupe d'image unique (sujet fixe, superposé sur un fond).

Chrome décode le VP9 alpha nativement, donc le .webm s'intègre dans une composition comme n'importe quelle autre vidéo en lecture automatique muette — voir le skill hyperframes pour les conventions de pistes <video>.

Préréglages de qualité

--quality fast|balanced|best contrôle uniquement le CRF du codeur VP9 — la qualité de segmentation est fixe.

PréréglageCRFQuand
fast30Itération, fichier plus petit, correspondance couleur lâche
balanced18Par défaut. Visuellement identique pour la plupart des usages
best12Version finale / maître. Fichier le plus volumineux, correspondance la plus serrée

Motifs de composition — choisissez le bon

Le webm découpé est une copie ré-encodée du RVB de la source mp4. Ce choix a des conséquences en fonction de ce que vous placez derrière :

MotifCe qui se trouve derrière la découpeRésultat
Découpe sur une scène différente (le plus courant)Image statique, dégradé ou vidéo sans rapportRendu excellent. Le RVB de la découpe est la seule source du sujet — pas de doublement, pas de halo de bord. C'est à cela que sert remove-background.
Découpe sur son propre fichier source mp4 (texte-derrière-le-sujet)Même mp4 à partir duquel la découpe a été généréeDeux sources RVB pour la même personne. Avec --quality balanced (crf 18) par défaut, le doublement est à peine visible ; avec --quality fast (crf 30), vous verrez un léger décalage de couleur / un halo de bord.

...

[Le contenu des sections sur les autocollants de messagerie et la composition a été tronqué dans l'original, mais les parties essentielles sont traduites ci-dessus.]

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

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

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 associés