# Praeko Studio: vídeos com o seu agente > Instale o Praeko Studio, faça o primeiro vídeo em 10 minutos com o seu agente de código (Claude Code, Codex, Gemini CLI, Cursor, opencode), veja os comandos, o projeto, as chaves, as licenças (Remotion não é MIT) e como publicar pelo Praeko. Fonte: https://praeko.app/docs/studio Node 22 ou mais novo · macOS e Linux · Remotion não é MIT O Praeko Studio faz vídeos curtos (9:16) e longos (16:9) a partir de um roteiro: voz, legenda palavra a palavra, cenas, capa e os textos de cada rede. **Você opera com o seu próprio agente de código**, na sua máquina: o agente escreve o roteiro e o `episode.yaml`, roda os comandos e, só depois do seu sim, publica pelo Praeko. A voz, o render e o agente são por sua conta; o Studio não chama nenhum modelo de linguagem e nenhum roteiro seu sai da máquina até você publicar. > **Quer que o agente faça quase tudo?** O guia [Começar com o seu agente](https://praeko.app/docs/get-started-with-agent) traz o prompt para colar numa pasta vazia, o que só você faz e o primeiro vídeo. ## Requisitos | Item | Detalhe | |---|---| | Node | 22 ou mais novo. | | ffmpeg e ffprobe | No PATH. macOS: `brew install ffmpeg`; Debian e Ubuntu: `sudo apt install ffmpeg`. | | Chrome | O Remotion baixa o *Chrome Headless Shell* sozinho no primeiro render (internet nesse momento; cerca de 570 MB em disco, medido no macOS). Ou use um Chrome instalado com `CHROME_PATH`. | | Fontes | O modelo usa fontes do sistema (`Arial Black`, `Menlo`). Se faltarem, o `doctor` avisa; troque em `brand.json` por fontes que existam nos seus sistemas. | | Sistemas | macOS e Linux. Windows é melhor esforço e **não foi testado**. | | Terminal | O agente precisa de **terminal (shell)** para renderizar: é ele quem roda `ffmpeg`, o Remotion e os comandos do Studio. Sem terminal (por exemplo, o Claude Desktop sem shell), use o [servidor MCP local do Studio](https://praeko.app/docs/studio/mcp) (`@praeko/studio-mcp`); o [servidor MCP](https://praeko.app/docs/mcp) remoto só publica e traz métricas, não renderiza vídeo. | | Seu agente | Claude Code, Codex, Gemini CLI, Cursor, opencode, Cline ou Windsurf, com a sua assinatura ou chave. O Praeko não cobra nem intermedeia o agente. | ## Instalar **npm** ```bash npm install -g @praeko/studio ``` **yarn** ```bash yarn global add @praeko/studio ``` **pnpm** ```bash pnpm add -g @praeko/studio ``` **bun** ```bash bun add -g @praeko/studio ``` **Sem instalar** ```bash npx @praeko/studio doctor npx @praeko/studio init my-channel ``` O comando é `praeko-studio` e também `praeko studio …` quando o [`@praeko/cli`](https://praeko.app/docs/sdk) está instalado: ele entrega ao Studio, procurando no projeto, ao lado da CLI, na instalação global e no PATH. ## Licenças: leia antes do primeiro render > **O Remotion não é MIT** O código do Praeko Studio é MIT. O **Remotion**, o motor padrão (de vídeos e capas), é *source-available*: **grátis para pessoas, organizações sem fins lucrativos e empresas de até 3 funcionários**; empresas com 4 ou mais pessoas precisam da **Company License** ([remotion.pro/license](https://www.remotion.pro/license)). Quem instala e roda o Remotion é você, então a licença é sua. O Remotion também vende planos para quem automatiza renders por programa ou agente, e o FAQ deles não diz se um agente local entra: pergunte a eles antes de usar em escala. Não prometemos "grátis para sempre". | Componente | Licença | |---|---| | `@praeko/studio`, `studio-core`, `studio-kit` | MIT | | Remotion (`remotion`, `@remotion/cli`) | Remotion License (não MIT); você instala | | HyperFrames (`--engine hyperframes`, opcional) | Apache-2.0 | | ffmpeg, Chrome | Termos próprios; o Studio não os redistribui | | Modelo OmniVoice do VoiceStudio (voz local opcional) | CC-BY-NC: uso não comercial; **não use em conteúdo monetizado** | O Remotion é o motor padrão dos vídeos **e** das capas; com `--engine hyperframes` o vídeo e a capa saem pelo HyperFrames e nada do Remotion é usado. Texto completo e fontes: `praeko studio docs licenses` (o `LICENSES.md` do pacote); `praeko studio licenses --accept` registra que você leu. ## Seu primeiro vídeo em 10 minutos ### 1. Conferir o ambiente **bash** ```bash praeko-studio doctor ``` Mostra Node, ffmpeg, Chrome, fontes, se há chaves (nunca o valor), as contas de voz ElevenLabs (saldo e renovação quando a chave lê; a voz final e em quais contas ela tem id; avisa se duas contas mostram o mesmo saldo), a rede e as licenças, com uma linha de correção por item. Com `--offline` não chama a rede e mostra só a configuração. ### 2. Criar o projeto **bash** ```bash praeko-studio init my-channel --name "My Channel" --agent claude cd my-channel ``` Cria `brand.json`, `src/`, `episodes/`, os sons e as instruções para o seu agente (`--agent claude,codex,gemini,cursor,opencode,cline,windsurf` ou `all`), e roda `npm install`. Num terminal ele antes faz uma entrevista curta (nome, para quem é, tom de voz, cores, fonte, até 3 referências) e grava `brief.md` e um rascunho de `playbook.md`, que o seu agente lê antes do primeiro roteiro; o Studio não assiste às referências, o agente é quem as analisa. Sem terminal (ou com `--yes`) nada é perguntado. Os pacotes vêm do npm por versão, sem `file:`. ### 3. Pedir o vídeo ao agente Abra o seu agente **na pasta do projeto** e cole: **Prompt para o agente** ```text Faça um Short de 40 segundos sobre neste projeto do Praeko Studio. Leia as instruções do projeto e rode `praeko studio docs episode-yaml` antes de escrever o YAML. Use a voz draft, mostre o roteiro e as cenas para eu aprovar antes de gastar crédito de voz, rode check e contact-sheet, e não publique nada sem eu pedir. ``` ### 4. Voz rascunho, conferência e render **bash** ```bash praeko-studio new my-first --title "My first video" praeko-studio voice my-first --quality draft praeko-studio check my-first praeko-studio render my-first --scale 0.5 praeko-studio contact-sheet my-first praeko-studio cover my-first praeko-studio package my-first ``` O agente faz estes passos por você. A voz `draft` é **estimada e muda** (grátis, sem rede) e serve para montar as cenas; `check` avisa até haver voz real. Para a voz final, `--quality final` usa a **sua** conta do ElevenLabs. ### 5. Simular a publicação **bash** ```bash echo $PRAEKO_KEY | praeko-studio schedule --via praeko --key praeko-studio schedule my-first --when "20/12 17:30" --via praeko ``` Sem `--send` o comando só lê os canais e mostra o que faria. Veja [Publicar](#publicar). ## Comandos Todos começam por `praeko studio` (ou `praeko-studio`). `praeko studio --help` lista o mesmo. | Comando | Faz | |---|---| | `doctor [--json] [--offline]` | Confere o ambiente e mostra o aviso de licenças. | | `licenses [--accept]` | O aviso de licenças; `--accept` registra a leitura. | | `skill install [--agent …] [--lang en\|pt]` | Grava as instruções do Studio no formato do seu agente. | | `docs [topic]` | Documentação da versão instalada: `episode-yaml`, `long-yaml`, `voice`, `publish`, `hyperframes`, `licenses`. | | `init ` | Cria um projeto (`--name`, `--handle`, `--agent`, `--lang`, `--no-install`; `--dev ` para quem contribui). Num terminal faz a entrevista de marca (Enter pula cada pergunta); com `--yes` ou sem terminal não pergunta nada e importa cores e fonte do `../brand/build/tokens.json` (ou `../brand/tokens.json`) quando existir, ou da pasta dada em `--brand`; as flags mandam sobre o tokens e a saída diz o que foi importado. Respostas por flag: `--about`, `--audience`, `--tone`, `--accent`, `--background`, `--font`, `--brand `, `--reference` (até 3, com `--reference-note`), `--voice-alias`, `--voice-provider`. | | `brief [--only …]` | Reabre a entrevista num projeto existente (só as respostas escolhidas) e reescreve o `brief.md`; guarda `brief.md.bak` e não sobrescreve um `playbook.md` que você editou (grava `playbook.md.new`). | | `new [--long \| --image]` | Cria um episódio (`--title`) e o registra em `src/Root.tsx`. `--image` cria um post de foto (`format: image`, um slide, sem voz nem vídeo). | | `voice --quality draft\|final\|local` | Gera a voz e os tempos por palavra. `voice balance`, `voices`, `account`, `config key` cuidam das contas. | | `compile ` | Lê `episode.yaml`, confere âncoras e sobreposição, gera `episode.spec.json`. | | `cut --from … --to …` | Short vertical fatiado da voz de um longo. | | `preview [slug]` | Abre o Remotion Studio (ou o preview do HyperFrames). | | `render [--scale 0.5] [--engine remotion\|hyperframes]` | Renderiza em `out/.mp4`. | | `cover ` | Renderiza a capa (`out/-cover.png`). | | `slides ` | Renderiza um post de imagem em `out/-slide-01.jpg`: 1080x1350 (4:5), JPEG sRGB, só com Remotion. Por enquanto vai só para o Instagram (`schedule --via praeko`); o formato está em `praeko studio docs image`. | | `contact-sheet [--n 12]` | Mosaico de quadros para você (e o agente) olharem. | | `check ` | Roteiro, voz, publicação, declaração de IA e, com vídeo, duração, volume e quadros vazios. | | `package ` | Gera `texts.md` (YouTube, Instagram, TikTok, UTM) e confere limites. | | `schedule --when … --via praeko [--send]` | Agenda pelo Praeko; sem `--send` só simula. | | `post`, `queue`, `account ` | Avançado: publicação direta com credenciais suas de cada rede. `queue install` só no macOS. | | `migrate [--dry-run]` | Converte um projeto do Studio 0.1.x (nomes em português) para o layout em inglês, com backup em `.studio-backup/`. | | `help` | Mostra a lista de comandos (`--lang pt` traduz as mensagens). | ## O projeto **Estrutura** ```text my-channel/ brand.json # cores, fontes, handle, voz, links, hashtags voices.json # (opcional) a sua voz; nunca chaves src/ # index.ts, Root.tsx, brand.ts (o Root registra os episódios) public/ # sfx/, cover/avatar.png, audio/ (voz gerada) episodes// script.txt # o texto falado episode.yaml # as cenas, declarativas scenes.tsx # peças em TSX (capa e o que o YAML não cobre) publication.json # textos de cada rede, hashtags, ai.synthetic out/ # vídeos e capas renderizados ``` **brand.json** ```json { "name": "My Channel", "handle": "@mychannel", "avatar": "cover/avatar.png", "colors": { "background": "#14110f", "accent": "#f4b942", "text": "#f3ece0" }, "fonts": { "title": "'Arial Black', system-ui, sans-serif", "mono": "Menlo, monospace" }, "links": { "main": "https://example.com/" }, "voice": "draft-silent", "pronunciation": { "example.com": "example dot com" }, "bannedNames": [], "publishing": { "provider": "praeko", "hashtags": { "allowed": [], "banned": [] } } } ``` O `episode.yaml` é declarativo: cada item liga a uma frase da voz com `when: "frase"`, e `praeko studio compile` confere. O que o YAML não cobre vira uma peça em `scenes.tsx`, feita com as peças do `@praeko/studio-kit` (panel, box, line, bubble, code, window, phone, frame). O render é uma função pura do episódio compilado e dos arquivos do projeto. **episode.yaml** ```yaml id: MyVideo duration: 14 caption: 80 voice: audio/MyVideo.mp3 background: ["My video"] outro: { start: 10, cta: FOLLOW THE PROFILE } cover: { id: CoverMyVideo, component: CoverMyVideo } scenes: - start: 0 title: THE PROBLEM label: PROBLEM items: - { type: big, at: 0.2, color: accent, size: 92, text: "The cache took the deploy down" } - { type: box, when: "deploy", text: "cleared the cache" } ``` Formato completo: `praeko studio docs episode-yaml`, `praeko studio docs long-yaml` e, para um post de foto, `praeko studio docs image`. ## Posts de imagem (uma foto) `praeko studio new --image` cria uma peça de imagem: o mesmo `publication.json`, `check`, `package` e envio de um vídeo, mas sem roteiro, voz nem vídeo. O `episode.yaml` tem `format: image` e **um** slide (vários slides seriam um carrossel, que chega numa fase futura), que reaproveita os itens de uma capa e leva um texto alternativo (`alt`, obrigatório, até 1000 caracteres). `praeko studio slides ` renderiza `out/-slide-01.jpg` em 1080x1350, JPEG sRGB (só com Remotion). O `package` grava as imagens e o `alt` no `publication.json` e o `texts.md` só com a legenda do Instagram. Só o Instagram aceita foto por enquanto (YouTube não tem post de imagem; a foto do TikTok é uma fase futura): `praeko studio schedule --via praeko` sobe a foto como mídia `type: image` e cria o post com `kind: image`. O `alt` vai pelo Instagram quando o Praeko publica pela Meta; pelo Buffer ele é ignorado e o item avisa `alt_ignored`. ## Chaves e custos: você traz as suas | O quê | Quem paga | Onde fica a chave | |---|---|---| | Agente de código | Você (sua assinatura ou chave) | No próprio agente | | Voz final (ElevenLabs) | Você, na sua conta | Variável `ELEVENLABS_API_KEY`, cofre do macOS ou `~/.config/praeko/secrets.json` (permissão 600) | | Render | Você (sua máquina) | - | | Publicar pelo Praeko | Seu plano do Praeko | `PRAEKO_KEY` ou `praeko studio schedule --via praeko --key` (a mesma chave da `praeko` CLI) | **Guardar a chave da voz** ```bash echo $ELEVENLABS_API_KEY | praeko-studio voice config key elevenlabs/principal praeko-studio voice account add principal --voice my-voice --voice-id ``` **Adicionar mais uma conta de voz (ou só conferir)** ```bash praeko-studio voice account list praeko-studio voice account add backup --from-env ELEVENLABS_API_KEY_2 --dry-run # only checks the key and shows the plan, stores nothing praeko-studio voice account add backup --from-env ELEVENLABS_API_KEY_2 # stores the key in the keychain and the voice in voices.json ``` Sem `--from-env`, o comando pede a chave no terminal (sem mostrá-la) ou lê da entrada padrão. `--voice` dá um apelido à voz e `--voice-id` informa o id; sem eles o comando procura o clone da sua voz na conta. Com mais de uma conta, o Studio escolhe pelo saldo e troca de conta se uma esgotar (`--no-failover` desliga). A chave nunca vai para o projeto, o git, o log ou o chat com o agente. Use **somente a sua voz** ou uma voz que você tem autorização para usar. Detalhes: `praeko studio docs voice`. ## Publicar pelo Praeko O Studio **não publica nada sozinho**. Duas formas, as duas só depois do seu sim: - **CLI:** `praeko studio schedule --via praeko --when "dd/mm hh:mm"` simula; com `--send` envia o vídeo e agenda de verdade. O YouTube sobe privado e agendado; o TikTok vai como rascunho. - **MCP do Praeko:** um agente com shell envia o arquivo local com `create_media_upload` (um passo; devolve o `curl`), termina com `complete_media_upload` e cria o post com `create_post` ou `schedule_post` em **dois passos**: a primeira chamada devolve só a prévia e um `confirmation_code`; o agente mostra a prévia inteira a você e só repete a chamada com `confirm` depois do seu sim. Veja [Servidor MCP](https://praeko.app/docs/mcp). ## Instruções para o seu agente **bash** ```bash praeko-studio skill install --agent claude,codex,gemini,cursor,opencode,cline,windsurf --lang en ``` | Agente | Arquivo gravado no projeto | |---|---| | Claude Code | `.claude/skills/praeko-studio/SKILL.md` + `CLAUDE.md` | | Codex, opencode | `AGENTS.md` | | Gemini CLI | `GEMINI.md` | | Cursor | `.cursor/rules/praeko-studio.mdc` | | Cline | `.clinerules/praeko-studio.md` | | Windsurf | `.windsurf/rules/praeko-studio.md` | O texto traz o fluxo do vídeo, o envio de arquivo local, a regra de dois passos e a declaração de IA. Em arquivos compartilhados (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`) o Studio grava só um bloco delimitado e preserva o resto. Os formatos de cada agente mudam com o tempo: confira na documentação do seu agente. ## Problemas comuns | Sintoma | O que fazer | |---|---| | `ffmpeg` não encontrado | Instale (`brew install ffmpeg` ou `sudo apt install ffmpeg`) e rode `praeko studio doctor`. | | O primeiro render demora ou falha por rede | O Remotion está baixando o Chrome Headless Shell. Com internet, repita. Sem internet, instale o Chrome e defina `CHROME_PATH`. | | O texto sai diferente ou quebra linha estranho | Falta uma fonte do `brand.json`. O `doctor` mostra qual; instale-a ou troque por uma fonte aberta. | | Linux: não há cofre de chaves | O cofre do macOS (`security`) só existe no macOS. No Linux use `ELEVENLABS_API_KEY`, `PRAEKO_KEY` ou o arquivo `~/.config/praeko/secrets.json` (permissão 600). | | Windows | Não foi testado. Prefira variáveis de ambiente para as chaves e abra um relato se algo falhar. | | `praeko studio` diz que não achou o Studio | Instale `@praeko/studio` (no projeto ou globalmente) ou rode com `npx @praeko/studio`. | | `check` avisa que a voz é estimada | Esperado com o rascunho. Gere `--quality final` (com a sua chave) antes de publicar. | | Projeto do Studio 0.1.x (nomes em português) | Rode `praeko studio migrate --dry-run` e depois `praeko studio migrate`: renomeia arquivos e chaves, com backup em `.studio-backup/`. | ## Conteúdo gerado por IA e conformidade Voz sintética realista, ou imagem e vídeo gerados que pareçam reais, exigem o **rótulo de conteúdo alterado ou sintético** no YouTube, o "AI info" no Instagram e o rótulo de conteúdo gerado por IA no TikTok. Preencha `"ai": { "synthetic": true }` no `publication.json`: `check` e `package` avisam quando falta. Na publicação direta do Studio o YouTube recebe o campo (`containsSyntheticMedia`); pelo caminho do Praeko e no Instagram e no TikTok **você marca o rótulo no app da rede** antes de publicar, porque a API pública do Praeko ainda não leva esse campo. As regras de cada rede mudam: confira a política vigente. > **Privacidade** Roteiros, vozes e chaves ficam na sua máquina. O Praeko recebe só o vídeo, a capa e os textos que você mandar publicar. Não há telemetria.