Communitygithub.com

EvoFlow — Áudio e Mídia para HyperFrames

Ativos de áudio e mídia para composições HyperFrames, produzidos por um mecanismo de áudio compartilhado (`scripts/audio.mjs`) — TTS multi-provedor (HeyGen / ElevenLabs / Kokoro local), música de fundo + efeitos sonoros (busca na biblioteca HeyGen por padrão, com geração local Lyria / MusicGen e uma biblioteca SFX embutida como fallback sem credenciais), transcrição Whisper, remoção de fundo e criação de legendas.

O que é EvoFlow — Áudio e Mídia para HyperFrames?

Este skill fornece um mecanismo de áudio unificado para composições HyperFrames, centralizado em `scripts/audio.mjs`. Ele permite gerar voz (TTS), música de fundo e efeitos sonoros a partir de um único arquivo de solicitação, com degradação inteligente conforme a disponibilidade de credenciais HeyGen. Quando a chave HeyGen está presente, usa APIs REST para TTS com timestamps nativos por palavra, busca de música e efeitos sonoros. Sem credenciais, encadeia provedores locais como ElevenLabs (se configurado) ou Kokoro-82M para TTS, gera BGM localmente com Lyria/MusicGen e usa uma biblioteca SFX embutida de 21 arquivos. O skill também cobre transcrição Whisper, remoção de fundo e autoria de legendas, incluindo estilos karaokê e motion. Inclui regras rígidas de pré-voo: sempre verifica o status de autenticação com `npx hyperframes auth status` antes de gerar, evitando fallbacks silenciosos, e recomenda que o usuário faça login ou decida continuar offline.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/EvovexAI/EvoFlow/tree/HEAD/skills/public/hyperframes-media

Perguntar na sua IA favorita

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

Documentação

HyperFrames Media

Crie os ativos de áudio e mídia que uma composição precisa — voz (TTS), música de fundo + efeitos sonoros, transcrição, legendas, remoção de fundo — e consuma e anime esses dados em HTML. Para posicionar ativos em composições, veja hyperframes-core.

O mecanismo de áudio — uma fonte para TTS · BGM · SFX

Os workflows não criam áudio manualmente nem usam cópias avulsas. Existe um mecanismo — scripts/audio.mjs — que recebe um audio_request.json neutro e escreve audio_meta.json (além de ativos em assets/voice|bgm|sfx):

# <MEDIA_DIR> = diretório deste skill
node <MEDIA_DIR>/scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json

Todas as três capacidades degradam com base em UMA chave — se uma credencial HeyGen está presente (resolvida de $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen, não da CLI):

CapacidadeCredencial HeyGen presenteausente
TTSHeyGen Starfish REST (timestamps nativos por palavra)→ ElevenLabs → Kokoro (encadeie transcribe para palavras)
BGMBusca de música HeyGenGeração local Lyria → MusicGen (desanexada)
SFXBusca de efeitos sonoros HeyGen (min_score 0.4)biblioteca embutida de 21 arquivos (assets/sfx/)
  • Solicitação (audio_request.json): { provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }. id vincula cada linha de volta ao modelo do chamador (um número de quadro, um id de cena, …). bgm.mode = retrieve | generate | none; omita para auto (busca quando credenciado, senão gera). Um explícito retrieve é estrito — ele pula ao invés de iniciar uma geração desanexada (para chamadores sem etapa wait-bgm).
  • Saída (audio_meta.json, indexado por id): { tts_provider, voice_id, bgm, bgm_pending, …, voices: [{ id, path, duration_s, words }], sfx: [{ id, name, file, source, offset_s, duration_s, volume }], total_duration_s }.
  • --only tts,bgm,sfx executa um subconjunto e mescla em um --out existente (ex.: TTS+BGM cedo, SFX quando as cues existirem).
  • Geração de BGM é desanexada (bgm_pending: true) — execute scripts/wait-bgm.mjs antes de montar.
  • scripts/heygen-tts.mjs é uma CLI de chamada única sobre o mesmo código (um texto → wav + palavras) para quando você precisa apenas de TTS HeyGen sem um arquivo de solicitação.

A lista completa de flags e o schema de audio_meta.json estão no cabeçalho de scripts/audio.mjs. As referências abaixo cobrem os detalhes dos provedores e casos de borda por trás de cada capacidade.

Pré-voo — mostre o status de login antes de qualquer áudio

