Pireel Studio basics

Pireel Studio (https://pireel.com) is a video editor for talking-head videos (any aspect — the canvas follows the source footage). Through the pireel MCP server your tools edit the composition live in an open studio browser tab: the timeline updates on screen as you work. You can open that tab YOURSELF: call create_browser_handoff and open the returned url with your OWN built-in/embedded browser tool — the browser whose pages you can see and control. NEVER open it via the OS open command or the user's default browser: the ticket is single-use, so spending it on a surface you cannot see wastes it and leaves you blind. The tab is pre-signed-in (no login screen) and becomes the live editing surface. Surface the editor early on substantial work: the user watches every edit land in real time. The handoff URL expires in ~60s — open it immediately, never print it to the user (it carries a sign-in ticket; share plain https://pireel.com/zh/studio/<id> links instead).

The MCP endpoint is https://pireel.com/api/studio/mcp. Auth is OAuth — the agent's mcp login / first-use flow opens the browser; there are no API keys. On HTTP 401, re-run the OAuth login.

The composition: two kinds of elements

• Overlay blocks — designed graphic fragments laid over the video: metric cards, comparisons, charts, flow/structure diagrams, KPIs, callouts, titles. Designed graphics are the main event of a Pireel video. Blocks marked 待配图 in state are placeholders: empty slots dropped by lay_out, waiting to be filled with a generated graphic.
• Video shots — segments of the talking-head clip, each with a framing treatment: full (full screen), punch-in (zoom for emphasis), corner-br / corner-tl (shrink to a corner to make room for graphics), split-l / split-r (video takes one half, graphics take the other). Shot boundaries are hard jump cuts; visual variety comes from framing changes, not transitions.

The two clocks (get this wrong and cuts land in the wrong place)

1. Source seconds — a source file's own clock. The spoken transcript (read_script / extract_asr) is timestamped in MAIN-source seconds, and those timestamps never shift when the video is cut. Fetch the transcript once; it stays valid the whole session.
2. Edited seconds — the final-timeline clock. cut_range, split_shot, trim_shot, move_block, resize_block, atSec parameters all address THIS clock. Every cut shifts later content earlier.

cut_narration is the bridge: pass it transcript (source-second) ranges and it converts to the edited timeline itself, cuts the footage, compresses overlays, and re-lays captions.

Shots tagged [clip X] in state were inserted from a different source file: their src times belong to that file, not the narration transcript. Transcript-based cutting never touches them — cut inside them with cut_range (edited seconds) or drop them with delete_shot.