Praeko Studio: make videos with your agent

Praeko Studio makes short (9:16) and long (16:9) videos from a script: voice, word-by-word captions, scenes, a cover and the texts for each network. You drive it with your own coding agent, on your machine: the agent writes the script and episode.yaml, runs the commands and, only after your yes, publishes through Praeko. Voice, rendering and the agent are on you; Studio never calls a language model and none of your scripts leave the machine until you publish.

Requirements

Install

npm install -g @praeko/studio

yarn global add @praeko/studio

pnpm add -g @praeko/studio

bun add -g @praeko/studio

npx @praeko/studio doctor
npx @praeko/studio init my-channel

The command is praeko-studio, and also praeko studio … when @praeko/cli is installed: it hands over to Studio, looking in the project, next to the CLI, in the global install and on the PATH.

Licenses: read before your first render

Remotion is the default engine for videos and covers; with --engine hyperframes the video and the cover are rendered by HyperFrames and nothing from Remotion is used. Full text and sources: praeko studio docs licenses (the package's LICENSES.md); praeko studio licenses --accept records that you read it.

Your first video in 10 minutes

praeko-studio doctor

praeko-studio init my-channel --name "My Channel" --agent claude
cd my-channel

Make a 40-second Short about <TOPIC> in this Praeko Studio project.
Read the project instructions and run `praeko studio docs episode-yaml` before writing the YAML.
Use the draft voice, show me the script and scenes to approve before spending any voice credit,
run check and contact-sheet, and do not publish anything unless I ask.

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

echo $PRAEKO_KEY | praeko-studio schedule --via praeko --key
praeko-studio schedule my-first --when "20/12 17:30" --via praeko

Commands

All start with praeko studio (or praeko-studio). praeko studio --help lists the same.

The project

my-channel/
  brand.json            # colors, fonts, handle, voice, links, hashtags
  voices.json           # (optional) your voice; never keys
  src/                  # index.ts, Root.tsx, brand.ts (Root registers the episodes)
  public/               # sfx/, cover/avatar.png, audio/ (generated voice)
  episodes/<slug>/
    script.txt          # the spoken text
    episode.yaml        # the scenes, declarative
    scenes.tsx          # TSX pieces (cover and what YAML cannot express)
    publication.json    # texts for each network, hashtags, ai.synthetic
  out/                  # rendered videos and covers

{
  "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": [] } }
}

episode.yaml is declarative: each item ties to a spoken phrase with when: "phrase", and praeko studio compile checks it. What YAML cannot express becomes a piece in scenes.tsx, built with the @praeko/studio-kit pieces (panel, box, line, bubble, code, window, phone, frame). Rendering is a pure function of the compiled episode and the project files.

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" }

Full format: praeko studio docs episode-yaml, praeko studio docs long-yaml and, for a photo post, praeko studio docs image.

Image posts (a photo)

praeko studio new <slug> --image creates an image piece: the same publication.json, check, package and upload as a video, but with no script, voice or video. Its episode.yaml has format: image and one slide (several slides would be a carousel, which arrives in a later phase) that reuses the items of a cover and carries an alternative text (alt, required, up to 1000 characters). praeko studio slides <slug> renders out/<slug>-slide-01.jpg at 1080x1350, sRGB JPEG (Remotion only). package writes the images and the alt into publication.json and a texts.md with only the Instagram caption. Only Instagram takes a photo for now (YouTube has no image posts; TikTok photo mode is a later phase): praeko studio schedule <slug> --via praeko uploads the photo as media of type: image and creates the post with kind: image. The alt goes to Instagram when Praeko publishes through Meta; through Buffer it is ignored and the item warns alt_ignored.

Keys and costs: bring your own

echo $ELEVENLABS_API_KEY | praeko-studio voice config key elevenlabs/principal
praeko-studio voice account add principal --voice my-voice --voice-id <YOUR_VOICE_ID>

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

Without --from-env, the command asks for the key in the terminal (hidden) or reads it from standard input. --voice gives the voice a nickname and --voice-id sets the id; without them the command looks for your voice clone in the account. With more than one account, Studio picks by remaining balance and switches account when one runs out (--no-failover turns it off).

The key never goes into the project, git, logs or the chat with your agent. Use only your own voice or one you are authorized to use. Details: praeko studio docs voice.

Publish through Praeko

Studio never publishes on its own. Two ways, both only after your yes:

• CLI: praeko studio schedule <slug> --via praeko --when "dd/mm hh:mm" simulates; with --send it uploads the video and really schedules. YouTube goes up private and scheduled; TikTok goes as a draft.
• Praeko MCP: an agent with a shell uploads the local file with create_media_upload (one step; it returns the curl), finishes with complete_media_upload and creates the post with create_post or schedule_post in two steps: the first call returns only the preview and a confirmation_code; the agent shows you the whole preview and repeats the call with confirm only after your yes. See MCP server.

Instructions for your agent

praeko-studio skill install --agent claude,codex,gemini,cursor,opencode,cline,windsurf --lang en

The text carries the video workflow, the local file upload, the two-step rule and the AI disclosure. In shared files (AGENTS.md, CLAUDE.md, GEMINI.md) Studio writes only a delimited block and keeps the rest. Each agent's formats change over time: check your agent's documentation.

Troubleshooting

AI-generated content and compliance

Realistic synthetic voice, or generated image and video that looks real, requires the altered or synthetic content label on YouTube, "AI info" on Instagram and the AI-generated content label on TikTok. Fill "ai": { "synthetic": true } in publication.json: check and package warn when it is missing. In Studio's direct publishing YouTube receives the field (containsSyntheticMedia); through Praeko and on Instagram and TikTok you set the label in the network's app before publishing, because Praeko's public API does not carry this field yet. Each network's rules change: check the current policy.