Communitygithub.com

alecs5am/ralphy

Pré-processamento de assets para composições HyperFrames — narração de texto para fala (Kokoro), transcrição de áudio/vídeo (Whisper) e remoção de fundo para sobreposições transparentes (u2net).

O que é ralphy?

O skill `alecs5am/ralphy` fornece três comandos CLI para pré-processamento de mídia em composições HyperFrames: `tts` para gerar narração de texto para fala localmente com Kokoro-82M, `transcribe` para transcrever áudio/vídeo com timestamps em nível de palavra usando Whisper (modelos otimizados para cada idioma), e `remove-background` para remover o fundo de vídeos e imagens com u2net, produzindo sobreposições transparentes em formato WebM com alpha. Todos os comandos baixam seus modelos automaticamente na primeira execução e os armazenam em cache sob `~/.cache/hyperframes/`, sem necessidade de chaves de API externas. O skill suporta palestras multissistema, com recomendações detalhadas de voz e tamanho de modelo conforme o tipo de conteúdo e qualidade desejada, e documenta práticas avançadas como separação de camadas com `--background-output` e composição em HTML. Ideal para desenvolvedores que precisam integrar voiceovers, legendas e elementos sobrepostos em projetos multimídia sem depender de serviços online.

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

Perguntar na sua IA favorita

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

Prévia

Do README da skill

Documentação

Pré-processamento de Mídia HyperFrames

Três comandos CLI que produzem assets para composições: tts (fala), transcribe (timestamps) e remove-background (vídeo transparente). Cada um baixa um modelo na primeira execução e o armazena em cache em ~/.cache/hyperframes/. Coloque a saída no projeto e referencie-a no HTML da composição — veja o skill hyperframes para as convenções de elementos de áudio/vídeo.

Texto para Fala (tts)

Gere áudio de fala localmente com Kokoro-82M. Sem chave de API.

npx hyperframes tts "Texto aqui" --voice af_nova --output narracao.wav
npx hyperframes tts script.txt --voice bf_emma --output narracao.wav
npx hyperframes tts --list                       # todas as 54 vozes

Seleção de Voz

Combine a voz ao conteúdo. O padrão é af_heart.

Tipo de conteúdoVozMotivo
Demonstração de produtoaf_heart/af_novaCaloroso, profissional
Tutorial / instruçõesam_adam/bf_emmaNeutro, fácil de seguir
Marketing / promoçãoaf_sky/am_michaelEnergético ou autoritário
Documentaçãobf_emma/bm_georgeInglês britânico claro, formal
Casual / socialaf_heart/af_skyAcessível, natural

Multilíngue

Os IDs das vozes codificam o idioma na primeira letra: a=Inglês Americano, b=Inglês Britânico, e=Espanhol, f=Francês, h=Hindi, i=Italiano, j=Japonês, p=Português Brasileiro, z=Mandarim. O CLI detecta automaticamente a localidade do fonemizador a partir do prefixo — não precisa de --lang quando a voz corresponde ao 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

Use --lang apenas para substituir a detecção automática (sotaques estilizados). Códigos válidos: en-us, en-gb, es, fr-fr, hi, it, pt-br, ja, zh. A fonemização em idiomas não-ingleses requer espeak-ng no sistema (brew install espeak-ng / apt-get install espeak-ng).

Velocidade

  • 0.7-0.8 — tutorial, conteúdo complexo, acessibilidade
  • 1.0 — ritmo natural (padrão)
  • 1.1-1.2 — introduções, transições, conteúdo animado
  • 1.5+ — raramente apropriado; teste com cuidado

Scripts Longos

Para mais do que alguns parágrafos, escreva em um arquivo .txt e passe o caminho. Entradas com mais de ~5 minutos de fala podem se beneficiar da divisão em segmentos.

Requisitos

Python 3.8+ com kokoro-onnx e soundfile (pip install kokoro-onnx soundfile). Os modelos são baixados no primeiro uso (~311 MB + ~27 MB de vozes, armazenados em cache em ~/.cache/hyperframes/tts/).

Transcrição (transcribe)

Produza um transcript.json normalizado com timestamps em nível de palavra.

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

Regra de Idioma (Inegociável)

Nunca use modelos .en a menos que o usuário declare explicitamente que o áudio está em inglês. Modelos .en (small.en, medium.en) traduzem áudio não-inglês para inglês em vez de transcrevê-lo. Isso destrói silenciosamente o idioma original.

  1. Idioma conhecido e não-inglês → --model small --language <código> (sem sufixo .en)
  2. Idioma conhecido e inglês → --model small.en
  3. Idioma desconhecido → --model small (sem .en, sem --language) — whisper detecta automaticamente

