Communitygithub.com

delorenj/skills

Pré-processamento de ativos 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 é skills?

Este pacote de habilidades fornece três comandos CLI para pré-processar mídia antes de usá-la em composições HyperFrames: `tts` gera narração de alta qualidade localmente com Kokoro-82M, `transcribe` produz um transcript.json com timestamps por palavra usando Whisper, e `remove-background` isola o sujeito de um vídeo ou imagem usando u2net_human_seg. Cada comando baixa seu modelo na primeira execução e o armazena em cache em `~/.cache/hyperframes/`, eliminando a necessidade de chaves de API. A habilidade inclui seleção de voz multilíngue, regras de modelagem para transcrição (incluindo a importante regra de evitar modelos `.en` para áudio não-inglês), e padrões avançados de composição como separação de camadas para texto entre o sujeito e o fundo. É parte do ecossistema HyperFrames, projetado para desenvolvedores que constroem composições interativas de vídeo na web.

Funciona com~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/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 ativos 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 faça referência a ela a partir do HTML da composição — veja a habilidade hyperframes para as convenções de elementos de áudio/vídeo.

Texto para Fala (tts)

Gere áudio de fala localmente com Kokoro-82M. Sem necessidade de 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 com o conteúdo. O padrão é af_heart.

Tipo de conteúdoVozPor quê
Demonstração de produtoaf_heart/af_novaCalorosa, profissional
Tutorial / guiaam_adam/bf_emmaNeutra, fácil de seguir
Marketing / promoçãoaf_sky/am_michaelEnergética ou autoritária
Documentaçãobf_emma/bm_georgeInglês britânico claro, formal
Casual / socialaf_heart/af_skyAcessível, natural

Multilíngue

Os IDs de voz 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. A CLI detecta automaticamente a localidade do fonemizador a partir do prefixo — não é necessário --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 instalado 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 — intros, 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). O modelo é baixado no primeiro uso (~311 MB + ~27 MB de vozes, armazenado em cache em ~/.cache/hyperframes/tts/).

Transcrição (transcribe)

Produza um transcript.json normalizado com timestamps por 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 (Não Negociável)

Nunca use modelos .en a menos que o usuário afirme explicitamente que o áudio é 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 <code> (sem sufixo .en)
  2. Idioma conhecido e inglês → --model small.en
  3. Idioma desconhecido → --model small (sem .en, sem --language) — o whisper detecta automaticamente

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

Tamanhos de Modelo

