PandaStudio

🛑 Pick your interface FIRST — prefer the CLI

PandaStudio exposes the same editing surface through two transports:

1. pandastudio

   CLI (localhost HTTP). Prefer this. A single bash tool covers the entire ~150-verb surface — no per-tool schema needs to live in your context. Probe once with

   command -v pandastudio

   (or just call

   pandastudio system.status --json

   ). If it succeeds, you're on the CLI path; every example in this skill is written for it directly.
2. MCP server — tools prefixed

   mcp__pandastudio__*

   (in-app PandaStudio agent) or

   mcp__writepanda__*

   (external hosts like Cursor, Claude Desktop). Use only when the CLI is not installed — i.e.

   command -v pandastudio

   returned empty AND one of the MCP prefixes is visible in your tools.

Why CLI is preferred: every MCP tool definition costs context tokens (per-tool input schema + description). With ~150 verbs that overhead adds up quickly. The CLI is one bash tool — schema cost stays constant regardless of which verb you call.

The verbs, argument names, and behaviors are identical across both transports. A CLI call like

pandastudio project.add-zoom --id=… --atMs=…

maps 1:1 to the MCP tool

project_add_zoom

with the same args (

{id, atMs, …}

). If you're on MCP fallback, translate the CLI examples below by lowercasing the verb and replacing the dot with an underscore.

Do not search the filesystem for the CLI. Don't run

ls /Applications

,

npm list @writepanda/cli

, etc.

command -v pandastudio

is the only probe you need; if it returns nothing, immediately move to the MCP fallback without further discovery.

Version check. This skill requires

@writepanda/cli

≥ 1.15.0 (or

@writepanda/mcp

≥ 1.15.0). On the MCP path, call

system_status

and read the returned version. On the CLI path, run

pandastudio --version

. If < 1.15.0, tell the user to update (

npx @writepanda/mcp@latest

) and restart their agent host. Commands like

asset.list-music

,

asset.list-luts

, and

project.set-clip-lut

do not exist in older versions.

Motion graphics: use the bundled templates first

PandaStudio ships a curated set of YouTube-creator motion-graphic templates — title cards, lower thirds, stat reveals, checklists, comparisons, a host+panel split, animated-title overlays. They are production-grade and the primary path when you are layering graphics OVER existing footage (see the Mode A / Mode B note below):

1. motion_list

   → see every template, its editable slots, and whether it's an overlay (sits over the video with alpha). It also returns

   registryBlocks

   — ~38 curated standalone compositions (effects, overlays, flowcharts, code snippet, beat-driven cuts) that have no slots; render a block's

   htmlPath

   with

   motion_render_html

   . See

   reference/templates.md

   §"Hyperframes registry blocks".

2. motion_generate { templateId, slots, background }

   → render it with your own text/colors. Returns a

   jobId

   .

3. job_wait

   → then

   project_add_motion_graphic { fromJob }

   (or

   project_add_designed_segment

   for

   split-panel

   ).

Everything editable — text, colors, list items, and the background mode (

solid

/

transparent

/

glass

) — is controlled through

slots

+

background

