remotion-orchestrator — Ponto de Entrada do Pacote de Skills Remotion
Comando único /remotion-video
/remotion-video é o comando único para vídeos de marketing com Remotion. Ele transforma um briefing simples em um pacote de produção governado, um caminho de renderização e um relatório de evidências finais.
Regras rígidas para este comando:
- apenas uma voz; sem elenco com múltiplas vozes e sem troca de voz por cena.
- usar apenas as credenciais e configuração de voz existentes do Synthex ElevenLabs.
- nenhum novo fornecedor, nenhuma nova conta, nenhuma plataforma de conectores.
- começar com simulação (
dry-run) a menos que o operador solicite explicitamente a renderização de produção. - escrever
.harness/remotion/<jobId>/production-packet.json,script.md,preflight-report.mderender-command.sh. - nunca fazer commit de MP4s gerados.
O comando roteia através de remotion-script, remotion-production, remotion-direction, remotion-editing, remotion-integrations e remotion-professionalism, preservando o fluxo de trabalho existente do Pacote de Skills Remotion.
Ponto de entrada único para o Pacote de Skills Remotion — um conjunto de 10 skills irmãs (remotion-orchestrator, remotion-brand-research, remotion-brand-codify, remotion-designer, remotion-colour-family, remotion-motion-language, remotion-screen-storyteller, remotion-marketing-strategist, remotion-composition-builder, remotion-render-pipeline) instaladas globalmente em ~/.claude/skills/remotion-* (link simbólico para ~/Pi-Dev-Ops/skills/remotion-*). Disponível em todos os projetos, não apenas no Pi-Dev-Ops.
Portão de validação do briefing (turno 1, obrigatório)
Adotado de nexu-io/open-design (Apache-2.0). Antes de qualquer plano de ondas ser emitido, fixe o briefing. Recuse-se a prosseguir até que todos os campos obrigatórios estejam preenchidos — briefings vagos produzem planos de ondas excessivamente longos e renderizações fora da marca.
Campos obrigatórios
| Campo | Tipo | Notas |
|---|---|---|
brand | BrandSlug | Deve ser resolvido em src/brands/. Desconhecido → despachar remotion-brand-research primeiro. |
composition | Explainer | Intro | SocialAd | NIRReport | ProductDemo | v1 suporta apenas Explainer; outros retornam com aviso. |
channel | linkedin | youtube | instagram | tiktok | training | Define proporção de aspecto + disciplina de duração. |
aspectRatio | 1920x1080 | 1080x1920 | 1080x1080 | Padrão derivado do channel se omitido. |
durationSec | 15 | 30 | 60 | 90 | 120 | Define o limite de número de ondas. |
topic | string | Uma frase sobre o que o vídeo diz. "Vídeo de conscientização de marca" sozinho é recusado — deve nomear o ponto específico. |
audience | string | Herdado de BrandConfig.audience.primary se omitido, mas o fundador deve confirmar. |
Opcionais: school (substituição de estilo visual para o gerador de cores), voiceoverScript (pular storyteller se pré-escrito), referenceComposition (trabalho existente para remixar).
Condições de parada obrigatórias
topiclê como uma categoria ("nosso produto", "o lançamento") em vez de uma afirmação específica → bloqueio.composition≠Explainerna v1 sem aviso explícito de fallback → bloqueio.- Múltiplas marcas nomeadas em um único briefing → dividir em N trabalhos paralelos (uma por marca); nunca misturar.
O portão é executado antes do plano de ondas ser calculado. Um briefing bloqueado nunca chega ao despachante.
Invocação
O usuário pode invocar o pacote:
- Dizendo: "use o Pacote de Skills Remotion", "pacote remotion", "use remotion".
- Nomeando qualquer skill individual (ex.: "use remotion-designer para revisar este layout").
- Enviando um briefing que classifica como
intent: "video"viaapp/server/brief.py.
Traduz um briefing em texto livre em um trabalho de renderização estruturado e um plano de ondas que o orquestrador Pi-Dev-Ops (app/server/orchestrator.py) despacha via fan-out P3-B.
O projeto Remotion
Todas as composições, configurações de marca, helpers de movimento/cores e o ponto de entrada de renderização estão em:
../../remotion-studio/
Ao trabalhar de qualquer outro projeto, as sub-skills mudam (cd) para esse caminho antes de ler ou editar arquivos de marca/composição. O ponto de entrada da renderização é npx tsx render/render.ts ... dentro de remotion-studio.
Gatilhos
Briefing contém qualquer um de: video, explainer, promo, ad, reel, intro, outro, cta, social cut, 60s/30s/15s, render, marketing video, training video, release video, feature video, combinado com um dos identificadores de marca dr / disaster recovery / nrpg / ra / restoreassist / carsi / ccw / carpet cleaners warehouse.
Entradas
O planejador Pi-Dev-Ops (Opus 4.7) chama esta skill com:
brief— solicitação original em texto livrerepo_url— geralmentelocal:Pi-Dev-Ops/remotion-studiolinear_team_id,linear_project_id— pré-resolvidos deconfig/harness/projects.json
Saída
Um plano de ondas JSON escrito em remotion-studio/.research/wave-plans/{job_id}.json com esta estrutura:
{
"jobId": "ra-nir-explainer-2026-04-28T15-30-00",
"brand": "ra",
"composition": "Explainer",
"channel": "linkedin",
"durationSec": 60,
"topic": "RestoreAssist NIR Phase 1 standardisation",
"linear": { "teamId": "...", "projectId": "..." },
"outputPath": "output/ra-nir-explainer-2026-04-28T15-30-00.mp4",
"waves": [
{ "id": 1, "parallel": [ {"skill":"remotion-brand-research","if":"brands/ra.ts missing or stale"}, {"skill":"remotion-marketing-strategist"} ] },
{ "id": 2, "parallel": [ {"skill":"remotion-screen-storyteller"}, {"skill":"remotion-colour-family","if":"palette incomplete"}, {"skill":"remotion-motion-language","if":"motion missing"} ] },
{ "id": 3, "parallel": [ {"skill":"remotion-brand-codify","if":"any new brand artifacts"}, {"skill":"remotion-designer"} ] },
{ "id": 4, "serial": [ {"skill":"remotion-composition-builder"}, {"skill":"remotion-render-pipeline"} ] }
]
}
Disciplina de número de ondas
- ≤3 ondas para saída <30s
- ≤5 ondas para saída ≤120s
- ≤8 ondas para saída >120s
A superdecomposição é o modo de falha contra o qual isso protege.
Roteamento de composição (brief → composição)
| Sinal do briefing | composition |
|---|---|
| "explainer", "feature video", "how it works" | Explainer |
| "intro", "title card", "channel opener" | Intro (v1.1) |
| "ad", "promo", "reel", "social cut", "Instagram", "TikTok" | SocialAd (v1.1) |
| "NIR report", "inspection report", RA + "report" | NIRReport (v1.1) |
| "demo", "product walkthrough" | ProductDemo (v1.1) |
v1 suporta apenas Explainer. Outros ids de composição retornam: "{Composition} chega na v1.1 — usando Explainer com enquadramento específico do canal".
Resolução de marca
Corresponder palavras-chave → BrandSlug:
disaster recovery,dr→drnrpg→nrpgrestoreassist,ra,nir→racarsi→carsiccw,carpet cleaners warehouse→ccw
Se o briefing nomear várias marcas, peça ao planejador para dividir em N trabalhos paralelos (uma por marca) e emitir N planos de ondas. Nunca misturar marcas em uma única composição.
Roteamento Linear
Após a skill de renderização escrever o MP4, esta skill (ou a skill de renderização) abre um ticket Linear no projeto mapeado de config/harness/projects.json:
| Marca | Time Linear | projeto |
|---|---|---|
| ra | a8a52f07-63cf-4ece-9ad2-3e3bd3c15673 (RA) | 3c78358a-b558-4029-b47d-367a65beea7b |
| dr / nrpg | 43811130-ac12-47d3-9433-330320a76205 (DR) | d2c1d63b-1e85-424d-9278-efff15b0d46b |
| carsi | 91b3cd04-... (GP) | resolvido em tempo de execução |
| ccw | tempo de execução | tempo de execução |
Geração de thumbnail e imagem estática (Canva primeiro — NÃO caçar credenciais)
Para um thumbnail de vídeo, pôster ou qualquer imagem estática de marketing, o caminho confiável é o Canva MCP conectado, não uma chave de API bruta de geração de imagem:
generate-design(design_type: your_storypara 9:16,youtube_thumbnailpara 16:9) com uma consulta detalhada alinhada à marca — passe a paleta/título na consulta; o Canva renderiza texto de título de forma confiável.- Baixar as visualizações candidatas e escolher a melhor;
create-design-from-candidate→export-design(PNG no tamanho alvo WxH,export_quality: pro).
Regras rígidas (aprendidas da pior forma, 2026-07-01):
- Nunca caçar credenciais para chaves de geração de imagem. Não escanear arquivos
.envou executarvercel env pullem projetos/ambientes procurando porGEMINI_API_KEY/OPENAI_API_KEY/AI_GATEWAY_API_KEY. O classificador de modo automático bloqueia isso como exploração de credenciais, e desperdiça toda a sessão. - Variáveis de ambiente "Sensíveis" do Vercel são somente escrita —
vercel env pullretorna VAZIO. Não tentar puxar uma; obter o valor de sua fonte original ou usar Canva. - Se nenhuma ferramenta de imagem estiver conectada e nenhuma chave estiver acessível em UMA verificação direcionada, parar e perguntar ao fundador uma vez — oferecer Canva antecipadamente.
- Um quadro extraído do MP4 renderizado (ffmpeg incluído em
node_modules/@remotion/compositor-*/ffmpeg) é o fallback offline. Nota: no macOS, criar link simbólico dos arquivos*.dylibirmãos para o diretório atual para que o ffprobe/ffmpeg incluído funcione (SIP removeDYLD_*).
O que esta skill NÃO faz
- Não cria composições — isso é com
remotion-composition-builder. - Não executa
npx remotion render— isso é comremotion-render-pipeline. - Não edita arquivos BrandConfig — isso é com
remotion-brand-codify.
Ela apenas planeja + delega.
Modelo de uso por projeto
O pacote é infraestrutura compartilhada; cada projeto chamador fornece sua própria configuração de tempo de execução e chaves de API.
| Aspecto | Onde reside |
|---|---|
| Definições de skill | ~/.claude/skills/remotion-* (link simbólico → Pi-Dev-Ops/skills/remotion-*) — disponível globalmente. |
| Projeto Node Remotion (composições, configurações de marca, ponto de entrada de renderização) | ../../remotion-studio/ — substrato compartilhado único. |
| Configurações de marca | Synthex/packages/brand-config/src/brands/{slug}.ts — uma fonte de verdade por marca, usado por todos os projetos que renderizam para essa marca. (Migrado de Pi-Dev-Ops/remotion-studio/src/brands/ conforme RA-1985 / Synthex SYN-897.) |
| Chaves de API (ElevenLabs, Telegram, Supabase, Linear, licença Remotion) | .env / .env.local do projeto chamador. Skills leem process.env no momento da renderização. |
| Saída MP4 renderizada | Diretório .remotion-renders/ do projeto chamador por padrão. Substituir com --out=. |
Adicionando uma nova marca para seu projeto
Se seu projeto (ex.: Synthex) precisar renderizar para uma marca que ainda não está em src/brands/:
- Executar
remotion-brand-researchnas fontes públicas da marca. - Executar
remotion-brand-codifypara produzirSynthex/packages/brand-config/src/brands/{slug}.ts. - Estender a união
BrandSlugemSynthex/packages/brand-config/src/types.ts. - Registrar em
Synthex/packages/brand-config/src/brands/index.ts. - Executar
npm run typecheckdeSynthex/packages/brand-config/(depoisnpm run buildpara regenerardist/).
Marcas atualmente registradas: dr, nrpg, ra, carsi, ccw, synthex, unite.