Communitygithub.com

alecs5am/ralphy

Preprocesamiento de activos para composiciones HyperFrames: narración de texto a voz (Kokoro), transcripción de audio/video (Whisper) y eliminación de fondos para superposiciones transparentes (u2net).

¿Qué es ralphy?

Este skill proporciona tres comandos CLI para generar activos multimedia para composiciones HyperFrames: `tts` para sintetizar voz a partir de texto usando Kokoro-82M, `transcribe` para crear un archivo JSON con marcas de tiempo palabra por palabra usando Whisper, y `remove-background` para eliminar fondos de imágenes o videos usando u2net_human_seg. Es especialmente útil para creadores de contenido y desarrolladores que necesitan generar locuciones, transcribir discursos para subtítulos, o crear superposiciones transparentes sin depender de APIs de pago. Cada comando descarga su modelo automáticamente en la primera ejecución y lo almacena en caché local. El skill soporta múltiples idiomas, selección de voces, y produce salidas listas para integrar directamente en proyectos HyperFrames.

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

Preguntar en tu IA favorita

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

Vista previa

Del README del skill

Documentación

Preprocesamiento de Medios para HyperFrames

Tres comandos CLI que generan activos para composiciones: tts (voz), transcribe (marcas de tiempo) y remove-background (video transparente). Cada uno descarga un modelo en la primera ejecución y lo almacena en caché en ~/.cache/hyperframes/. Coloca la salida en el proyecto, luego refiérete a ella desde el HTML de la composición; consulta el skill hyperframes para las convenciones de elementos de audio/video.

Texto a Voz (tts)

Genera audio de voz localmente con Kokoro-82M. Sin clave API.

npx hyperframes tts "Texto aquí" --voice af_nova --output narracion.wav
npx hyperframes tts script.txt --voice bf_emma --output narracion.wav
npx hyperframes tts --list                       # las 54 voces

Selección de Voz

Empareja la voz con el contenido. La opción predeterminada es af_heart.

Tipo de contenidoVozPor qué
Demo de productoaf_heart/af_novaCálida, profesional
Tutorial / guíaam_adam/bf_emmaNeutral, fácil de seguir
Marketing / promociónaf_sky/am_michaelEnérgica o autoritaria
Documentaciónbf_emma/bm_georgeInglés británico claro, formal
Casual / socialaf_heart/af_skyCercana, natural

Multilingüe

Los IDs de voz codifican el idioma en la primera letra: a=inglés americano, b=inglés británico, e=español, f=francés, h=hindi, i=italiano, j=japonés, p=portugués brasileño, z=mandarín. La CLI detecta automáticamente la configuración regional del fonemizador a partir del prefijo — no necesitas --lang cuando la voz coincide con el texto.

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

Usa --lang solo para anular la detección automática (acentos estilizados). Códigos válidos: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. La fonemización en idiomas no ingleses requiere espeak-ng a nivel de sistema (brew install espeak-ng / apt-get install espeak-ng).

Velocidad

  • 0.7-0.8 — tutorial, contenido complejo, accesibilidad
  • 1.0 — ritmo natural (predeterminado)
  • 1.1-1.2 — intros, transiciones, contenido dinámico
  • 1.5+ — raramente apropiado; probar con cuidado

Guiones Largos

Para más de unos pocos párrafos, escribe en un archivo .txt y pasa la ruta. Las entradas de más de ~5 minutos de voz pueden beneficiarse de dividirse en segmentos.

Requisitos

Python 3.8+ con kokoro-onnx y soundfile (pip install kokoro-onnx soundfile). El modelo se descarga en el primer uso (~311 MB + ~27 MB de voces, almacenado en caché en ~/.cache/hyperframes/tts/).

Transcripción (transcribe)

Genera un transcript.json normalizado con marcas de tiempo a nivel de palabra.

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

Regla de Idioma (No Negociable)

Nunca uses modelos .en a menos que el usuario indique explícitamente que el audio está en inglés. Los modelos .en (small.en, medium.en) traducen audio no inglés a inglés en lugar de transcribirlo. Esto destruye silenciosamente el idioma original.

  1. Idioma conocido y no inglés → --model small --language <código> (sin sufijo .en)
  2. Idioma conocido e inglés → --model small.en
  3. Idioma desconocido → --model small (sin .en, sin --language) — whisper detecta automáticamente