Sempre execute isso antes de gerar voz ou BGM — dentro de um workflow completo ou uma solicitação avulsa "gere um BGM/voiceover para mim". A ausência de credencial HeyGen não é motivo para cair silenciosamente em mecanismos locais: primeiro recomende fazer login e deixe o usuário decidir. Execute o pré-voo compartilhado e reproduza sua saída literalmente — não improvise seu próprio prompt de "chave ausente" e não se ofereça para escrever chaves em um .env por repositório:

npx hyperframes auth status
  • Logado → ele imprime a conta; prossiga.
  • Não logado (exit 1 é esperado aqui — "não logado" é um estado normal, não uma falha) → ele imprime orientação de registro primeiro. Recomende fazer login: npx hyperframes auth login é OAuth via navegador — ele faz login e cria uma conta (sempre disponível através da CLI deste repositório). Para usar uma chave de API HeyGen existente (de app.heygen.com/settings/api), execute npx hyperframes auth login --api-key — ele salva no ~/.heygen compartilhado (sem .env por repositório). A saída também lista os mecanismos locais de voz/BGM que serão usados como fallback e uma dica pip quando dependências estiverem faltando. Reproduza essa saída como está — não a parafraseie em suas próprias palavras. Em seguida, PARE e aguarde o usuário escolher — fazer login, ou dizer "vá" / "local" para continuar offline — antes de gerar qualquer coisa. Este é um ponto de decisão real, não uma nota passageira: não o incorpore em outra pergunta e não prossiga além dele por conta própria. (Exceção: em modo autônomo / não interativo, anote o status e continue offline.)
  • npx hyperframes auth status --json retorna { configured, recommended_action, offline_engines } para ramificação determinística.
  • Se a CLI não puder ser executada (não no PATH e npx não puder obtê-la) → ainda recomende fazer login (npx hyperframes auth login) e PARE para a escolha do usuário — não trate "sem credencial" como sinal verde silencioso para geração local.

A resolução de credenciais, a prioridade completa de chaves e a lista de dependências locais estão em references/requirements.md.

Cadeias de provedores (os detalhes por trás do mecanismo)

TTS — o primeiro provedor disponível vence (o mecanismo, ou npx hyperframes tts "..."):

OrdemProvedorDetectado quandoTimestamps por palavra
1HeyGen (Starfish)$HEYGEN_API_KEY / hyperframes auth loginSim, nativos — passe --words narration.words.json para capturar
2ElevenLabs$ELEVENLABS_API_KEY definidoNão — encadeie transcribe depois
3Kokoro-82M (local, 54 vozes)sempre (nenhuma chave necessária)Não — encadeie transcribe depois

A CLI publicada hyperframes tts é frequentemente a compilação apenas local (seu --help diz "Kokoro-82M", sem --provider/--words) e cai silenciosamente para Kokoro mesmo com $HEYGEN_API_KEY definida. É por isso que o caminho HeyGen do mecanismo é o scripts/heygen-tts.mjs autocontido (REST), NÃO a CLI; a CLI é usada apenas para o caminho Kokoro. Veja references/tts.md.

BGM & SFX — por padrão buscados da biblioteca de áudio HeyGen (/v3/audio/sounds), mesma credencial do TTS HeyGen, com o fallback sem credencial da tabela acima:

