# O estúdio do HyperFrames

A pessoa revê a edição no estúdio do HyperFrames: o player em cima e, embaixo, a linha do tempo com uma faixa
por camada (Vídeo do corte, Legenda, cada animação, cada cena, Pessoa recortada, Voz e sons), com o nome de
cada uma. Dá para arrastar a agulha e ver o segundo exato em que cada coisa entra e sai. Tudo roda no
computador dela; nada sobe para a internet.

O estúdio mostra o projeto como ele está, sem render. Mudou o `projeto.json` ou uma cena e rodou o build, ele
recarrega sozinho. Por isso o ciclo de ajuste é rápido: mexe, roda o build, ela olha. Render só no fim.

## Abrir

Dentro do `<PROJ>`:

```
cd '<PROJ>' && python3 build.py corte        # ou amostra <início> <fim>, ou completo
python3 build.py estudio --sem-abrir
```

O comando sobe o estúdio em segundo plano, confere que ele responde e imprime a URL completa, por exemplo
`http://127.0.0.1:3002/#project/criativo-bolsa`. Use essa URL do jeito que saiu: sem o `#project/<pasta>` o
estúdio abre vazio. Se o estúdio deste projeto já estava no ar, ele só mostra a URL de novo.

O estúdio roda o HyperFrames na versão fixa do `package.json` do projeto, a mesma do `python3 build.py hf lint`,
`hf check` e `hf render`. Um estúdio deste projeto que esteja no ar em outra versão é derrubado e sobe de novo.
Nunca chame `npx hyperframes ...` sem versão: o npx baixa a mais nova e o check e o render rodam numa versão, o
estúdio em outra.

- Porta: a primeira livre a partir de 3002, ou `--porta N`. Porta ocupada dá erro sugerindo outra.
- O estúdio continua no ar depois que o comando termina. Derrube no fim do trabalho com
  `python3 build.py estudio --parar`. Ele só derruba o deste projeto (o próprio estúdio diz de que pasta é) e
  confere que a porta fechou; com a máquina carregada o HyperFrames às vezes não acha o estúdio, e aí o comando
  tenta de novo e, se preciso, encerra só o processo desse estúdio. Se ainda assim não fechar, ele diz a porta e
  o processo. **Nunca** use `npx hyperframes preview --kill-all`: derruba os estúdios de outros projetos da
  pessoa.
- Sem o Node: o comando diz que falta e que o instalador do pacote põe o Node em `~/.editor-video/node`.

### Em cada app

- **Claude Code no app (com o painel Browser):** rode com `--sem-abrir` e abra a URL no painel Browser
  (`preview_start` com a `url`). A pessoa vê o estúdio ao lado da conversa. Com o painel **escondido**, a página
  não desenha o vídeo do corte (a prévia fica preta; a legenda, as peças e as miniaturas da linha do tempo
  aparecem): mostre o painel e o vídeo toca normal. Não conclua nada sobre enquadramento com o painel escondido.
- **Claude Code no terminal ou Codex:** rode sem `--sem-abrir`: ele abre o navegador padrão. Ou mande a URL
  para ela abrir no Chrome.
- **Safari:** evite. A pessoa recortada (texto atrás da pessoa, tela verde) é um vídeo com fundo transparente
  que o Safari pode mostrar com fundo preto. Chrome ou Edge mostram certo.
- Se nada abrir, passe a URL por escrito e diga para colar no Chrome.

## O que mostrar em cada etapa

| Etapa | Build | O que pedir para ela olhar |
|---|---|---|
| Corte | `build.py corte` | se sobrou respiro, se alguma palavra ficou mordida, se a ordem conta a história |
| Amostra | `build.py amostra <início> <fim>` (8 s em edição simples, uns 15 s com animação, uns 5 s para texto atrás da pessoa ou 3D) | se cada coisa entra na palavra, se dá para ler no celular, se nada cobre o rosto, se o estilo é esse |
| Vídeo inteiro | `build.py completo` | o vídeo do começo ao fim, com som |

Diga onde olhar ("dá o play em 00:12, é ali que entra a lista"). Antes de mostrar, confira você mesmo:
`python3 build.py hf lint` e `python3 build.py hf check` sem erro, e um snapshot ou quadros dos pontos de troca.

Os efeitos sonoros aparecem numa faixa cada um e o estúdio toca todos, desde que estejam no `projeto.json`
(`plano_sfx.py --projeto`, `references/som-e-trilha.md`). O fim parado (`segura_fim`) aparece como a faixa "Fim
parado".

## Pedidos que chegam do estúdio

- **Por tempo** ("em 00:14 a legenda cobre o produto"): o tempo do estúdio é o tempo do corte. Ache a peça
  que está ali no `projeto.json` e ajuste.
- **"Muda isso aqui"** com ela clicando num elemento: rode no `<PROJ>`
  `python3 build.py hf preview --context --json --context-fields selection`
  e veja o arquivo da composição (`compositions/<id>.html` é a peça `<id>` do `projeto.json`;
  `compositions/cenas/...` é uma cena sob medida) e o texto do que ela selecionou. Sem seleção
  (`no-selection`), peça para ela clicar no elemento e rode de novo.
- **Ela mexeu no estúdio** (arrastou, esticou, trocou um texto): o próximo build reescreve os arquivos. O
  build guarda uma cópia do que foi mexido em `.mexido-no-estudio/` e avisa. Leve a mudança para o
  `projeto.json` (ou para a cena) antes de rodar o build de novo, e conte que fez isso.

## O que pisca no estúdio e não no vídeo

O estúdio toca o vídeo do corte e a pessoa recortada como dois vídeos separados. Numa emenda, no texto atrás
da pessoa ou na tela verde, uma camada pode aparecer um quadro atrasada. No render isso não acontece, porque
ele monta quadro a quadro. Se a pessoa estranhar, diga isso e mostre o trecho renderizado:
`python3 build.py hf render --quality draft --output renders/trecho.mp4` com a `amostra` daquele trecho
(uns 3 minutos por minuto de vídeo neste tipo de Mac). O arquivo renderizado é sempre a referência final.

## Quando dá errado

- Estúdio vazio ou "projeto não encontrado": falta o `#project/<pasta>` na URL. Use a URL que o comando
  imprimiu.
- `preview-not-running` no `--context`: o estúdio caiu. Rode `python3 build.py estudio` de novo.
- A mudança não aparece: confira se o build rodou sem `Erro` e se ela está na aba do projeto certo.
- Vídeo preto na prévia, com a legenda e as peças aparecendo: o painel Browser do app está escondido (mostre)
  ou o navegador é o Safari (use o Chrome).
- Máquina carregada (outros agentes, render rodando): o `estudio` pode levar mais de um minuto para responder, a
  primeira visita mostra a moldura vazia e o estúdio diz que "não recarregou (demorou demais)". Recarregue a
  página. O render draft continua sendo a referência.
- Com um render rodando, o painel Compositions lista também as pastas `renders/work-*`: ignore, somem no fim.
- `--parar` disse que não havia estúdio, mas a porta continua ocupada: rode de novo (ele confere a porta e as
  primeiras 100 portas a partir de 3002). O `.estudio.json` do projeto guarda a porta do último estúdio.
- Faixa chamada "Track N": é uma faixa com vários clipes (a legenda, por exemplo); cada clipe tem o nome dele.