🛑 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.

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.

undefined

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)

undefined

STOP. Do not silently switch. Ask the user.

"This project lives in workspace '$WS_NAME', current is '<X>' — switch?"

**Why this matters:** `project.read` happily resolves a project from any workspace, but `export.publish-youtube`, `media.generate-image`, `export.generate-thumbnail`, and `youtube.list-accounts` all use the **active workspace's** credentials. Editing project A while workspace B is active and then publishing → the video lands on Client B's YouTube channel. **The worst kind of mistake.**

**Every `project.read` response now also carries the workspace fields** (`workspaceId`, `workspaceName`, `isInActiveWorkspace`) — so even if you skipped `project.locate`, you can still detect the mismatch from the read response and bail before mutating anything. But `project.locate` is cheaper (no project body) and clearer in intent — call it first when working from a bare id.

**Hard rule: never call `export.publish-youtube` without confirming `isInActiveWorkspace === true` for the project being published.** If the user asks you to publish a project in a different workspace, walk them through the explicit switch:

```bash
pandastudio workspace.switch --id=$TARGET_WS --json

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.

undefined

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.)

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

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

• 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)

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

   .

• 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

  .

{ 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

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

• 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.

• 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

  ).

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.

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

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.

🛑 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).

undefined

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.

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