Orinkle/ideaform

Vídeo Explicativo Construtivista · Workflow

Um eixo temporal principal, três downstreams derivados dele.

① Roteiro            ② TTS define eixo                ③ Variação BGM            ④ Vídeo final
   Texto    ──→   Trilha de narração (eixo temporal) ──→   Música LMMS (camadas) ──→   Renderização Remotion + integração de áudio + capa
                          │                        ▲
                          └──── Pontos de transição de camada ────┘

• Quadros por segundo são determinados pela velocidade natural da narração (não o contrário).
• Os pontos de variação do BGM coincidem com as transições de camada da narração.
• O vídeo final é alinhado à trilha de narração como base; o BGM serve apenas como fundo.

---

0. Início: Leia o contrato de caminhos (esta etapa não pode ser pulada)

Este skill não procura ferramentas sozinho; todos os caminhos vêm do contrato escrito pela skill de configuração de ambiente:

$VW_CONTRACT  (padrão ~/.config/ideaform/toolchain.json)

CONTRACT="${VW_CONTRACT:-$HOME/.config/ideaform/toolchain.json}"
source "$(dirname "$CONTRACT")/env.sh"     # Exporta VW_NODE / VW_VENV / VW_FFMPEG / …

Três verificações obrigatórias antes de começar:

1. O arquivo de contrato existe? Se não → peça ao usuário para executar primeiro o skill ideaform-setup.
2. A schema_version é compatível com este skill? Se não → solicite reexecução do skill de configuração de ambiente.
3. verified_at é null? Sim → Aviso ao usuário: "Ambiente não passou na verificação de fumaça". Corrija antes de prosseguir. Além disso, tools.lmms.stkdir_ok deve ser true, caso contrário o BGM ficará silencioso sem erro.

Referência rápida dos campos principais:

Uso	Campo do contrato
Executar script TTS (edge-tts no venv)	tools.venv.python
Sintetizar áudio/vídeo	tools.ffmpeg.path / tools.ffprobe.path
Renderizar vídeo	tools.remotion.project / tools.remotion.browser.resolved
Renderizar BGM	tools.lmms.apprun
Diretório temporário (deve ser em disco grande)	tmpdir

⚠️ O tmpdir no contrato não é opcional. O /tmp local tem apenas 10 MB; tanto o empacotamento do Remotion quanto a instalação do pip escrevem nele → ENOSPC. Cada comando do Remotion deve incluir TMPDIR.

⚠️ Caminhos nunca devem ser resolvidos (resolved symlinks). Os caminhos gerenciados da toolchain contêm links simbólicos; resolver o interpretador do venv pode perder o contexto do venv, resultando em falha de importação de pacotes. Veja raiz do repositório docs/03-ContratoCaminhos.md.

---

1. Visão geral dos quatro estágios

Estágio	O que faz	Entrada	Saída (tudo no workspace)	Referência
① Roteiro	Transforma a entrada do usuário em um roteiro com camadas	Entrada do usuário	script.md + falas.txt (camadas marcadas)	references/stage1-script.md
② TTS define eixo	Mede velocidade natural → projeta timeline → gera trilha de narração	falas.txt	plan.json / timeline.ts / voice.wav	references/stage2-tts.md
③ Variação BGM	Limites de camada → plano de variação → LMMS gera trilha	plan.json + marcações de camada	bgm-plan.json / bgm.wav	references/stage3-bgm.md
④ Vídeo final	Remotion organiza vídeo + integra áudio + renderiza + capa	timeline.ts + áudio + bgm-plan.json	final.mp4 + cover.png	references/stage4-render.md · references/cover.md

O estilo unificado é gerenciado por references/constructivist-style.md, que define paleta de cores / fontes / grid tanto para o vídeo quanto para a capa, garantindo consistência natural.

---

2. Estágio um · Roteiro (camadas são obrigatórias)

O usuário fornece uma entrada (um tópico / um material / uma ideia falada). A saída é:

• script.md — roteiro completo, com camadas de argumentação explicitamente marcadas
• falas.txt — uma fala por linha, para consumo do TTS

As camadas não são apenas para estética; são a entrada do estágio três. Sem a marcação das camadas, a variação do BGM não tem onde se apoiar.

## Camada 1 · Introdução
Esta é a primeira camada do "Roteiro como Eixo Temporal".
A trilha de narração é o eixo temporal principal de toda a pipeline.
## Camada 2 · Desenvolvimento
Os quadros por segundo são determinados por ela, não o contrário.
...