El modelo predeterminado es small, no small.en.

Tamaños de Modelo

ModeloTamañoVelocidadCuándo usarlo
tiny75 MBMás rápidoVista previa rápida, pruebas de pipeline
base142 MBRápidoClips cortos, audio claro
small466 MBModeradoPredeterminado — la mayoría del contenido
medium1.5 GBLentoContenido importante, audio ruidoso, música
large-v33.1 GBMás lentoCalidad de producción

Música con voces: comenzar con medium como mínimo; las pistas producidas a menudo necesitan importación manual de SRT/VTT. Para controles de calidad de subtítulos (obligatorios después de cada transcripción), el JS de limpieza, las reglas de reintento y la ruta de importación de API de OpenAI/Groq, consulta hyperframes/references/transcript-guide.md.

Formato de Salida

Las composiciones consumen un array plano de objetos de palabra. El campo id (w0, w1, ...) se agrega durante la normalización para referencias estables en anulaciones de subtítulos; es opcional para compatibilidad hacia atrás.

[
  { "id": "w0", "text": "Hola", "start": 0.0, "end": 0.5 },
  { "id": "w1", "text": "mundo.", "start": 0.6, "end": 1.2 }
]

Eliminación de Fondo (remove-background)

Elimina el fondo de un video o imagen para que el sujeto (típicamente una persona — avatar, presentador, cabeza parlante) se sitúe como una superposición transparente en una composición.

npx hyperframes remove-background sujeto.mp4 -o transparente.webm  # predeterminado: VP9 alpha WebM
npx hyperframes remove-background sujeto.mp4 -o transparente.mov   # ProRes 4444 (edición)
npx hyperframes remove-background retrato.jpg -o recorte.png       # recorte de imagen única
npx hyperframes remove-background sujeto.mp4 -o sujeto.webm \
  --background-output plato.webm                                   # ambas capas en un solo paso
npx hyperframes remove-background sujeto.mp4 -o transparente.webm --device cpu
npx hyperframes remove-background --info                           # proveedores detectados

Usa u2net_human_seg (MIT). La primera ejecución descarga ~168 MB de pesos a ~/.cache/hyperframes/background-removal/models/.

NO uses u2net para pegatinas troqueladas con contorno blanco