O modelo padrão é small, não small.en.

Tamanhos de Modelo

ModeloTamanhoVelocidadeQuando usar
tiny75 MBMais rápidoPré-visualizações rápidas, teste de pipeline
base142 MBRápidoClipes curtos, áudio claro
small466 MBModeradoPadrão — a maioria dos conteúdos
medium1.5 GBLentoConteúdo importante, áudio ruidoso, música
large-v33.1 GBMais lentoQualidade de produção

Música com vocais: comece com medium no mínimo; faixas produzidas frequentemente precisam de importação manual de SRT/VTT. Para verificações de qualidade de legendas (obrigatórias após cada transcrição), o JS de limpeza, regras de repetição e o caminho de importação da API OpenAI/Groq, veja hyperframes/reference/transcript-guide.md.

Formato de Saída

As composições consomem um array plano de objetos de palavra. O campo id (w0, w1, ...) é adicionado durante a normalização para referências estáveis em substituições de legendas; é opcional para compatibilidade retroativa.

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

Remoção de Fundo (remove-background)

Remova o fundo de um vídeo ou imagem para que o sujeito (tipicamente uma pessoa — avatar, apresentador, cabeça falante) fique como uma sobreposição transparente em uma composição.

npx hyperframes remove-background sujeito.mp4 -o transparente.webm  # padrão: VP9 alpha WebM
npx hyperframes remove-background sujeito.mp4 -o transparente.mov   # ProRes 4444 (edição)
npx hyperframes remove-background retrato.jpg -o recorte.png         # recorte de imagem única
npx hyperframes remove-background sujeito.mp4 -o sujeito.webm \
  --background-output fundo.webm                                   # ambas as camadas em uma passada
npx hyperframes remove-background sujeito.mp4 -o transparente.webm --device cpu
npx hyperframes remove-background --info                           # provedores detectados

Usa u2net_human_seg (MIT). A primeira execução baixa ~168 MB de pesos para ~/.cache/hyperframes/background-removal/models/.

NÃO use u2net para adesivos recortados com contorno branco

remove-background (u2net) é segmentação de objeto saliente — ele segmenta o corpo do sujeito e corta o contorno branco do recorte, porque o traço branco ao redor da figura não é "o objeto". Para adesivos transparentes de Telegram / mensagens renderizados com um contorno branco sobre um fundo de cor plana conhecida, key o fundo em vez de segmentar o sujeito:

  • Preenchimento por inundação do fundo plano. PIL.ImageDraw.floodfill semeado a partir de pontos ao longo das quatro bordas (passo ~24px), marque pixels preenchidos → alpha 0, todo o resto opaco. Isso preserva o contorno branco E props internos da mesma cor E ilhas desconectadas (um copo voando separado do corpo mantém seu próprio contorno). Requer que o prompt de geração coloque o sujeito em um fundo uniforme e plano e peça pelo contorno branco recortado explicitamente.
  • Variante sem contorno (mais limpa do que remover um contorno assado): re-execute cada imagem imagem-para-imagem — passe o render finalizado como --ref e peça "recrie a pose/props idênticos mas REMOVA o contorno branco e coloque em um chroma-key verde puro (#00b140) plano", então key o verde com um chroma key suave, nunca uma máscara binária (alpha = limitar((HIGH-(G-max(R,B)))/(HIGH-LOW),0,1), LOW≈30 HIGH≈95, mais despill global G = min(G, max(R,B))). Um preenchimento por inundação binário + erosão produz bordas serrilhadas / aliased — desfoque o alpha binário (GaussianBlur(0.8)) para uma borda suave em vez de erodir.
  • Dimensionamento para adesivos de mensagens: corte para a bbox alpha sólida e dimensione o lado maior para exatamente o alvo (ex. 512) — não preencha para um quadrado 512² (isso deixa o sujeito pequeno com espaço vazio ao redor).

NÃO se aplica a: recortes humanos para sobreposições de vídeo (u2net está correto lá); arte sem contorno recortado; sujeitos em um fundo não uniforme / ocupado (preenchimento por inundação precisa de uma cor chave plana).

Separação de Camadas (--background-output)

Passe --background-output (ou -b) para emitir um segundo vídeo transparente junto com o recorte: mesmo RGB de origem, alpha é 255 − máscara em vez de máscara. O recorte é o sujeito com um fundo transparente; a placa é o entorno original com um buraco transparente onde o sujeito estava.

ArquivoAlpha é…Use para
-o sujeito.webmA máscara — sujeito opaco, fundo transparenteCamada de primeiro plano, coloque no topo
--background-output fundo.webmInverso — entorno opaco, região do sujeito transparenteCamada inferior; coloque texto ou gráficos entre esta e o sujeito