• Uma fala = uma unidade semântica, não coloque duas coisas em uma fala (o TTS organiza por fala; colocar mais de uma coisa pode alongar o slot)
• Sugere-se 8–30 caracteres por fala; muito longa, divida; muito curta, junte.
• Use ponto final/ponto de interrogação para encerrar, ajudando o TTS a quebrar frases.

Detalhes em references/stage1-script.md.

---

3. Estágio dois · TTS define eixo (ordem é regra de ferro)

"$VW_VENV/bin/python" skills/ideaform/scripts/make-tts-track.py \
    --lines falas.txt --fps 30 --audio \
    --plan-out out/plan.json --ts-out out/timeline.ts

Primeiro narração, depois eixo. A timeline emerge da velocidade real da narração:

① Escrever falas
② make-tts-track.py --lines falas.txt --fps 30 --audio   ← Mede velocidade natural, projeta timeline
③ Pegar TOTAL_FRAMES da saída para escrever a composição Remotion       ← Quadros determinados aqui
④ Então renderizar

Custo do contraexemplo (testado): Fixar 43 timecodes com base em storyboard antes da narração; a velocidade natural totalizou 212,90 s, enquanto o vídeo tinha apenas 174,80 s → compressão forçada de 1,218x. Essa concessão poderia ter sido evitada.

O mesmo script também pode fazer o inverso (quando já há SRT ou timecodes fixos, usa ajuste de velocidade em dois estágios), mas isso é remendo, não cenário principal. Veja references/stage2-tts.md.

⚠️ É proibido perguntar ao usuário "quantos minutos deve ter o vídeo final". A duração = velocidade da fala × quantidade de falas; é saída, não entrada; não se deve perguntar nem oferecer opções como "X minutos padrão" no início. Apenas informe "Com base neste roteiro, medimos X minutos e Y segundos". Se o usuário quiser maior/menor duração → altere o roteiro, não o tempo. (2026-10-15 Projeto Guihua testou, registrado E16)

Saída: plan.json contém para cada fala start/end/dur/frameStart/frameEnd; timeline.ts pode ser copiado diretamente para o projeto Remotion como src/timeline.ts.

---

4. Estágio três · Variação BGM (a alma deste workflow)

Ponto chave: toda vez que a argumentação entra em uma nova camada, a música muda de forma — mas não de música.

# ① Mapear as camadas do roteiro em números de cue, marcando a função narrativa de cada camada
"$VW_VENV/bin/python" skills/ideaform/scripts/bgm-plan.py \
    --plan out/plan.json \
    --layers "1:present,4:develop,6:resolve" \
    --key "A minor" --out out/bgm-plan.json

# ② Gerar projeto LMMS a partir do bgm-plan.json e renderizar (usando composer.py do electronic-music-production)
#    A renderização usa tools.lmms.apprun do contrato; bpm e timeline lp1pos devem seguir as dicas mmp_hints

Seis funções narrativas (escolha uma por camada):

Função	Intenção	O que muda
present	Apresentar·Introduzir	Apenas motivo, uma voz, espaço vazio
develop	Desenvolver·Aprofundar	+baixo +ritmo, motivo em sequência
intensify	Enfatizar·Conflito	Todas as vozes, oitava acima, acordes emprestados, aumento de dinâmica
contrast	Contraste·Virada	Mudar textura sem aumentar volume: remover camadas, trocar timbre, modular
resolve	Concluir·Retornar	Reduzir, voltar à tônica, aumentar o motivo
sustain	Manter·Transição	Não muda (quando a camada não mudou, não varie, senão dilui o contraste)

Regras de ferro:

• Elementos de identidade não podem mudar — célula do motivo, centro tonal, andamento básico. Mudar isso é trocar de música, não variar.
• Cada segmento deve variar pelo menos 1 elemento de forma; em bgm-plan.md, cada segmento terá as "evidências da variação". Se dois segmentos adjacentes ficarem sem evidências, significa que a marcação de camada está faltando.
• O ponto de variação deve cair no limite da camada da narração (pode usar --lead-in para a música começar um pouco antes).

Método completo e implementação no LMMS veja references/stage3-bgm.md.

---

5. Estágio quatro · Vídeo final

5.1 Vídeo: narração como eixo temporal

cp out/timeline.ts <projetoRemotion>/src/timeline.ts     # Número de quadros/limites de cena derivados de CUES
cd <projetoRemotion>
export TMPDIR="$VW_TMPDIR"                             # ★ Obrigatório
npx remotion studio                                    # Primeiro mostrar pré-visualização ao usuário

