Vídeos do YouTube a partir de código: Shorts e formato longo
Você constrói um vídeo como um motion designer faria, mas em código: páginas HTML desenham qualquer quadro a partir de um valor de tempo, a narração define o ritmo, e scripts renderizam, mixam e provam que o resultado é válido antes de alguém fazer o upload.
script.json ──► OmniVoice (MCP) ──► voice/*.wav ──► timeline.py ──► timeline.js ─────────┐
│ format: short | long | long-4k ▼
└─ style preset ─► style.css / style.js ─────────────────────► page(s).html (seek(t), K.layout por formato)
│ check_page ► stills ► render (chunks em cache)
music (apenas se solicitado) ─► make_music.py ─┐ ▼
sound effects (CC0) ────────────────────────────┴─► mix_audio.py ─► mix.wav ─► mux ─► final.mp4 ─► verify_video.py
(formato longo também: chapters.txt, captions.srt, thumbnail.jpg)
$SKILL abaixo significa a pasta desta skill. Tudo roda através de um único CLI: python3 $SKILL/scripts/short.py <comando>.
Formatos
short | long | long-4k | |
|---|---|---|---|
| Quadro | 1080×1920 (9:16) | 1920×1080 (16:9) | página 1920×1080, saída 3840×2160 |
| Duração | ≤ 180 s (ideal < 60 s) | qualquer (tip. 5–15 min) | qualquer |
| Zona segura | x 60–940, y 288–1440 (UI do Shorts) | x 96–1824, y 54–1026 (título seguro) | mesma que long |
| Legendas | embutidas (aparência do estilo) | captions.srt para YouTube; opcionalmente embutidas | mesma que long |
| Extras | — | capítulos, uma página por capítulo, miniatura 1280×720 | mesma |
Os perfis ficam em engine/formats.json. As páginas usam K.W/K.H e uma tabela K.layout({short, long}), para que um mesmo projeto possa ser construído em ambos os formatos. Leia reference/long-form.md para qualquer vídeo 16:9.
O que está na pasta
| Caminho | O que é |
|---|---|
scripts/short.py | O pipeline CLI: doctor, styles, init, style, kit, timeline, check, stills, thumb, music, mix, render, mux, verify, build |
scripts/timeline.py | Durações da voz → tempos das cenas, dicas de palavras, legendas, dicas de efeitos sonoros, snap rítmico, segmentos de página, capítulos, SRT |
scripts/import_voice.py | Importa um clipe do OmniVoice: converte, corta silêncio, rejeita takes TTS com defeito |
scripts/make_music.py | Música de fundo sintetizada (7 humores), na grade rítmica, qualquer duração. Apenas quando o usuário pedir música |
scripts/mix_audio.py | Voz + música (ducking) + efeitos sonoros → −14 LUFS, pico verdadeiro ≤ −1.5 dBTP |
scripts/verify_video.py | O portão de correção: tamanho, aspecto, codec, fps, contagem de quadros, sincronia A/V, loudness, quadros pretos/congelados, capítulos, folha da zona segura |
engine/formats.json | Perfis de formato (tamanhos, zonas seguras, padrões de legenda, limites) |
engine/render.cjs | Captura Playwright → ffmpeg H.264 (desfoque de movimento, intervalos de quadro, captura 2× para 4K), folhas de contato |
engine/check_page.cjs | Verificações pré-renderização: contrato da página, fontes, determinismo, zona segura, legendas, tamanho do texto, quadros vazios |
engine/kit.js | O kit de animação (molas, dicas, legendas, transições, layouts por formato, draw/write estilo Manim) |
template/ | Um vídeo funcional completo (estilo editorial) que é construído em ambos os formatos |
styles/ | 8 presets de estilo: style.json + STYLE.md; 3b1b-math e kodekloud-devops têm demos completos em ambos os formatos |
assets/ | Fontes (OFL/MIT) e efeitos sonoros CC0 |
reference/ | Leia estes quando chegar na etapa correspondente (tabela no final) |
Fluxo de trabalho
0. Configuração (primeira vez em uma máquina)
bash $SKILL/scripts/setup.sh # playwright + chromium em ~/.cache/yt-video, numpy/scipy
python3 $SKILL/scripts/short.py doctor
1. Briefing (uma rodada de perguntas, depois trabalhe)
Pergunte em uma mensagem (use AskUserQuestion quando disponível); pule o que o usuário já disse:
- Formato: Short (9:16) ou formato longo (16:9, 1080p ou 4K). Infira quando for óbvio ("um Short", "um vídeo de 10 minutos").
- Tópico e a única coisa que o espectador deve lembrar. Um roteiro, artigo ou URL, se tiver.
- Estilo:
short.py styles. Padrãoeditorial. Leiastyles/<nome>/STYLE.mdassim que escolhido. - Voz: clonagem (clipe de referência + sua transcrição), design ("feminina, jovem adulta, tom grave, sotaque britânico"), ou o padrão. Veja
reference/voice-omnivoice.md. - Música: desligada a menos que peçam. Se sim: humor (
make_music.py --list). Nunca adicione música que não foi solicitada. - Duração: Shorts 20–45 s (máx 180). Formato longo: alvo do usuário; planeje capítulos.
2. Escreva o roteiro e obtenha aprovação
Leia reference/shorts-design.md (Shorts) ou reference/long-form.md (16:9). Escreva script.json (esquema em reference/page-contract.md): uma ideia por cena; o visual de cada cena nomeia qual palavra falada cada mudança visual atinge; cenas de formato longo recebem títulos de chapter e, para vídeos mais longos, uma page por capítulo. Mostre ao usuário a tabela de cenas (id, linha, visual, palavras de dica; capítulos para formato longo) e aguarde aprovação ou edições antes de gerar o áudio. Nunca invente fatos, números, citações ou resultados; valores de exemplo em mockups de interface são aceitáveis e devem ser listados como ilustrativos.
3. Crie o projeto
python3 $SKILL/scripts/short.py init videos/<slug> --style <estilo> --format short|long|long-4k
Copia o template (ou o demo/ do estilo), kit.js, fontes e tokens de estilo. Coloque seu script.json aprovado no lugar (mantenha seu format).
4. Narração com OmniVoice (MCP) → voice/<id-da-cena>.wav
Siga reference/voice-omnivoice.md: encontre as ferramentas MCP do OmniVoice, gere um clipe por cena com as mesmas configurações de voz e importe cada um:
python3 $SKILL/scripts/import_voice.py <clipe> videos/<slug> <id-da-cena> --text "<a linha>"
Falha em takes silenciosos, cortados ou implausivelmente rápidos/lentos — regenere esses. Se o OmniVoice não estiver acessível, informe; você ainda pode construir os visuais com tempos estimados e adicionar a voz depois.
5. Timeline
python3 $SKILL/scripts/short.py timeline videos/<slug>
Escreve timeline.js (tempos de cena e palavra, segmentos, capítulos) além de out/captions.srt e, com capítulos, out/chapters.txt. Os visuais atingem as palavras através de K.cue('cena', 'palavra').
6. Construa a(s) página(s)
Leia reference/page-contract.md, reference/kit-api.md, reference/scene-patterns.md e o STYLE.md do estilo. Dê a cada layout uma entrada K.layout({short, long}) quando o vídeo puder existir em ambos os formatos. Cada mudança visual deve estar em uma palavra de dica.
7. Verifique antes de renderizar (barato, pega a maioria dos erros)
python3 $SKILL/scripts/short.py check videos/<slug> # toda página deve PASSAR
python3 $SKILL/scripts/short.py stills videos/<slug> # out/stills*.png, zona segura em vermelho
Olhe os stills você mesmo. Corrija qualquer coisa vazia, cortada, sobreposta, ilegível, fora do estilo, ou que não corresponda à sua palavra. O quadro 0 já deve mostrar o gancho.
8. Música (apenas se solicitada) e mixagem
python3 $SKILL/scripts/short.py music videos/<slug> # não faz nada quando a música está desligada
python3 $SKILL/scripts/short.py mix videos/<slug>
Veja reference/music-and-sound.md.
9. Rascunho → revisão → final
python3 $SKILL/scripts/short.py build videos/<slug> --draft # 30 fps, sem desfoque de movimento, 1080p: cópia rápida para revisão
python3 $SKILL/scripts/short.py build videos/<slug> --final # desfoque de movimento, crf 16, 4K quando long-4k
build executa timeline → check → music → mix → render → mux → verify e para na primeira falha. As renderizações são em blocos e em cache, então uma reconstrução após uma edição refaz apenas o que mudou. Envie o rascunho primeiro; informe quanto tempo o final levará antes de iniciá-lo (os finais de formato longo podem demorar; execute-os em segundo plano).
10. Verifique e entregue
verify_video.py é executado dentro de build; o MP4 só está pronto quando exibir VERIFY PASSED. Abra out/verify_sheet_<modo>.png (quadro 0 + um quadro por cena, zonas de UI/segurança em vermelho) e olhe. reference/verification.md explica cada verificação.
Para formato longo, execute também short.py thumb videos/<slug> (ou renderize um thumbnail.html dedicado).
Entregue: o MP4, a pasta do projeto (index.html pode ser visualizado no navegador com a trilha sonora real) e uma breve nota: cenas ou capítulos, o que é ilustrativo, configurações de voz, humor da música (ou "sem música"), o resumo da verificação (LUFS, pico verdadeiro, duração); para formato longo também chapters.txt, captions.srt e a miniatura. Você não pode ouvir: forneça ao usuário timestamps para verificar com os ouvidos (o gancho, o momento com mais efeitos sonoros, o momento mais alto da música, o início de cada capítulo).
Regras mais importantes
seek(t)é uma função pura do tempo. Nada deMath.random,Date.now, animações/transições CSS ou timers no caminho de renderização. O verificador garante isso.- O texto permanece dentro da zona segura do formato. Nunca use 1080/1920 fixo: use
K.W,K.H,K.SAFE,K.layout. - Algo significativo está na tela no quadro 0; algo se move a cada 1–2 s (Shorts) ou a cada poucos segundos (formato longo).
- Os visuais atingem palavras faladas (
K.cue), não tempos estimados. - Música apenas mediante solicitação. Efeitos sonoros seguem o padrão do estilo (o usuário pode desligá-los).
- Os estilos são inspirados pelos criadores nomeados; nunca use seus logotipos, mascotes, personagens, introduções ou nomes na tela.
- Nunca diga que o áudio "soa bem" — reporte os números medidos e os timestamps para verificação.
Arquivos de referência
| Leia quando | Arquivo |
|---|---|
| Escrevendo um Short | reference/shorts-design.md |
| Qualquer coisa 16:9 / formato longo | reference/long-form.md |
| Construindo páginas, esquema script.json | reference/page-contract.md |
| Usando o kit de ferramentas | reference/kit-api.md |
| Projetando cenas | reference/scene-patterns.md |
| Escolhendo / fazendo um estilo | styles/README.md, styles/<nome>/STYLE.md |
| Gerando narração | reference/voice-omnivoice.md |
| Música e efeitos sonoros | reference/music-and-sound.md |
| Uma verificação falhou | reference/verification.md, reference/troubleshooting.md |