Communitygithub.com

remotion-voiceover

Skill do Remotion para Claude Code, Codex e Cursor que adiciona narração por IA e legendas a um projeto de vídeo Remotion. Transforma um roteiro de narração em áudio de voz por cena, um arquivo voiceover.json com timeline (startFrame, durationInFrames) e captions.json compatível com @remotion/captions, além de SRT/VTT, com clonagem de voz a partir de um clipe de referência.

O que é remotion-voiceover?

Este skill permite que agentes de IA como Claude Code, Codex e Cursor adicionem narração realista e legendas sincronizadas a projetos de vídeo Remotion. O processo começa com a definição de um roteiro (script.md) que descreve as falas por cena, permitindo escolher vozes de atores pré-definidos ou clonar uma voz a partir de um clipe de áudio de referência. O skill gera automaticamente os arquivos de áudio (WAV/MP3), um arquivo voiceover.json com a timeline completa (frames de início e duração para cada linha), e arquivos de legenda nos formatos JSON (Caption[] para @remotion/captions), SRT e VTT, com quebras de linha inteligentes. O usuário deve fornecer a chave de API MIRAGEA_API_KEY (nunca perguntada em chat) e pode optar por executar o gerador via Python (embutido, sem instalação) ou via Node CLI. O skill também oferece recursos avançados como sintaxe especial no roteiro para definir emoções, pausas, velocidade e substituições de texto nas legendas, além de suporte a várias cenas e vozes diferentes no mesmo vídeo.

Funciona com✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/RTY2345RR/miragea-agent-skills/tree/HEAD/skills/remotion-voiceover

Perguntar na sua IA favorita

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

Documentação

Narração e legendas Remotion

Dê a um projeto Remotion um narrador real. O agente escreve ou recebe um roteiro de narração, dubla cena por cena e conecta o áudio e as legendas sincronizadas com o tempo à composição. As vozes e a clonagem de voz vêm do motor de voz Miragea (https://miragea.ai/v1); nunca substitua por outro TTS.

Saídas (pasta padrão public/voiceover/, para que staticFile() possa carregá-las):

ArquivoO que é
<cena>-NN.wavum clipe por linha falada
voiceover.wav (+ .mp3 com --mp3)a trilha de narração completa
voiceover.jsontimeline: fps, durationInFrames, cenas e linhas com startMs, startFrame, durationInFrames, src
captions.jsonCaption[] para @remotion/captions (text, startMs, endMs, timestampMs, confidence)
captions.srt, captions.vttarquivos de legenda com segmentos balanceados (sem palavras isoladas)

0. Pré-condições

  • A variável de ambiente MIRAGEA_API_KEY deve estar definida (chaves em: https://miragea.ai/workspace/api). Nunca peça a chave no chat e nunca a imprima. Ajuda para configurar: "Instale https://miragea.ai/skills/miragea-audio/install.md".
  • Execute python scripts/remotion_voiceover.py check uma vez. Ele lista os modelos e as únicas tags de emoção válidas.
  • Dois mecanismos para o mesmo trabalho, escolha um:
    • Python (incluído, sem instalação): python scripts/remotion_voiceover.py generate script.md
    • Node CLI: npx -y github:RTY2345RR/remotion-voiceover generate script.md (mesmo formato de script; adiciona HyperFrames audio_request.json). O script incluído pode chamá-lo com python scripts/remotion_voiceover.py npx generate script.md.

1. Briefing (pergunte apenas o que estiver faltando)

  • O roteiro, ou a fonte para escrevê-lo (página do produto, README, resumo). Mantenha as linhas curtas e faladas; uma frase por linha.
  • A voz: um ID de ator, ou uma URL de clipe de referência pública mais as palavras exatas faladas nele (melhor clone). As URLs dos clipes devem ser diretamente acessíveis (não links de resolução do Hugging Face).
  • Estrutura de cenas se a composição já tiver <Sequence>s; combine os títulos das cenas com eles.

2. Escreva script.md

---
voices:
  narrator: https://exemplo.com/me.wav | Palavras exatas faladas no clipe.
  convidado: ACTOR_ID
voice: narrator
fps: 30
---
# Gancho
Seu vídeo Remotion finalmente tem uma narração de verdade.

# Lançamento [voice: convidado]
[emotion: animado] Versão [[2.0|dois ponto zero]] chega hoje.
[pause: 600ms]
Renderize uma vez e as legendas caem no quadro certo.
  • # Título = uma cena (seu slug é o identificador da cena). [voice: nome], [emotion: tag], [speed: 1.1], [pause: 600ms] funcionam em uma linha ou em um título.
  • [[texto da legenda|texto falado]] mostra 2.0 nas legendas enquanto a voz diz "dois ponto zero". Escreva números, versões e URLs desta forma.
  • Execute plan primeiro para uma execução de teste (sem chamadas de API) e confirme scripts longos com o usuário.

3. Gerar

python scripts/remotion_voiceover.py generate script.md (detecta automaticamente a pasta public/ do Remotion; --out para sobrescrever, --fps, --scene-gap 600, --gap 250, --max-chars 32, --mp3).

  • Todas as linhas são enviadas de uma vez e coletadas; linhas clonadas podem levar alguns minutos.
  • Se reportar que uma tarefa ainda está em execução, execute novamente o mesmo comando. Requisições idênticas se reconectam ao mesmo trabalho, linhas finalizadas são reutilizadas, e apenas linhas editadas são regravadas. --take 2 força uma nova gravação.

4. Conecte à composição

import {AbsoluteFill, Audio, Sequence, staticFile, useCurrentFrame, useVideoConfig} from 'remotion';
import {createTikTokStyleCaptions, Caption} from '@remotion/captions';
import timeline from '../public/voiceover/voiceover.json';
import captions from '../public/voiceover/captions.json';

export const Narrated: React.FC = () => {
  const frame = useCurrentFrame();
  const {fps} = useVideoConfig();
  const {pages} = createTikTokStyleCaptions({captions: captions as Caption[], combineTokensWithinMilliseconds: 1200});
  const ms = (frame / fps) * 1000;
  const page = pages.find((p) => ms >= p.startMs && ms < p.startMs + p.durationMs);
  return (
    <AbsoluteFill>
      {timeline.lines.map((l) => (
        <Sequence key={l.id} from={l.startFrame} durationInFrames={l.durationInFrames}>
          <Audio src={staticFile(l.src)} />
        </Sequence>
      ))}
      {page && <AbsoluteFill style={{justifyContent: 'flex-end', alignItems: 'center', paddingBottom: 160}}>
        <div style={{fontSize: 64, fontWeight: 800, color: 'white', textShadow: '0 4px 12px #000'}}>{page.text}</div>
      </AbsoluteFill>}
    </AbsoluteFill>
  );
};
  • Defina a duração da composição a partir da timeline: durationInFrames={timeline.durationInFrames} em Root.tsx, ou leia voiceover.json em calculateMetadata.
  • Os <Sequence> das cenas podem usar timeline.scenes[i].startFrame / durationInFrames para que os visuais acompanhem a narração.
  • Instale o suporte a legendas se estiver faltando: npx remotion add @remotion/captions.
  • Um único <Audio src={staticFile(timeline.audio)} /> também funciona em vez de clipes por linha.

5. Entrega

Informe os arquivos, a duração total em segundos e quadros, e o próximo passo (renderizar com npx remotion render). Apenas use voz ou conteúdo clonado para o qual o usuário tenha direitos.

Exemplo

examples/ contém uma execução real: script.md (narradora feminina + final masculino, ambos clonados), voiceover.mp3, captions.srt, captions.json e voiceover.json.

Habilidades Relacionadas