Os limites de cena no lado do vídeo não devem ser escritos manualmente com números de quadro, mas derivados de CUES:

export const SCENES = {
  s1: { from: 0,            dur: CUES[2].start },
  s2: { from: CUES[2].start, dur: CUES[4].start - CUES[2].start },
} as const;

Diagramas estruturais / vias de sinalização / mecanismos → sempre gerados deterministicamente, nunca com IA gerando imagens. IA desenhando estruturas químicas certamente alucinará ligações, e você não perceberá o erro — esse tipo de material deve ser reproduzível e verificável. Use scripts/gen-structures.py: SMILES → RDKit desenho determinístico → Componente Remotion orientado a quadros.

python3 scripts/gen-structures.py --tsv structures.tsv --out structures
#   → svg/*.svg  +  components/*.tsx (com animação própria)  +  manifest.json
#   → Verificação offline da fórmula molecular (RDKit CalcMolFormula); se divergir, sai com código não zero, pode ser encadeado com `&&`

• Use as opções oficiais do RDKit (useBWAtomPalette / singleColourBonds / setSymbolColour), não faça pós-processamento de cores no SVG com regex — isso é reinventar a roda e quebra com versões futuras do RDKit (veja caderno de erros E20).
• Os componentes gerados usam variáveis CSS --mol-dash / --mol-text para animação de traçado; o contexto externo deve fornecer color.
• Para visualizações moleculares mais amplas (grid / destaque de esqueleto / conformação 3D / interação proteína-ligante), procure skills existentes (veja §7), não force dentro da pipeline de vídeo.

5.2 Integração de áudio (duas rotas, padrão A)

A. Integração no Remotion (recomendado) — use <Audio> na composition, o mp4 renderizado já terá trilha sonora:

<Audio src={staticFile("voice.wav")} />
<Audio src={staticFile("bgm.wav")} volume={0.1694} />

O valor de volume não é chute, calcule usando RMS medido:

bash scripts/mix-av.sh --plan-only --voice voice.wav --bgm bgm.wav --drop 9
# RMS da narração = -23.46 dBFS   RMS do BGM = -17.04 dBFS
# → BGM precisa de -15.42 dB  →  volume = 0.1694

B. Pós-síntese (vídeo já renderizado / precisa regravar narração):

bash scripts/mix-av.sh --video silent.mp4 --voice voice.wav --bgm bgm.wav --out final.mp4

⚠️ Rota B deve usar explicitamente -map 0:v:0 -map 1:a:0. O mp4 do Remotion já vem com uma trilha AAC silenciosa; sem -map, o ffmpeg a seleciona automaticamente → o resultado código de saída 0, duração correta, reproduz, mas não tem som. O mix-av.sh já inclui este -map.

5.3 Renderização e capa

export TMPDIR="$VW_TMPDIR"
npx remotion render <CompositionId> out/video.mp4 --concurrency=3
npx remotion still Cover out/cover.png --props='{...}'    # Capa: composition estática, sem animação

• Renderize vídeos longos em segmentos: um vídeo de 7 minutos pode exceder o tempo limite devido ao estouro de memória. Use --frames=A-B segmentado → concat -c copy para união sem perdas.
• Capa use composition estática com durationInFrames={1}; dentro do componente não use useCurrentFrame (durante still, é sempre 0, o valor inicial da animação tornará elementos invisíveis).
• Layout da capa veja references/cover.md; especificações de estilo veja references/constructivist-style.md.

---

6. Entrega sem inspeção visual: cada estágio deve passar pelo verificador

O modelo não vê imagens nem ouve som. Portanto, "renderização bem-sucedida" ≠ "imagem correta, som correto". Cada etapa usa medições numéricas; se não passar, recuse a entrega:

# Autoverificação de áudio (trilha TTS, BGM): pico/RMS/clipping/desvio de duração
# Autoverificação de vídeo: cor dos pixels / pureza do corredor / contagem de pixels de texto
#   --layout deve corresponder: cover=layout de capa; scene=cena de vídeo (padrão).
#   A amostragem é definida pelo layout; usar o layout errado pode reprovar até uma capa correta (veja 05-Diagnóstico D2).
python3 scripts/verify-video.py cover out/cover.png --layout cover