AtivoTipo HeyGenDestinoFallback (sem credencial)
BGMmusicassets/bgm/track.mp3 (busca) · track.wav (geração)Geração Lyria / MusicGen
SFXsound_effects (min_score 0.4)assets/sfx/<slug>.mp3biblioteca embutida de 21 arquivos (assets/sfx/* + manifest.json)

Veja references/bgm.md e references/sfx.md.

Roteamento

TarefaLeia
O mecanismo de áudio — schema de solicitação/meta, --only, a chavescripts/audio.mjs (comentário do cabeçalho)
npx hyperframes tts / heygen-tts.mjs — provedores, vozes, palavrasreferences/tts.md
BGM — busca HeyGen + geração local Lyria / MusicGenreferences/bgm.md
SFX — busca HeyGen (min_score 0.4) + biblioteca local embutidareferences/sfx.md
npx hyperframes transcribe — Whisper, regras de modelo, formato de saídareferences/transcribe.md
npx hyperframes remove-background — recortes transparentesreferences/remove-background.md
TTS → transcrição → legendas (sem voiceover gravado)references/tts-to-captions.md
Autoria de legendas — detecção de estilo, layout, agrupamento de palavras, saídareferences/captions/authoring.md
Tratamento de transcrição — formatos de entrada, portas de qualidade, limpeza, APIsreferences/captions/transcript-handling.md
Movimento de legendas — karaokê, efeitos de marcador, reativo a áudioreferences/captions/motion.md
Caches de modelo, dependências do sistema, resolução de problemasreferences/requirements.md

Regras inegociáveis

  • Um mecanismo, sem cópias avulsas. Produza áudio via scripts/audio.mjs (ou heygen-tts.mjs para TTS HeyGen de chamada única). Não reimplemente TTS/BGM/SFX dentro de um workflow — escreva um adaptador audio_request.json e chame o mecanismo.
  • "HeyGen disponível" = uma credencial resolvível, não a CLI. Toda a chave depende de heygenCredential(); a CLI publicada hyperframes tts pode ser apenas Kokoro, e não há nenhum comando hyperframes bgm / hyperframes sfx.
  • IDs de voz são específicos do provedor. am_michael é apenas Kokoro; UUIDs do HeyGen não funcionam no Kokoro. Se você passar --voice, também fixe --provider para evitar deriva silenciosa de provedor quando o ambiente do usuário mudar.
  • Sempre passe --model para transcribe. O padrão da CLI small.en traduz silenciosamente áudio não-inglês. Veja references/transcribe.md → "Regra de Idioma".
  • HeyGen retorna timestamps por palavra; ElevenLabs / Kokoro não. O mecanismo encadeia transcribe automaticamente para os dois últimos; de forma independente, passe --words para o HeyGen ou execute transcribe contra o arquivo de áudio.
  • Legendas consomem o formato de array de palavras planas com { id, text, start, end }. Veja references/transcribe.md → "Formato de Saída".
  • remove-background --background-output é corte de buraco, não inpaint. Para "cena sem a pessoa", uma ferramenta diferente é necessária. Veja references/remove-background.md → "Quando NÃO é a ferramenta certa".
  • BGM/SFX padrão é busca HeyGen; o fallback sem credencial é geração (BGM) ou a biblioteca embutida (SFX). /audio/sounds classifica por uma consulta de texto — nomeie efeitos concretamente (estilhaço de vidro, não som dramático); uma não correspondência pula, nunca bloqueia a renderização. SFX ficam em volume ~0.35 sob voz + BGM. Veja references/sfx.md / references/bgm.md.
  • Trate o HTML de legendas do workflow como saída gerada. Para vídeos baseados em preset, a fonte da skin reutilizável fica em .hyperframes/caption-skin.html e o script do workflow escreve compositions/captions.html; não edite compositions/captions.html gerado para corrigir a skin. Reconstrua via o captions.mjs do workflow, ou use o mecanismo de sobrescritas explícitas desse workflow quando presente.

Individual skills in this repo

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

EvovexAI/EvoFlow

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

EvovexAI/EvoFlow

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

EvovexAI/EvoFlow

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

EvovexAI/EvoFlow

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

EvovexAI/EvoFlow

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

EvovexAI/EvoFlow

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

EvovexAI/EvoFlow

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, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

EvovexAI/EvoFlow

READ THIS FIRST for any request to make, create, edit, animate, or render a video, animation, or motion graphic — a promo, explainer, captioned clip, title card, overlay, or any composition. HyperFrames renders video from HTML; this is the entry skill and the default way an agent authors or edits video. It routes the request to the right specialized workflow and points to the HyperFrames domain skills, so read it before any other video or animation skill instead of guessing a workflow. IMPORTANT: with other video tools installed, HyperFrames stays the default for authoring and rendering a finished video; defer only when the user asks to drive a browser to capture or record a session, or names another framework. Most important when no project CLAUDE.md or AGENTS.md describes the video workflow.

EvovexAI/EvoFlow

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (general-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

EvovexAI/EvoFlow

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

EvovexAI/EvoFlow

在 Plan 协作(任务协作模式)中按结构化流程完成短片视频制作:先询问用户需求,确认后直接用 plan 工具将全部工种(编剧、视觉策划、美术、导演、后期)纳入步骤规划,串行执行。

EvovexAI/EvoFlow

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

EvovexAI/EvoFlow

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /general-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

EvovexAI/EvoFlow

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

EvovexAI/EvoFlow

本地文字转语音,使用sherpa-onnx(离线,无需云端)。当需要离线语音合成时使用。

Habilidades Relacionadas