@praeko/studio 0.0.0-stage → 0.1.0

package/dist/voz-vozes.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);
+
+// ../voz/src/index.mjs
+import { ElevenLabsClient as ElevenLabsClient2 } from "@elevenlabs/elevenlabs-js";
+
+// ../voz/src/config.mjs
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+
+// ../voz/src/padrao.mjs
+var VOZES_PADRAO = {
+  "contas": {
+    "elevenlabs": [
+      "principal"
+    ]
+  },
+  "vozes": {
+    "rascunho-mudo": {
+      "provedor": "estimado",
+      "palavrasPorMin": 190
+    },
+    "minha-voz": {
+      "provedor": "elevenlabs",
+      "modelo": "eleven_v4",
+      "ids": {},
+      "alinhador": "scribe"
+    },
+    "voz-local": {
+      "provedor": "voicestudio",
+      "modelo": "",
+      "id": "",
+      "idioma": "pt-BR",
+      "ajustes": {},
+      "alinhador": "voicestudio"
+    }
+  },
+  "estrategia": {
+    "elevenlabs": "failover-saldo"
+  },
+  "qualidade": {
+    "rascunho": "rascunho-mudo",
+    "local": "voz-local",
+    "final": "minha-voz"
+  },
+  "voicestudio": {
+    "base": "http://127.0.0.1:3900"
+  }
+};
+
+// ../voz/src/config.mjs
+var pastaConfigUsuario = () => process.env.PRAEKO_STUDIO_CONFIG || join(homedir(), ".config", "praeko", "studio");
+var arquivoVozesUsuario = () => join(pastaConfigUsuario(), "vozes.json");
+var arquivoSegredos = () => process.env.PRAEKO_SEGREDOS || join(homedir(), ".config", "praeko", "segredos.json");
+var SERVICO_CHAVEIRO = "praeko";
+var chaveiroAtivo = () => process.platform === "darwin" && !process.env.PRAEKO_SEM_CHAVEIRO;
+function raizDoProjeto(de = process.cwd()) {
+  let d = resolve(de);
+  for (; ; ) {
+    if (existsSync(join(d, "marca.json"))) return d;
+    const p = dirname(d);
+    if (p === d) return null;
+    d = p;
+  }
+}
+var arquivoVozesProjeto = (de) => {
+  const r = raizDoProjeto(de);
+  return r ? join(r, "vozes.json") : null;
+};
+var lerJson = (a) => {
+  try {
+    return JSON.parse(readFileSync(a, "utf8"));
+  } catch (e) {
+    throw new Error(`${a}: JSON inv\xE1lido (${e.message})`);
+  }
+};
+var mesclar = (base, extra) => ({
+  ...base,
+  ...extra,
+  contas: { ...base.contas, ...extra.contas },
+  vozes: { ...base.vozes, ...extra.vozes },
+  estrategia: { ...base.estrategia, ...extra.estrategia },
+  qualidade: { ...base.qualidade, ...extra.qualidade },
+  voicestudio: { ...base.voicestudio, ...extra.voicestudio }
+});
+function carregarConfig(arquivo) {
+  if (arquivo) return mesclar({ contas: {}, vozes: {}, estrategia: {} }, lerJson(arquivo));
+  let c = structuredClone(VOZES_PADRAO);
+  for (const a of [arquivoVozesUsuario(), arquivoVozesProjeto()]) if (a && existsSync(a)) c = mesclar(c, lerJson(a));
+  return c;
+}
+var envDe = (ref) => [`PRAEKO_STUDIO_KEY_${ref.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`, ...ref === "elevenlabs/principal" ? ["ELEVENLABS_API_KEY"] : [], ...ref === "praeko/principal" ? ["PRAEKO_KEY"] : []];
+var canonica = (ref) => ref === "praeko/principal" ? "praeko/chave" : ref;
+var lerSegredos = () => {
+  try {
+    return existsSync(arquivoSegredos()) ? JSON.parse(readFileSync(arquivoSegredos(), "utf8")) : {};
+  } catch {
+    return {};
+  }
+};
+function obterChave(ref) {
+  for (const n of envDe(ref)) if (process.env[n]) return process.env[n];
+  const refs = [.../* @__PURE__ */ new Set([canonica(ref), ref])];
+  if (chaveiroAtivo()) for (const r of refs) {
+    try {
+      const k = execFileSync("security", ["find-generic-password", "-s", SERVICO_CHAVEIRO, "-a", r, "-w"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      if (k) return k;
+    } catch {
+    }
+  }
+  const seg = lerSegredos();
+  for (const r of refs) if (seg[r]) return seg[r];
+  return null;
+}
+
+// ../voz/src/provedores/elevenlabs.mjs
+import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
+function criarElevenLabs({ chave }) {
+  const client = new ElevenLabsClient({ apiKey: chave });
+  return {
+    nome: "elevenlabs",
+    /** `{ texto, id, modelo, ajustes }` → Buffer de mp3 */
+    async gerar({ texto, id, modelo, ajustes = {} }) {
+      const audio = await client.textToSpeech.convert(id, {
+        text: texto,
+        modelId: modelo || "eleven_v4",
+        languageCode: "pt",
+        outputFormat: "mp3_44100_128",
+        voiceSettings: { stability: ajustes.stability ?? 0.5, similarityBoost: ajustes.similarity ?? 0.75, style: ajustes.style ?? 0, useSpeakerBoost: true, speed: ajustes.speed ?? 1 }
+      });
+      const chunks = [];
+      for await (const c of audio) chunks.push(c);
+      return Buffer.concat(chunks);
+    },
+    /** `{ usados, limite, restantes, plano, reinicia }` (caracteres) */
+    async saldo() {
+      const r = await fetch("https://api.elevenlabs.io/v1/user/subscription", { headers: { "xi-api-key": chave } });
+      if (!r.ok) {
+        const e = new Error(`saldo: HTTP ${r.status}`);
+        e.statusCode = r.status;
+        throw e;
+      }
+      const d = await r.json();
+      return { usados: d.character_count, limite: d.character_limit, restantes: d.character_limit - d.character_count, plano: d.tier, reinicia: d.next_character_count_reset_unix ? new Date(d.next_character_count_reset_unix * 1e3) : null };
+    }
+  };
+}
+
+// ../voz/src/roteador.mjs
+async function saldos({ config = carregarConfig(), criar } = {}) {
+  const fabrica = criar || ((conta, chave) => criarElevenLabs({ chave }));
+  const out = [];
+  for (const conta of config.contas?.elevenlabs || []) {
+    const chave = obterChave(`elevenlabs/${conta}`);
+    if (!chave) {
+      out.push({ conta, erro: "sem chave" });
+      continue;
+    }
+    try {
+      out.push({ conta, ...await fabrica(conta, chave).saldo() });
+    } catch (e) {
+      out.push({ conta, erro: e.message });
+    }
+  }
+  return out;
+}
+
+// ../voz/src/provedores/voicestudio.mjs
+var BASE_PADRAO = "http://127.0.0.1:3900";
+var dormir = (ms) => new Promise((r) => setTimeout(r, ms));
+function prepararTexto(texto) {
+  return texto.replace(/\[[^\]]*\]/g, "").replace(/\bIA\b/g, "intelig\xEAncia artificial").replace(/\s*\n\s*/g, " ").replace(/ {2,}/g, " ").trim();
+}
+function criarVoiceStudio({ base = BASE_PADRAO, esperar = dormir } = {}) {
+  return {
+    nome: "voicestudio",
+    base,
+    /** { ok, device, versao } ou { ok: false, motivo } */
+    async disponivel() {
+      try {
+        const r = await fetch(`${base}/health`, { signal: AbortSignal.timeout(3e3) });
+        if (!r.ok) return { ok: false, motivo: `HTTP ${r.status}` };
+        const d = await r.json();
+        return { ok: d.status === "ok", device: d.device, versao: d.version };
+      } catch (e) {
+        return { ok: false, motivo: `sem resposta em ${base} (abra o VoiceStudio)` };
+      }
+    },
+    /** Perfis de voz: [{ id, name, language }] */
+    async perfis() {
+      const r = await fetch(`${base}/profiles`, { signal: AbortSignal.timeout(1e4) });
+      const d = await r.json();
+      return (Array.isArray(d) ? d : d.profiles || d.data || []).map((p) => ({ id: p.id, name: p.name, language: p.language }));
+    },
+    /** `{ texto, id, modelo, idioma, ajustes, tentativas, intervalo }` → Buffer (wav). 429 = ocupado: espera e repete. */
+    async gerar({ texto, id, modelo = "omnivoice", idioma = "pt-BR", ajustes = {}, tentativas = 15, intervalo = 6e4, limite = 18e5 }) {
+      const corpo = JSON.stringify({ model: modelo, input: prepararTexto(texto), voice: id, language: idioma, response_format: "wav", ...ajustes });
+      for (let i = 0; i < tentativas; i++) {
+        const r = await fetch(`${base}/v1/audio/speech`, { method: "POST", headers: { "Content-Type": "application/json" }, body: corpo, signal: AbortSignal.timeout(limite) });
+        if (r.status === 429) {
+          await esperar(intervalo);
+          continue;
+        }
+        if (!r.ok) {
+          const e = new Error(`VoiceStudio: HTTP ${r.status} ${(await r.text()).slice(0, 200)}`);
+          e.statusCode = r.status;
+          throw e;
+        }
+        return Buffer.from(await r.arrayBuffer());
+      }
+      throw new Error("VoiceStudio ocupado (429) depois de v\xE1rias tentativas");
+    },
+    /** Transcrição com tempo por palavra (faster-whisper do próprio VoiceStudio). → [{ t, a, b }] */
+    async transcrever({ audio, bytes, idioma = "pt" }) {
+      const f = new FormData();
+      f.append("file", new Blob([bytes]), audio.split("/").pop());
+      f.append("model", "whisper-1");
+      f.append("language", idioma);
+      f.append("response_format", "verbose_json");
+      f.append("timestamp_granularities[]", "word");
+      const r = await fetch(`${base}/v1/audio/transcriptions`, { method: "POST", body: f, signal: AbortSignal.timeout(6e5) });
+      if (!r.ok) throw new Error(`VoiceStudio (transcri\xE7\xE3o): HTTP ${r.status} ${(await r.text()).slice(0, 200)}`);
+      const d = await r.json();
+      return { palavras: (d.words || []).map((w) => ({ t: w.word.trim(), a: +w.start.toFixed(2), b: +w.end.toFixed(2) })), texto: d.text };
+    }
+  };
+}
+
+// ../voz/src/alinhamento.mjs
+var NUM = new Set("zero um uma dois duas tr\xEAs tres quatro cinco seis sete oito nove dez onze doze treze catorze quatorze quinze dezesseis dezessete dezoito dezenove vinte trinta quarenta cinquenta sessenta setenta oitenta noventa cem cento duzentos duzentas trezentos trezentas quatrocentos quatrocentas quinhentos quinhentas seiscentos seiscentas setecentos setecentas oitocentos oitocentas novecentos novecentas mil milh\xE3o milh\xF5es bilh\xE3o bilh\xF5es meio meia primeiro primeira".split(" "));
+
+// ../voz/bin/vozes.mjs
+var cfg = carregarConfig();
+var vs = criarVoiceStudio({ base: cfg.voicestudio?.base });
+var st = await vs.disponivel();
+var perfis = st.ok ? await vs.perfis() : [];
+console.log(`VoiceStudio: ${st.ok ? `no ar (${st.versao}, ${st.device})` : st.motivo}`);
+for (const [nome, v] of Object.entries(cfg.vozes)) {
+  let nota = "";
+  if (v.provedor === "voicestudio") nota = !st.ok ? "indispon\xEDvel" : perfis.find((p) => p.id === v.id) ? `perfil "${perfis.find((p) => p.id === v.id).name}" ok` : "PERFIL N\xC3O ENCONTRADO";
+  else nota = `contas: ${Object.keys(v.ids || {}).join(", ")}`;
+  console.log(`  ${nome.padEnd(14)} ${v.provedor.padEnd(12)} ${v.modelo || ""} \xB7 alinhador ${v.alinhador || "scribe"} \xB7 ${nota}`);
+}
+console.log("Saldos (ElevenLabs):");
+for (const s of await saldos({ config: cfg })) console.log(`  ${s.conta.padEnd(10)} ${s.erro || `${s.restantes} restantes de ${s.limite}`}`);

package/docs/episodio-yaml.md

@@ -0,0 +1,57 @@
+# Episódio em YAML
+
+`episodios/<slug>/episodio.yaml` descreve o Short; `praeko studio compilar <slug>` (ou `render`/`capa`, que compilam sozinhos) confere e gera `episodio.spec.json`, que o `EpisodioDecl` do `@praeko/studio-kit` lê. O `episodio.tsx` é fixo (criado por `praeko studio novo`). O que o YAML não cobre vai em `cenas.tsx` e é chamado por `componente:`.
+
+## Topo
+```yaml
+id: ComentarioTimestamp          # nome da Composition (padrão: o de episodio.json)
+duracao: 60.2                    # s, vídeo inteiro
+legenda: 80                      # px da legenda palavra a palavra
+voz: audio/comentario-timestamp.mp3
+fundo: ["linhas que flutuam no fundo", "…"]
+golpes: [{ em: 31.5, tipo: flash }, { em: 44.9, tipo: zoom }]   # shake | zoom | flash | tudo
+fechamento: { inicio: 52.4, cta: ARTIGO NO DEVLOG }
+capa: { id: CapaComentario, componente: CapaComentario }          # TSX em cenas.tsx; ou titulo/cor/glow/tam/itens
+cenas: [ … ]
+```
+
+## Tempos por frase (acompanham a voz)
+Em `duracao`, `fechamento.inicio`, `golpes[].em` e no `inicio`/`fim` das cenas vale: número (s) · `"frase"` (início da frase na voz) · `{ quando: "frase", nth: 1, depois: 20, mais: -0.1 }` · `{ voz: 2.5 }` (2,5 s depois do fim da voz; negativo = antes). Resolvido no `praeko studio compilar` com o `palavras.json` atual, então basta recompilar (o `render` já faz) depois de uma voz nova ou de um `praeko studio corte --refazer`. Exemplo: `duracao: { voz: 2.5 }`, `fechamento: { inicio: { voz: -2 }, cta: … }`, `inicio: { quando: "Agora um bug real", mais: -0.1 }`.
+
+## Cena
+```yaml
+- inicio: 7.05          # s; a cena vai até o inicio da próxima (ou `fim:`, ou o fechamento)
+  fim: 52.35            # opcional; muda só a saída do painel
+  titulo: FUI CONFERIR  # faixa do PainelD (layout padrão: painel)
+  layout: painel | livre   # livre = itens soltos na tela (posição absoluta, vídeos)
+  rotulo: FUI CONFERIR  # etiqueta curta da cena
+  sons: [{ at: 0.2, f: pop }]      # s locais; pop | ding | thump | whoosh
+  itens: [ … ]          # ou `componente: NomeEmCenas` (um dos dois)
+```
+
+## Itens
+Todo item tem `tipo`. **Quando aparece:** `quando: "frase"` (ou `[frase, n]` para a n-ésima ocorrência, a partir de 0) liga ao instante da voz em que a frase começa; `deslocar: 0.4` soma segundos; `em: 1.2` é em segundos desde o início da cena. Frase não encontrada na voz é erro. Posição absoluta: `pos: { esquerda, direita, topo, base, largura, altura }`. Cores: nomes do tema (`destaque texto suave ok erro info extra caixa`) ou `#hex`. **Dentro de `{ … }`, texto com vírgula vai entre aspas.**
+
+| tipo | campos |
+|---|---|
+| `texto` | `texto` (`\n` quebra), `tamanho`, `cor`, `fonte` (`padrao`, `mono`; omitido herda), `alinhar: esquerda`, `altura`, `peso`, `pop`, `semFade`, `semQuebra` |
+| `big` | `texto`, `tamanho`, `cor`, `mono` |
+| `caixa` | `texto`, `tamanho`, `cor`, `mono`, `apagada`, `tracejada` |
+| `linha` | `partes: [{texto, mono, cor, peso}]`, `tamanho`, `cor` |
+| `balao` | `texto`, `cor`, `autor` |
+| `codigo` | `titulo`, `cor`, `linhas: [{s, cor, marca}]` |
+| `cartao` | `linhas: [[{texto, cor, peso}]]`, `tamanho`, `cor` (entra deslizando) |
+| `barra` | `altura`, `raio`, `gradiente: [cor, "cor 60%", …]`, `borda: false`, `preenche: {de, ate, inicio, duracao}`, `brilhoAoFim`, `semFade` |
+| `barras` | `linhas: [{rotulo, valor, texto}]`, `max`, `larguraMax`, `larguraRotulo`, `passo`, `gap`, `cor` |
+| `janela` | `src`, `duracaoClipe`, `de`, `reg: [x, y, w, h]`, `tag`, `pos` (esquerda, topo, largura) |
+| `celular` | `src`, `duracaoClipe`, `de`, `pos` |
+| `pilha` / `fila` | `itens`, `gap`, `alinhar` (`centro`, `inicio`, `fim`, `esticar`); fila: `centrar: false`, `espalhar: true` |
+
+## O que o compilador confere
+Erros (não grava o spec): campo obrigatório ausente, `tipo` ou cor desconhecidos, chave desconhecida (inclui a vírgula sem aspas), cenas fora de ordem, frase que não está em `palavras.json`. Avisos (estimativa, não prova): âncora fora da janela da cena, itens que somam mais altura do que o painel (920 px) ou largura maior que 844 px, texto que deve quebrar, itens com posição absoluta que se cruzam, duração com menos de 1 s depois do fim da voz. Sempre olhe também `praeko studio folha <slug>`.
+
+## Equivalência com TSX
+`comentario-timestamp` (7 cenas) e `raide-ep1` (6 cenas, vídeos e barras animadas) foram portados do TSX para este formato: o primeiro renderiza **idêntico** (PSNR inf), o segundo dentro do ruído do `OffthreadVideo` (média 54,2 dB, mínimo 47,4). A conferência achou um bug do original do raide: a âncora `"dano"` da cena 5 pegava a primeira ocorrência (18,98 s) e a frase aparecia no início da cena.
+
+## Motor de render
+`motor: hyperframes` (ou `remotion`) no topo do YAML escolhe quem renderiza este episódio; `praeko studio render --motor …` tem a palavra final. Cenas com `componente:` só renderizam no Remotion. Ver [`hyperframes.md`](hyperframes.md).

package/docs/hyperframes.md

@@ -0,0 +1,79 @@
+# HyperFrames como segundo motor de render
+
+O Praeko Studio renderiza com o **Remotion** (padrão) ou com o **HyperFrames** (HTML + GSAP, render por captura de quadros). O `episodio.yaml`, a voz, a legenda, a capa e o pacote de publicação são os mesmos; só muda quem desenha os quadros.
+
+```
+praeko studio render <slug> --motor hyperframes     # out/<slug>.hf.mp4 (não sobrescreve o do Remotion)
+praeko studio prever <slug> --motor hyperframes     # abre o preview do HyperFrames no projeto gerado
+praeko studio compilar <slug> --motor hyperframes   # avisa as cenas que usam `componente:` (TSX)
+```
+
+Qual motor um episódio usa (a primeira que existir): `--motor` na linha de comando → `motor: hyperframes` no topo do `episodio.yaml` → `"motor": "hyperframes"` no `marca.json` → `remotion`. Um canal novo pode usar `"motor": "hyperframes"` na marca e nunca tocar no Remotion (a capa continua sendo um `still` do Remotion: `praeko studio capa`).
+
+## O que acontece
+
+1. Compila o `episodio.yaml` (`episodio.spec.json`), como sempre.
+2. `@praeko/studio-hyperframes` gera um projeto em `<projeto>/.hf/<slug>/` (já no `.gitignore` do `praeko studio init`): `index.html`, uma sub-composição por cena em `compositions/`, `assets/` com **só** o que o episódio usa (copiado do `publico` da marca).
+3. `npx hyperframes@0.9.13 check --json`: erros param o render; avisos viram uma linha de resumo (código × quantidade).
+4. `npx hyperframes@0.9.13 render --output out/<slug>.hf.mp4`.
+
+O projeto gerado é descartável: não edite `.hf/`, edite o YAML e rode de novo. Para editar visualmente, abra `.hf/<slug>` no app do HyperFrames; o que você mexer lá some na próxima geração.
+
+## Short (1080×1920)
+
+Os itens do YAML (`texto`, `big`, `caixa`, `linha`, `balao`, `codigo`, `janela`, `celular`, `barra`, `barras`, `pilha`, `fila`, `cartao`) viram HTML com as mesmas medidas do kit do Remotion: painel de 70 px de margem, rótulo, legenda palavra a palavra (mesmo agrupamento de 3 palavras), barra de progresso, golpes (tremor, zoom, clarão), fundo de terminal de duas colunas, sons (whoosh, pop por cena, ding no fecho) e fechamento com avatar, handle e CTA. `quando` resolve para o tempo local da cena como no Remotion.
+
+Diferenças conhecidas:
+- **Fontes:** só as embutidas do HyperFrames resolvem pelo nome. Arial Black vira Montserrat 900 e Menlo vira JetBrains Mono (largura um pouco diferente; texto que quebra em uma pode quebrar na outra). Com `"hyperframes": { "fontesLocais": true }` no `marca.json` a fonte da marca é carregada do sistema (`local()`), com a embutida de reserva: paridade exata, mas só nesta máquina.
+- **Vídeos gravados de tela ou de app** (`janela`, `celular`): o trecho `[de, duracaoClipe]` repete até o fim da cena (vários `<video>` em sequência, no lugar do `Loop`).
+- **Ponto vermelho** da etiqueta da janela é fixo (no Remotion pisca).
+- **Áudio** sai uns 3 dB mais alto (média −16,8 dB contra −19,8 dB no mesmo Short): conferir com `praeko studio checar` antes de publicar.
+- **Zona segura vertical:** as posições do YAML valem como estão (o rótulo fica em y=70, a legenda em 190 px da base). O `check` do HyperFrames não reclama, mas as bordas dos apps cobrem o topo.
+
+## Longo (1920×1080)
+
+Reaproveita o plano do `episodio.yaml` (`formato: longo`: `codigo`, `cartao`, `chip`, `txt`, `video`, `celular`, `barra`, `contador`, `fluxo`) e acrescenta uma edição própria do motor:
+- barra de capítulos no topo, com o título do capítulo corrente;
+- transição entre capítulos (varredura horizontal, vertical, íris e escurecimento, em rodízio) com o número e o nome do capítulo, no silêncio entre os blocos (`blocos.json`) e com whoosh;
+- número do capítulo ao fundo, brilho de fundo que muda de cor por capítulo;
+- legenda palavra a palavra (a palavra falada fica dourada);
+- tela final com `fecho:` (texto, link, imagem).
+
+Mascote opcional, só neste motor: no `episodio.yaml` do longo,
+
+```yaml
+mascote:
+  - { quando: "cinco radiantes voltaram", gato: chocado }       # gatos/gato-chocado.png
+  - { quando: "a trava so fazia", gato: cafe, mais: 0.5 }
+```
+
+o gato aparece no canto inferior direito por ~3 s na cena em que a frase é falada.
+
+Linhas de código: `hl: [frase-de-início, frase-de-fim]` acende a linha entre as duas frases (como no Remotion).
+
+## Limites
+
+- **`componente:` (TSX) não existe no HyperFrames.** Cena (ou capa) feita em `cenas.tsx` precisa virar itens no YAML ou o episódio fica no Remotion. O gerador falha com o slug, o número, o título e o componente da cena; `praeko studio compilar --motor hyperframes` avisa antes. A capa de TSX não conta: ela sempre sai do Remotion.
+- Os tempos do `check` são de um instante amostrado: avisos de contraste em barras ainda zeradas e de tela vazia no quadro 0 são esperados (o quadro 0 de um Short é só o fundo; a capa é a miniatura).
+- O HyperFrames busca o GSAP no CDN (jsdelivr) e as fontes embutidas na primeira vez: precisa de internet no primeiro render.
+- Versão fixa: `hyperframes@0.9.13` (`VERSAO_HF` em `packages/hyperframes/src/comum.mjs`). Subir a versão = rodar os testes e comparar quadros.
+
+## Remotion × HyperFrames (medido em 04/11/2026, M4 de 10 núcleos)
+
+| Episódio | Remotion (GL angle) | HyperFrames (render) | HyperFrames (com geração e check) |
+|---|---|---|---|
+| Short `heranca-corte-cofre` (53 s) | 26 s | 32 s | 38 s |
+| Short `raide-ep1` (42 s, janelas, celular, barras) | 43 s | 40 s | 54 s |
+| Longo `heranca-longo` (7:47; saída 38 MB contra 56 MB do Remotion) | 7:12 (GL padrão) · 7:53 (GL angle) | 3:29 | 3:54 |
+
+Observações: o `angle` só ajuda nos Shorts (blur, sombras em 1080×1920); no longo ele não ganhou nada (7:12 com o padrão, 7:53 com `angle`; em 1200 quadros, 46 s contra 44 s), então vale medir antes de trocar. O Remotion só ficou rápido nos Shorts depois de `Config.setChromiumOpenGlRenderer("angle")` no `remotion.config.ts` (antes: 102 s para o mesmo Short; PSNR de 48 dB entre os dois renderizadores). O HyperFrames paga ~6 s de compilação por render e ~6 s de `check`. Concorrência do Remotion (5 ou 10) não mudou nada.
+
+## Quando escolher cada um
+
+| Situação | Motor |
+|---|---|
+| Episódio com cena em TSX (`componente:`) ou capa de peça própria | Remotion |
+| Short de rotina do canal atual | Remotion (mesmo tempo, mesma aparência de sempre) |
+| Longo, ou qualquer vídeo em que a edição (transições, capítulos, mascote) pesa | HyperFrames |
+| Canal novo, sem TSX legado | HyperFrames como padrão (`"motor": "hyperframes"` na marca) |
+| Quer mexer no resultado em editor visual | HyperFrames (abre `.hf/<slug>` no app) |

package/docs/longo-yaml.md

@@ -0,0 +1,78 @@
+# Longo em YAML (16:9, 1920×1080)
+
+`episodio.yaml` com `formato: longo`. Tempo é **global** (segundos desde o início do vídeo). `praeko studio compilar <slug>` valida e gera `episodio.spec.json`; `praeko studio render <slug>` renderiza (compila antes).
+
+## Roteiro em blocos
+```
+## 1 · O GANCHO
+[curious] texto falado…
+
+## 2 · O PROBLEMA
+…
+```
+`praeko studio voz <slug> [--qualidade rascunho|final|local]` gera um áudio por bloco em `voz-blocos/` (nome com hash do texto, voz e pronúncia: só o bloco editado é regerado, o que poupa crédito do ElevenLabs), junta com 0,6 s de pausa em `voz.mp3` e escreve `palavras.json`, `palavras.ts` e `blocos.json` (`[{n, titulo, a, b}]`). Blocos antigos ficam no cache.
+
+## Topo e cenas
+```yaml
+formato: longo
+id: BancaLongo
+duracao: 334
+voz: audio/banca-longo-voz.mp3
+cenas:
+  - { titulo: O GANCHO, inicio: 0, componente: S1 }          # cena em TSX (cenas.tsx exporta S1: React.FC<{t:number}>)
+  - titulo: O PROBLEMA
+    inicio: 31.0                                              # s; ou { bloco: 2 } (usa blocos.json); `n` opcional (padrão: posição)
+    itens: [ … ]
+```
+Cada cena vai do seu `inicio` ao da próxima (a última, até `duracao`); entra e sai com fade e mostra "n · TÍTULO" no canto.
+
+## Tempo (`quando`, `hl`)
+`número` (s) · `"frase"` (início da frase na voz) · `{ quando: "frase", nth: 1, depois: 83, mais: 0.6 }` (`nth` = ocorrência, `depois` = ignora antes de N s, `mais` = soma segundos). Frase que não está em `palavras.json` é erro.
+
+## Itens (todos com `pos: { esquerda, topo, largura, altura }` em px, exceto `texto`)
+| tipo | campos |
+|---|---|
+| `codigo` | `quando`, `titulo`, `tamanho`, `linhas: [{ s, hl: [tempo, tempo], vermelho }]` (a linha acende entre os dois tempos) |
+| `cartao` | `quando`, `cor`, `itens: [texto…]` (entra deslizando) |
+| `texto` | só dentro de `cartao`: `tamanho`, `cor`, `espacar`, `quando` (fade), `texto` ou `partes` |
+| `chip` | `quando`, `cor`, `tamanho`, `texto` |
+| `txt` | `quando`, `tamanho`, `cor`, `alinhar: centro`, `mono`, `texto` ou `partes: [{ texto, cor, mono }]` |
+
+Cores: nomes do tema (`destaque texto suave ok erro info extra caixa`) ou `#hex`. **Texto com vírgula dentro de `{ … }` vai entre aspas** (o compilador acusa chave desconhecida).
+
+## Avisos do compilador (estimativa)
+Item que passa da borda direita ou invade a legenda (abaixo de ~960 px), itens de posição absoluta que se sobrepõem, item que entra fora da janela da cena, duração com menos de 1 s depois do fim da voz.
+
+## Tela final (opcional)
+```yaml
+duracao: { voz: 6 }                 # a tela final precisa de uns 5 s depois da voz
+fecho: { inicio: { quando: "última frase", depois: 480 }, texto: "Obrigado por assistir", link: meusite.com.br }
+```
+Mostra avatar, `texto` (a assinatura), o `handle` do tema e o `link`, sobre as cenas, de `inicio` até o fim (a legenda continua). `inicio` aceita número, "frase" ou `{ voz: N }`; `texto`, `link` e `imagem` (arquivo em `public/`, ex.: `gatos/gato-feliz.png`; padrão: o avatar do tema) são opcionais.
+
+## Capa (YouTube 16:9 e Instagram vertical)
+```yaml
+capa:
+  id: CapaBancaLongo                  # padrão: Capa<id>; a vertical é <id>Vertical
+  titulo: ["DOIS CLIQUES", "UM ITEM"] # 2 linhas; a 2ª sai em destaque (≤ ~16 letras cada na 16:9)
+  gato: chocado                       # gatos/gato-<nome>.png (opcional)
+  codigo: { titulo: social.mjs · marketBuy, linhas: [{ s: "UPDATE market ..." }, { s: "AND sold_to IS NULL", hl: true }] }   # até 3 linhas
+  chips: [{ texto: "ok ✔", cor: ok }, { texto: vendido, cor: erro }]
+```
+`praeko studio capa <slug>` gera `out/<slug>-capa-1280x720.png` e `out/<slug>-capa-vertical-1080x1920.png` (a vertical usa a `Moldura` das capas dos Shorts, dentro da grade 3:4 do Instagram). A capa da banca bate com a publicada a 58,4 dB.
+
+## Pacote de publicação do longo
+`publicacao.json` com `"formato": "longo"` (campos como no Short, mais `yt.comentarioFixo` e `arquivos.capaVertical`). `praeko studio pacote <slug>` monta o `textos.md`: título e alternativas, descrição **com capítulos**, comentário fixo, legenda do Instagram e a conferência. Os capítulos saem das cenas (`inicio` + título em minúsculas) e valem as regras do YouTube: começar em 0:00, 3 ou mais, 10 s cada um (senão é ERRO). Para outros textos, escreva `capitulos: [{ t, titulo }]` no `publicacao.json`. O UTM do YouTube usa `utm_medium=long`. No longo da banca os 9 capítulos saíram iguais aos publicados à mão.
+
+## Itens de mídia e animação (longo)
+Todos com `quando` e `pos`:
+| tipo | campos |
+|---|---|
+| `video` | `src` (em `public/`, 16:9), `duracaoClipe`, `de` (s do clipe), `reg: [x, y, w, h]` (recorte em 1920×1080), `tag`, `pos: { esquerda, topo, largura }` (altura sai do recorte) |
+| `celular` | `src` (vertical 1080×1920), `duracaoClipe`, `de`, `pos: { esquerda, topo, largura }` |
+| `barra` | `valor` (0–1), `duracao`, `cor`, `rotulo`, `texto` (dentro da barra), `altura`, `pos` |
+| `contador` | `de`, `ate`, `duracao`, `casas`, `prefixo`, `sufixo`, `tamanho`, `cor`, `mono`, `alinhar: centro`, `pos` |
+| `fluxo` | `nos: [{ texto (\n quebra), cor, quando }]`, `tamanho`, `cor`, `pos: { esquerda, topo, largura }`: caixas ligadas por setas que entram uma a uma |
+
+## Motor e mascote (HyperFrames)
+`motor: hyperframes` no topo escolhe o motor de render deste longo (padrão: o da marca, depois `remotion`). `mascote: [{ quando: "frase", gato: chocado, mais: 0.5 }]` faz o gato `gatos/gato-chocado.png` aparecer no canto por ~3 s; só o HyperFrames desenha o mascote (o Remotion ignora). Ver [`hyperframes.md`](hyperframes.md).

package/docs/publicar.md

@@ -0,0 +1,22 @@
+# Publicar pelo Praeko
+
+O Studio **não publica nada sozinho**. `praeko studio pacote <slug>` gera `textos.md` e confere limites, hashtags e a declaração de IA; `praeko studio agendar` entrega vídeo, capa e textos ao Praeko, que agenda nas redes conectadas ao seu workspace.
+
+## Pela CLI (`--via praeko`)
+```sh
+echo $CHAVE | praeko studio agendar --via praeko --chave        # chave praeko_… (escopo write); a mesma da `praeko` CLI
+praeko studio agendar --canais --via praeko                     # lista os canais conectados
+praeko studio agendar <slug> --quando "06/11 17:30" --via praeko            # SIMULA (só lê os canais)
+praeko studio agendar <slug> --quando "06/11 17:30" --via praeko --enviar   # envia o vídeo e agenda de verdade
+praeko studio agendar <slug> --status | --cancelar | --limpar
+```
+`marca.json` → `publicacao.provedor: "praeko"` torna o Praeko o padrão (o `init` já grava assim). `publicacao.praeko.canais` fixa a conta quando há mais de uma por rede. YouTube sobe privado e é agendado; TikTok vai como rascunho (`publicacao.praeko.tiktok.modo`); o horário mínimo é 5 minutos à frente.
+
+## Pelo MCP do Praeko (agente com shell)
+O arquivo do vídeo nunca passa pelo MCP. Em um passo: `create_media_upload { type: "video", name, mime, size }` (`size` em bytes: `wc -c < arquivo`) devolve o `curl` pronto; envie o arquivo; depois `complete_media_upload { mediaId }` até o estado `ready`. Então `create_post`/`schedule_post` em **dois passos**: a 1ª chamada devolve só a **prévia** e um `confirmation_code`; **mostre a prévia inteira à pessoa**, espere o sim e repita a chamada com os mesmos argumentos mais `confirm`. O agente nunca confirma sozinho. Veja a documentação de MCP em praeko.app/docs.
+
+## Declaração de IA (conferida pelo `checar` e pelo `pacote`)
+Preencha `"ia": { "sintetico": true|false }` no `publicacao.json`. Voz sintética realista, ou imagem/vídeo gerado que pareça real, precisa do rótulo de conteúdo alterado/sintético: YouTube (campo `containsSyntheticMedia`, enviado quando o Studio publica direto), "AI info" no Instagram e o rótulo de IA no TikTok. Pelo caminho do Praeko, **marque o rótulo no app de cada rede antes de publicar** (a API pública do Praeko ainda não leva esse campo). Rascunhar roteiro com IA ou clonar a **sua própria** voz para narrar não exigem o rótulo no YouTube, mas as regras mudam: confira a política vigente de cada rede.
+
+## Avançado
+`postar` (publicação direta com credenciais suas de cada rede), `fila` e `conta <rede>` seguem no pacote para quem precisa; `fila instalar` usa o launchd e só funciona no macOS. O provedor Buffer (`--via buffer`) é legado.

package/docs/voz.md

@@ -0,0 +1,22 @@
+# Voz no Praeko Studio
+
+`praeko studio voz <slug> --qualidade rascunho|final|local` gera `voz.mp3` e os tempos por palavra (`palavras.json`/`palavras.ts`).
+
+| Qualidade | O que faz | Custo |
+|---|---|---|
+| `rascunho` | voz **estimada e muda** (~190 palavras/min), sem rede | grátis |
+| `final` | ElevenLabs (TTS) + Scribe (tempos por palavra), conta e chave **suas** | caracteres do seu plano |
+| `local` | VoiceStudio (servidor local compatível, `http://127.0.0.1:3900` por padrão) | grátis, precisa estar rodando |
+
+## Configurar a sua voz
+Camadas de `vozes.json` (a de cima vence): **projeto** (ao lado do `marca.json`) > **usuário** (`~/.config/praeko/studio/vozes.json`, ou `PRAEKO_STUDIO_CONFIG`) > padrão do pacote (sem ids).
+1. Guarde a chave: `echo $CHAVE | praeko studio voz config chave elevenlabs/principal` (cofre do sistema no macOS; arquivo `~/.config/praeko/segredos.json` com permissão 600 em Linux; no Windows prefira a variável `ELEVENLABS_API_KEY`).
+2. Cadastre a voz: `praeko studio voz conta adicionar principal --voz minha-voz --voz-id <id da voz>` (grava o id no `vozes.json` do projeto) ou defina `ELEVENLABS_VOICE_ID`.
+3. No `marca.json`, `"voz": "minha-voz"` vale para `voz` sem `--qualidade`; com `--qualidade final` vale a voz de `qualidade.final`. O padrão do `init` é `rascunho-mudo`, para nunca gastar sem querer.
+Mais de uma conta (failover por saldo): `conta adicionar <outra>`; o roteador pula a conta sem saldo ou com chave inválida.
+
+## Regras
+- Use **somente a sua voz** ou uma que você tem autorização para usar (termos do ElevenLabs).
+- Voz sintética realista exige o rótulo de IA nas plataformas: preencha `"ia": { "sintetico": true }` no `publicacao.json`.
+- Chave nunca em arquivo do projeto, em log ou em chat com agente. Ordem de leitura: variável de ambiente, cofre do macOS, arquivo de segredos.
+- O modelo OmniVoice do VoiceStudio é CC-BY-NC (não comercial): não use em conteúdo monetizado.

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@praeko/studio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Praeko Studio: vídeos curtos (9:16) e longos (16:9) a partir de um roteiro, para você operar com o seu próprio agente de código (Claude Code, Codex, Gemini CLI, Cursor, opencode). Voz, legenda palavra a palavra, cenas, capa, textos e publicação pelo Praeko.",
+  "license": "MIT",
+  "keywords": [
+    "praeko",
+    "video",
+    "shorts",
+    "remotion",
+    "captions",
+    "studio",
+    "cli",
+    "agent",
+    "shorts"
+  ],
+  "homepage": "https://praeko.app/docs",
+  "bugs": {
+    "url": "https://praeko.app/docs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Praeko/praeko-js.git",
+    "directory": "studio/packages/cli"
+  },
+  "bin": {
+    "praeko-studio": "dist/praeko-studio.mjs"
+  },
+  "files": [
+    "dist",
+    "modelos",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSES.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../../scripts/build-studio.mjs cli",
+    "prepack": "npm run build",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@elevenlabs/elevenlabs-js": "^2.75.0"
+  },
+  "devDependencies": {
+    "@praeko/studio-hyperframes": "*",
+    "@praeko/studio-publicar": "*",
+    "@praeko/studio-revisar": "*",
+    "@praeko/studio-voz": "*",
+    "yaml": "^2.9.1"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}