primocode 8.42.2 → 9.1.0

package/studio/ferramentas/corte.md

@@ -1,919 +0,0 @@
-# CORTE — vídeo
-
-No lugar de CapCut, Premiere e After Effects. Modelo `cena`, com `duracao` em cada
-cena, trilha sonora, transições e download em `.mp4`.
-
-<!-- O EXEMPLO FICA NO COMEÇO DE PROPÓSITO: quando o plano de tokens é
-apertado, o agente recebe só os primeiros ~3500 caracteres desta spec. Um
-vídeo inteiro saiu PRETO porque o formato do documento estava depois do
-corte e o agente inventou a estrutura. Formato primeiro; detalhe depois. -->
-
-## Exemplo completo
-
-**ATENÇÃO — este exemplo ensina o FORMATO, não o conteúdo.** O assunto dele
-(conta de luz, bandeira tarifária) é inventado para a demonstração. Copiar
-qualquer frase dele para o SEU documento é ERRO: escreva cada cena com os
-fatos da SUA tarefa. O servidor recusa documento que venha com estas frases.
-
-```json
-{
-  "ferramenta": "corte",
-  "titulo": "Reels — por que sua conta de luz subiu",
-  "doc": {
-    "tema": "brasa",
-    "largura": 1080, "altura": 1920,
-    "acabamento": "grao",
-    "trilha": { "tipo": "gerada", "estilo": "pulso", "volume": 0.7 },
-    "cenas": [
-      { "layout": "centro", "duracao": 3, "fundo": "aurora", "transicao": "flash",
-        "elementos": [
-          { "tipo": "texto", "papel": "titulo", "texto": "Sua conta subiu\nde novo.",
-            "tamanho": 124, "estilo": "gradiente", "anim": "desfoque" }]},
-
-      { "layout": "centro", "duracao": 3, "fundo": "vinheta", "transicao": "limpar",
-        "elementos": [
-          { "tipo": "texto", "papel": "titulo", "texto": "E não foi o seu chuveiro.",
-            "tamanho": 78, "estilo": "marcador", "anim": "palavra" }]},
-
-      { "layout": "centro", "duracao": 4, "transicao": "zoom", "acabamento": "vinheta",
-        "fundo": { "imagem": "/midia/torre.jpg", "escurecer": 0.5 },
-        "elementos": [
-          { "tipo": "numeros", "contar": true, "anim": "saltar", "tamanho": 180,
-            "itens": ["+38% | bandeira tarifária em 12 meses"] }]},
-
-      { "layout": "livre", "duracao": 4, "transicao": "deslizar",
-        "elementos": [
-          { "tipo": "imagem", "src": "/midia/campo.jpg", "x": 0, "y": 0,
-            "l": 1080, "a": 1920, "raio": 0, "movimento": "aproximar", "filtro": "contraste" },
-          { "tipo": "forma", "forma": "retangulo", "x": 0, "y": 1180, "l": 1080, "a": 740,
-            "preenchimento": "rgba(10,5,6,.72)" },
-          { "tipo": "texto", "x": 90, "y": 1320, "l": 900, "a": 420,
-            "texto": "O custo está\nna transmissão", "tamanho": 104, "peso": 750,
-            "estilo": "sombra", "anim": "cortina" }]},
-
-      { "layout": "centro", "duracao": 5, "fundo": "raios", "transicao": "subir",
-        "elementos": [
-          { "tipo": "lista", "revelar": true, "tamanho": 52, "intervalo": 0.9,
-            "itens": ["Linhas saturadas no Nordeste",
-                      "Usina gerando sem escoar",
-                      "A conta chega em quem consome"] }]},
-
-      { "layout": "centro", "duracao": 3, "fundo": "brilho", "transicao": "fade",
-        "acabamento": "luz",
-        "elementos": [
-          { "tipo": "texto", "papel": "titulo", "texto": "Segue para\nentender a próxima.",
-            "tamanho": 96, "estilo": "contorno-tom", "anim": "elastico" }]}
-    ]
-  }
-}
-```
-
----
-
-## ANTES DE ESCREVER: escolha, não repita
-
-O exemplo acima é UMA receita. Usar sempre ela — `brasa`, `pulso`, gancho →
-problema → virada — é o que faz todo vídeo sair com a mesma cara. O dono já
-reclamou disso: *"ele não alterna entre os temas, usa um tema só pra todos os
-vídeos, e o vídeo sempre tem a mesma estrutura, fica tudo genérico"*.
-
-Escolha as quatro coisas abaixo **pelo assunto**, antes de escrever a primeira
-cena. Se o assunto não empurrar para nenhuma, escolha a que você NÃO usou da
-última vez — nunca a primeira da lista por comodidade.
-
-| Assunto | `tema` | `trilha` | Estrutura |
-|---|---|---|---|
-| produto, tecnologia, lançamento | `meia-noite` ou `neon` | `pulso` | **Gancho** |
-| institucional, quem somos, serviço | `oceano` ou `floresta` | `foco` | **Retrato** |
-| urgência, notícia, alerta, dado duro | `brasa` | `tenso` | **Manchete** |
-| explicação, tutorial, passo a passo | `papel` ou `claro` | `foco` | **Aula** |
-| conquista, agradecimento, celebração | `doce` ou `neon` | `alegre` | **Brinde** |
-| memória, história, retrospectiva | `retro` ou `mono` | `lofi` | **Linha** |
-| curso, aula, treinamento, método | `ambar` | `suave` | **Aula** |
-| relatório, número, análise técnica | `grafite` | `ambiente` | **Manchete** |
-
-### As seis estruturas
-
-Cada uma tem ritmo próprio. Não misture, e não use "Gancho" para tudo.
-
-**Gancho** (vender algo) — 7 a 9 cenas de 3 a 5 s
-frase que segura o dedo · o problema, concreto · a virada, um argumento por
-cena · número ou prova · chamada.
-
-**Retrato** (apresentar quem faz) — 5 a 6 cenas de 4 a 6 s, mais calmo
-o nome e o que faz · para quem · como trabalha · uma prova (número, cliente,
-tempo de casa) · convite. Transições suaves (`fade`, `limpar`), sem `flash`.
-
-**Manchete** (informar rápido) — 4 a 6 cenas de 2 a 4 s, seco
-o fato em uma linha · o número que dói · por que aconteceu · o que muda para
-você. Corte duro entre cenas (`corte`, `flash`), texto grande, pouca palavra.
-
-**Aula** (ensinar) — 6 a 10 cenas de 4 a 7 s
-a pergunta · por que importa · passo 1, 2, 3 (uma cena cada, com `lista`
-revelando) · o resumo · o erro comum a evitar. Fundo calmo, sem fogos.
-
-**Brinde** (celebrar) — 4 a 6 cenas de 3 a 4 s
-a conquista · os números dela · quem fez acontecer · agradecimento.
-Animações vivas (`saltar`, `elastico`), fundo com brilho.
-
-**Linha** (contar uma história no tempo) — 6 a 8 cenas de 4 a 5 s
-o começo · o que mudou em cada etapa (uma cena por marco, com o ano no
-`chapeu`) · onde chegou · o que vem. Um `tema` por época, se fizer sentido.
-
-### Regras que matam o genérico
-
-- **O `fundo` muda a cena a cena.** Onze existem. Dez cenas com o mesmo fundo
-  é o que faz parecer template. Repetir um fundo tudo bem; repetir TODOS não.
-- **A `transicao` muda também.** Tudo em `fade` parece slide, não vídeo.
-- **A `trilha` combina com o assunto.** Seis estilos existem; `pulso` não é o
-  padrão de nada — é o de vídeo de produto.
-- **Cor de destaque.** Se o usuário tem marca, `marca.cor` pinta números,
-  gráficos e detalhes. Sem marca, escolha `tom` na cena que mais importa.
-- **Uma cena fora do tom.** Uma citação em `papel` no meio de um deck escuro,
-  ou uma cena `mono` antes do fecho, vale mais que dez efeitos.
-
-Um Reels de 30 s é 7 a 9 cenas de 3 a 5 segundos. A regra é dura:
-**uma frase por cena**. Se não dá para ler em voz alta dentro da duração,
-corte texto.
-
-Vertical é `1080 × 1920`. Horizontal (`1920 × 1080`) só quando o destino for YouTube
-ou tela grande. Em vertical, os tamanhos padrão de texto já crescem sozinhos.
-
----
-
-## Trilha sonora
-
-Vai no **documento**, não na cena:
-
-```json
-"trilha": { "tipo": "gerada", "estilo": "pulso", "volume": 0.7 }
-```
-
-### Geradas pelo estúdio
-
-Música sintetizada na hora, sem arquivo e sem licença de terceiro.
-
-| `estilo` | Cara | BPM |
-|---|---|---|
-| `pulso` | eletrônico, batida marcada | 112 |
-| `ambiente` | pads longos, sem bateria | 68 |
-| `lofi` | levada atrasada, acordes soltos | 76 |
-| `epico` | grave, crescendo | 88 |
-| `alegre` | maior, arpejo rápido | 124 |
-| `tenso` | menor, suspense | 100 |
-| `suave` | cama grave, sem bateria, quase não se nota | 60 |
-| `foco` | pulso leve, sem caixa, para tutorial e institucional | 96 |
-
-A trilha gerada não acaba — acompanha o vídeo até a última cena.
-
-**Vídeo de alguém falando pede `suave` ou `foco`.** As duas foram feitas para
-ficar EMBAIXO de uma voz: moram fora da faixa da fala e não têm caixa batendo
-em cima dela. `epico` e `tenso` são faixas grandes — bonitas num teaser sem
-narração, e uma disputa com quem fala em qualquer outro caso.
-
-### Arquivo do usuário
-
-```json
-"trilha": { "tipo": "arquivo", "src": "/midia/minha-faixa.mp3",
-            "volume": 0.7, "inicio": 0, "repetir": true }
-```
-
-`src` vem de `POST /api/midia` (upload) ou é uma URL direta de áudio.
-`inicio` pula os primeiros segundos da faixa.
-
-### Música da internet, com licença (`buscar_audio`)
-
-Uma faixa de verdade, tocada por gente, sem o usuário ter arquivo nenhum:
-`buscar_audio` procura no Openverse (Jamendo, Freesound, Wikimedia — licenças
-Creative Commons que permitem uso, inclusive comercial), **baixa** a melhor e
-devolve a URL `/midia/…` pronta:
-
-```
-buscar_audio { "consulta": "upbeat corporate", "duracao": 30 }
-→ url "/midia/corporate-succes-8c2911.mp3", licenca "CC BY-SA",
-  credito "Corporate Succes — Arkadii Kaplan (CC BY-SA 3.0, via jamendo)"
-```
-
-```json
-"trilha": { "tipo": "arquivo", "src": "/midia/corporate-succes-8c2911.mp3", "volume": 0.55, "repetir": true }
-```
-
-Consulta **em inglês**, pelo clima: `upbeat corporate`, `calm piano`, `epic
-cinematic`, `lofi chill`, `acoustic warm`. `duracao` é a do vídeo, para a faixa
-combinar. Para efeitos, `"tipo": "efeito"` (`whoosh`, `click`, `ding`,
-`swoosh`, `pop`) — a URL vai em `som: {"arquivo": …}`.
-
-**O crédito faz parte da peça.** Licença `CC BY`/`BY-SA` pede o crédito: ponha
-a linha `credito` da resposta na assinatura ou numa legenda pequena da última
-cena. `CC0` e domínio público não pedem nada. A resposta diz qual é o caso.
-Quando a busca não acha nada, use a trilha **gerada** — nunca um "parecido"
-de YouTube.
-
-**Não baixe áudio de YouTube, Spotify ou similares** — quebra os termos dessas
-plataformas e o direito autoral da faixa. Use `buscar_audio`, música do próprio
-usuário ou uma das trilhas geradas acima.
-
----
-
-## Studio E Remotion — os dois, mesclados
-
-**Não é uma escolha.** O Studio é quem AUTORA e mostra: a cena, o motion, a
-narração, a trilha gerada, os efeitos — o link "ver" é o vídeo, na hora. Quando
-o usuário pede o ARQUIVO (`studio_exportar`), o PrimoCode renderiza a mesma
-peça quadro a quadro pelo **Remotion** (instalado uma vez, sozinho, em
-`~/.primocode/remotion`) — determinístico, sem perder quadro, com todas as
-animações, chaves 3D, contagem e clipes no instante certo — e **mistura o
-áudio do Studio** (narração, trilha, efeitos sintetizados) no MP4 final. Você
-não escolhe motor: chama `studio_exportar` e recebe o arquivo.
-
-O primeiro vídeo que saiu só do Remotion estava **mudo e parado** — animações
-desligadas, só `trilha.src` como som. Foi por isso que a mescla existe: o
-Remotion sozinho não tem a narração nem a trilha gerada; o Studio sozinho
-grava em tempo real. Juntos, o arquivo sai como a prévia.
-
-`remotion_projeto` (com o `id` da peça) é OUTRA coisa: gera o **projeto React**
-na pasta do usuário, com as cenas, a mídia e o motion, para quem quer mexer no
-código, versionar no git ou renderizar em servidor. Só quando o usuário pedir
-isso — não é o jeito de gerar o arquivo. O projeto nasce sem `node_modules`;
-diga os dois comandos (`npm install`, `npm run render`) e deixe ele decidir. A
-trilha **gerada** e os sons **sintetizados** não existem no projeto solto
-(são WebAudio ao vivo): lá, use `buscar_audio` para ter a trilha em arquivo.
-
----
-
-## Elementos que dão cara de produção
-
-Estes existem porque um vídeo genérico é feito só de título + texto. São
-baratos de escrever e mudam completamente o resultado.
-
-**Todo vídeo leva pelo menos um.** Texto sobre fundo, do primeiro segundo ao
-último, é o vídeo que o usuário chamou de "sem efeito nenhum" — e não é falta
-de recurso: é este bloco não ter sido lido.
-
-## Anúncio de marca — o kit
-
-Quando o pedido é o COMERCIAL de um produto (um cartão, um app, um plano), o
-que separa uma peça de agência de um slide com música são quatro coisas, e as
-quatro têm elemento próprio. Uma peça de marca sem elas sai genérica por mais
-bonito que esteja o texto.
-
-**Primeiro, declare a marca no documento.** Ela pinta o destaque de tudo —
-número, botão, detalhe, o cartão — e libera o fundo `"marca"`:
-
-```json
-"marca": { "cor": "#21C25E", "logo": "/midia/logo.svg" },
-"tema": "claro"
-```
-
-**De onde vêm a cor e a logo: do site da empresa.** Antes de escrever a peça,
-chame `marca_da_empresa { "nome": "PicPay" }` (ou `"site": "https://…"`). Ela
-lê o site, baixa a logo para o estúdio e devolve `marca: {cor, logo}` pronta
-para colar, mais a paleta, as fontes e a frase da empresa. Não chute cor de
-marca nem peça o arquivo ao usuário antes de tentar isso — a logo está no
-site. Só quando a tool não achar (site montado por JavaScript, sem logo
-baixável) é que se pede o arquivo (`studio_midia`) ou se assina com o nome em
-texto.
-
-Tema CLARO na maioria dos anúncios de marca. O escuro é para a cena de
-produto e para a vitrine; o resto da peça respira no branco.
-
-### `cartao` — o produto
-
-```json
-{ "tipo": "cartao", "nome": "PicPay", "variante": "Gold", "movimento": "flutuar" }
-```
-
-Sai um cartão desenhado: chip, símbolo de aproximação, numeração mascarada,
-nome e validade, com luz e sombra. `cor` (sem ela, a da marca), `largura`,
-`numero` (só os 4 últimos aparecem), `titular`, `validade`, `face: "verso"`,
-`movimento`: `flutuar` | `girar`.
-
-**Mostre o produto antes de falar dele.** Um anúncio de cartão que só tem
-frases é um anúncio sem produto.
-
-### `app` — a tela do aplicativo
-
-```json
-{ "tipo": "app", "topo": "Minha conta", "rotulo": "saldo disponível",
-  "valor": "R$ 1.284,90",
-  "linhas": [["Café da manhã", "R$ 18,90"], ["Mercado", "R$ 92,40"]],
-  "botao": "Pagar com o cartão" }
-```
-
-Cabeçalho, um número grande, linhas com o nome à esquerda e o valor à direita
-separadas por fio, e o botão cheio embaixo — que é o que faz o olho ler
-"aplicativo". Aceita `["nome", "valor"]` e `"nome|valor"`. `escuro: true` para
-a versão noturna.
-
-**Ele vai DENTRO do `dispositivo`**, e aí ocupa a tela inteira do aparelho:
-
-```json
-{ "tipo": "dispositivo", "forma": "celular", "dentro": [ { "tipo": "app", ... } ] }
-```
-
-Solto na cena ele vira o print da campanha. É o mesmo elemento de propósito:
-com dois, a tela do celular e o print divergiriam na primeira mudança.
-
-### `vitrine` — a linha de produtos
-
-```json
-{ "tipo": "vitrine", "titulo": "Escolha seu cartão", "atual": 1, "nome": "PicPay",
-  "itens": [ { "nome": "Gold", "cor": "#C9A227", "detalhe": "sem anuidade" },
-             { "nome": "Verde", "detalhe": "cashback" },
-             { "nome": "Black", "cor": "#181B1F", "detalhe": "sala VIP" } ] }
-```
-
-Os cartões numa fila, o `atual` à frente e os outros recuados. Vai bem sobre
-fundo escuro (`"fundo": "#0b0f0c"`), que é como toda tela de "escolha o seu" é
-desenhada.
-
-### `assinatura` — o ponto final
-
-```json
-{ "tipo": "assinatura", "nome": "PicPay", "frase": "o jeito fácil de pagar", "sobre": "marca" }
-```
-
-Ela toma a CENA INTEIRA: o logo sozinho, grande, sobre a cor da casa. `sobre`:
-`marca` | `claro` | `escuro`. Com `logo` ela usa a imagem; sem, o `nome`.
-
-**Todo anúncio termina assim.** Sem a assinatura a peça acaba numa frase, e
-ninguém fica sabendo quem falou.
-
-### A ordem que funciona
-
-Uma peça de marca de 20 a 30 segundos, com 8 a 10 cenas:
-
-| # | cena | o que entra |
-|---|---|---|
-| 1 | a promessa, em uma frase curta | `texto` pequeno, muito ar, fundo claro |
-| 2 | o produto | `cartao` com `movimento` |
-| 3 | o mote, na cor da casa | `fundo: "marca"`, `texto` branco, `anim: "palavra"` |
-| 4 | funcionando | `dispositivo` + `app` |
-| 5 | o benefício | `texto` |
-| 6 | a linha | `vitrine` sobre fundo escuro |
-| 7 | a última razão | `texto` |
-| 8 | assinatura | `assinatura` |
-
-E o rosto de quem fala, quando houver, entra por `clipe` entre a 4 e a 5 — o
-depoimento é o que dá confiança, e nenhum desenho substitui.
-
----
-
-### `icone` — o desenho ao lado do argumento
-
-```json
-{ "tipo": "icone", "nome": "raio", "tamanho": 120 }
-{ "tipo": "icone", "nome": "crescimento", "tamanho": 90, "cor": "#22d3ee", "traco": 2 }
-{ "tipo": "icone", "caminho": "M4 7h16M4 12h10M4 17h7", "tamanho": 100 }
-{ "tipo": "icone", "caminho": ["M12 3a9 9 0 100 18 9 9 0 000-18z", "M9 12l2 2 4-4"], "preenchido": false }
-```
-
-O jeito mais barato de uma cena deixar de ser um slide. Um ícone grande acima
-do título, ou um por item de uma lista de três, e a mesma frase passa a ter
-imagem.
-
-**O ícone que a lista não tem, você DESENHA** — `caminho` é o path SVG numa
-caixa de 24×24 (uma string, ou uma lista com um traço por peça). Ele sai no
-mesmo traço dos ícones prontos, na cor do tema, então o seu não destoa. Um
-carrinho de compras, uma xícara, o símbolo do produto do cliente: três ou
-quatro comandos `M`/`L`/`A`/`C` resolvem. Nunca emoji no lugar de ícone.
-
-Os nomes que existem (traço, no tom do tema):
-
-`raio` `alvo` `foguete` `escudo` `relogio` `usuario` `pessoas` `coracao`
-`estrela` `nuvem` `engrenagem` `lampada` `cadeado` `chave` `casa` `email`
-`telefone` `camera` `fogo` `globo` `presente` `sino` `mapa` `dinheiro`
-`crescimento` `balao` `pasta` `livro` `check` `grafico` `codigo` `video`
-`play` `olho` `baixar` `tela` `cartao` `numero` `tabela` `imagem` `lista`
-
-Nome que não existe desenha a estrela — então use os daqui, e não o que
-parecer natural.
-
-### `selo` — a pílula de estado
-
-```json
-{ "tipo": "selo", "texto": "Módulo 2 de 5" }
-{ "tipo": "selo", "texto": "Resultado 4", "icone": "★", "estilo": "vivo" }
-```
-
-`estilo`: sem nada (contorno), `"vivo"` (preenchido) ou `"solto"` (só o texto
-em versalete). Vai sozinho para cima do título.
-
-### `progresso` — onde estamos no caminho
-
-```json
-{ "tipo": "progresso", "atual": 4, "total": 15 }
-```
-
-Mostra "4/15" e os pontinhos. Use em série de cenas: diz ao espectador que
-existe um percurso, e isso segura ele até o fim. `"numero": false` deixa só
-os pontos.
-
-### `avatar` — a pessoa
-
-```json
-{ "tipo": "avatar", "src": "/midia/foto.jpg", "nome": "Cleiton Paris", "tamanho": 280 }
-```
-
-Círculo com anel aceso. Sem `src`, mostra as iniciais do `nome` — melhor que
-um buraco cinza. Vai para cima do nome sozinho.
-
-### `dispositivo` — celular, notebook ou navegador com conteúdo dentro
-
-```json
-{ "tipo": "dispositivo", "forma": "celular", "dentro": [ ...elementos... ] }
-```
-
-`forma`: `celular` | `notebook` | `tablet` | `navegador` (este aceita
-`"endereco": "primocode.dev"`). `dentro` é uma lista de elementos comuns — o
-que couber. Nos layouts `imagem-direita` / `imagem-esquerda` o aparelho vai
-para o lado sozinho, com o texto do outro. É o enquadramento mais forte que
-existe aqui: use quando estiver mostrando uma tela.
-
-### `conversa` — balões de pergunta e resposta
-
-```json
-{ "tipo": "conversa", "itens": [
-    { "de": "eu",  "texto": "Como acelero meu workflow?" },
-    { "de": "ela", "texto": "Peça o storyboard em seis quadros." } ] }
-```
-
-Entram um de cada vez, como diálogo. `de: "eu"` à esquerda; qualquer outra
-coisa à direita, com a cor do tema. Combina com `dispositivo` — a conversa
-dentro do celular é a cena mais usada em vídeo de IA.
-
-### `passos` e `opcoes`
-
-```json
-{ "tipo": "passos", "atual": 2, "itens": ["Passo 1|roteiro", "Passo 2|storyboard", "Passo 3|corte"] }
-{ "tipo": "opcoes", "pergunta": "O que garante o look?", "certa": 1,
-  "itens": ["LUT uniforme", "Saturação aleatória", "Espaços de cor diferentes"] }
-```
-
-`passos` acende a etapa `atual` e apaga as outras — mude o `atual` a cada
-cena e a série ganha movimento sem esforço. `opcoes` marca a alternativa
-`certa` com ✓ (não escreva o ✓ no texto: ele vem sozinho). Alternativa faz o
-espectador pensar antes da resposta, e pensar é o que segura alguém no vídeo.
-
-### Vidro — o liquid glass, em qualquer elemento
-
-`"material": "vidro"` em **qualquer** elemento: texto vira pílula de vidro,
-`forma` vira painel, `imagem` ganha moldura, `lista`/`cartoes`/`numeros`
-ganham fundo. É vidro de verdade: **desfoca o que está atrás** (o fundo
-`aurora`, a foto, o círculo colorido), tem o bisel de luz em cima e a sombra
-embaixo, e o reflexo diagonal atravessa devagar durante a cena.
-
-```json
-{ "tipo": "forma", "forma": "retangulo", "material": "vidro", "raio": 36,
-  "x": 120, "y": 140, "l": 860, "a": 420, "preenchimento": "#22d3ee" }
-{ "tipo": "texto", "material": "vidro", "texto": "pílula de vidro", "tamanho": 32 }
-```
-
-Na forma, `preenchimento` vira a **tinta** do vidro (fraca) — não pinta o
-fundo. `raio` arredonda (padrão 28). **Ponha algo atrás**: vidro sobre fundo
-liso é só um retângulo claro; sobre `aurora`, `brilho`, uma foto ou uma forma
-colorida, é o efeito. `"estilo": "vidro"` em `cartoes` continua valendo.
-
-### Ícone como objeto (`estilo: "app"` / `"vidro"`)
-
-```json
-{ "tipo": "icone", "nome": "foguete", "estilo": "app",   "tamanho": 220, "fundo": "#8b5cf6" }
-{ "tipo": "icone", "nome": "raio",    "estilo": "vidro", "tamanho": 220, "cor": "#ffb03a" }
-```
-
-`app` é o azulejo de aplicativo: gradiente da cor, brilho na metade de cima,
-sombra colorida embaixo, o traço branco. `vidro` é o mesmo azulejo em liquid
-glass. `fundo` pinta o azulejo (sem ele, a cor do tema). Um ícone de traço
-sozinho é sinal; no azulejo vira **coisa** — é o que se usa para "o app", "o
-produto", "o recurso" numa cena de lançamento. Combina com `som: "pop"` na
-entrada e com `chaves` de `giroY` para ele virar ao pousar.
-
----
-
-## Editar o vídeo do usuário (`clipe`)
-
-Quando a pessoa manda uma gravação dela — o rosto falando, uma tela gravada,
-uma cena de celular — o trabalho é EDITAR, não ilustrar. O elemento `clipe`
-põe um trecho dessa gravação dentro de uma cena.
-
-**Primeiro passo, sempre:** `studio_midia` com o caminho do arquivo. Ele
-devolve uma URL `/midia/...`. Um caminho do disco (`/Users/...`, `C:\...`)
-não funciona — o navegador não abre arquivo local.
-
-```json
-{ "tipo": "clipe", "src": "/midia/gravacao.mp4", "de": 12.4, "ate": 19.8 }
-```
-
-| campo | o que faz |
-|---|---|
-| `src` | a URL que `studio_midia` devolveu — obrigatório |
-| `de` / `ate` | segundos **no arquivo original**. O trecho, não a cena |
-| `mudo` | `true` deixa só a imagem (quando quem fala é a narração) |
-| `volume` | 0 a 1, para misturar a voz da gravação com a trilha |
-| `ajuste` | `"cobrir"` (padrão, enche o quadro) ou `"conter"` |
-| `filtro` | `"cinza"`, `"sepia"`, `"contraste"`, `"desbotado"` |
-| `x`/`y` | só se quiser quadro-dentro-do-quadro; sem eles ocupa a cena inteira |
-
-Sem `x`/`y` o clipe é o CHÃO da cena: a imagem enche o quadro e o texto fica
-por cima. É o que se quer quase sempre.
-
-**Não escreva `duracao` numa cena com clipe.** A cena passa a durar o trecho
-(`ate` − `de`) sozinha. Escrever `duracao` por cima é o que faz o corte não
-cortar: o trecho de 1,2s fica congelado até completar os 4s.
-
-### Cortar as pausas
-
-**Não adivinhe onde estão.** Chame `studio_analisar` com a URL do vídeo: ele
-ouve o arquivo e devolve `trechos`, a lista de `[início, fim]` já sem os
-silêncios. Cada trecho vira uma cena.
-
-```
-studio_analisar  arquivo: "/midia/gravacao.mp4"
-→ { trechos: [[0.8, 6.2], [9.5, 17.1], [19.0, 24.3]], cortado: 4.6 }
-```
-
-`pausa` (padrão 0,6s) é a partir de quantos segundos de silêncio conta como
-pausa. Suba para 1.0 se a pessoa fala pausado e o corte ficou ofegante.
-
-A análise leva alguns segundos e abre uma aba que se fecha sozinha — é o
-navegador que sabe ler o áudio de um .mp4. Se ela não responder, siga com o
-vídeo inteiro num clipe só; não invente tempos.
-
-Cortar as pausas é escrever VÁRIOS clipes do mesmo `src`, com os silêncios de
-fora. Uma cena por trecho aproveitado:
-
-```json
-"cenas": [
-  { "layout": "capa", "transicao": "fade",
-    "elementos": [{ "tipo": "clipe", "src": "/midia/gravacao.mp4", "de": 0.8, "ate": 6.2 },
-                  { "tipo": "texto", "papel": "titulo", "texto": "O que ninguém te conta" }] },
-  { "layout": "capa", "transicao": "corte",
-    "elementos": [{ "tipo": "clipe", "src": "/midia/gravacao.mp4", "de": 9.5, "ate": 17.1 }] }
-]
-```
-
-Entre 6.2 e 9.5 havia uma pausa: ela simplesmente não entra. Use `"transicao":
-"corte"` entre trechos da mesma fala — fade entre dois pedaços da mesma frase
-parece defeito.
-
-### Legendar
-
-A legenda é um `texto` com `"papel": "fala"` na mesma cena do clipe:
-
-```json
-{ "tipo": "texto", "papel": "fala", "texto": "isso mudou tudo pra mim" }
-```
-
-Ela já vai sozinha para o terço de baixo, branca, com chapa escura atrás —
-legível sobre qualquer imagem. Não use `papel: "legenda"` para isso: aquele é
-o rodapé de um slide, com 18px, ilegível num vídeo.
-
-Uma frase curta por cena, no ritmo da fala — nunca o parágrafo inteiro. Se o
-trecho é longo, quebre em mais cenas do mesmo `src` em vez de encher a tela.
-
-### Só a voz dele
-
-Três combinações, e elas resolvem coisas diferentes:
-
-**A voz dele com a imagem dele** (o padrão) — `"mudo": false` no clipe e a
-trilha em volume baixo (`"volume": 0.15`) ou `"trilha": {"tipo": "nenhuma"}`.
-
-**A imagem dele com a sua narração por cima** — `"mudo": true` no clipe e
-`narracao` na cena.
-
-**A VOZ DELE COM A SUA TELA POR CIMA** — `"apenas": "som"` no clipe:
-
-```json
-{ "layout": "centro", "elementos": [
-    { "tipo": "clipe", "src": "/midia/gravacao.mp4", "de": 9.5, "ate": 17.1, "apenas": "som" },
-    { "tipo": "icone", "nome": "crescimento", "tamanho": 120 },
-    { "tipo": "texto", "papel": "titulo", "texto": "Três vezes mais rápido" },
-    { "tipo": "numeros", "itens": ["3x|velocidade", "0|instalação"], "contar": true } ] }
-```
-
-O clipe some do quadro e continua tocando: a cena dura o trecho, o áudio dele
-entra no arquivo exportado, e o que se VÊ é o que você montou. É assim que se
-entrega "só a voz, com uma tela de exemplos" — a gravação vira a narração da
-sua peça.
-
-Use na parte em que ele EXPLICA, e não na em que ele aparece: o rosto de quem
-fala é o que dá confiança, e escondê-lo o vídeo inteiro joga isso fora. O
-desenho que costuma funcionar é alternar — ele na tela quando se apresenta e
-quando conclui, a tela montada enquanto ele explica.
-
-Não junte `"apenas": "som"` com `"mudo": true`: um cancela o outro e a cena
-vira um silêncio do tamanho do trecho.
-
-### A música que combina
-
-Não repita a mesma trilha em todo vídeo do usuário.
-
-A primeira pergunta é se **alguém fala** no vídeo — narração ou o áudio da
-gravação. Se fala, a trilha é cama: `suave` (mais discreta) ou `foco` (com
-andamento). Só depois vem o assunto: depoimento e história pessoal pedem `lofi`
-ou `ambiente`; anúncio e lançamento pedem `pulso` ou `epico`; algo leve pede
-`alegre`. A tabela de estilos está acima.
-
----
-
-## Narração
-
-A voz que fala por cima do vídeo. Vai **na cena**, e o estúdio narra sozinho
-na hora de tocar — sem gravar nada, sem arquivo:
-
-```json
-{ "layout": "centro", "duracao": 6,
-  "narracao": "O texto que a voz vai falar nesta cena.",
-  "elementos": [ ... ] }
-```
-
-Escolha da voz no **documento** (opcional):
-
-```json
-"voz": { "voz": "brian", "grave": true, "velocidade": 1 }
-```
-
-**Com o ElevenLabs configurado** (chave em `POST /api/voz/elevenlabs` ou na
-variável `ELEVENLABS_API_KEY`), a narração inteira sobe de nível e as vozes
-passam a ser: `brian` (grave, de locução — padrão) · `daniel` (grave, de
-noticiário) · `adam` (firme) · `bill` (maduro) · `liam` (jovem, redes
-sociais) · `sarah` e `alice` (femininas). Também aceita um voice_id cru do
-ElevenLabs — é assim que a voz clonada do próprio usuário entra. Consulte
-`GET /api/voz/status` para saber o que está ativo nesta máquina.
-
-**A corrente de voz, em ordem de qualidade** (cada motor cai no seguinte
-quando não responde — a narração nunca fica muda):
-
-1. **ElevenLabs** — premium, se houver chave com crédito.
-2. **Edge TTS** — vozes neurais da Microsoft, **grátis e sem chave**, só
-   pede internet. É a melhor voz gratuita: `antonio` (masculina, de locução
-   — **a padrão gratuita**), `francisca` e `thalita` (femininas). Instala-se
-   sozinho na primeira vez (`pip install edge-tts`, ~1 min) e, enquanto isso,
-   a narração sai por outro motor. Não há por que citar "voz de robô": com
-   internet, o padrão já é voz neural de gente.
-3. **Piper** — neural e **offline**, sem limite (detalhado abaixo).
-4. **Voicebox** — se o app estiver instalado (voz clonável).
-5. **Google** — última reserva, robótica, mas responde sempre.
-
-O **Piper** roda na máquina do usuário — offline, sem limite. As vozes
-pt-BR, com a frequência de cada uma medida (menor = mais grave):
-
-| id | timbre | Hz |
-|---|---|---|
-| `jeff` | grave, de locução — **é a padrão** | 139 |
-| `cadu` | grave, mais solta | 140 |
-| `edresson` | média, mais leve de baixar | 151 |
-| `faber` | clara, de leitura | 167 |
-| `tugao` | português de Portugal | — |
-
-`"grave": true` abaixa mais uns 10% — é o registro de abertura de vídeo. Não
-há voz feminina em pt-BR neste motor; se pedirem uma, diga isso em vez de
-prometer. Na primeira vez o motor é baixado sozinho (~90 MB); enquanto isso
-a narração sai por uma voz de reserva, e o vídeo nunca fica mudo.
-
-Regras que fazem diferença:
-
-- **Escreva para o ouvido, não para o olho.** A narração NÃO repete o texto da
-  tela: a tela dá o título, a voz dá o argumento. Repetir os dois é o erro mais
-  comum, e soa a leitura de slide.
-- **Caiba na duração.** Fale ~2,5 palavras por segundo: uma cena de 6s aguenta
-  ~15 palavras. Texto mais longo que a cena é cortado no meio.
-- **Uma ideia por cena**, em uma ou duas frases curtas. Ponto final ajuda a voz
-  a respirar.
-- Para o vídeo ficar mudo de propósito, é só não pôr `narracao` em cena nenhuma.
-
-O usuário também pode gravar a própria voz pelo editor; aí a cena ganha
-`narracaoAudio` com o arquivo, e ela tem prioridade sobre a voz sintetizada.
-
-**Sincronia é automática.** Quando o estúdio gera a narração em arquivo, ele
-mede o áudio e grava `narracaoDur` na cena; a cena então dura o que for maior —
-a `duracao` pedida ou a fala inteira mais um respiro. Não calcule isso à mão,
-e não apague `narracaoDur` ao ajustar um documento.
-
-**Mixagem é automática.** A música abaixa sozinha enquanto a voz fala (ducking)
-e volta no intervalo entre as falas. Não compense baixando o `volume` da trilha:
-deixe em 0.6–0.8 e o duck cuida do resto.
-
----
-
-## Efeitos sonoros
-
-Cada troca de cena ganha um efeito sintetizado na hora, sem arquivo e sem
-licença: transição `flash` e `zoom` soam um **impacto** grave; as demais, um
-**whoosh** (variado, para não repetir); `corte` fica em silêncio.
-
-Para controlar:
-
-```json
-"sfx": false                  // no documento: desliga todos os efeitos
-{ "transicao": "deslizar", "som": "impacto" }   // na cena: força um efeito
-```
-
-Valores: `"whoosh"` · `"impacto"` · `"click"` · `"pop"` · `"ding"` ·
-`"subida"` · `"tique"` · `"brilho"` · `"nenhum"`. (`sfx` na cena ainda vale;
-`som` é o nome novo, o mesmo dos elementos.)
-
-### Som por elemento — o que faz motion soar motion
-
-`"som"` num **elemento** toca no instante em que ele entra (o mesmo atraso da
-animação de entrada). É a diferença entre um slide animado e uma peça de
-motion: o número faz **ding** ao aparecer, o ícone faz **pop** ao pousar, a
-barra sobe com a **subida** (o riser) e o texto final chega com **brilho**.
-
-```json
-{ "tipo": "numeros", "itens": ["+38% | em 12 meses"], "contar": true, "som": "ding" }
-{ "tipo": "icone", "nome": "foguete", "estilo": "app", "som": "pop" }
-{ "tipo": "texto", "texto": "Agora.", "som": { "arquivo": "/midia/little-whoosh-3.mp3", "volume": 0.8 } }
-{ "tipo": "texto", "texto": "3, 2, 1", "som": { "nome": "tique", "em": 1.5 } }
-```
-
-`som` aceita o nome, ou `{ "arquivo": "/midia/…", "volume": 0–1 }` para um
-efeito baixado com `buscar_audio` (tipo `"efeito"`) ou enviado pelo usuário;
-`"em"` (segundos na cena) força o instante. O arquivo entra no mesmo grafo da
-trilha, então vai junto para o MP4. Regra: **um som por ideia, não por
-elemento** — três ou quatro por vídeo; tudo apitando é ruído, e a narração
-tem de continuar por cima.
-
----
-
-## Transições
-
-Na cena, `transicao` define como ela **entra**:
-
-`corte` (sem efeito) · `fade` · `deslizar` · `subir` · `zoom` · `limpar` ·
-`persiana` · `flash`
-
-Vale o mesmo conselho das animações: varie. Tudo em `fade` parece slide, não vídeo.
-
-## Chaves de animação
-
-`anim` faz o elemento **entrar** e parar por ali. Para ele se mexer ao longo da
-cena — atravessar, crescer devagar, sumir no fim — use `chaves`: uma lista de
-instantes, com `t` de 0 (começo da cena) a 1 (fim).
-
-```json
-{ "tipo": "texto", "texto": "Atravessa a tela",
-  "chaves": [
-    { "t": 0,    "x": -400, "opacidade": 0 },
-    { "t": 0.25, "x": 0,    "opacidade": 1 },
-    { "t": 0.75, "x": 0,    "opacidade": 1 },
-    { "t": 1,    "x": 400,  "opacidade": 0 }
-  ] }
-```
-
-Campos de uma chave, todos opcionais: `x` e `y` (**deslocamento** em pixels a
-partir de onde o elemento está — não é posição absoluta), `escala` (1 = tamanho
-normal), `giro` (graus), `opacidade` (0 a 1) e `desfoque` (pixels).
-
-**Em 3D:** `giroY` e `giroX` (graus — o elemento vira em profundidade, como um
-cartão girando na mão), `prof` (pixels — aproxima ou afasta da câmera) e
-`escalaX`/`escalaY` (achatar num eixo só: a gota que pousa e se espalha).
-
-```json
-{ "tipo": "icone", "nome": "foguete", "estilo": "app", "tamanho": 220,
-  "chaves": [
-    { "t": 0,   "giroY": -90, "prof": -400, "opacidade": 0 },
-    { "t": 0.35, "giroY": 0,  "prof": 0,    "opacidade": 1 },
-    { "t": 1,   "giroY": 12 }
-  ], "suavizar": "elastico", "som": "pop" }
-```
-
-**A curva** (`suavizar`, no elemento): `"suave"` (padrão) · `"linear"` ·
-`"entrada"` (acelera) · `"saida"` (freia) · `"elastico"` (passa do ponto e
-volta — o pouso de app) · `"salto"` (recua, dispara e assenta) · `"degrau"`
-(quadro a quadro, stop-motion). Aceita também um `cubic-bezier(…)` cru.
-`"repetir": true` roda sem parar; com `"vaiEVolta": true` ele vai e volta em
-vez de recomeçar — é a levitação de um objeto.
-
-Um exemplo de cada coisa que motion pede — **entrar de lado, respirar, sair**:
-
-```json
-"chaves": [ { "t": 0, "x": -300, "opacidade": 0 }, { "t": 0.2, "x": 0, "opacidade": 1 },
-            { "t": 0.85, "x": 0, "opacidade": 1 }, { "t": 1, "x": 120, "opacidade": 0 } ]
-```
-
-Duas chaves já bastam. Quem tem `chaves` ignora `anim` — as duas disputariam o
-mesmo movimento, e a chave é mais específica. Use em **um ou dois** elementos
-por vídeo: tudo se mexendo ao mesmo tempo cansa e esconde a mensagem.
-
-## Câmera da cena — o quadro também se move
-
-`chaves` move um elemento. `camera` move o **quadro inteiro**: é o que separa
-motion de slide animado. Na cena:
-
-```json
-{ "layout": "capa", "duracao": 4, "camera": "aproximar" }
-```
-
-Movimentos com nome: `aproximar` · `afastar` · `pan-direita` · `pan-esquerda` ·
-`subir` · `descer` · `empurrar` (zoom com um grau de giro — a mão humana) ·
-`balanco`.
-
-Para um movimento seu, as mesmas chaves dos elementos:
-
-```json
-"camera": { "chaves": [ { "t": 0, "escala": 1.15, "x": -40 },
-                        { "t": 1, "escala": 1, "x": 0 } ], "suavizar": "saida" }
-```
-
-O **fundo não anda junto** — é assim de propósito: o quadro passa sobre o
-fundo, e é daí que vem a sensação de profundidade sem custo nenhum.
-
-### Paralaxe — as camadas andam em velocidades diferentes
-
-No elemento, `paralaxe` diz o quanto ele acompanha a câmera: `1` é o padrão
-(anda com o quadro), acima de 1 vem à frente e anda **mais**, abaixo de 1 fica
-ao fundo e anda **menos**.
-
-```json
-{ "tipo": "imagem", "src": "/midia/cidade.jpg", "paralaxe": 0.4 }
-{ "tipo": "texto", "papel": "titulo", "texto": "São Paulo", "paralaxe": 1.25 }
-```
-
-Duas ou três camadas bastam: fundo em 0,3–0,5, conteúdo em 1, o que está na
-frente em 1,2–1,4. Um elemento que já tem `chaves` próprias e está no fluxo
-ignora a paralaxe — a animação dele é mais específica, e embrulhar mudaria o
-espaçamento da cena.
-
-**Um movimento de câmera por cena, e não em todas.** Câmera em tudo embrulha o
-olho; o que dá ritmo é alternar cena parada e cena com movimento.
-
-## Acabamento
-
-Textura por cima da cena inteira — é o que tira a cara de template:
-
-`grao` · `vinheta` · `scanlines` · `luz` · `brilho` · `moldura`
-
-Pode ir no documento (vale para tudo) ou por cena. `grao` no documento inteiro
-dá unidade de película ao vídeo.
-
-## Fundos
-
-`malha` `brilho` `grade` `pontos` `suave` `vinheta` `aurora` `raios` `ondas`
-`nevoa` `xadrez`, ou cor, gradiente e foto:
-
-```json
-"fundo": { "imagem": "/midia/foto.jpg", "escurecer": 0.55 }
-```
-
-## Movimento de imagem (Ken Burns)
-
-```json
-{ "tipo": "imagem", "src": "/midia/foto.jpg", "x": 0, "y": 0, "l": 1080, "a": 1920,
-  "raio": 0, "movimento": "aproximar", "filtro": "contraste" }
-```
-
-`movimento`: `aproximar` `afastar` `esquerda` `direita` `cima` ·
-`filtro`: `cinza` `sepia` `contraste` `desbotado`
-
-Imagem parada em vídeo denuncia preguiça. Sempre dê movimento.
-
-## Texto com estilo
-
-`estilo` no elemento de texto:
-
-`gradiente` · `contorno` · `contorno-tom` · `sombra` · `brilho` · `relevo` ·
-`marcador` (fundo tipo caneta) · `fita` (tarja cheia) · `caixa`
-
-## Animações de entrada
-
-`subir` `surgir` `esquerda` `direita` `zoom` `desfoque` `cair` `girar` `saltar`
-`revelar` `cortina` `elastico` `palavra` (palavra por palavra) `nenhuma`
-
-Em `numeros`, `"contar": true` faz o número subir do zero — funciona muito bem
-combinado com `saltar`.
-
-Em `lista`, `"revelar": true` distribui os itens dentro da duração da cena;
-`intervalo` (segundos) controla o espaçamento entre eles.
-
----
-
-## No modo Abrir
-
-Toca sozinho ao carregar, com barra de transporte embaixo:
-play/pausa, linha do tempo clicável com marca por cena, tempo, volume e **Gravar**.
-
-`K` toca e pausa · `M` corta o som · `→` `←` pulam cena · `F` tela cheia · `Escape` para.
-
-## Baixar o vídeo como arquivo
-
-O botão **Baixar MP4** no player faz tudo sozinho: pede a permissão de captura, toca
-do começo, para no fim e baixa. Sai `.mp4` (H.264/AAC, que toca em qualquer lugar) nos
-navegadores que sabem gravar MP4; onde não sabem, sai `.webm`.
-
-**Se o usuário pedir o arquivo do vídeo** — "baixa", "exporta", "me manda em mp4",
-"quero mandar no WhatsApp" — abra o player já em modo de gravação:
-
-```
-open_in_browser  →  http://localhost:7777/v/<id>#gravar
-```
-
-A âncora `#gravar` dispara o download assim que a página abre; o usuário só confirma a
-permissão de captura. **Não** use `write_file` para criar `.mp4`, e **nunca** chame
-ffmpeg: o vídeo já nasce pronto aqui, e escrever um `.mp4` com write_file produz um
-arquivo de texto com nome de vídeo — já aconteceu.
-
-Para o melhor resultado, entre em tela cheia (`F`) antes de gravar.
-
-O export normal (`/api/arquivos/<id>/export`) devolve um `.html` autônomo com a
-mídia embutida — abre offline em qualquer navegador e toca igual.