@praeko/studio 0.1.0 → 0.2.0

package/dist/voice-voices.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { createRequire as __cr } from 'node:module'; const require = __cr(import.meta.url);
+
+// ../voice/src/index.ts
+import { ElevenLabsClient as ElevenLabsClient2 } from "@elevenlabs/elevenlabs-js";
+
+// ../voice/src/config.ts
+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";
+
+// ../voice/src/defaults.ts
+var DEFAULT_VOICES = {
+  accounts: { elevenlabs: ["principal"] },
+  voices: {
+    "draft-silent": { provider: "estimated", wordsPerMin: 190 },
+    "my-voice": { provider: "elevenlabs", model: "eleven_v4", ids: {}, aligner: "scribe" },
+    "local-voice": { provider: "voicestudio", model: "", id: "", language: "pt-BR", settings: {}, aligner: "voicestudio" }
+  },
+  strategy: { elevenlabs: "failover-balance" },
+  quality: { draft: "draft-silent", local: "local-voice", final: "my-voice" },
+  voicestudio: { base: "http://127.0.0.1:3900" }
+};
+
+// ../voice/src/config.ts
+var userConfigDir = () => process.env.PRAEKO_STUDIO_CONFIG || join(homedir(), ".config", "praeko", "studio");
+var userVoicesFile = () => join(userConfigDir(), "voices.json");
+var secretsFile = () => process.env.PRAEKO_SECRETS || join(homedir(), ".config", "praeko", "secrets.json");
+var KEYCHAIN_SERVICE = "praeko";
+var keychainActive = () => process.platform === "darwin" && !process.env.PRAEKO_NO_KEYCHAIN;
+function projectRoot(from = process.cwd()) {
+  let d = resolve(from);
+  for (; ; ) {
+    if (existsSync(join(d, "brand.json"))) return d;
+    const p = dirname(d);
+    if (p === d) return null;
+    d = p;
+  }
+}
+var projectVoicesFile = (from) => {
+  const r = projectRoot(from);
+  return r ? join(r, "voices.json") : null;
+};
+var readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    throw new Error(`${file}: invalid JSON (${e.message})`);
+  }
+};
+var merge = (base, extra) => ({
+  ...base,
+  ...extra,
+  accounts: { ...base.accounts, ...extra.accounts },
+  voices: { ...base.voices, ...extra.voices },
+  strategy: { ...base.strategy, ...extra.strategy },
+  quality: { ...base.quality, ...extra.quality },
+  voicestudio: { ...base.voicestudio, ...extra.voicestudio }
+});
+function loadConfig(file) {
+  if (file) return merge({ accounts: {}, voices: {}, strategy: {} }, readJson(file));
+  let c = structuredClone(DEFAULT_VOICES);
+  for (const f of [userVoicesFile(), projectVoicesFile()]) if (f && existsSync(f)) c = merge(c, readJson(f));
+  return c;
+}
+var keyEnvNames = (ref) => [`PRAEKO_STUDIO_KEY_${ref.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`, ...ref === "elevenlabs/principal" ? ["ELEVENLABS_API_KEY"] : [], ...ref === "praeko/main" ? ["PRAEKO_KEY"] : []];
+var canonical = (ref) => ref === "praeko/main" ? "praeko/chave" : ref;
+var readSecrets = () => {
+  try {
+    return existsSync(secretsFile()) ? JSON.parse(readFileSync(secretsFile(), "utf8")) : {};
+  } catch {
+    return {};
+  }
+};
+function getKey(ref) {
+  for (const n of keyEnvNames(ref)) if (process.env[n]) return process.env[n];
+  const refs = [.../* @__PURE__ */ new Set([canonical(ref), ref])];
+  if (keychainActive()) for (const r of refs) {
+    try {
+      const k = execFileSync("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-a", r, "-w"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      if (k) return k;
+    } catch {
+    }
+  }
+  const secrets = readSecrets();
+  for (const r of refs) if (secrets[r]) return secrets[r];
+  return null;
+}
+
+// ../voice/src/providers/elevenlabs.ts
+import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
+function createElevenLabs({ key }) {
+  const client = new ElevenLabsClient({ apiKey: key });
+  return {
+    name: "elevenlabs",
+    /** `{ text, id, model, settings }` → mp3 Buffer */
+    async generate({ text, id, model, settings = {} }) {
+      const audio = await client.textToSpeech.convert(id, {
+        text,
+        modelId: model || "eleven_v4",
+        languageCode: "pt",
+        outputFormat: "mp3_44100_128",
+        voiceSettings: { stability: settings.stability ?? 0.5, similarityBoost: settings.similarity ?? 0.75, style: settings.style ?? 0, useSpeakerBoost: true, speed: settings.speed ?? 1 }
+      });
+      const chunks = [];
+      for await (const c of audio) chunks.push(c);
+      return Buffer.concat(chunks);
+    },
+    /** Characters used, limit, remaining, plan and reset date. */
+    async balance() {
+      const r = await fetch("https://api.elevenlabs.io/v1/user/subscription", { headers: { "xi-api-key": key } });
+      if (!r.ok) {
+        const e = new Error(`balance: HTTP ${r.status}`);
+        e.statusCode = r.status;
+        throw e;
+      }
+      const d = await r.json();
+      return { used: d.character_count, limit: d.character_limit, remaining: d.character_limit - d.character_count, plan: d.tier, resets: d.next_character_count_reset_unix ? new Date(d.next_character_count_reset_unix * 1e3) : null };
+    }
+  };
+}
+
+// ../voice/src/router.ts
+async function balances({ config = loadConfig(), create } = {}) {
+  const factory = create || ((_a, key) => createElevenLabs({ key }));
+  const out = [];
+  const el = config.accounts?.elevenlabs;
+  for (const account of Array.isArray(el) ? el : []) {
+    const key = getKey(`elevenlabs/${account}`);
+    if (!key) {
+      out.push({ account, error: "no key" });
+      continue;
+    }
+    try {
+      out.push({ account, ...await factory(account, key).balance() });
+    } catch (e) {
+      out.push({ account, error: e.message });
+    }
+  }
+  return out;
+}
+
+// ../voice/src/providers/voicestudio.ts
+var DEFAULT_BASE = "http://127.0.0.1:3900";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function prepareText(text) {
+  return text.replace(/\[[^\]]*\]/g, "").replace(/\bIA\b/g, "intelig\xEAncia artificial").replace(/\s*\n\s*/g, " ").replace(/ {2,}/g, " ").trim();
+}
+function createVoiceStudio({ base = DEFAULT_BASE, wait = sleep } = {}) {
+  return {
+    name: "voicestudio",
+    base,
+    async available() {
+      try {
+        const r = await fetch(`${base}/health`, { signal: AbortSignal.timeout(3e3) });
+        if (!r.ok) return { ok: false, reason: `HTTP ${r.status}` };
+        const d = await r.json();
+        return { ok: d.status === "ok", device: d.device, version: d.version };
+      } catch {
+        return { ok: false, reason: `no response at ${base} (open VoiceStudio)` };
+      }
+    },
+    /** Voice profiles. */
+    async profiles() {
+      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 }));
+    },
+    /** Returns a wav Buffer. 429 = busy: waits and retries. */
+    async generate({ text, id, model = "omnivoice", language = "pt-BR", settings = {}, retries = 15, interval = 6e4, limit = 18e5 }) {
+      const body = JSON.stringify({ model, input: prepareText(text), voice: id, language, response_format: "wav", ...settings });
+      for (let i = 0; i < retries; i++) {
+        const r = await fetch(`${base}/v1/audio/speech`, { method: "POST", headers: { "Content-Type": "application/json" }, body, signal: AbortSignal.timeout(limit) });
+        if (r.status === 429) {
+          await wait(interval);
+          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 is busy (429) after several attempts");
+    },
+    /** Transcription with per-word timing (VoiceStudio's own faster-whisper). */
+    async transcribe({ audio, bytes, language = "pt" }) {
+      const f = new FormData();
+      f.append("file", new Blob([bytes]), audio.split("/").pop());
+      f.append("model", "whisper-1");
+      f.append("language", language);
+      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 (transcription): HTTP ${r.status} ${(await r.text()).slice(0, 200)}`);
+      const d = await r.json();
+      return { words: (d.words || []).map((w) => ({ t: String(w.word).trim(), a: +w.start.toFixed(2), b: +w.end.toFixed(2) })), text: d.text };
+    }
+  };
+}
+
+// ../voice/src/alignment.ts
+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(" "));
+
+// ../voice/bin/voices.ts
+var cfg = loadConfig();
+var vs = createVoiceStudio({ base: cfg.voicestudio?.base });
+var st = await vs.available();
+var profiles = st.ok ? await vs.profiles() : [];
+console.log(`VoiceStudio: ${st.ok ? `up (${st.version}, ${st.device})` : st.reason}`);
+for (const [name, v] of Object.entries(cfg.voices)) {
+  let note = "";
+  if (v.provider === "voicestudio") note = !st.ok ? "unavailable" : profiles.find((p) => p.id === v.id) ? `profile "${profiles.find((p) => p.id === v.id).name}" ok` : "PROFILE NOT FOUND";
+  else note = `accounts: ${Object.keys(v.ids || {}).join(", ")}`;
+  console.log(`  ${name.padEnd(14)} ${v.provider.padEnd(12)} ${v.model || ""} \xB7 aligner ${v.aligner || "scribe"} \xB7 ${note}`);
+}
+console.log("Balances (ElevenLabs):");
+for (const s of await balances({ config: cfg })) console.log(`  ${s.account.padEnd(10)} ${"error" in s ? s.error : `${s.remaining} left of ${s.limit}`}`);

package/docs/episode-yaml.md

@@ -0,0 +1,57 @@
+# Episode in YAML
+
+`episodes/<slug>/episode.yaml` describes the Short; `praeko studio compile <slug>` (or `render`/`cover`, which compile on their own) checks it and writes `episode.spec.json`, which the `EpisodeDecl` of `@praeko/studio-kit` reads. `episode.tsx` is fixed (created by `praeko studio new`). What the YAML cannot express goes in `scenes.tsx` and is called with `component:`.
+
+## Top level
+```yaml
+id: CommentTimestamp             # Composition name (default: the one in episode.json)
+duration: 60.2                   # s, whole video
+caption: 80                      # px of the word-by-word caption
+voice: audio/comment-timestamp.mp3
+background: ["lines that float in the background", "…"]
+hits: [{ at: 31.5, type: flash }, { at: 44.9, type: zoom }]   # shake | zoom | flash | all
+outro: { start: 52.4, cta: ARTICLE ON THE DEVLOG }
+cover: { id: CoverComment, component: CoverComment }          # TSX in scenes.tsx; or title/color/glow/size/items
+scenes: [ … ]
+```
+
+## Times by phrase (they follow the voice)
+In `duration`, `outro.start`, `hits[].at` and in the `start`/`end` of scenes you can use: a number (s) · `"phrase"` (start of the phrase in the voice) · `{ when: "phrase", nth: 1, after: 20, plus: -0.1 }` · `{ voice: 2.5 }` (2.5 s after the end of the voice; negative = before). Resolved by `praeko studio compile` with the current `words.json`, so just recompile (`render` already does) after a new voice or after `praeko studio cut --redo`. Example: `duration: { voice: 2.5 }`, `outro: { start: { voice: -2 }, cta: … }`, `start: { when: "Now a real bug", plus: -0.1 }`.
+
+## Scene
+```yaml
+- start: 7.05           # s; the scene runs until the start of the next one (or `end:`, or the outro)
+  end: 52.35            # optional; only changes when the panel leaves
+  title: I WENT TO CHECK # strip of the kit's Panel (default layout: panel)
+  layout: panel | free  # free = loose items on the screen (absolute position, videos)
+  label: I WENT TO CHECK # short tag of the scene
+  sounds: [{ at: 0.2, sound: pop }]   # local s; pop | ding | thump | whoosh
+  items: [ … ]          # or `component: NameInScenes` (one of the two)
+```
+
+## Items
+Every item has a `type`. **When it appears:** `when: "phrase"` (or `[phrase, n]` for the n-th occurrence, from 0) ties it to the instant of the voice where the phrase starts; `offset: 0.4` adds seconds; `at: 1.2` is in seconds since the start of the scene. A phrase not found in the voice is an error. Absolute position: `pos: { left, right, top, bottom, width, height }`. Colors: theme names (`accent text muted ok error info extra box`) or `#hex`. **Inside `{ … }`, text with a comma goes in quotes.**
+
+| type | fields |
+|---|---|
+| `text` | `text` (`\n` breaks), `size`, `color`, `font` (`default`, `mono`; omitted inherits), `align: left`, `lineHeight`, `weight`, `pop`, `noFade`, `noWrap` |
+| `big` | `text`, `size`, `color`, `mono` |
+| `box` | `text`, `size`, `color`, `mono`, `dim`, `dashed` |
+| `line` | `parts: [{text, mono, color, weight}]`, `size`, `color` |
+| `bubble` | `text`, `color`, `author` |
+| `code` | `title`, `color`, `lines: [{s, color, mark}]` |
+| `card` | `lines: [[{text, color, weight}]]`, `size`, `color` (slides in) |
+| `bar` | `height`, `radius`, `gradient: [color, "color 60%", …]`, `border: false`, `fill: {from, to, start, duration}`, `glowAtEnd`, `noFade` |
+| `bars` | `lines: [{label, value, text}]`, `max`, `maxWidth`, `labelWidth`, `step`, `gap`, `color` |
+| `window` | `src`, `clipDuration`, `from`, `reg: [x, y, w, h]`, `tag`, `pos` (left, top, width) |
+| `phone` | `src`, `clipDuration`, `from`, `pos` |
+| `stack` / `row` | `items`, `gap`, `align` (`center`, `start`, `end`, `stretch`); row: `center: false`, `spread: true` |
+
+## What the compiler checks
+Errors (the spec is not written): missing required field, unknown `type` or color, unknown key (this includes the comma without quotes), scenes out of order, phrase that is not in `words.json`. Warnings (an estimate, not a proof): anchor outside the scene window, items that add up to more height than the panel (920 px) or more width than 844 px, text that should wrap, absolutely positioned items that cross, a duration with less than 1 s after the end of the voice. Always look at `praeko studio contact-sheet <slug>` too.
+
+## Equivalence with TSX
+`comment-timestamp` (7 scenes) and `raid-ep1` (6 scenes, videos and animated bars) were ported from TSX to this format: the first one renders **identically** (PSNR inf), the second within the noise of `OffthreadVideo` (mean 54.2 dB, minimum 47.4). The check found a bug in the raid original: the `"damage"` anchor of scene 5 hit the first occurrence (18.98 s) and the phrase showed up at the start of the scene.
+
+## Render engine
+`engine: hyperframes` (or `remotion`) at the top of the YAML chooses who renders this episode; `praeko studio render --engine …` has the final word. Scenes with `component:` only render in Remotion. See [`hyperframes.md`](hyperframes.md).

package/docs/hyperframes.md

@@ -1,79 +1,79 @@
-# HyperFrames como segundo motor de render
+# HyperFrames as a second render engine
 
-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 renders with **Remotion** (default) or with **HyperFrames** (HTML + GSAP, frame-capture rendering). `episode.yaml`, the voice, the captions, the cover and the publication package are the same; only who draws the frames changes.
 
 ```
-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)
+praeko studio render <slug> --engine hyperframes     # out/<slug>.hf.mp4 (does not overwrite the Remotion one)
+praeko studio preview <slug> --engine hyperframes    # opens the HyperFrames preview of the generated project
+praeko studio compile <slug> --engine hyperframes    # warns about scenes that use `component:` (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`).
+Which engine an episode uses (the first one that exists): `--engine` on the command line → `engine: hyperframes` at the top of `episode.yaml` → `"engine": "hyperframes"` in `brand.json` → `remotion`. A new channel can use `"engine": "hyperframes"` in the brand and never touch Remotion (with `--engine hyperframes` the cover is rendered by HyperFrames too: `praeko studio cover <slug> --engine hyperframes`; nothing from Remotion is used).
 
-## O que acontece
+## What happens
 
-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).
+1. Compiles `episode.yaml` (`episode.spec.json`), as always.
+2. `@praeko/studio-hyperframes` generates a project in `<project>/.hf/<slug>/` (already in the `.gitignore` of `praeko studio init`): `index.html`, one sub-composition per scene in `compositions/`, and `assets/` with **only** what the episode uses (copied from the brand's `publicDir`).
+3. `npx hyperframes@0.9.13 check --json`: errors stop the render; warnings become one summary line (code × count).
 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.
+The generated project is disposable: do not edit `.hf/`, edit the YAML and run again. To edit visually, open `.hf/<slug>` in the HyperFrames app; whatever you change there disappears at the next generation.
 
 ## 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.
+The YAML items (`text`, `big`, `box`, `line`, `bubble`, `code`, `window`, `phone`, `bar`, `bars`, `stack`, `row`, `card`) become HTML with the same measures as the Remotion kit: a panel with 70 px margins, label, word-by-word captions (same 3-word grouping), progress bar, hits (shake, zoom, flash), a two-column terminal background, sounds (whoosh, pop per scene, ding at the outro) and an outro with avatar, handle and CTA. `when` resolves to the local time of the scene as in 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.
+Known differences:
+- **Fonts:** only the fonts bundled with HyperFrames resolve by name. Arial Black becomes Montserrat 900 and Menlo becomes JetBrains Mono (slightly different width; text that wraps in one may wrap in the other). With `"hyperframes": { "localFonts": true }` in `brand.json` the brand font is loaded from the system (`local()`), with the bundled one as a fallback: exact parity, but only on this machine.
+- **Game videos** (`window`, `phone`): the segment `[from, clipDuration]` repeats until the end of the scene (several `<video>` elements in sequence, instead of `Loop`).
+- **Red dot** of the window label is fixed (it blinks in Remotion).
+- **Audio** comes out about 3 dB louder (mean −16.8 dB against −19.8 dB in the same Short): check with `praeko studio check` before publishing.
+- **Vertical safe zone:** the YAML positions are used as they are (the label sits at y=70, the caption 190 px from the bottom). HyperFrames' `check` does not complain, but the apps' borders cover the top.
 
-## Longo (1920×1080)
+## Long form (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).
+Reuses the plan of `episode.yaml` (`format: long`: `code`, `card`, `chip`, `freetext`, `video`, `phone`, `bar`, `counter`, `flow`) and adds an edit of the engine's own:
+- a chapter bar at the top, with the title of the current chapter;
+- a transition between chapters (horizontal sweep, vertical, iris and fade, in rotation) with the chapter number and name, in the silence between blocks (`blocks.json`) and with a whoosh;
+- chapter number in the background, a background glow that changes color per chapter;
+- word-by-word captions (the spoken word turns gold);
+- an end screen with `endcard:` (text, link, image).
 
-Mascote opcional, só neste motor: no `episodio.yaml` do longo,
+Optional mascot, only in this engine: in the long form's `episode.yaml`,
 
 ```yaml
-mascote:
-  - { quando: "cinco radiantes voltaram", gato: chocado }       # gatos/gato-chocado.png
-  - { quando: "a trava so fazia", gato: cafe, mais: 0.5 }
+mascot:
+  - { when: "five radiants came back", name: shocked }       # mascotPath: mascots/{name}.png
+  - { when: "the lock only did", name: coffee, plus: 0.5 }
 ```
 
-o gato aparece no canto inferior direito por ~3 s na cena em que a frase é falada.
+the mascot appears in the bottom right corner for ~3 s in the scene where the phrase is spoken.
 
-Linhas de código: `hl: [frase-de-início, frase-de-fim]` acende a linha entre as duas frases (como no Remotion).
+Code lines: `hl: [start-phrase, end-phrase]` lights the line between the two phrases (as in Remotion).
 
-## Limites
+## Limits
 
-- **`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.
+- **`component:` (TSX) does not exist in HyperFrames.** A scene (or cover) made in `scenes.tsx` has to become YAML items or the episode stays in Remotion. The generator fails with the slug, the number, the title and the component of the scene; `praeko studio compile --engine hyperframes` warns before. A cover written as a TSX component (`cover.component`) only exists in Remotion; a declarative cover (title/items) renders in HyperFrames too.
+- The `check` times are those of a sampled instant: contrast warnings on still-empty bars and empty-screen warnings on frame 0 are expected (frame 0 of a Short is only the background; the cover is the thumbnail).
+- HyperFrames fetches GSAP from the CDN (jsdelivr) and the bundled fonts the first time: it needs internet on the first render.
+- Pinned version: `hyperframes@0.9.13` (`HF_VERSION` in `packages/hyperframes/src/common.ts`). Raising the version = running the tests and comparing frames.
 
-## Remotion × HyperFrames (medido em 04/11/2026, M4 de 10 núcleos)
+## Remotion × HyperFrames (measured on 2026-11-04, 10-core M4)
 
-| Episódio | Remotion (GL angle) | HyperFrames (render) | HyperFrames (com geração e check) |
+| Episode | Remotion (GL angle) | HyperFrames (render) | HyperFrames (with generation and 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 |
+| Short (53 s) | 26 s | 32 s | 38 s |
+| Short (42 s, windows, phone, bars) | 43 s | 40 s | 54 s |
+| Long (7:47; output 38 MB against Remotion's 56 MB) | 7:12 (default GL) · 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.
+Notes: `angle` only helps the Shorts (blur, shadows at 1080×1920); on the long form it gained nothing (7:12 with the default, 7:53 with `angle`; on 1200 frames, 46 s against 44 s), so it is worth measuring before switching. Remotion only got fast on the Shorts after `Config.setChromiumOpenGlRenderer("angle")` in `remotion.config.ts` (before: 102 s for the same Short; PSNR of 48 dB between the two renderers). HyperFrames pays ~6 s of compilation per render and ~6 s of `check`. Remotion concurrency (5 or 10) changed nothing.
 
-## Quando escolher cada um
+## When to choose each
 
-| Situação | Motor |
+| Situation | Engine |
 |---|---|
-| 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) |
+| Episode with a TSX scene (`component:`) or a cover of its own | Remotion |
+| Routine Short of an existing channel | Remotion (same time, same look as always) |
+| Long form, or any video where the edit (transitions, chapters, mascot) matters | HyperFrames |
+| New channel, no legacy TSX | HyperFrames as the default (`"engine": "hyperframes"` in the brand) |
+| You want to tweak the result in a visual editor | HyperFrames (open `.hf/<slug>` in the app) |

package/docs/long-yaml.md

@@ -0,0 +1,78 @@
+# Long form in YAML (16:9, 1920×1080)
+
+`episode.yaml` with `format: long`. Time is **global** (seconds since the start of the video). `praeko studio compile <slug>` validates and writes `episode.spec.json`; `praeko studio render <slug>` renders (compiling first).
+
+## Script in blocks
+```
+## 1 · THE HOOK
+[curious] spoken text…
+
+## 2 · THE PROBLEM
+…
+```
+`praeko studio voice <slug> [--quality draft|final|local]` generates one audio per block in `voice-blocks/` (the name carries a hash of the text, voice and pronunciation: only the edited block is regenerated, which saves ElevenLabs credit), joins them with a 0.6 s pause into `voice.mp3` and writes `words.json`, `words.ts` and `blocks.json` (`[{n, title, a, b}]`). Old blocks stay in the cache.
+
+## Top level and scenes
+```yaml
+format: long
+id: StallLong
+duration: 334
+voice: audio/stall-long-voice.mp3
+scenes:
+  - { title: THE HOOK, start: 0, component: S1 }             # TSX scene (scenes.tsx exports S1: React.FC<{t:number}>)
+  - title: THE PROBLEM
+    start: 31.0                                               # s; or { block: 2 } (uses blocks.json); `n` optional (default: position)
+    items: [ … ]
+```
+Each scene runs from its `start` to the next one's (the last one, until `duration`); it fades in and out and shows "n · TITLE" in the corner.
+
+## Time (`when`, `hl`)
+`number` (s) · `"phrase"` (start of the phrase in the voice) · `{ when: "phrase", nth: 1, after: 83, plus: 0.6 }` (`nth` = occurrence, `after` = ignore before N s, `plus` = add seconds). A phrase that is not in `words.json` is an error.
+
+## Items (all with `pos: { left, top, width, height }` in px, except `text`)
+| type | fields |
+|---|---|
+| `code` | `when`, `title`, `size`, `lines: [{ s, hl: [time, time], red }]` (the line lights up between the two times) |
+| `card` | `when`, `color`, `items: [text…]` (slides in) |
+| `text` | only inside `card`: `size`, `color`, `spacing`, `when` (fade), `text` or `parts` |
+| `chip` | `when`, `color`, `size`, `text` |
+| `freetext` | `when`, `size`, `color`, `align: center`, `mono`, `text` or `parts: [{ text, color, mono }]` |
+
+Colors: theme names (`accent text muted ok error info extra box`) or `#hex`. **Text with a comma inside `{ … }` goes in quotes** (the compiler reports an unknown key).
+
+## Compiler warnings (estimate)
+Item that goes past the right edge or covers the captions (below ~960 px), absolutely positioned items that overlap, item that enters outside the scene window, a duration with less than 1 s after the end of the voice.
+
+## End screen (optional)
+```yaml
+duration: { voice: 6 }              # the end screen needs about 5 s after the voice
+endcard: { start: { when: "productive idle", after: 480 }, text: "Productive idle", link: example.com }
+```
+Shows the avatar, `text` (the signature), the theme's `handle` and the `link`, over the scenes, from `start` to the end (the captions go on). `start` accepts a number, "phrase" or `{ voice: N }`; `text`, `link` and `image` (a file in `public/`; default: the theme avatar) are optional.
+
+## Cover (YouTube 16:9 and Instagram vertical)
+```yaml
+cover:
+  id: CoverStallLong                  # default: Cover<id>; the vertical one is <id>Vertical
+  title: ["TWO CLICKS", "ONE ITEM"]   # 2 lines; the 2nd one is highlighted (≤ ~16 letters each on 16:9)
+  mascot: shocked                     # mascot image by name (optional; brand.json mascotPath)
+  code: { title: social.mjs · marketBuy, lines: [{ s: "UPDATE market ..." }, { s: "AND sold_to IS NULL", hl: true }] }   # up to 3 lines
+  chips: [{ text: "ok ✔", color: ok }, { text: sold, color: error }]
+```
+`praeko studio cover <slug>` writes `out/<slug>-cover-1280x720.png` and `out/<slug>-cover-vertical-1080x1920.png` (the vertical one uses the Short covers' `Frame`, inside Instagram's 3:4 grid).
+
+## Publication package of the long form
+`publication.json` with `"format": "long"` (fields as in the Short, plus `yt.pinnedComment` and `files.verticalCover`). `praeko studio package <slug>` builds `texts.md`: title and alternatives, description **with chapters**, pinned comment, Instagram caption and the check. Chapters come from the scenes (`start` + title in lowercase) and the YouTube rules apply: start at 0:00, 3 or more, 10 s each (otherwise it is an ERROR). For other texts, write `chapters: [{ t, title }]` in `publication.json`. The YouTube UTM uses `utm_medium=long`.
+
+## Media and animation items (long form)
+All with `when` and `pos`:
+| type | fields |
+|---|---|
+| `video` | `src` (in `public/`, 16:9), `clipDuration`, `from` (s of the clip), `reg: [x, y, w, h]` (crop in 1920×1080), `tag`, `pos: { left, top, width }` (height comes from the crop), `motionDuration` |
+| `phone` | `src` (vertical 1080×1920), `clipDuration`, `from`, `pos: { left, top, width }`, `motionDuration` |
+| `bar` | `value` (0–1), `duration`, `color`, `label`, `text` (inside the bar), `height`, `pos` |
+| `counter` | `from`, `to`, `duration`, `decimals`, `prefix`, `suffix`, `size`, `color`, `mono`, `align: center`, `pos` |
+| `flow` | `nodes: [{ text (\n breaks), color, when }]`, `size`, `color`, `pos: { left, top, width }`: boxes joined by arrows that enter one by one |
+
+## Engine and mascot (HyperFrames)
+`engine: hyperframes` at the top chooses the render engine of this long video (default: the brand's, then `remotion`). `mascot: [{ when: "phrase", name: shocked, plus: 0.5 }]` makes the mascot image (the `brand.json` `mascotPath` template, default `mascots/{name}.png`) appear in the corner for ~3 s; only HyperFrames draws the mascot (Remotion ignores it). See [`hyperframes.md`](hyperframes.md).

package/docs/publish.md

@@ -0,0 +1,22 @@
+# Publishing through Praeko
+
+Studio **publishes nothing on its own**. `praeko studio package <slug>` writes `texts.md` and checks limits, hashtags and the AI disclosure; `praeko studio schedule` hands the video, cover and texts to Praeko, which schedules them on the networks connected to your workspace.
+
+## From the CLI (`--via praeko`)
+```sh
+echo $KEY | praeko studio schedule --via praeko --key          # praeko_… key (write scope); the same one as the `praeko` CLI
+praeko studio schedule --channels --via praeko                 # lists the connected channels
+praeko studio schedule <slug> --when "06/11 17:30" --via praeko           # SIMULATES (only reads the channels)
+praeko studio schedule <slug> --when "06/11 17:30" --via praeko --send    # uploads the video and really schedules
+praeko studio schedule <slug> --status | --cancel | --clear
+```
+`brand.json` → `publishing.provider: "praeko"` makes Praeko the default (`init` already writes it that way). `publishing.praeko.channels` pins the account when there is more than one per network. YouTube is uploaded as private and scheduled; TikTok goes as a draft (`publishing.praeko.tiktok.mode`); the minimum time is 5 minutes ahead.
+
+## Through the Praeko MCP (agent with a shell)
+The video file never goes through the MCP. In one step: `create_media_upload { type: "video", name, mime, size }` (`size` in bytes: `wc -c < file`) returns a ready `curl`; upload the file; then `complete_media_upload { mediaId }` until the state is `ready`. Then `create_post`/`schedule_post` in **two steps**: the 1st call returns only the **preview** and a `confirmation_code`; **show the whole preview to the person**, wait for the yes and repeat the call with the same arguments plus `confirm`. The agent never confirms on its own. See the MCP documentation at praeko.app/docs.
+
+## AI disclosure (checked by `check` and `package`)
+Fill `"ai": { "synthetic": true|false }` in `publication.json`. A realistic synthetic voice, or a generated image/video that looks real, needs the altered/synthetic content label: YouTube (the `containsSyntheticMedia` field, sent when Studio publishes directly), "AI info" on Instagram and the AI label on TikTok. Through Praeko, **set the label in each network's app before publishing** (Praeko's public API does not carry this field yet). Drafting a script with AI or cloning **your own** voice to narrate does not require the label on YouTube, but the rules change: check each network's current policy.
+
+## Advanced
+`post` (direct publishing with your own credentials for each network), `queue` and `account <network>` stay in the package for those who need them; `queue install` uses launchd and only works on macOS. The Buffer provider (`--via buffer`) is legacy.

package/docs/voice.md

@@ -0,0 +1,22 @@
+# Voice in Praeko Studio
+
+`praeko studio voice <slug> --quality draft|final|local` writes `voice.mp3` and the per-word timings (`words.json`/`words.ts`).
+
+| Quality | What it does | Cost |
+|---|---|---|
+| `draft` | **estimated, silent** voice (~190 words/min), no network | free |
+| `final` | ElevenLabs (TTS) + Scribe (per-word timings), **your** account and key | characters of your plan |
+| `local` | VoiceStudio (compatible local server, `http://127.0.0.1:3900` by default) | free, must be running |
+
+## Set up your voice
+Layers of `voices.json` (the top one wins): **project** (next to `brand.json`) > **user** (`~/.config/praeko/studio/voices.json`, or `PRAEKO_STUDIO_CONFIG`) > package default (no ids).
+1. Store the key: `echo $KEY | praeko studio voice config key elevenlabs/principal` (system keychain on macOS; file `~/.config/praeko/secrets.json` with 600 permission on Linux; on Windows prefer the `ELEVENLABS_API_KEY` variable).
+2. Register the voice: `praeko studio voice account add principal --voice my-voice --voice-id <voice id>` (writes the id into the project's `voices.json`) or set `ELEVENLABS_VOICE_ID`.
+3. In `brand.json`, `"voice": "my-voice"` applies to `voice` without `--quality`; with `--quality final` the voice in `quality.final` applies. The `init` default is `draft-silent`, so it never spends by accident.
+More than one account (failover by balance): `account add <other>`; the router skips an account with no balance or with an invalid key.
+
+## Rules
+- Use **only your own voice** or one you are authorized to use (ElevenLabs terms).
+- A realistic synthetic voice requires the AI label on the platforms: fill `"ai": { "synthetic": true }` in `publication.json`.
+- A key never goes in a project file, in a log or in a chat with an agent. Reading order: environment variable, macOS keychain, secrets file.
+- The VoiceStudio OmniVoice model is CC-BY-NC (non-commercial): do not use it in monetized content.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@praeko/studio",
-  "version": "0.1.0",
+  "version": "0.2.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.",
+  "description": "Praeko Studio: short (9:16) and long (16:9) videos from a script, for you to run with your own coding agent (Claude Code, Codex, Gemini CLI, Cursor, opencode). Voice, word-by-word captions, scenes, cover, texts and publishing through Praeko.",
   "license": "MIT",
   "keywords": [
     "praeko",
@@ -29,7 +29,7 @@
   },
   "files": [
     "dist",
-    "modelos",
+    "templates",
     "docs",
     "README.md",
     "CHANGELOG.md",
@@ -43,16 +43,17 @@
   "scripts": {
     "build": "node ../../../scripts/build-studio.mjs cli",
     "prepack": "npm run build",
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
     "@elevenlabs/elevenlabs-js": "^2.75.0"
   },
   "devDependencies": {
     "@praeko/studio-hyperframes": "*",
-    "@praeko/studio-publicar": "*",
-    "@praeko/studio-revisar": "*",
-    "@praeko/studio-voz": "*",
+    "@praeko/studio-publish": "*",
+    "@praeko/studio-review": "*",
+    "@praeko/studio-voice": "*",
     "yaml": "^2.9.1"
   },
   "engines": {