Set picture card
set_picture_cardPROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Compose FOOTAGE ONLY as a rounded picture card during start/end program seconds. Captions, designed type and branding stay independent and sharp. Calling it again with an existing id changes that card: every argument you leave out keeps the card's current value (box, fit, entrance/exit, canvas, framing), so id/start/end alone re-times it; source='auto' frames the speaker again. box=[left,top,right,bottom] on the output canvas; radius 0-.25 of card short side; border 0-.015 of canvas short side. entrance/exit none, fade, lift (restrained settle), or reveal (picture opens/closes inside its rounded window): an animated end DISSOLVES the whole card with the full-frame shot under it — never a frame of bare canvas; a source card that opens or closes on a cut cuts in with its panels populated ('none' says so outright). duration_s .12-1.2. Windows must not overlap. Inspect entry, settle, exit and the speaker framing. Rounded cards are one purposeful format, not a quota. FOOTAGE — source: the card takes its picture straight from the full SOURCE frame (enlarged once, at most 2x — up to 3x only so a small archival face reads at ~15% of the frame, with lanczos, light sharpening and the card's grain over it), never from the already-cropped 9:16 program. Default 'auto' frames the speaker as a medium close-up (>=8% headroom above the head) from a face track measured on the window's kept footage (4 fps) and FOLLOWS a speaker who moves inside a shot: the card holds STILL while they sway and glides (eased, speed-limited, never a whip) only when a still framing would cut the head; a re-aim that can land on a jump cut happens on the cut; every camera shot gets its own framing and nothing moves across a cut (the result says how many shots follow). follow=false keeps one still framing per shot. Without a measurable track it frames every measured position of the head (index boxes) and re-aims on the cut. On a source below 720p 'auto' shows the WHOLE frame (contain: the box shrinks to the footage's aspect, edge blanking trimmed; never a 3.7x crop) — except ONE 4:3 archival speaker (no two-shot) in a 9:16 frame, face measured, no box: a full-width near-square window (y .27-.70, ~43% of the frame: the most that keeps the headline band above and a whole caption band below) framed on the speaker; fit='crop' frames the speaker as a medium close-up in any box and follows them, fit='pad' always shows the whole frame. A thin band of a pillar or frame edge along an 'auto' card's or speaker panel's edge (a straight high-contrast source edge within 8% of it) is slid off once per held framing (never a glide), else named (EDGE SLIVER). 'full' = the whole source frame; [left,top,right,bottom] = that rect of the SOURCE frame (look_at gives the fractions); 'inset' = the burned-in screen / picture-in-picture box measured in the window's footage (four straight edges, the same place across frames), shown WHOLE and fitted (a screenshot the host reads from is legible this way, never sliced by a 9:16 crop; auto_reframe names the box and this call when it finds one). Alone it shows no face: over more than a second of speech the result says NO FACE ON SCREEN — stack the speaker over it with panels instead (below); 'program' = the composed program picture (frame.picture region) as before. fit: 'crop' keeps the box and trims the source rect to it; 'pad' keeps the whole rect and shrinks the box around it (the default for 'full' and explicit rects). The result reports the rect, box, enlargement and headroom. One rect frames ONE shot: an 'auto' window across a camera cut the reframe re-aims on (focus_track) frames each shot itself; across any other cut to a differently framed shot it keeps the program picture (it follows the reframe) and says so — give each shot its own card for source framing. Spliced inserts inside a source card play full-frame and the card returns after them. SPEAKER + EVIDENCE — panels: 2-3 {box, source[, fit]} shown at once over the window, each box its own rounded window on one canvas, each source its own region of the SAME source frame: e.g. [{box:[.04,.13,.96,.475], source:'auto'} (the speaker), {box:[.04,.54,.96,.93], source:'inset'} (the screen/study/inset they show — or its rect)]. Use it when the source shows a speaker beside a picture-in-picture screen, document or browser that a 9:16 crop would either drop or slice; never crop to the evidence and lose the speaker for seconds. A SPEAKER panel ('auto', or a crop rect holding most of the measured face) is solved from the face track (measured into its shot, so a profile turn is carried): the whole head with chin and hair margins, lead room where they look, every face box >= 8% of the panel inside each edge first, burned-in screen boxes kept out wherever such a framing can (where the box touches the face the face wins: the head keeps its composition, the corner that shows is never a thin strip and is softened only away from the face, and the result measures a speaker card alone and the speaker full-bleed against the stack and names the cleanest: BETTER LAYOUT / LAYOUT (measured)), following a speaker who moves; a given rect that cuts the face is moved and grown only as far as it must. Stacked panels keep a caption band of >= .065 of the frame height between them (a narrower gap is opened, and said). Panel boxes must not overlap; zooms do not play inside a stack. CANVAS — omitted, it is a dark canvas sampled from the footage (its hue, near-black at the edges, vignette; film grain on sources below 720p). Name one to override: background_style 'radial_gradient' glows from background behind the card out to background_color2, 'vertical_gradient' runs background (top) to background_color2 (bottom); a bare background is a flat colour; 'blur' fills the frame with the card's own footage blurred and darkened (background_dim 0-.9, default .45) — HD footage only: on a low-resolution source it reads as a muddy smear. vignette 0-1 darkens the edges (.4). grain 0-1 adds animated film grain: .25 is the references' texture. Grain is a FINAL-export finish with a cliff — the encoder smooths it out of previews and out of any value below ~.2 entirely, and where it survives it costs ~3-4x the file size and ~+0.5s of export per 8s of card at 1080x1920. Both only on the backdrop (grain also over footage enlarged past 2x). background_color2 alone implies vertical_gradient; a knob the chosen style cannot draw (color2 on blur/solid, background_dim off blur) is rejected.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| box | No | ||
| end | Yes | ||
| fit | No | ||
| exit | No | ||
| grain | No | ||
| start | Yes | ||
| border | No | ||
| follow | No | ||
| panels | No | ||
| radius | No | ||
| shadow | No | ||
| source | No | ||
| entrance | No | ||
| vignette | No | ||
| background | No | ||
| duration_s | No | ||
| project_id | Yes | Required immutable scope for this call. Copy the id from list_projects/open_project/project_state; the active-project pointer is never used to guess. | |
| border_color | No | ||
| motion_motif | No | ||
| background_dim | No | ||
| background_style | No | ||
| background_color2 | No |