# Autoverificação do vídeo final: número de quadros / duração / taxa de bits da trilha (evitar trilha silenciosa)
# Ordem de localização ffprobe: VW_FFPROBE → contrato de caminhos toolchain.json → sistema
VW_FFPROBE="$VW_FFPROBE" python3 scripts/verify-video.py video out/final.mp4 --frames 732 --fps 30

Os scripts indicam falha com código de saída não zero, podendo ser encadeados diretamente com &&.

Referência rápida de critérios comuns:

Objeto	Critério	Limiar
Áudio	Não silencioso	Pico > 1000 e RMS > 100
Áudio	Sem clipping	Amostras em escala cheia < 0,01%
Áudio	Alinhamento de duração	Desvio < 50 ms do planejado
Capa	Dimensões	1920×1080
Capa	Renderização de texto	Pixels pretos na área de texto > 300
Capa	Eixo não atravessa texto	Pixels vermelhos na área do título < 60
Vídeo final	Número de quadros	Estritamente igual ao planejado
Vídeo final	Trilha não silenciosa	Taxa de bits > 64000 bps
BGM	Nível de fundo	8–12 dB abaixo da narração

---

7. Outras habilidades que complementam este skill

Precisa de quê	Use qual
Detecção de ambiente / instalação / contrato	ideaform-setup (uma vez)
Skills prontos para novas ferramentas open source (apropriação: coletar do GitHub → verificar segurança → salvar)	ideaform-setup com scripts/harvest-skills.py <nome-da-ferramenta>
Gráficos determinísticos de estruturas químicas / vias	scripts/gen-structures.py deste skill (RDKit → SVG → componentes Remotion)
Visualização molecular mais ampla (grid / destaque de esqueleto / conformação 3D / interação proteína-ligante)	Skills externos prontos: synthetic-sciences/openscience's molecule-visualization (Apache-2.0), ghutchis/chem-skill (MIT)
Formato de projeto LMMS, parâmetros de plugins, envelope eldata	electronic-music-production + suas references/05
Técnicas de composição (harmonia, motivo, composição sem audição, emergência)	electronic-music-production references/06–10
Sintaxe Remotion e detalhes de renderização	remotion-best-practices
Método completo de verificação sem inspeção visual em nível de pixel	headless-visual-verify
Armadilhas do WSL (/mnt, gh fetch, caminho de áudio)	wsl-pitfalls

---

8. Lista de entrega

Ao finalizar um vídeo, o workspace deve conter:

<workspace>/
├── script.md            Roteiro com camadas
├── falas.txt             Falas para narração
├── out/
│   ├── plan.json        Eixo temporal (segundos/quadros de cada cue)
│   ├── timeline.ts      Timeline pronta para Remotion
│   ├── voice.wav        Master da trilha de narração
│   ├── bgm-plan.json    Plano de variação + bgm-plan.md (evidências de variação)
│   ├── bgm.wav          Trilha BGM
│   ├── video.mp4        Vídeo sem áudio (ou vídeo final com áudio integrado)
│   ├── final.mp4        ★ Vídeo final
│   └── cover.png        ★ Capa
└── .tts/                Cache TTS (mantido; reexecução leva apenas alguns segundos)

Antes de entregar, execute obrigatoriamente todas as verificações da seção 6 e informe honestamente quais passaram e quais não foram testadas.

---

9. Auto-evolução: registre cada erro

Este workflow é um skill composto mutável — com o uso, deve se ajustar cada vez mais ao seu ritmo de produção:

• Quando encontrar um erro e corrigi-lo → registre no raiz do repositório docs/06-cadernoErros.md (formato de seis colunas, numeração sequencial). ⚠️ Não crie um docs/ separado dentro de skills/ideaform/ — isso seria um segundo caderno, causando conflito de numeração com o original (2026-10-15 testado, registrado E19).
• Quando um erro for permanentemente corrigido por script/documentação (não contornado) → marque o status como Curado e descreva o método.
• Se o mesmo tipo de erro ocorrer pela segunda vez → não registre uma terceira entrada; coloque a defesa diretamente no script (verificador / valor padrão / contrato).
• Ao introduzir uma nova ferramenta open source → primeiro colete, depois execute: harvest-skills.py <nome-da-ferramenta> para encontrar skills maduros da comunidade (com proteção de fork, não sobrescreve suas modificações locais); só escreva do zero se não encontrar um qualificado. Erros em skills coletados também devem ser registrados.
• Antes de encerrar a sessão, dê uma olhada: há alguma correção que não foi registrada?