Ambas as saídas compartilham a mesma predefinição --quality e são executadas a partir de uma única passada de inferência — o custo de codificação aproximadamente dobra, o custo de segmentação permanece o mesmo. Válido apenas para entradas de vídeo e saídas .webm/.mov.

Placa com furo, não uma placa limpa inpainted. A região do sujeito em fundo.webm é totalmente transparente — componha algo opaco sob ela para preencher o buraco. O único teste para saber se --background-output é a ferramenta certa: alguma coisa será visível através da silhueta do sujeito onde o sujeito costumava estar?

Caso de usoFerramenta correta
Texto/gráficos entre o recorte e a placa (a razão de existir deste comando)Furo (--background-output)
Sujeito em uma cena não relacionadaApenas sujeito.webm; ignore a placa
Mostrar a sala sem a pessoa, sozinha sobre nenhum outro conteúdoPlaca limpa — precisa de um inpaintador (LaMa, ProPainter, E2FGVI). Não este comando.
Substituir o sujeito por um sujeito diferentePlaca limpa — mesma que acima

Se um usuário pedir por "a sala com a pessoa removida" e pretender exibi-la sozinha, não recorra a --background-output. Diga a eles que precisam de um inpaintador.

Composição em camadas típica (o caso de uso canônico de furo):

<!-- z=1 a placa com alpha inverso preenche tudo exceto a região do sujeito -->
<video
  src="fundo.webm"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>

<!-- z=2 gráficos/texto ficam entre as duas camadas -->
<h1 id="headline" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>

<!-- z=3 o recorte flutua o sujeito de volta sobre o título -->
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3">
  <video
    src="sujeito.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

Isso é funcionalmente equivalente ao padrão texto-atrás-do-sujeito abaixo, mas você não precisa do apresentador.mp4 original no projeto — a placa o substitui. Útil quando você quer enviar apenas as duas camadas transparentes e permitir que o usuário coloque conteúdo arbitrário entre elas.

Formato de Saída

FormatoQuando
.webm (VP9 + alpha)Padrão. Composições reproduzem isso diretamente via <video>.
.mov (ProRes 4444)Edição no DaVinci/Premiere/FCP. Arquivos grandes.
.pngRecorte de imagem única (sujeito parado, sobreposto a um fundo).

O Chrome decodifica VP9 alpha nativamente, então o .webm se encaixa em uma composição como qualquer outro vídeo com autoplay mudo — veja o skill hyperframes para as convenções de faixa <video>.

Predefinições de Qualidade

--quality fast|balanced|best controla apenas o CRF do codificador VP9 — a qualidade da segmentação é fixa.

PredefiniçãoCRFQuando
fast30Iterando, arquivo menor, correspondência de cor mais solta
balanced18Padrão. Visualmente idêntico para a maioria dos usos
best12Master / entrega final. Arquivo maior, correspondência mais precisa

Padrões de Composição — escolha o certo

O webm recortado é uma cópia re-codificada do RGB da fonte mp4. Essa escolha tem consequências dependendo do que você coloca atrás dele:

PadrãoO que está atrás do recorteResultado
Recorte sobre uma cena diferente (mais comum)Imagem estática, gradiente ou vídeo não relacionadoFica ótimo. O RGB do recorte é a única fonte do sujeito — sem duplicação, sem halo na borda. É para isso que remove-background foi construído.
Recorte sobre seu próprio mp4 de origem (texto-atrás-do-sujeito)Mesmo mp4 de onde o recorte foi geradoDuas fontes RGB para a mesma pessoa. Na --quality balanced padrão (crf 18) a duplicação é quase imperceptível; na --quality fast (crf 30) você verá uma leve mudança de cor / halo na borda. Considere --quality best (crf 12) para correspondência quase perfeita.

Para o padrão texto-atrás-do-sujeito sem duplicação, use a separação de camadas (--background-output, descrito acima) — a placa substitui o mp4 de origem, então não há duas cópias do sujeito.

Sobreposição de legenda (overlay-caption)

Adicione uma barra de legenda sobre um vídeo recortado. O desenho acontece no espaço do canvas: --width e --height devem corresponder às dimensões do vídeo de saída. Usa ffmpeg com o filtro subtitles.

npx hyperframes overlay-caption \
  -i sem_legenda.mp4 \
  -o legendado.mp4 \
  --srt legendas.srt \
  --width 1200 \
  --height 1200

Formato

O SRT de entrada deve seguir o formato de legendas SubRip. A saída é um arquivo de vídeo único com as legendas queimadas no quadro (não separadas).

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.

Habilidades Relacionadas