Communitygithub.com

shengdabai/Tony-Claude-Code-Skills

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

O que é Tony-Claude-Code-Skills?

Este conjunto de habilidades fornece três comandos CLI (`tts`, `transcribe`, `remove-background`) para pré-processar mídia em composições HyperFrames. O comando `tts` gera narração localmente usando o modelo Kokoro-82M, sem necessidade de chave de API, suportando 54 vozes multilíngues. O comando `transcribe` produz arquivos `transcript.json` com timestamps em nível de palavra usando Whisper, com regras cuidadosas de seleção de modelo para evitar a tradução acidental de áudio não-inglês. O comando `remove-background` utiliza u2net para criar vídeos e imagens com fundo removido, incluindo suporte para separação de camadas (recorte + placa). Todos os comandos baixam seus modelos automaticamente na primeira execução e os armazenam em cache. A habilidade também cobre o encadeamento completo de TTS → transcrição para gerar legendas sincronizadas. É útil para desenvolvedores que precisam criar narrações, legendas ou sobreposições de vídeo com transparência para projetos HyperFrames.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shengdabai/Tony-Claude-Code-Skills/tree/HEAD/skills/hyperframes-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 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 / guiaam_adam/bf_emmaNeutro, fácil de acompanhar
Marketing / promoaf_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 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 fonetizador 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 para 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 — 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). O modelo é baixado na primeira execução (~311 MB + ~27 MB de vozes, armazenado 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 (Innegociá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 o 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, testar 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 geralmente 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 uma matriz plana 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, pessoa falando) 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 placa.webm                                   # ambas as camadas em uma passagem
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: mesmo RGB da fonte, alfa é 255 − máscara em vez de máscara. O recorte é o sujeito com fundo transparente; a placa é o ambiente original com um buraco transparente onde o sujeito estava.

ArquivoAlfa é…Use para
-o sujeito.webmA máscara — sujeito opaco, fundo transparenteCamada de primeiro plano, coloque por cima
--background-output placa.webmInverso — ambiente opaco, região do sujeito transparenteCamada de fundo; 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 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.

Placa com furo, não uma placa limpa com preenchimento. A região do sujeito em placa.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 ficará visível através da silhueta do sujeito onde o sujeito estava?

Caso de usoFerramenta certa
Texto/gráficos entre o recorte e a placa (razão de existir deste comando)Furo (--background-output)
Sujeito sobre 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 inpaint (LaMa, ProPainter, E2FGVI). Não é este comando.
Substituir o sujeito por um sujeito diferentePlaca limpa — mesma situação acima

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

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

<!-- z=1 a placa com alfa inverso preenche tudo exceto a região do sujeito -->
<video
  src="placa.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="headline" 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 — a placa 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 com <video>.
.mov (ProRes 4444)Edição em 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 muted-autoplay — veja a 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. Maior arquivo, correspondência mais precisa

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

O webm recortado é uma cópia recodificada do 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 relacionadoÓtimo resultado. O RGB do recorte é a única fonte do sujeito — sem duplicação, sem halo nas bordas. É para isso que remove-background foi criado.
Recorte sobre seu próprio mp4 de origem (texto-atrás-do-sujeito)Mesmo mp4 do qual o recorte foi geradoDuas fontes de RGB para a mesma pessoa. Na predefiniçã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 nas bordas. Use --quality best (crf 12) para masters.
Recorte sobre uma tomada diferente da mesma pessoaFilmagem do mesmo sujeitoVai parecer 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="headline" 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 essenciais:

  1. Envolva o vídeo recortado em um <div> sem temporização e anime a opacidade do wrapper, não do elemento de vídeo. O framework força opacity:1 em clipes ativos (qualquer elemento com data-start/data-duration), então animar a opacidade do vídeo diretamente é silenciosamente sobrescrito. 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 resulta em 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 → Transcrever → Legendas

Quando não há narração pré-gravada, gere uma e a transcreva de volta para obter timestamps em nível de palavra para legendas:

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

# chain the output

Individual skills in this repo

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

shengdabai/Tony-Claude-Code-Skills

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

shengdabai/Tony-Claude-Code-Skills

接收抖音、小红书、微信视频号等短视频链接或分享文案,查询作品/账号数据并提取语音文字稿,按作者和标题归档为 Markdown。用户希望完整解析短视频、取得数据或文字稿时使用;运行前检查 TikHub 与轻抖使用凭证,缺少时用新手能理解的方式引导购买和安全配置。

shengdabai/Tony-Claude-Code-Skills

Read-only queue dashboard for workspace-aware ship. (gstack)

shengdabai/Tony-Claude-Code-Skills

Anime.js adapter patterns for HyperFrames. Use when writing Anime.js animations or timelines inside HyperFrames compositions, registering animations on window.__hfAnime, making Anime.js seek-driven and deterministic, or translating Anime.js examples into render-safe HyperFrames HTML.

shengdabai/Tony-Claude-Code-Skills

Author a new HyperFrames registry block (caption style, VFX block, transition, lower third) or component (text effect, overlay, snippet) and ship it as an upstream PR to the hyperframes repo. Use ONLY when the user wants to CONTRIBUTE to the public catalog — for in-project caption/transition authoring use the `hyperframes` skill, for installing existing registry items use the `hyperframes-registry` skill.

shengdabai/Tony-Claude-Code-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.

shengdabai/Tony-Claude-Code-Skills

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

shengdabai/Tony-Claude-Code-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.

Habilidades Relacionadas