ModeloTamanhoVelocidadeQuando usar
tiny75 MBMais rápidoVisualizaçõ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 legenda (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/references/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 legenda; é opcional para compatibilidade reversa.

[
  { "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/.

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

Passe --background-output (ou -b) para emitir um segundo vídeo transparente junto com o recorte: mesma RGB de origem, alfa é 255 − máscara em vez de máscara. O recorte é o sujeito com fundo transparente; o fundo é os arredores originais com um buraco transparente onde o sujeito estava.

ArquivoAlfa é…Use para
-o sujeito.webmA máscara — sujeito opaco, fundo transparenteCamada frontal, coloque por cima
--background-output fundo.webmInverso — arredores opacos, 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 de --quality e executam a partir de uma única passagem 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.

Fundo com buraco recortado, não um fundo limpo com inpaint. A região do sujeito em fundo.webm é totalmente transparente — componha algo opaco por baixo 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 ele estava?

Caso de usoFerramenta certa
Texto/gráficos entre o recorte e o fundo (razão de existir deste comando)Buraco recortado (--background-output)
Sujeito sobre uma cena não relacionadaApenas sujeito.webm; ignore o fundo
Mostrar a sala sem a pessoa, sozinha sobre nenhum outro conteúdoFundo limpo — precisa de um inpaint (LaMa, ProPainter, E2FGVI). Não é este comando.
Substituir o sujeito por um sujeito diferenteFundo limpo — o mesmo que acima

Se um usuário pedir "a sala com a pessoa removida" e planejar exibi-la sozinha, não use --background-output. Diga a ele que precisa de uma ferramenta de inpaint.

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

<!-- z=1 o fundo com alfa 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 vivem entre as duas camadas -->
<h1 id="titulo" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>

<!-- z=3 o recorte coloca 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 — o fundo o substitui. Útil quando você quer enviar apenas as duas camadas transparentes e deixar o usuário colocar conteúdo arbitrário entre elas.

Formato de Saída

FormatoQuando
.webm (VP9 + alpha)Padrão. As composições reproduzem isso diretamente via <video>.
.mov (ProRes 4444)Edição no DaVinci/Premiere/FCP. Arquivos grandes.
.pngRecorte de imagem única (assunto estático, 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 reprodução automática sem áudio — veja a habilidade hyperframes para as convenções de faixa de <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 frouxa
balanced18Padrão. Visualmente idêntico para a maioria dos usos
best12Versão final / entrega final. Arquivo maior, correspondência mais precisa

Padrões de Composição — Escolha o Correto

O webm de recorte é uma cópia recodificada da RGB do mp4 de origem. 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. A RGB do recorte é a única fonte do sujeito — sem duplicação, sem halo na borda. É para isso que remove-background foi feito.
Recorte sobre seu próprio mp4 de origem (texto-atrás-do-sujeito)Mesmo mp4 do qual o recorte foi geradoDuas fontes RGB para a mesma pessoa. No padrão --quality balanced (crf 18) a duplicação é quase invisível; em --quality fast (crf 30) você verá uma leve mudança de cor / halo na borda. Use --quality best (crf 12) para versões finais.
Recorte sobre uma tomada diferente da mesma pessoaFilmagem do mesmo sujeitoParecerá duas pessoas diferentes sobrepostas. Não faça isso.

Texto-atrás-do-sujeito (título atrás de um apresentador):

<video
  src="apresentador.mp4"
  id="bg"
  data-start="0"
  data-duration="6"
  data-track-index="0"
  muted
  playsinline
></video>
<h1 id="titulo" style="z-index:2; ...">FAÇA EM HYPERFRAMES</h1>
<div class="cutout-wrap" style="position:absolute;inset:0;z-index:3;opacity:0">
  <video
    src="apresentador.webm"
    data-start="0"
    data-duration="6"
    data-track-index="1"
    muted
    playsinline
  ></video>
</div>

Duas regras principais:

  1. Envolva o vídeo de recorte em um <div> sem temporização e anime a opacidade do wrapper, não a do elemento de vídeo. O framework força opacidade:1 em clipes ativos (qualquer elemento com data-start/data-duration), então animar a opacidade do vídeo diretamente é silenciosamente substituído. O wrapper não tem atributos data-*, então é controlado pelo seu CSS/GSAP.
  2. Ambos os vídeos usam data-start="0" e data-media-start="0" para que o framework os decodifique em sincronia a partir de t=0. Montar o recorte tardiamente (data-start=3.3) introduz uma busca + aquecimento que termina um quadro fora do mp4 base — visível como um quadro de desalinhamento no corte.

Em seguida, inverta a opacidade do wrapper com GSAP no corte: tl.set(cutoutWrap, { opacity: 1 }, 3.3).

TTS → Transcrição → Legendas

Quando não houver narração pré-gravada, gere uma e transcreva-a de volta para obter timestamps por palavra para legendas:

npx hyperframes tts script.txt --voice af_heart --output narracao.wav
npx hyperframes transcribe narracao.wav   # → transcript.json

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

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.

delorenj/skills

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.

delorenj/skills

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.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

delorenj/skills

Generate speech using the self-hosted voxxy (vox) TTS service at https://vox.delo.sh. Use when the user asks to speak, say, narrate, synthesize speech, clone a voice, create a voice, add or register a voice, pipe TTS, or control voice qualities by description (e.g. "a young woman with a cheerful voice"). Handles HTTP API usage, voice profile management, description-based voice design, cloning, MCP registration, and integration patterns for new platforms.

delorenj/skills

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

Habilidades Relacionadas