remove-background (u2net) es segmentación de objetos salientes — segmenta el cuerpo del sujeto y corta el contorno blanco troquelado, porque el trazo blanco alrededor de la figura no es "el objeto". Para pegatinas transparentes de Telegram / mensajería renderizadas con un contorno blanco sobre un fondo de color plano conocido, clavea el fondo en lugar de segmentar el sujeto:

  • Relleno por inundación del fondo plano. PIL ImageDraw.floodfill sembrado desde puntos a lo largo de los cuatro bordes (paso ~24px), marca los píxeles rellenos → alfa 0, todo lo demás opaco. Esto preserva el contorno blanco Y los objetos interiores del mismo color Y las islas desconectadas (una taza voladora separada del cuerpo mantiene su propio contorno). Requiere que el prompt de generación coloque al sujeto sobre un fondo plano uniforme y solicite el contorno blanco troquelado explícitamente.
  • Variante sin contorno (más limpia que eliminar un contorno horneado): vuelve a ejecutar cada imagen imagen-a-imagen — pasa el renderizado final como --ref y solicita "recrea la misma pose/props pero QUITA el contorno blanco y ponlo en un fondo verde croma puro plano (#00b140)", luego clavea el verde con una clave croma suave, nunca una máscara binaria (alpha = clip((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1), LOW≈30 HIGH≈95, más despill global G = min(G, max(R,B))). Un relleno por inundación binario + erosión produce bordes escalonados/aliasing — difumina la alfa binaria (GaussianBlur(0.8)) para un borde suave en lugar de erosionar.
  • Tamaño para pegatinas de mensajería: recorta al bbox alfa sólido y escala el lado largo exactamente al objetivo (ej. 512) — no rellenes a un cuadrado de 512² (deja al sujeto pequeño con espacio vacío alrededor).

NO se aplica a: recortes humanos para superposiciones de video (u2net es correcto ahí); arte sin contorno troquelado; sujetos sobre un fondo no uniforme/ocupado (el relleno por inundación necesita un color clave plano).

Separación de Capas (--background-output)

Usa --background-output (o -b) para emitir un segundo video transparente junto con el recorte: mismo RGB de origen, alfa es 255 − máscara en lugar de máscara. El recorte es el sujeto con un fondo transparente; el plato es el entorno original con un agujero transparente donde estaba el sujeto.

ArchivoAlfa es…Úsalo para
-o sujeto.webmLa máscara — sujeto opaco, fondo transparenteCapa frontal, colocar encima
--background-output plato.webmInversa — entorno opaco, región del sujeto transparenteCapa inferior; colocar texto o gráficos entre esta y el sujeto

Ambas salidas comparten el mismo preset --quality y se ejecutan desde una sola inferencia — el costo de codificación se duplica aproximadamente, el costo de segmentación se mantiene igual. Solo válido para entradas de video y salidas .webm/.mov.

Plato con agujero, no un plato limpio inpintado. La región del sujeto en plato.webm es completamente transparente — compón algo opaco debajo para llenar el agujero. La única prueba para saber si --background-output es la herramienta correcta: ¿se verá algo a través de la silueta del sujeto donde solía estar el sujeto?

Caso de usoHerramienta correcta
Texto/gráficos entre el recorte y el plato (razón de existir de este comando)Agujero (--background-output)
Sujeto sobre una escena no relacionadaSolo sujeto.webm; ignora el plato
Mostrar la habitación sin la persona, sola sobre ningún otro contenidoPlato limpio — necesita un inpintador (LaMa, ProPainter, E2FGVI). No este comando.
Reemplazar al sujeto con un sujeto diferentePlato limpio — igual que arriba

Si un usuario pide "la habitación sin la persona" y tiene la intención de mostrarla sola, no uses --background-output. Diles que necesitan un inpintador.

Composición típica en capas (el caso de uso canónico del agujero):

<!-- z=1 el plato con alfa inversa llena todo excepto la región del sujeto -->
<video
  src="plato.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<!-- z=2 gráficos / texto viven entre las dos capas -->
<h1 id="headline" style="z-index:2; ...">HÁZLO EN HYPERFRAMES</h1>

<!-- z=3 el recorte flota al sujeto de vuelta sobre el titular -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
  <video
    src="sujeto.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

Esto es funcionalmente equivalente al patrón texto-detrás-de-sujeto a continuación, pero no necesitas el presenter.mp4 original en el proyecto — el plato lo reemplaza. Útil cuando quieres enviar solo las dos capas transparentes y permitir que el usuario coloque contenido arbitrario entre ellas.

Formato de Salida

FormatoCuándo
.webm (VP9 + alfa)Predeterminado. Las composiciones lo reproducen directamente via <video>.
.mov (ProRes 4444)Edición en DaVinci/Premiere/FCP. Archivos grandes.
.pngRecorte de imagen única (sujeto fijo, superpuesto sobre un fondo).

Chrome decodifica alfa VP9 de forma nativa, por lo que el .webm se conecta a una composición como cualquier otro video con reproducción automática silenciada; consulta el skill hyperframes para las convenciones de pista <video>.

Presets de Calidad

--quality fast|balanced|best controla solo el CRF del codificador VP9 — la calidad de segmentación es fija.

PresetCRFCuándo
fast30Iterando, archivo más pequeño, coincidencia de color menos estricta
balanced18Predeterminado. Visualmente idéntico para la mayoría de usos
best12Entrega final / maestra. Archivo más grande, coincidencia más precisa

Patrones de Composición — elige el correcto

El webm recortado es una copia re-codificada del RGB del mp4 de origen. Esa elección tiene consecuencias dependiendo de lo que coloques detrás:

PatrónQué hay detrás del recorteResultado
Recorte sobre una escena diferente (más común)Imagen estática, degradado o video no relacionadoSe ve genial. El RGB del recorte es la única fuente del sujeto — sin duplicación, sin halos en los bordes. Para esto está diseñado remove-background.
Recorte sobre su propio mp4 de origen (texto-detrás-de-sujeto)El mismo mp4 del que se generó el recorteDos fuentes RGB para la misma persona. Con --quality balanced (crf 18) la duplicación es apenas visible; con --quality fast (crf 30) verás un ligero cambio de color / borde en ... [truncado para traducción]

…

[truncado para traducción]

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 relacionados