. The full catalog (when to use each, what's editable) is in the "Motion graphics" section below.

Templates-first vs. custom depends on whether there's footage underneath:

• Mode A — graphics layered OVER existing footage (lower thirds, stat callouts, side panels, captions on a talking-head or screen recording): bundled templates are the default. Fast, on-brand, composite cleanly over the host. All the "templates first" guidance applies here.
• Mode B — a video built FROM SCRATCH where the motion graphics ARE the video (promo, explainer, intro/outro, product teaser, CTA piece — anything with NO source clip on the main track): default to fully custom, hand-authored scenes via

  motion_render_html

  , NOT bundled templates. EXCEPTION — faceless videos are Mode B but IMAGE-driven, not HTML text scenes. If the ask is a "faceless" video (faceless YouTube / faceless short / narrated story or explainer with no face), do NOT author text motion-graphic scenes — that produces a title slideshow. Generate an IMAGE per beat + Ken-Burns + voiceover. See the dedicated "Faceless videos" section below. For the other Mode B pieces (promos/explainers): In from-scratch work templates read as generic and "templated" — exactly the wrong feel for a hero/marketing asset, which is usually the most visible, brand-defining thing the user makes. Load

  reference/promo-and-mg-videos.md

  first — it is the design bar for this case: every scene a DISTINCT composition that SHOWS its point (don't headline features — depict them), one system never one layout, rotate layout archetypes. Then author each scene from the canonical shell in

  reference/motion-philosophy.md

  . One NAMED alternative design system exists for Mode B: the whiteboard / hand-drawn explainer (

  reference/whiteboard-style.md

  ) — paper canvas, SVG draw-on strokes, handwriting text reveal. Reach for it when the brief says "whiteboard / hand-drawn / sketch / doodle / handwritten", or when an abstract CONCEPT needs to be drawn (science, process, metaphor) and the tone wants friendly-approachable rather than premium-brand. Templates are still fine as building blocks inside an otherwise-custom piece (e.g. a transition between custom scenes) — just not the backbone. Reach for templates as the backbone of from-scratch work ONLY for a deliberately quick draft or when the user explicitly asks for speed over bespoke; if you do, SAY you're using templates for speed and offer the custom version.

For Mode A, author custom HTML (

motion_render_html

) only when no bundled template fits the brief — a bespoke one-off, an unusual layout, a brand-specific 3D treatment. That path is documented under "Custom motion graphics — HTML authoring"; load

reference/motion-philosophy.md

before authoring.

Video templates (storyboards): a whole video, not one overlay

When the user wants a finished short video (a channel intro, an episode open, a lesson opener) rather than a single overlay, use a storyboard — a multi-scene video template you fill in once:

1. motion_list_storyboards

   → see every storyboard: its id,

   audience

   (youtube | podcaster | course), and its

   params

   (the brief — text + color fields; color fields default to the workspace brand kit).

2. motion_generate_storyboard { storyboardId, params }

   → the server renders each scene and concatenates them into ONE MP4. Returns a

   jobId

   . Omitted color params fall back to the brand kit (

   workspace_set_brand

   ); omitted required text params fail fast, so read the brief first.

3. job_wait

   → then

   project_add_motion_graphic { fromJob }

   , same as a single template.

Storyboards are slower than a single template (they render N scenes sequentially), so set a generous

job_wait

timeout. Transitions between scenes are baked into each scene's own animation in v1 (the join is a hard cut). Prefer a storyboard over hand-composing several

motion_generate

calls when one fits the brief — it's one call and on-brand by default.

Quickstart

Reminder: examples below are the CLI path (preferred). If

command -v pandastudio

returned empty, mentally translate each verb — e.g.

pandastudio system.status --json

→

system_status

MCP tool,

pandastudio project.add-zoom --id=… …

→

project_add_zoom

with the same args.

# 1. Confirm the server is reachable AND the user has a license.
#    MCP equivalent: call `system_status` with no args.
pandastudio system.status --json

# 2. Discover what's available — never guess command names.
#    MCP equivalent: call `system_list_commands`.
pandastudio commands

# 3. Render a motion graphic from a bundled template (the primary path).
#    See the "Motion graphics" section for the full catalog.
JOB=$(pandastudio motion.generate \
  --templateId=creator-card \
  --slots='{"headline":"live demo","eyebrow":"now","brandColor":"#2563EB"}' \
  --aspectRatio=16:9 \
  --json | jq -r '.data.jobId')

pandastudio job.wait --id="$JOB" --json | jq '.data.job.result'

# 4. Add the rendered clip to the timeline at the playhead / a given time.
pandastudio project.add-motion-graphic --id="$PROJECT" --fromJob="$JOB" --durationMs=4500

job.wait

timeouts are not failures. Default 5 min, hard cap 30 min. If the wait returns

{ job, timedOut: true }

, the job is still running — call

job.wait

again with the same id to keep polling. NEVER treat

timedOut: true

as a render failure; the underlying render keeps going regardless of whether anyone's waiting on it. For heavy 30s @ 1080p motion-graphic renders, expect 8–15 minutes — pass

--timeoutMs=600000

or higher up front, or re-poll until the result lands.

Before any tool call: license check

pandastudio system.status --json

license

licensed: true

licensed: false

trialUsesRemaining > 0

automationGated: true

system.*

window.focus

invalid or missing bearer token

~/.config/pandastudio/{token,port}

Workspaces (v1.19+)

project.*

export.*

motion.*

caption.*

audio.*

workspace.current

system.status

pandastudio workspace.list --json | jq '.data | { current: .currentWorkspaceId, count: (.workspaces | length), cap: .limit }'

limit.max

• 1

  — Starter plan or Trial

• 3

  — Creator plan

• null

  — Team plan (unlimited)

# Get the id of a specific client's workspace
WS=$(pandastudio workspace.list --json | jq -r '.data.workspaces[] | select(.name == "ACME Agency — Client A") | .id')
pandastudio workspace.switch --id=$WS --json
# Every subsequent query now operates inside that workspace.

# Agencies: one workspace per client.
pandastudio workspace.create --name="ACME Agency — Client A" --switchTo=true --json

# If the plan cap is hit, the response looks like:
# { "ok": false, "error": "Your Starter plan allows 1 workspace. Upgrade to Creator to create more.",
#   "details": { "code": "workspace_limit_reached", "upgradeTo": "Creator" } }
# Tell the user to upgrade at writepanda.ai/#pricing; do NOT retry.

workspace.contents

workspace.delete

.pandastudio

pandastudio workspace.contents --id=$WS --json | jq '.data.counts'
# { "projectCount": 12, "exportCount": 4, "publishedVideoCount": 3 }
# Confirm with user before:
pandastudio workspace.delete --id=$WS --json

⚠ When given a project id with no other context

project.locate

RES=$(pandastudio project.locate --id=$PID --json)
# { "data": { "id": ..., "filePath": ..., "workspaceId": ..., "workspaceName": "Client A",
#             "isInActiveWorkspace": false } }
IN_ACTIVE=$(echo "$RES" | jq -r '.data.isInActiveWorkspace')
WS_NAME=$(echo "$RES" | jq -r '.data.workspaceName')

if [ "$IN_ACTIVE" != "true" ]; then
  # STOP. Do not silently switch. Ask the user.
  # "This project lives in workspace '$WS_NAME', current is '<X>' — switch?"
fi

project.read

export.publish-youtube

media.generate-image

export.generate-thumbnail

youtube.list-accounts

project.read

workspaceId

workspaceName

isInActiveWorkspace

project.locate

project.locate

export.publish-youtube

isInActiveWorkspace === true

pandastudio workspace.switch --id=$TARGET_WS --json
# Then re-run any pre-flight that depends on workspace state
# (license check, youtube account list, replicate key check)

Project-look defaults (v1.49.1+)

wallpaper

captionSettings

editorDefaults

# Read the current defaults (null = none set)
pandastudio workspace.get-project-defaults --json

# Set them — pass any subset; unknown fields are dropped.
pandastudio workspace.set-project-defaults \
  --defaults='{"wallpaper":"/wallpapers/wallpaper5.jpg","captionSettings":{"enabled":true,"templateId":"editorial"},"editorDefaults":{"padding":18,"borderRadius":8}}' \
  --json

# Clear them
pandastudio workspace.set-project-defaults --defaults=null --json

Brand kit — set it, or auto-capture it from a URL (v1.84+)

# Manual: set any subset.
pandastudio workspace.set-brand --brand='{"name":"Acme","colors":{"primary":"#2563EB","ink":"#111827","background":"#FFFFFF"},"typography":{"display":"Inter"}}' --json

# Auto: pull the real brand straight off a website. Runs HyperFrames capture,
# classifies the site's actual colors/fonts/logo, and MERGES them into the kit
# (your hand-set fields survive). ASYNC — poll job.wait; first run downloads the
# capture CLI so use a long timeout.
JOB=$(pandastudio workspace.capture-brand --url=https://acme.com --json | jq -r '.data.jobId')
pandastudio job.wait --id="$JOB" --timeoutMs=300000 --json | jq '.data.job.result.brand'

workspace.capture-brand

workspace.set-brand

Organising projects, renaming, transcription languages

project.rename

reference/projects-and-transcription.md

Recording the screen yourself (agent-driven, v1.86+)

# 1. (optional) see what you can target — displays + windows
pandastudio recording.list-sources --json
#   → { displays:[{id:"screen:1:0",name:"…",primary:true}], windows:[{id:"window:123:0",name:"Google Chrome — …"}] }

# 2. start (defaults to the primary display; pass --source to pick a window/display)
pandastudio recording.start --json                          # whole primary display
pandastudio recording.start --source="window:123:0" --json  # just that Chrome window
#   → { recordingId }

# 3. …now do the thing you want to capture (click through the app, etc.)…

# 4. stop — finalizes the MP4 AND creates an editable project by default
pandastudio recording.stop --name="ACME tutorial" --json
#   → { screenPath, durationMs, projectId, projectPath, projectCreated:true }

transcript.transcribe

transcript.remove-fillers

project.add-zoom

media.generate-narration

project.add-audio

export.start

• Permission: screen capture needs the one-time OS Screen Recording grant. It is already granted for anyone who has ever recorded in the app, so this runs with zero interaction. On a brand-new install that never recorded, the first

  recording.start

  returns a clear "grant Screen Recording and retry" error instead of hanging — surface that to the user; you cannot grant it for them.
• One at a time.

  recording.start

  fails if a recording is already active — call

  recording.stop

  first.
• No mic on this path. Only screen (and optional

  --systemAudio=true

  ). Record clean, then add narration with

  media.generate-narration

  .

• recording.stop --createProject=false

  just finalizes the MP4 and returns

  screenPath

  if you want to compose

  project.new --withMedia=…

  yourself.

Shorts: turning an exported video into vertical clips

export.find-shots

project.fork-from-shot

reference/shorts.md

reference/shorts-styles.md

reference/shorts-cheatsheet.md

youtube-long

reference/longform-styles.md

Shorts layout: full-frame vs camera-corner-over-blur

project.set-shorts-layout

# Camera shrinks to a draggable bottom-right tile over a blurred copy of itself
pandastudio project.set-shorts-layout --id=$PID --layout=camera-corner
# Camera fills the frame (clears the transform + backdrop)
pandastudio project.set-shorts-layout --id=$PID --layout=full

camera-corner

blur-self

project.set-screen-transform

x

y

scale

project.set-backdrop --mode=blur-self|wallpaper

project.set-webcam-layout --preset=picture-in-picture

Active-speaker auto-reframe: landscape multi-person → vertical (v1.70+)

project.auto-reframe

1. Shot detection (ffmpeg scene cuts) segments the source.
2. Dense face tracking — MediaPipe FaceLandmarker (bundled, offline) samples ~7fps, with adaptive tiling so small/far faces in wide shots are still found. Detections are associated into per-person tracks.
3. Audio active-speaker — on multi-person shots it frames whoever is talking (mouth-open × speech-energy), not the biggest face.
4. Smoothed camera — the crop pans to follow the subject within a shot (with a dead-band hold + a safe-zone clamp so the face never leaves frame) and cuts at shot boundaries.

# Reframe every landscape clip — tracks + follows the active speaker.
pandastudio project.auto-reframe --id=$PID --json
# → { reframed: [{clipId, shots, shotsWithFace}], skipped: [...] }

# One clip only, or tune shot sensitivity / punch-in:
pandastudio project.auto-reframe --id=$PID --clipId=clip-1 --threshold=0.3 --minShotMs=500 --zoom=1.3 --json

# Revert to the plain static cover-crop:
pandastudio project.auto-reframe --id=$PID --clear=true --json

• This is the right verb (NOT

  project.set-focal-point

  ) whenever a landscape source with multiple/alternating speakers is cut to 9:16.

  set-focal-point

  sets ONE static point for the whole clip — correct only for a single, stationary talking-head. For director-cut / multi-person footage, reach for

  auto-reframe

  .
• Async + needs a renderer (bundled offline detection). It opens a hidden editor for the pass; the DENSE tracking + audio makes it slower than a plain edit — allow a couple of minutes for a few-minute source. Skips clips already matching the canvas aspect (nothing to reframe) → reported under

  skipped

  .

• --zoom

  : omit for the default ADAPTIVE punch-in (each speaker's face sized to a consistent fraction of frame). Pass a fixed value (e.g.

  1.3

  ) to force a uniform punch-in on every shot.
• Set the 9:16 aspect FIRST (

  project.set-aspect-ratio --aspect=9:16

  ), then auto-reframe — the track is computed for the canvas aspect and is ignored if the aspect later changes (recompute after an aspect switch).
• Preview and export render the crop identically, per frame — the preview camera pans live. Verify from the EXPORTED mp4 across a close-up, a pan, AND a wide two-shot (render-frame is fine too, but the export is the source of truth near shot cuts).
• Also exposed in the editor as the "Track speakers" button (Video → Layout).
• v1 limitation: one subject per shot — a held two-shot where two people banter frames the dominant talker (no mid-shot switching yet).

Publishing (YouTube + Instagram)

privacyStatus

unlisted

isInActiveWorkspace

reference/publishing.md

Memory — remember preferences across chats

pandastudio memory.save --note="Channel is WritePanda; energetic tone, fast cuts"
pandastudio memory.save --note="Default caption template: editorial; brand accent #2563EB"
pandastudio memory.list --json      # { entries: [{id,text}], count } — get ids
pandastudio memory.forget --query="a1b2c3"     # by id, or a text fragment

memory.forget

Editorial decisions — what to ask, what to assume, what NEVER to ask

The default edit pipeline (vague "edit my video", no specifics)

1. Transcribe any clip where

   clipStates[i].transcribed === false

   (

   transcript.transcribe

   ).
2. Remove filler words + immediate repeats (

   transcript.remove-fillers

   ).
3. Fix transcript spelling / STT errors. Read the transcript and correct obvious misspellings — especially product, brand, person, and technical names the speech-to-text got wrong (e.g. "Right Panda" → "WritePanda") — with

   transcript.find-replace

   (patches the word text in place, keeps timing). Do this BEFORE captions, motion graphics, or title generation — they all derive their text from the transcript, so a typo propagates.

   find-replace

   only rewrites words that already exist. When STT DROPPED a word entirely (the transcript is missing a spoken word), use

   transcript.insert-words

   instead — anchor it with

   --afterWordId

   (or

   --beforeWordId

   to add at the very start) from

   transcript.get

   , and pass

   --text

   . It computes plausible timing (fills the gap the drop left, sized to the local speaking rate) and is non-destructive — existing word ids, and any trims/zooms/captions anchored to them, are untouched. It does NOT re-transcribe.
4. Cut bad takes. Run

   transcript.find-issues

   (read-only — it never edits). For each

   duplicate-take

   /

   false-start

   , the default is to keep the most recent (last, cleaner) take and delete the earlier attempt — feed the candidate's

   wordIds

   (which point at the discarded attempt) into

   transcript.delete-words

   . EXCEPT

   severity: "low"

   candidates — those are REVIEW-class: KEEP them by default. A low-severity

   false-start

   means the restart diverges from the fragment, which is often deliberate parallel structure ("one for transcription, one for outreach"), not a flub — deleting it destroys the sentence. Only delete a low candidate when the surrounding context clearly shows an abandoned take. If a candidate is genuinely ambiguous (the repeat might be intentional emphasis, or you can't tell which take is better), ask the user which take to keep rather than guessing.
5. Remove silences (

   transcript.remove-silences

   , 600ms default — same as the UI Remove Silences button) — after content cleanup so it tightens the final timing. The verb returns

   removedCount

   + the new

   revision

   (synchronous — you'll know immediately how many it cut). Every transcript cleanup step (2, 4, 5) ADDS trims and shifts the edited timeline, so always finish cleanup BEFORE placing graphics/zooms/lower-thirds (steps 8–9). If you ever place a region from a transcript word before cleanup is done, pass

   --anchorSourceMs

   so it re-anchors when the timeline shifts. (If the user already removed silences in the UI, a fresh

   project.read

   shows the new

   trimCount

   /

   editedDurationMs

   /

   totalTrimmedMs

   — treat that as "silences already done".)
6. Clean audio (

   audio.clean

   ) on clips where

   audioCleaned === false

   .
7. Add captions —

   caption.toggle

   +

   caption.set-template

   (default

   bold

   per profile; see the caption styles in "DO BY DEFAULT").
8. Add motion graphics — follow the Motion-graphics Rules + selection guide:

   motion_list

   first, vary templates by beat, prefer the featured (premium) templates (

   paper-panel

   /

   vox-side-panel

   / the Vox family), and for camera-only / imported footage lead with

   paper-panel

   or

   vox-side-panel

   designed segments (not the plainer

   split-panel

   ). On any talking-head (

   kind === "camera"

   ), open with a

   caption-editorial-emphasis

   TOPIC card in the first 10–30s that names what the video is about (from the speaker's opening lines) — the default hook for talking-heads. For explainer content, author custom animated diagrams / flowcharts / charts when the speaker explains how something works or connects and no template captures it (see "Authored graphics") — don't flatten a real explanation into a bullet list.
9. Add emphasis zooms — punch in on the key beats for a dynamic, edited feel (see "Emphasis zooms" just below).
10. (Only when the brief is "make it engaging / cinematic / dynamic / give it energy", NOT a plain "clean it up") — add scene transitions at the real section boundaries (

    project.add-transition

    , ~1 per major section, one consistent style). See the "Effects (FX) & transitions" section — restraint is the rule: a transition belongs at a section change, never on every cut. Do NOT add FX overlays here — FX is explicit-request-only (see the "NOT part of the default pipeline" list below); "make it engaging" does not authorize adding effects.
11. Generate title / description / timestamps, then preview.

• transcript.remove-fillers

  — vocalised pauses (um, uh, uhm, umm, hmm, hm) AND immediate repeated words. Default behavior is the SAFE tier only — the words above are sounds, never lexical, so removing every match is unambiguously correct. Pass

  --aggressive

  to additionally remove

  like / you know / i mean / sort of / kind of

  ; these are real English words too, so the aggressive mode will sometimes cut legitimate uses ("I like this template" loses "like"). Only opt in when the user explicitly asks for a thorough cleanup AND is willing to skim the result for false positives.

• transcript.find-issues

  →

  transcript.delete-words

  — bad takes and repeated phrases.

  find-issues

  is read-only; you MUST then actually delete the discarded

  wordIds

  (keep the most recent take). Running

  find-issues

  and not deleting is the same as doing nothing — the bad take stays in the video. (

  severity: "low"

  false-starts are the exception — REVIEW-class, keep by default; see the transcript verbs table.)

• transcript.remove-silences

  — the single most-skipped step; silence removal is what makes a talking-head edit feel tight.

• On yes (or if they said "just go" / "do everything" / "use defaults") → run the whole pipeline without further per-step asking, then narrate.
• If they named a specific operation ("just add captions", "only remove silences", "add a lower third") → do exactly that and nothing else.

• Background music. Never add a music track to "edit my video" / "do the full polish". Add it only when the user explicitly asks ("add background music", "put a track under it"). "Full polish" does NOT include music.
• Intro / outro cards. Never open with a title card or append an outro/CTA card unless the user explicitly asks for one ("add an intro", "add an outro"). A plain edit keeps the user's footage as the first and last frame.
• FX overlays (

  project.add-fx

  ). Never add an FX overlay (film burn, light leak, grain, VHS, embers, film-flash, etc.) on your own — NOT on a plain edit, and NOT even for "make it engaging / cinematic". FX is a deliberate creative choice the user makes; add one only when they explicitly ask for an effect ("add a film burn between these clips", "put some grain on it", "add a light leak"). When they do, follow the restraint rules in the "Effects (FX) & transitions" section. (Transitions are different — those ARE part of the engaging-tier flourish; see step 10.)

Emphasis zooms — punch in on the key beats

project.add-zoom

kind === "screen"

camera

upload

MUST ASK (3 things, only when context is missing)

project.read --includeTranscript=false

• User mentioned "Shorts" / "TikTok" / "Reels" / "Instagram story" / "vertical" / "phone"? →

  shorts

  profile (9:16, punchy)
• User mentioned "LinkedIn" / "client pitch" / "professional" / "corporate"? →

  linkedin

  profile (16:9 or 1:1, restrained)
• User mentioned "Loom" / "internal" / "async update" / "for the team" / "quick video"? →

  loom

  profile (minimal editing)
• User mentioned "YouTube" / "long-form" / "tutorial" / "vlog" / "channel"? →

  youtube-long

  profile (16:9, full pipeline)
• Project was created by

  project.fork-from-shot

  ? →

  shorts

  (it exists to BE a short)
• Project aspect ratio is already 9:16 or 1:1 (project setting, not just source orientation — the user chose that canvas)? →

  shorts

• Workspace project defaults name a destination (

  workspace.get-project-defaults

  )? → use it
• Duration bands (total source duration): · ≤ 90s →

  shorts

  — regardless of orientation; nobody publishes a 45s "long-form video", and a landscape short gets auto-reframed to 9:16 · > 8 min →

  youtube-long

  (or

  loom

  if it's a screen recording with cursor telemetry and no user framing — internal walkthroughs look exactly like this) · 90s–8 min → genuinely ambiguous: could be a long-form video OR source to cut a short from. Use content type as tiebreaker (screen recording → youtube-long/loom; phone-framed talking head → shorts), else ASK.
• Source clip is portrait (height > width), no other signal? →

  shorts

• Source clip is landscape, no other signal? →

  youtube-long

  (safe default — most common)
• Ambiguous or no clips yet? → ASK ONE QUESTION:

  "Where is this going — YouTube long-form, Shorts/TikTok/Reels, LinkedIn, or internal/async (Loom-style)?"

youtube-long

shorts

"What's the name and the subtitle (e.g. role / company)?"

shorts

loom

slots

reference/motion-philosophy.md

"Any brand colors, fonts, or visual references — or default look?"

"Templated quick version, or fully custom? For a promo I'd default to fully custom scenes — they look bespoke, not templated."

motion.render-html

reference/motion-philosophy.md

media.generate-narration

--model

--model=elevenlabs-direct

media.generate-music

asset.list-music

"Want a voiceover and/or a music bed? Both shape the timing, so I'll lock them in before building the scenes."

--transcribe=true

project.add-audio

transcript.transcribe

transcribeJobId

job.wait

caption.toggle

NARR=$(pandastudio media.generate-narration --text="..." --json | jq -r '.data.path')
OUT=$(pandastudio project.add-audio --id=$ID --audioPath="$NARR" --startMs=0 \
  --transcribe=true --json)
pandastudio job.wait --id=$(echo "$OUT" | jq -r '.data.transcribeJobId') --json
pandastudio caption.toggle --id=$ID --enabled=true   # now has words to render

reference/promo-and-mg-videos.md

DO BY DEFAULT, narrate transparently

transcript.transcribe

audio.clean

project.read

clipStates

{ "clipId": "clip-1", "mediaPath": "...", "durationMs": 62400,
  "transcribed": true, "wordCount": 312,
  "audioCleaned": false, "kind": "camera" }

• transcribed: true

  → skip

  transcript.transcribe

  for that clip — it already has a transcript. Running it again would overwrite any manual word edits the user made in the app.

• audioCleaned: true

  → skip

  audio.clean

  for that clip — the

  .cleaned.wav

  already exists.

• kind

  → how the clip was captured:

  "camera"

  (talking-head — a PandaStudio camera-only recording),

  "screen"

  (screen recording, maybe with a webcam PiP), or

  "upload"

  (external import). This is the authoritative signal for your visual strategy — use it, don't guess from aspect ratio:

  kind === "camera"

  (talking-head) OR

  kind === "upload"

  (imported video) → there's no screen to zoom into, so lead with a premium designed segment —

  paper-panel

  or

  vox-side-panel

  (

  project.add-designed-segment

  ) as the default for explainer beats; it's the highest-leverage way to make static footage look produced (

  split-panel

  is the plainer fallback — see the Motion-graphics "Rules" §5).

  kind === "screen"

  → use cursor-telemetry zooms, never clip-transform splits. On v1.28+ recordings this is stamped at capture; older projects don't have it, so

  project.read

  infers it (paired webcam track or cursor telemetry →

  screen

  ; managed-dir media →

  camera

  ; else

  upload

  ) and sets

  kindInferred: true

  .

kind

screen

screen

• A clip flagged

  kindInferred: true

  is a hint, not gospel. If it reads

  screen

  but you have any doubt (the footage is a person talking, not a UI; no cursor), treat it as

  camera

  — the default when unsure is always

  camera

  , never

  screen

  .
• If it genuinely matters and you can't tell, ask the user ("Is this clip a screen recording, or you on camera?") rather than guessing

  screen

  .
• Once known, lock it:

  project.set-clip-kind --clipId=… --kind=camera|screen|upload|podcast

  stamps an authoritative value so no future agent has to re-guess (ideal for pre-v1.28 projects — stamp each clip once).

  podcast

  = a two-speaker composite (host=mediaPath, guest=webcamPath) recorded via Record Podcast; it's set automatically at ingest and edits as one clip with the

  podcast

  webcam layout.

• contentIssues

  (top-level on the

  project.read

  result, not per-clip) → a count summary

  { total, duplicateTakes, falseStarts, adjacentRepeats }

  , present only when something is transcribed. If

  total > 0

  , run

  transcript.find-issues

  during the polish pass to see the actual candidates.

transcript.get

transcript.transcribe

clipStates[i].transcribed === false

transcript.remove-fillers

aggressive=true

transcript.find-issues

duplicate-take

false-start

adjacent-repeat

wordIds

wordIds

transcript.delete-words

severity: "low"

false-start

transcript.remove-silences

silencedetect

audio.clean

clipStates[i].audioCleaned === false

.cleaned.wav

caption.set-template

bold

classic, modern, minimal, spotlight, boxed, neon, colored, editorial

editorial

kineticSlam

clipWipe

gradientPop

matrixDecode

glitchRgb

blendDifference

bold

editorial

llm.generate-title

llm.generate-description

llm.generate-timestamps

project.add-fx

"Edited. • Transcribed both clips (136 words). • Removed 14 fillers + 3 repeats. Trim regions are reversible — say 'undo fillers' if you want any back. • Cut 2 bad takes (kept the cleaner second attempt each time). • Removed 67 silences (>600ms), tightening ~48s of dead air. • Cleaned audio with DeepFilter on both clips. • Added a zoom at 12.4s where you said 'click here'. • Captions enabled with the bold template (8 other styles available). • Generated a title: 'How I Built This in 24 Hours' — say if you want a different angle.

Opening preview now."

NEVER ASK about

• Whether to remove filler words (it's reversible — do it)
• Whether to remove repeated words (same)
• Whether to clean audio (sibling file, original untouched)
• Specific zoom positions or focus points (infer; user redirects via preview)
• Specific caption colors / font sizes (template defaults are good)
• Whether to generate a title / description / timestamps (cheap, useful)
• Whether to enable captions when user said "add captions" (yes — they said yes)
• Specific lower-third design/colour (use defaults; user can swap)

Preview, then export. Never export, then preview.

1. Call

   preview.show --id=<uuid>

   (opens the editor focused on the project — same single-step UX, ~2-3s).
2. Tell the user what you did (the narration block above).
3. Ask: "Does this look right? Anything to tweak before I export?"
4. Only after explicit user confirmation call

   export.start

   .

Output modes

• Default: pretty one-line summaries to stdout. Show these to the user.

• --json

  : raw

  { ok, data, error }

  envelope. Always use

  --json

  when you intend to parse the response or chain commands — pipe through

  jq

  .

Discovery (the most important habit)

pandastudio commands --json   # full schema with arg hints per command

summary

Async jobs

motion.generate

export.start

jobId

data

pandastudio job.wait --id="$JOB" --timeoutMs=120000 --json

job.status

succeeded | failed | canceled

result.outputPath

Argument shape

--name=value

--slots='{"title":"x"}'

{

[

true

false

Error model

{ ok: boolean, data?: ..., error?: string, details?: ... }

• HTTP 4xx/5xx → transport problem. CLI exits ≥ 1 to stderr.
• HTTP 200 +

  ok: false

  → handler-level error. CLI exits 1 with

  error: <msg>

  to stderr. The most useful machine-readable codes:

  • license_required

    /

    trial_expired

    — show the user the license activation flow

  • unknown command

    — typo; run

    pandastudio commands

    to recover

  • invalid or out-of-tree project path

    — project paths must live under the user's recordings dir; never pass arbitrary absolute paths

Composing a real edit

HARD INVARIANT — every video the agent creates lives in a project.

Whatever the brief — promo, explainer, transcript-driven edit, PDF-to-video, a single motion graphic, B-roll over a recording, a one-shot title card — the editor project is the deliverable, not the raw MP4. Loose files in

~/Library/Application Support/pandastudio/recordings/

are intermediates the editor consumes; they are never the agent's hand-off.

The two valid starting states:

1. A project is already open in the editor (

   project.current

   returns a non-null id) → use it. Add your work to that timeline. Save. Preview.
2. No project is open (

   project.current

   returns null, or the chat opened from the home screen) →

   project.new

   is your FIRST tool call, before any motion render / transcription / b-roll generation. Name the project something the user will recognise ("PandaScribe Promo", "Q4 Recap", "How to install — explainer"). Pick the aspect ratio from the destination profile (16:9 YouTube, 9:16 Shorts, 1:1 LinkedIn square).

After the work lands in the project,

preview.show --id=<project-id>

to open it in the editor for the user. THAT is the hand-off. The chat message reports the project name/id, not a file path on disk.

Exceptions are vanishingly rare — only when the user explicitly says "just give me the MP4, no project" (e.g. they want to upload it elsewhere right away). When in doubt, default to project.

system_list_commands

pandastudio commands

reference/commands.md

Target the right project

• project.new --withMedia='["/a.mp4","/b.mp4"]'

  — create pre-loaded; clip durations are FFmpeg-probed automatically.

• project.duplicate --id

  (or

  --path

  ) — EXACT copy of a project: every edit (trims, zooms, speed, crops, overlays, captions, spotlights, transcript, aspect ratio) is preserved. The copy gets a fresh id and a

  <name> (copy)

  name and a new

  .pandastudio

  file; the source is untouched (non-destructive) and media files are shared, not copied. Returns

  { id, path, name }

  . Use when the user asks to duplicate / copy / clone a project — e.g. to try a variant edit without disturbing the original.

• project.current

  → the open editor project (

  {id,path,name,revision,clipCount}

  or

  null

  ). Use it when the user says "this one" / "what's open" — don't ask for an id.

  null

  ≠ "no projects exist"; fall back to

  project.list

  .

• project.read --id

  → full state. Key fields the schema won't spell out:
  • clips at

    mainTrack.clips[]

    — each carries

    sourceDurationMs

    (the clip's own length); there is no per-clip

    durationMs

    on the raw clip. For a normalized per-clip view use the top-level

    clipStates[]

    , where each entry has

    clipId

    ,

    durationMs

    (= sourceDurationMs),

    kind

    ,

    transcribed

    .
  • motion-graphic / transition overlays at

    editor.mediaOverlayRegions[]

    .
  • audio overlays (voiceover, music) at top-level

    project.audioOverlays[]

    — NOT under

    editor

    . Different array from the visual overlays.
  • top-level read summary fields:

    aspectRatio

    ,

    editedDurationMs

    (post-trim — use for cadence planning),

    sourceDurationMs

    ,

    totalTrimmedMs

    ,

    trimCount

    , and per-clip

    clipStates[].kind

    (

    camera

    /

    screen

    /

    upload

    , your visual-strategy signal). Pass

    --includeTranscript=false

    after the first read.

Adding things — the gotchas (call discovery for the arg schemas)

• Clips:

  add-clip

  (

  --atIndex=0

  prepends),

  move-clip

  ,

  split-clip

  ,

  remove-clip

  .

  project.delete

  is permanent — no trash. By default it only removes the project file and KEEPS the original source recording. Pass

  --deleteRecording=true

  to ALSO delete the original recording file(s) from disk (irreversible — only do this when the user explicitly asks to delete the source footage, not just the project). Returns

  deletedRecordings

  (count removed).
• Motion graphics — use

  --fromJob

  , NOT

  --file

  , for render outputs. Pass the render

  jobId

  (after

  job.wait

  ); the server resolves the path itself:
  bash

  JOB=$(pandastudio motion.render-html --htmlPath=/tmp/card.html --durationMs=4000 --json | jq -r '.data.jobId')
  pandastudio job.wait --id="$JOB" --json
  pandastudio project.add-motion-graphic --id=$ID --fromJob="$JOB" --durationMs=4000

  --file

  is only for external uploads and must be quoted — render outputs live under

  …/Application Support/…

  (a space); an unquoted path truncates and silently produces a dead overlay (shows on the timeline, never renders).
• Placing on a spoken word in a trimmed timeline: trims make source-time ≠ output-time. From

  transcript.get

  , each word has

  startMs

  (source) and

  editedStartMs

  (output;

  null

  = inside a trim → skip it). Pass the source

  startMs

  as the position and

  --anchorSourceMs=<same>

  so the region re-anchors when later cleanup trims shift the timeline.

  timeline.source-to-edited --sourceMs=N

  returns the output time (or

  null

  if trimmed).
• Mid-video graphic on camera / upload footage: don't cover the host — use

  project.add-designed-segment

  (the split-panel beat; see Motion-graphics Rules §5). Screen recordings use

  project.add-zoom

  instead, never a split. Never place a zoom inside a designed-segment / split window — the camera is already cropped to a half-frame band, so zooming it looks wrong. Zoom the full-frame stretches, split the rest.
• Zoom depth → scale factor.

  depth

  (1–6) maps to a fixed zoom multiplier. When the user asks for "a 1.5x zoom," translate it with this table — there is no separate scale arg:

  depth	scale	feel
  1	1.25×	barely-there nudge
  2	1.5×	soft, modern default (talking-head, tutorials)
  3	1.8×	clear emphasis (UI clicks, callouts)
  4	2.2×	strong punch-in
  5	3.5×	dramatic detail
  6	5.0×	extreme macro

• Zoom / fx / SFX:

  add-zoom

  (default depth 2 = 1.5× + swoosh SFX;

  --soundUrl=none

  to silence),

  add-motion-graphic

  (default mouse-click SFX as of v1.36.0),

  add-fx

  (13 bundled FX overlays — film-burn, light-leak, light-flare, lens-flare-sweep, light-streaks, bokeh-drift, prism-leak, dust-scratches, film-grain, vhs-static, embers, snow-drift, film-flash;

  --speed=0.25–4

  adjusts loop speed, default 1; see the "Effects (FX) & transitions" section for when to reach for each),

  set-region-sound

  (retune/clear a placed region's SFX). Arg values: discovery (

  asset.list-fx

  ).
• Spotlight / blur (v1.50.0):

  add-spotlight --atMs=<ms> --durationMs=<ms> [--kind=spotlight|blur]

  — a focus rect over the video.

  kind=spotlight

  (default) DIMS everything outside the rect (draw the eye to one spot);

  kind=blur

  BLURS everything inside it (hide an email, username, or other sensitive detail in a screen recording). Rect placement is

  --x --y --width --height

  as 0..1 fractions of the video (default a centred half-size box,

  x=y=0.25 width=height=0.5

  ).

  --roundness

  (px corner radius, default 16),

  --feathering

  (px soft edge, default 12). Spotlight:

  --maskOpacity

  0..1 (surround darkness, default 0.6). Blur:

  --blurAmount

  px (default 12). The rect tracks content through zooms.

  atMs

  is EDITED time (no anchor arg). Edit or delete after placing (v1.85.0):

  update-spotlight --regionId=<id> [--startMs --endMs --kind --x --y --width --height --roundness --feathering --maskOpacity --blurAmount]

  patches only the fields you pass (move/resize, retime, restyle, or flip spotlight<->blur);

  remove-spotlight --regionId=<id>

  deletes it. Get ids from

  project.read

  under

  editor.spotlightRegions[].id

  .
• Background blur / removal / studio image + person outline (v3.69.0; outline v3.75.0; studio image v3.104.0):

  add-background-effect --mode=blur|remove|image [--atMs=<ms>] [--durationMs=<ms> | --endMs=<ms>] [--strength=<px>] [--backgroundImage=<studioId|path> --backgroundFit=cover|contain] [--outline --outlineWidth=<px> --outlineColor=<hex> --outlineShadow=<bool>] [--anchorSourceMs=<srcMs>]

  — AI PERSON SEGMENTATION on the camera video for the region's span, exactly like a zoom region on the timeline (draggable, trimmable, source-anchored, rebases on trims/speeds).

  mode=blur

  keeps the speaker sharp and gaussian-blurs everything behind them (video-call style;

  --strength

  is px sigma at 1080p, default 18).

  mode=remove

  cuts the background away entirely so the project wallpaper/background shows through behind the person — pair it with

  set-wallpaper

  for a branded backdrop, OR with a background-layer media overlay to put an IMAGE/VIDEO behind the speaker (the Shorts look): add the media with

  add-motion-graphic --file=<img/video> --layer=background

  (or flip an existing overlay with

  update-region --regionType=overlay --layer=background

  ; in the UI, right-click the overlay → "Send behind video"). The removed- background speaker composites OVER that overlay in preview and export.

  mode=image

  is the virtual studio: it removes the real background and composites the speaker over a STUDIO PLATE — the one-call way to put someone with a messy room into a clean studio. Set

  --backgroundImage

  to a bundled studio id:

  warm-creator

  (soft warm key),

  tech-rgb

  (cool RGB rim),

  neutral-grey

  (soft even),

  podcast-warm

  (warm tungsten),

  daylight-airy

  (natural daylight),

  gradient-gel

  (magenta/teal),

  cinematic-dark

  (dramatic side) — or an absolute/

  file://

  /

  data:

  image path for a custom background. Defaults to

  warm-creator

  .

  --backgroundFit=cover

  (default, fill+crop) or

  contain

  (fit whole plate). Pick a plate lit like the footage for the most natural composite. No outline by default (it's a real background, not a cutout). Same matte tuning as below applies. Matte boundary tuning:

  --matteContract=<px>

  manually tightens the person edge — >0 pulls it INWARD (kills a background fringe / cleans a loose cut), <0 pushes it out (−60..60);

  --matteFeather=<px>

  softens the edge (0..60). Both apply to blur AND remove (they adjust the person matte the outline is built from too).

  --outline

  is a colored keyline + drop shadow that hugs the person — the "VOX magazine cutout" look. It is ON BY DEFAULT for

  mode=remove

  (v3.80.0): a bare cutout reads as unintentional, the keyline makes it look designed, so removal ships the VOX look out of the box (pair with a cream

  set-wallpaper

  for the reference look). Pass

  --outline=false

  to remove the background with NO keyline. For

  mode=blur

  it's off unless you pass

  --outline

  .

  --outlineWidth

  px@1080p (default 36),

  --outlineColor

  hex (default

  #ffffff

  ),

  --outlineShadow

  bool (default true). Duration defaults to 5000ms. CAMERA / TALKING-HEAD footage only — pointless on screen recordings. Runs on a bundled on-device model (no network); preview and export render it identically. Regions live under

  editor.backgroundEffectRegions[]

  (

  .outline = {enabled,width,color,shadow}

  ); retime/restyle with

  update-region --regionType=background-effect [--startMs --endMs --mode --strength --backgroundImage --backgroundFit --outline --outlineWidth --outlineColor --outlineShadow --matteContract --matteFeather]

  , delete with

  remove-region --regionType=background-effect

  . Also batchable inside

  apply-edit-plan

  as

  {op:'add-background-effect',atMs,durationMs,mode, strength?,backgroundImage?,backgroundFit?,outline?,outlineWidth?, outlineColor?,outlineShadow?,matteContract?,matteFeather?}

  .
• See a frame to place it (v1.85.0):

  render-frame --atMs=<ms> [--outPath=<png>]

  composites the preview frame at that edited-time to a PNG and returns

  { path, width, height, timeMs, maskRect }

  . A vision model should

  read

  the returned

  path

  to LOCATE on-screen text/UI (e.g. the email to blur), then place a focus region.

  maskRect

  is the video content rect as 0..1 fractions of the image — the SAME space as spotlight/blur x/y/width/height. Convert an image-space box (ix,iy,iw,ih) to region coords:

  x=(ix-maskRect.x)/maskRect.width

  ,

  y=(iy-maskRect.y)/maskRect.height

  ,

  width=iw/maskRect.width

  ,

  height=ih/maskRect.height

  . Typical privacy-blur flow:

  render-frame

  → read PNG → locate text →

  add-spotlight --kind=blur

  with converted coords →

  render-frame

  again to verify →

  export.start

  . Caveats: existing focus regions are NOT drawn (you see content clearly); the frame reflects any active zoom at that time, so prefer an un-zoomed moment for placement.
• Transitions (v2.98.0):

  add-transition --transitionId=<id> --atMs=<cutMs>

  — places a scene-change overlay CENTERED on a cut (the opaque peak masks the join). Pass

  atMs

  = the cut time between two clips (from

  project.read

  clip boundaries).

  atMs

  here is EDITED (output) time, and add-transition has NO

  anchorSourceMs

  — unlike add-zoom / add-motion-graphic. If you only have a source-time value (a transcript word's

  startMs

  ), convert it first with

  timeline.source-to-edited --sourceMs=N

  and pass the result. Ids (

  asset.list-transitions

  ): fade-black, fade-white, flash, light-sweep, film-burn, glitch, scribble.

  --durationMs

  defaults to 1000 (the hand-drawn

  scribble

  is authored at 2200ms — pass

  --durationMs=2200

  to keep its scribble-on/clear beats intact). Always prefer

  asset.list-transitions

  over this static list — it is the source of truth.

  Time domains at a glance.

  atMs

  /

  startMs

  /

  endMs

  are ALWAYS edited (output) time.

  anchorSourceMs

  (source/raw-recording time) is an extra drift-proofing arg on add-zoom, add-motion-graphic, add-designed-segment, add-lower-third — pass it alongside

  atMs

  when

  atMs

  came from a transcript word so the region re-anchors across later trims. Verbs WITHOUT an anchor (add-transition, region edits) need a pre-converted edited time.

• Lower thirds (v2.96.0):

  project.add-lower-third --name="…" --title="…" --atMs=<ms> [--templateId=lt-*]

  — ONE async call that renders the nameplate template (default

  lt-vox-marker

  ) AND places it as a transparent overlay. Returns

  { jobId }

  ;

  job.wait

  resolves once the region is placed. Pass

  --anchorSourceMs

  when atMs comes from a transcript word. The 10

  lt-*

  designs are in the template catalog; they also live in the editor's Lower 3rds tab. (The pre-2.95 CSS designs +

  --designType

  are gone; the verb now drives the motion-template pipeline.)
• Reset:

  project.clear-edits

  — one atomic call wipes every region + audio overlays + turns captions off (keeps clips, transcript, aspect ratio;

  --full=true

  also resets LUT/crop/webcam/wallpaper). Use it for "start over"; do NOT loop

  project.remove-region

  (that's for removing ONE region by

  --regionType

  +

  --regionId

  ).

Conflict-safe save

--expectedRevision

project.read

revision

{ code:"revision_conflict", expected, actual, onDiskProject }

project.add-*

Preview without exporting

preview.show --id

--atMs

--autoplay

preview.seek --atMs

preview.hide

preview.list

preview.show

project.open

Motion graphics

motion_render_html

Rules — recommendations, not rigid law (bias toward DOING)

1. motion_list

   FIRST, every time. Discover the catalog + each template's editable slots at runtime; don't generate from memory or copy a templateId out of an example.
2. Add a graphic on most meaningful beats — don't be shy. Name-drops, claims, numbers, lists, comparisons, tool/product mentions, section changes — each is a candidate. If a 5-minute video has ten clear points, ~ten graphics is reasonable. Under-graphicking is as much a failure as the wrong graphic — when a beat clearly wants a visual, add one.
3. Vary every scene — consistency comes from a shared SYSTEM, not a repeated layout. Hold ONE design system across the video (same palette, type family, motion vocabulary) so it feels cohesive — but give every scene a distinct composition. Reusing one layout (or one template) beat after beat with only the text swapped is the #1 way a video reads as a flat, templated slideshow — and it is fatal for a from-scratch / promo video where the graphics ARE the video (see

   reference/promo-and-mg-videos.md

   ). The ONLY repetition that belongs is a recurring functional overlay on real footage — e.g. the same lower-third name-plate style each time a person is introduced — which is a consistent repeated ELEMENT, not a repeated SCENE. (This replaces the earlier "repetition is good, reuse freely" guidance, which produced templated, monotonous output.)
4. The ONE hard line: never misuse a purpose-specific template. A few templates mean something — use them only when the content matches:

   stat-reveal

   → a real number (never a generic title) ·

   comparison

   → exactly two things contrasted ·

   flowchart

   → an actual sequence of steps ·

   key-takeaways

   → a list of points ·

   yt-lower-third

   → introducing a person/channel. Everything else (the title family,

   split-panel

   , the parallax reveals) is generic — usable on any beat — but still vary the composition beat to beat; don't lean on one look for the whole video (Rule §3).
5. Camera-only / imported footage → lead with a PREMIUM designed segment. When the clip's

   kind

   is

   "camera"

   (talking-head) or

   "upload"

   (imported), there's no screen to zoom into, so a static frame is what makes it look flat. A designed segment (host one half, a panel the other, via

   project.add-designed-segment

   ) is the highest-leverage fix and your default workhorse for explainer beats on this footage. Default to

   paper-panel

   or

   vox-side-panel

   — those are the featured, high-production panels that instantly level a video up. Use

   split-panel

   only as a plainer fallback or for variety, NOT as the go-to. Use the panels liberally (alternate side + content). For

   kind === "screen"

   , prefer cursor-telemetry zooms; don't split the frame.
6. Reach for the FEATURED (premium) templates first. Six templates are flagged top-tier in

   motion_list

   (

   featured: true

   ) — they're the most produced looks we ship, and on an "engaging / cinematic / level it up" brief you should prefer them over the plainer templates (

   split-panel

   , the basic title cards):
   • Strong workhorses:

     paper-panel

     ,

     vox-side-panel

     (side panels) and

     vox-marker

     (the highlighter headline reveal) — reach for these on explainer beats over real footage, but vary the side, content, and which one you use; don't repeat a single panel across the whole video (Rule §3).
   • Reach for the moment the content gives you the hook:

     vox-stat

     (a real number / metric),

     vox-quote

     (a quote or testimonial),

     vox-annotation

     (circle/callout a specific subject word). Don't force a purpose template where the content doesn't fit — Rule §4 still holds; a stat card with no number looks worse, not better. But when the hook IS there, take it: these elevate the video far more than a generic title card.
7. Text isn't your only option. When a beat wants a visual — logos for the tools being named, a product screenshot, an animated diagram — author a custom graphic (see "Authored graphics" below). Don't force every beat into a text template.

Selection guide (beat → template)

creator-card

transitions-3d

grain-overlay

transitions-destruction

caption-parallax-layers

paper-panel

vox-side-panel

split-panel

parallax-zoom

parallax-unzoom

yt-lower-third

stat-reveal

key-takeaways

comparison

flowchart

reference/whiteboard-style.md

caption-editorial-emphasis

kind === "camera"

caption-editorial-emphasis

Authored graphics — your repertoire is bigger than the gallery

motion.render-html

flowchart

• Animated diagram / flowchart — a data-driven SVG that builds as the speaker talks: boxes + connecting arrows that draw on in sequence, a branching tree, a request flowing through services, a layered architecture stack, a cyclic loop. For ANY "here's how it works / how the pieces fit" explainer beat that's more than a flat list of steps. Reveal each node/edge in time with the narration so the diagram assembles, not just appears.
• Chart / data viz — bars growing, a line plotting, a metric counting, a donut filling — when the point is a trend or a structural comparison, not a single headline number (use

  stat-reveal

  /

  vox-stat

  for one number).
• Logo / brand-card row — N rounded white cards, each a logo, popped in over the lower third. For "we use X, Y, Z", tool / partner / integration mentions (e.g. HeyGen · Claude Code · Hyperframes).
• Image / screenshot showcase — real images via

  --assets

  (product shots, UI grabs) in a framed or tilted card.
• Icon / emoji concept callout — a glyph + short label punched on a concept.
• Reuse a template's shell, swap text → graphics — take the look of an overlay template (the lower-band card, the side panel, the depth stack) and put logos / images / animated SVG / a diagram where the text would go.

reference/examples.md

reference/motion-philosophy.md

The workflow

# 1. ALWAYS discover first — templates + editable slots (runtime source of truth).
pandastudio motion.list --json          # MCP: motion_list

# 2. Pick the template that fits THIS beat (see the selection guide), then
#    render it with your own text/colors + a background mode.
#    Replace <TEMPLATE_ID> + slots with the chosen template's — do NOT
#    hardcode one template for every insert.
JOB=$(pandastudio motion.generate \
  --templateId=<TEMPLATE_ID> \
  --slots='{ ...the chosen template's slots from motion.list... }' \
  --aspectRatio=16:9 \
  --json | jq -r '.data.jobId')          # MCP: motion_generate
pandastudio job.wait --id="$JOB" --json

# 3. Add the rendered clip to the timeline (at the playhead by default).
pandastudio project.add-motion-graphic --id="$PROJECT" --fromJob="$JOB" --durationMs=4000

• Editable everything — every template's text, colors, list items, and images are

  slots

  ; pass only the ones you want to change, the rest use defaults.

  motion.list

  returns each template's slot keys, types (

  string

  /

  color

  /

  list

  /

  image

  ), and defaults.
• Image slots — a slot of type

  image

  takes an absolute file path to an image; the renderer stages the file into the render. Pass a project-media path or a generated image (e.g. from

  media.generate-image

  ). Two templates take an image:

  image-showcase

  (the dedicated one — a screenshot/photo on a 3D-tilted card; the go-to for highlighting a product page or app screen in a demo, 16:9 + 9:16) and

  vox-side-panel

  (a small photo in its specimen card). Example:

  --slots='{"image":"/abs/screenshot.png","headline":"Ship faster.","eyebrow":"SEE IT IN ACTION"}'

  on

  image-showcase

  .

• --fromJob

  not

  --file

  — pass the render

  jobId

  to the add tool; it resolves the path internally (hand-built paths truncate at the space in "Application Support" and silently fail).
• Placement —

  add-motion-graphic

  drops it at the playhead/end as an overlay. To re-time, pass

  atMs

  . Anchor to a transcript word with

  anchorSourceMs

  so it survives later transcript edits.
• Default SFX — every primitive that places an animated callout on the timeline now attaches a stinger by default so the agent's output sounds the way a hand-edited timeline does. Don't pass

  soundUrl

  to "set the default" — omit it. Override only when the user asks for a different sound, or pass

  null

  (MCP) to make the callout silent.

  Verb	Default	Notes
  project.add-motion-graphic	bundled:sound/mouse-click	New in v1.36.0; previously silent. Applies to every motion graphic — generated templates, custom MP4/WebM, designed-segment panels.
  project.add-designed-segment	bundled:sound/mouse-click	Inherits from add-motion-graphic.
  project.add-zoom	bundled:sound/swoosh-fast	Pre-existing.
  project.add-lower-third	bundled:sound/mouse-click	v2.96.0 — inherits the motion-graphic default.
  project.add-fx	none	FX overlays often have their own audio; left to the caller.

  Use

  asset.list-sounds

  to discover other bundled sound ids when swapping.

Background modes, designed segments, and the template catalog

--background

reference/motion-templates.md

Custom motion graphics — HTML authoring

motion.screenshot

render-html

concat

reference/motion-philosophy.md

reference/motion-recipes.md

reference/custom-html.md

🛑 Pass the HTML INLINE — never write a file first.

motion.render-html

(MCP:

motion_render_html

) accepts the whole composition as an inline

html

string parameter:

motion_render_html({ html: "<!doctype html>…", durationMs, aspectRatio })

. Author the entire HTML in your response and hand it straight to the

html

arg. Do NOT try to

write

/save the HTML to a path and pass

htmlPath

— the in-app PandaStudio agent has no

write

,

edit

, or

bash

tool (that's deliberate), so a "write the file" plan fails with a tool error.

htmlPath

is only for the CLI path, where a shell already wrote the file. Local assets (images/fonts) ride along via the

assets

param (absolute paths, referenced by basename in the HTML) — you never write them either. If you catch yourself reaching for a

write

tool to make a motion graphic, stop: pass

html

inline, or use a bundled template (

motion_generate

) instead.

Effects (FX) & transitions

project.add-transition

project.add-fx

reference/fx-transitions.md

Narration (voiceover) + B-roll generation

reference/media-generation.md

Faceless videos — image-driven, voiceover-led

🛑 THE ONE RULE THAT MATTERS: a faceless video is IMAGES, not text cards. Each scene MUST be a real image that SHOWS the beat — for "the cyclops", generate a one-eyed giant in a torch-lit cave, NOT a motion-graphic card with the word "Cyclops" on it. The words belong in the voiceover, never on screen. A deck of animated text titles ("Departure", "The Sirens", …) is the classic failure — it's a title slideshow, not a faceless video, and it looks cheap. Motion-graphic templates /

motion_render_html

text scenes are the WRONG tool here. Reach for them only for an optional title card or a lower-third stat, never as the scene visuals.

1. Break the topic into beats. One clear VISUAL idea per beat (~8–20s of narration each). A 3–5 min video is ~12–20 beats.
2. Write the narration line for the beat (what the voice says).
3. Generate the narration →

   media.generate-narration

   (local Kokoro by default). Keep each call to ONE beat (~40–60 words); Kokoro caps a single call around ~25s, so long scripts get truncated — narrate per beat, not the whole script at once. Grab its

   durationMs

   .
4. Generate the IMAGE for the beat →

   media.generate-image

   with a vivid, LITERAL visual prompt of the scene (subject, setting, lighting, mood — no on-screen words). For 16:9 generate

   3:2

   ; for 9:16 generate

   2:3

   . Keep one art style across every image (state it in every prompt, e.g. "cinematic oil-painting, warm dramatic light") so the 12+ images read as ONE film, not random stock.
5. Ken-Burns the image to a clip sized to the narration →

   media.image-to-video --imagePath=<img> --durationMs=<beat narration + ~400ms> --aspectRatio=9:16 --zoom=in

   (or

   --zoom=out

   ). This is the NATIVE one-call path — FFmpeg pans/zooms the still into an MP4 and returns

   videoPath

   . Alternate

   in

   /

   out

   across beats so the cut breathes; a still held flat reads as a dead slideshow. (Only reach for the heavier

   motion_render_html

   Ken-Burns shell when you need a bespoke CSS treatment — grain, parallax layers, vignette animation — that plain pan/zoom can't do.)
6. Add the clip to the main track in order →

   project.add-clip --media=<videoPath>

   (append). The images-in-motion ARE the video.
7. Lay the narration under it →

   project.add-audio --audioPath=… --startMs=<beat start>

   (beat start = sum of prior beats' durations).
8. Polish (optional but expected): a quiet music bed (

   asset.list-music

   →

   project.add-audio

   at low volume, e.g. 0.15), burned captions (

   caption.toggle

   / caption template) since faceless viewers often watch muted, and maybe ONE title card at the top.
9. Export →

   export.start

   (16:9 for YouTube, 9:16 for a faceless short).

# For one beat — repeat, tracking the running start offset for narration.
IMG=$(pandastudio media.generate-image --prompt="a one-eyed giant in a torch-lit cave, cinematic oil-painting, warm dramatic light" --aspectRatio=2:3 --json | jq -r '.data.imagePath')
NARR=$(pandastudio media.generate-narration --text="In the cave of the cyclops, Odysseus faced a giant who ate men whole." --voice=am_michael --json)
DUR=$(echo "$NARR" | jq -r '.data.durationMs'); WAV=$(echo "$NARR" | jq -r '.data.audioPath')
CLIP=$(pandastudio media.image-to-video --imagePath="$IMG" --durationMs=$((DUR + 400)) --aspectRatio=9:16 --zoom=in --json | jq -r '.data.videoPath')
pandastudio project.add-clip --id="$PID" --media="$CLIP"
pandastudio project.add-audio --id="$PID" --audioPath="$WAV" --startMs=$OFFSET --endMs=$((OFFSET + DUR)) --volume=1
# OFFSET += clip duration (the add-clip return / project.read clip durations) for the next beat.

project.read

DUR + 400

Avatar (talking-head) videos — HeyGen

media.list-avatars

media.list-avatar-voices

generate-avatar-video

{ jobId }

job.wait

project.add-clip

# 1. Find the avatar (the user's clone) and a voice.
AVATAR=$(pandastudio media.list-avatars --json | jq -r '.data.avatars[0].avatarId')
VOICE=$(pandastudio media.list-avatar-voices --json | jq -r '.data.voices[0].voiceId')

# 2. Kick off the render (16:9 YouTube by default; 9:16 for Shorts).
JOB=$(pandastudio media.generate-avatar-video \
  --avatarId="$AVATAR" --voiceId="$VOICE" \
  --script="Hey everyone, in today's video…" \
  --aspectRatio=16:9 --resolution=720p \
  --json | jq -r '.data.jobId')

# 3. Wait for the server-side render (minutes) — poll with a long timeout.
VIDEO=$(pandastudio job.wait --id="$JOB" --timeoutMs=900000 --json | jq -r '.data.job.result.videoPath')

# 4. Add it to the timeline like any recording; edit/caption/export as normal.
pandastudio project.add-clip --id="$PROJECT" --path="$VIDEO"

avatarId

voiceId

script

avatarKind

avatar

talking_photo

aspectRatio

16:9

9:16

1:1

resolution

720p

1080p

speed

backgroundColor

outputName

job.wait

timedOut: true

Transcript-based editing — PandaStudio's signature feature

The full edit loop

# 0. Check which clips still need processing (avoids clobbering in-app edits)
STATE=$(pandastudio project.read --id=$ID --json | jq '.data.clipStates')
# clipStates: [{ clipId, transcribed, wordCount, audioCleaned }, ...]

# 1. Transcribe only clips that don't already have a transcript
#    (if all are transcribed, skip this step entirely)
JOB=$(pandastudio transcript.transcribe --id=$ID --json | jq -r '.data.jobId')
pandastudio job.wait --id=$JOB --timeoutMs=300000 --json

# 2. Pull the merged transcript — every word with edited-time start/end
pandastudio transcript.get --id=$ID --json | jq '.data.words[0:20]'

# 3a. AUTO: drop every "um" / "uh" / "you know" + immediate repeats
pandastudio transcript.remove-fillers --id=$ID --json
# → returns { removedCount, fillersRemoved, repeatsRemoved, trimsAdded }

# 3b. Remove silences (default ≥600ms = the UI button; covers leading/trailing/between-word)
#     Omit --thresholdMs to use the 600ms default; only pass it to override.
pandastudio transcript.remove-silences --id=$ID --json
# → returns { removedCount, totalTrimmedMs }

# 3c. Fix STT errors — NEVER use project.read → JSON mutation → project.save for this.
#     find-replace patches the word text in-place and preserves timing.
pandastudio transcript.find-replace --id=$ID --find="RightPanda" --replace="WritePanda" --json
# → returns { replacedCount, wordsPatched }
#  Matcher caveats:
#  - Matching is case-insensitive; punctuation is ignored on both sides
#    (`--find="graph, crew"` matches "graph crew").
#  - DIGITS are significant when the find phrase contains them:
#    `--find="try30"` matches only the merged STT token "try30", never a plain
#    "try". A letters-only find still ignores transcript-side digits
#    (`--find="than"` also matches "than60").
#  - A multi-word find ALSO matches a single merged STT token: `--find="Wispr
#    Flow"` hits the one token "Wispr Flow" (STT often emits multi-word brand
#    names as one token), and `--find="of $499"` hits the merged "of$499".
#  - A find that exactly equals a token's raw text always matches, so
#    space/digit/punctuation-bearing tokens — even pure numbers like "30%" —
#    are all targetable verbatim.
#  - A multi-word `--find` collapses to the FIRST word's slot: that word's text
#    becomes `--replace`, the other matched words are blanked. The replacement is
#    the literal `--replace` string, so include any punctuation you want kept
#    (the original word's trailing comma/period is not auto-preserved).

# 3d. SURGICAL: delete specific words by ID
pandastudio transcript.delete-words --id=$ID --wordIds='["clip-1:w-42","clip-1:w-43"]' --json

# 3e. PHRASE search → bulk delete
WORDS=$(pandastudio transcript.search --id=$ID --query="this is a test" --json \
  | jq -c '[.data.matches[].wordIds | .[]]')
pandastudio transcript.delete-words --id=$ID --wordIds="$WORDS" --json

# 3f. RESTORE previously deleted words (undo a delete / filler / repeat removal).
#     Removes the trim region(s) covering those words; silence trims are left
#     untouched. Mirrors the editor's right-click → Restore on struck-through words.
pandastudio transcript.restore-words --id=$ID --wordIds='["clip-1:w-42","clip-1:w-43"]' --json

transcript.get

trimsAdded

transcript.get

transcript.find-replace

motion.generate

llm.generate-title

Audio cleanup, background audio, music, and color grading

audio.clean

project.set-clip-volume

reference/audio-color-music.md

Visual edits — zooms, trims, speed, crop, layouts

--anchorSourceMs

reference/visual-edits.md

Captions, AI metadata, thumbnails

reference/captions-metadata.md

Export — produce the final MP4

job.wait

JOB=$(pandastudio export.start --id=$ID --quality=high --json \
  | jq -r '.data.jobId')

# Watch progress (server-side block; returns when done or 5min timeout)
pandastudio job.wait --id=$JOB --timeoutMs=600000 --json | jq '.data.job'
# → status: "succeeded", result: { outputPath, durationMs, width, height, frameRate }

draft

standard

high

ultra

set-aspect-ratio

--outputPath=/somewhere/file.mp4

motion.generate

motion.render-html

motion.render-html --transparent

export.start

project.add-motion-graphic

Video editing playbook — end-to-end recipe (per destination)

Destination profiles (the source of truth)

youtube-long

shorts

linkedin

loom

none

none

modernVibrant

naturalEnhanced

minimal

neon

minimal

minimal

high

high

high

standard

youtube-long

modernVibrant

cinematicTealOrange

naturalEnhanced

moodyDark

warmSunset

Creator-style overrides (when the user names a style)

youtube-long

modernVibrant

bold

youtube-long

modernVibrant

cinematicTealOrange

minimal

youtube-long

warmSunset

neon

youtube-long

naturalEnhanced

minimal

power2.inOut

stagger: 0.15

youtube-long

cinematicTealOrange

minimal

reference/motion-philosophy.md

• chrome gradient are mandatory regardless of named style.

Anchoring — every transcript-derived region MUST be anchored

transcript.remove-fillers

transcript.remove-silences

transcript.delete-words

transcript.find-replace

startMs

endMs

--anchorSourceMs

atMs

startMs

--anchorSourceMs

v1.35.0+: every region is auto-anchored on creation, even without

--anchorSourceMs

. The primitive now back-computes a source-time anchor from the resolved edited

atMs

(via

editedToSource

) whenever the caller doesn't supply one explicitly. Regions placed by direct atMs survive subsequent silence removal, filler removal, and word deletion just like transcript-anchored ones. Still pass

--anchorSourceMs

when you have a transcript word in hand — it makes the agent's intent self-documenting and avoids a two-step round trip through edited time. But the days of "I placed an overlay, then trimmed silences, now it's playing at the wrong moment" are over for any project saved by v1.35.0 or later. Legacy projects (schemaVersion < 4) are auto-migrated on the first mutation: every anchorless region gets a source anchor back-filled at its current position.

type: "free"

anchors are preserved as opt-outs.

project.add-zoom

--anchorSourceMs

--anchorSourceEndMs

project.add-motion-graphic

--anchorSourceMs

--anchorSourceEndMs

project.add-lower-third

--anchorSourceMs

--anchorSourceEndMs

project.add-annotation

--anchorSourceMs

--anchorSourceEndMs

project.add-audio

--anchorSourceMs

--anchorSourceEndMs

sourceDurationMs

--anchorSourceMs

timeline.source-to-edited

The runbook (ordered — do not rearrange)

# 0. Resolve the project + destination profile
ID=$(pandastudio project.current --json | jq -r '.data.project.id // empty')
[ -z "$ID" ] && ID=$(pandastudio project.list --json | jq -r '.data.projects[0].id')

# $PROFILE is set from HARD-GATE step 1: youtube-long | shorts | linkedin | loom
# $ASPECT is derived from the profile:
#   youtube-long | linkedin | loom → 16:9
#   shorts                         → 9:16
pandastudio project.set-aspect-ratio --id=$ID --aspect=$ASPECT

# 1. PACING — the default cleanup pipeline (see "default edit pipeline" in
#    Editorial decisions for the mandatory steps + report-counts rule). Run it
#    in full — none of these is optional. audio.clean fires async; wait on it
#    before export (step 5). First read pulls the transcript (needed for step 2);
#    later reads pass --includeTranscript=false.
pandastudio project.read --id=$ID --json
pandastudio transcript.transcribe --id=$ID               # skip if transcribed
AUDIO_CLEAN_JOB=$(pandastudio audio.clean --id=$ID --json | jq -r '.data.jobId // empty')  # async
pandastudio transcript.remove-fillers --id=$ID           # fillers + immediate repeats
# Bad takes + repeated phrases: find-issues is READ-ONLY — you MUST then delete
# the discarded wordIds (keep the most recent take). Skipping the delete cuts nothing.
ISSUES=$(pandastudio transcript.find-issues --id=$ID --json | jq -c '.data.issues')
DROP=$(echo "$ISSUES" | jq -c '[.[] | select(.type=="duplicate-take" or .type=="adjacent-repeat") | .wordIds[]]')
[ "$DROP" != "[]" ] && pandastudio transcript.delete-words --id=$ID --wordIds="$DROP"
SILENCE_MS=$([ "$PROFILE" = "loom" ] && echo 300 || echo 500)
pandastudio transcript.remove-silences --id=$ID --thresholdMs=$SILENCE_MS   # NEVER skip; arg is thresholdMs (500ms = UI default)

# 2. EMPHASIS — zooms (skip for `loom`). Cadence comes from the profile table.
#
#    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#    HARD RULE #1 — DO NOT add zooms to screen-share clips.
#    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#    PandaStudio auto-adds zooms to screen-share clips based on cursor
#    telemetry captured during recording. Adding more on top = stacked
#    zooms on the same moments, visual chaos.
#
#    For each clip returned by project.read:
#      - If clip.webcamPath is present  → "both" mode (screen + PiP
#        webcam). Telemetry zooms ALREADY exist on this clip. **SKIP.**
#      - If the clip is pure camera (no webcamPath AND mediaPath is a
#        camera recording) → safe to add zooms on emphasis.
#      - If screen-only (no webcamPath, mediaPath is screen) → telemetry
#        still exists, zooms are auto-added. **SKIP.**
#
#    Heuristic: if project.read returns existing zoomRegions for a clip
#    whose webcamPath is set, those are telemetry-based — stay OUT of
#    that clip's zoom space entirely. Only author zooms on pure-camera
#    clips (webcamPath absent, no pre-existing zoom regions).
#
#    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#    HARD RULE #2 — Zoom duration floor is 6 seconds, NOT 1.5–3 seconds.
#    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#    Premium YouTube zooms ride through a complete thought or cut. A 1.5s
#    or 3s zoom reads as a twitch. Defaults:
#      - Emphasis punch-in zoom (camera pulls in on a word/claim):
#        durationMs=6000 to 8000  (was 1500 — that was wrong)
#      - Sustained / held zoom (camera pulls in on a subject and
#        stays for the whole sub-topic):
#        durationMs=10000 to 20000
#      - Reveal moment (dramatic, loud SFX): durationMs=6000 minimum
#    Depth 3 (modest) for talking-head emphasis; depth 5 only for
#    dramatic reveal beats. Don't stack multiple zooms inside 5s of each
#    other — leaves no time to settle.
#
#    Shot selection: scan the transcript for punchy claims, specific
#    numbers, opinionated statements ("the best", "this changed
#    everything", "most people don't know"), moments of pivot ("and
#    now", "finally", "but here's the thing"). Aim for the user's
#    eyes to want to lean in. NOT every UI-verb word ("click", "select")
#    — that was the old rule, it's wrong for engagement-style edits.
#
#    CRITICAL: ALWAYS pass --anchorSourceMs when atMs comes from a transcript
#    word. Without it, the zoom drifts off the moment as soon as ANY trim is
#    added — and step 1 always adds trims (remove-fillers, remove-silences).
#    The anchor binds the zoom to the source recording moment so it
#    re-anchors automatically on every trim/speed change.

# Emphasis punch-in — modest scale, held through the thought
pandastudio project.add-zoom --id=$ID --clipId=$CLIP_ID \
  --atMs=<wordStartMs> --anchorSourceMs=<wordStartMs> \
  --durationMs=7000 --depth=3

# Sustained held zoom — reframe on a topic and stay for the full section
pandastudio project.add-zoom --id=$ID --clipId=$CLIP_ID \
  --atMs=<sectionStartMs> --anchorSourceMs=<sectionStartMs> \
  --durationMs=15000 --depth=3

# Reveal moment (dramatic, with SFX). Use SPARINGLY — 1-2 per video max.
pandastudio project.add-zoom --id=$ID --clipId=$CLIP_ID \
  --atMs=<ms> --anchorSourceMs=<ms> \
  --durationMs=6000 --depth=5 \
  --soundUrl=bundled:sound/dramatic-whoosh --soundVolume=0.7

# 3. POLISH — skip sections by profile:
#    - `shorts`: no lower thirds (tight vertical frame)
#    - `loom`:   skip 3b, 3c entirely
#    NOTE: 3a (intro/outro) and 3d (background music) are OPT-IN — run them
#    ONLY when the user explicitly asked for an intro/outro or music. They are
#    NOT part of the default "edit my video" pass for ANY profile.

# 3a. Intro / outro card — ONLY IF THE USER EXPLICITLY ASKED for one
# ("add an intro", "add an outro card", "open with a title"). Do NOT add
# one on a plain "edit this" request. When asked: fastest is the
# `creator-card` template via motion.generate; author custom HTML
# (reference/motion-philosophy.md §7) only for a bespoke intro.
if [ "$USER_ASKED_FOR_INTRO" = "1" ]; then
  JOB=$(pandastudio motion.render-html \
    --htmlPath=/tmp/intro-title.html \
    --durationMs=3000 --json | jq -r '.data.jobId')
  FILE=$(pandastudio job.wait --id=$JOB --json | jq -r '.data.job.result.outputPath')
  pandastudio project.add-motion-graphic --id=$ID --file=$FILE --durationMs=3000 --atMs=0
fi

# 3b. Lower third at first mention of a person/product (NOT shorts/loom)
#     One call renders the lt-* nameplate AND places it (async job).
if [ "$PROFILE" = "youtube-long" ] || [ "$PROFILE" = "linkedin" ]; then
  JOB=$(pandastudio project.add-lower-third --id=$ID \
    --name="<name>" --title="<role>" --atMs=<ms> --anchorSourceMs=<ms> \
    --json | jq -r '.data.jobId')
  pandastudio job.wait --id=$JOB
fi

# 3c. LUT (use the profile table. For youtube-long, use content-type sub-table.)
#     Apply to every clip via project.set-clip-lut.
#     Skip entirely for `loom`.

# 3d. Background music — ONLY IF THE USER EXPLICITLY ASKED for music
# ("add background music", "put a track under it"). Do NOT add music on a
# plain "edit this" request. When asked, use the profile volume (youtube-long
# 0.15, shorts 0.30) and let the user pick / swap the track.
if [ "$USER_ASKED_FOR_MUSIC" = "1" ]; then
  VOL=$([ "$PROFILE" = "shorts" ] && echo 0.30 || echo 0.15)
  pandastudio project.add-audio --id=$ID \
    --path=bundled:music/corporate-underscore --volume=$VOL --fadeIn=1000 --fadeOut=2000
fi

# 4. ACCESSIBILITY — captions per profile
if [ "$PROFILE" != "loom" ]; then
  pandastudio caption.toggle --id=$ID --enabled=true
  TEMPLATE=$(case "$PROFILE" in
    shorts)       echo "neon";;
    linkedin)     echo "minimal";;
    youtube-long) echo "bold";;
  esac)
  pandastudio caption.set-template --id=$ID --templateId=$TEMPLATE
  # ALL CAPS look (common for shorts): force uppercase on any template.
  # pandastudio caption.set-style --id=$ID --uppercase=true
  # (uppercase=false turns OFF a template that ships caps, e.g. editorial)

  # HIDE captions for part of the video. Captions are ON everywhere once
  # enabled, so these carve out exceptions — use when subtitles would cover
  # something on screen (a UI demo, on-screen text, a lower third).
  # Times are EDITED-timeline ms. Overlapping regions are fine.
  # pandastudio project.add-caption-region --id=$ID --atMs=12000 --durationMs=5000
  # Remove one (ids come from project.read → editor.captionRegions[].id):
  # pandastudio project.remove-caption-region --id=$ID --regionId=caption-hide-1
fi

# MUTE part of the video's audio. Silences the MAIN voice/screen track over a
# stretch — background music and SFX overlays keep playing (same as the editor).
# Times are EDITED-timeline ms; durationMs controls how much is silenced.
# Use for a cough, a name, or dead air you want silent WITHOUT deleting footage
# (deleting would also cut the video; mute keeps the picture, drops the sound).
# Overlapping regions are fine. To fully cut both picture and sound, use a trim.
# pandastudio project.add-mute-region --id=$ID --atMs=12000 --durationMs=3000
# Remove one (ids come from project.read → editor.muteRegions[].id):
# pandastudio project.remove-mute-region --id=$ID --regionId=mute-1

# 4.5. VERIFY FRAMES — MANDATORY. Never export without looking.
# Run motion.verify-frames on every rendered motion-graphic MP4 AND on
# a draft pass of the full composition (preview.show, then extract
# frames at hero timestamps). READ each PNG as a multimodal image and
# confirm against the motion-philosophy §4 pre-flight checklist:
# - no cropped faces / text overflow / blank frames
# - captions on the right word
# - no MG covers host face (Mode C) or screen zone (Mode B)
# - chrome-gradient text is actually rendering (not flat white)
# - grid + vignette + grain visible on every hero beat
# If any frame fails, iterate and re-verify. Do NOT skip this step
# even when "it's just a quick edit" — this is what separates
# ships-it-works-ish from ships-it-looks-good.
#
# 🛑 VERIFICATION IS A SEPARATE, BEST-EFFORT STEP — IT NEVER "FAILS" THE EDIT.
# Every project.* mutation (add-clip, add-motion-graphic, add-audio, etc.)
# COMMITS to the .pandastudio file the instant its tool returns ok. The
# verification pass (render a frame, then READ the PNG as a multimodal image)
# happens AFTER and is a QUALITY check, not part of the edit. So:
#   • Order matters: make the mutating edit FIRST, confirm ok, THEN verify.
#     The edit is already durable before you ever read a frame.
#   • If the frame-read step fails — model times out on the image, "no output
#     for N minutes", rate-limit, "tool read failed" — the EDIT STILL LANDED.
#     Do NOT report the task as failed. Report: "Done — <edit> is on the
#     timeline. I couldn't finish the visual check (model didn't respond);
#     retry the check or switch models." Presenting a committed edit as a
#     failure because a follow-up vision read hung is the wrong outcome.
#   • Keep the read LIGHT so it doesn't hang the model: verify a SINGLE
#     render-frame (one PNG) at the hero timestamp, NOT a big multi-frame
#     render-sheet. One small image is a cheap vision call; a large contact
#     sheet is the read that most often times the model out.
pandastudio preview.show --id=$ID   # let the project render a full draft
# Then verify each generated motion-graphic MP4 at its hero timestamps:
# pandastudio motion.verify-frames --videoPath=/tmp/motion-intro.mp4 \
#   --timestamps='[0.3,1.0,1.8,2.7]' --json
# Read every returned frame. If any fail, fix + re-render + re-verify.

# 5. EXPORT — quality per profile. Only run AFTER verify-frames passes.
# First: block on the audio.clean job that's been running in the
# background since step 1. By now it's almost certainly done (30-60s
# vs the ~90s+ the rest of the work took), so this resolves instantly.
[ -n "$AUDIO_CLEAN_JOB" ] && pandastudio job.wait --id="$AUDIO_CLEAN_JOB"
QUALITY=$([ "$PROFILE" = "loom" ] && echo "standard" || echo "high")
pandastudio export.start --id=$ID --quality=$QUALITY --json | jq -r '.data.jobId' | \
  xargs -I {} pandastudio job.wait --id={}