{"id":85147,"plugin_id":"plugin_asdk_app_6a18d4c190a0819186e6b129a09e931e","kind":"skill","collection_source":"plugin_package","comparison_source":"plugin_package","observed_at":"2026-11-07T00:09:10.840Z","digest":"2b0b62b0c15f8d39af05fcd84cd3389ae920873dba1c11b32ecb78e4912457e6","against":78692,"payload":{"description":"Put the user's own footage in a frame of another shape - landscape to a vertical reel, say - with the camera on the right person - measured once per source, checked and corrected by hand where the tool fails (a subject cut off, the wrong speaker, a late or jittery camera), then cut into a reel with scripts/reel_cut.py, so any re-cut is free. Use whenever footage is reframed or a reframe is checked - a reel or short from the user's own videos and photos, a landscape video reposted as a vertical one - or when a reframe or vertical crop misframes the subject.","included_files":[{"relative_path":"scripts/reel_cut.py","size_in_bytes":26168},{"relative_path":"scripts/reframe_fix.py","size_in_bytes":35018},{"relative_path":"scripts/split_layout.py","size_in_bytes":9975}],"name":"footage-reframing","skill_md_contents":"---\nname: footage-reframing\ndescription: Put the user's own footage in a frame of another shape - landscape to a vertical reel, say - with the camera on the right person - measured once per source, checked and corrected by hand where the tool fails (a subject cut off, the wrong speaker, a late or jittery camera), then cut into a reel with scripts/reel_cut.py, so any re-cut is free. Use whenever footage is reframed or a reframe is checked - a reel or short from the user's own videos and photos, a landscape video reposted as a vertical one - or when a reframe or vertical crop misframes the subject.\n---\n\n# Reframe\n\nA vertical crop of a landscape shot keeps about a third of its width. Centred, that third is often\na wall beside the speaker. So the subject's position is measured, never guessed, then checked and\ncorrected where the tool got it wrong, and the clips are cut from that path by a script.\n\nThis skill owns all reframing: the tool call, the check, the correction and the cut. A use case\nthat reframes loads it and keeps no reframing method of its own.\n\n## Measure each source once\n\n1. **Which sources need it.** A video whose shape differs from the reel's, with a person or\n   another subject in it. A source already the reel's shape, and one with nothing to follow (a\n   title card, a full-frame graphic, a wide shot with no subject), needs no reframe: its clips are\n   `full`.\n2. **Reframe it.** `picsart_media_reframe_video` with the source's Picsart-hosted `url` and the\n   reel's `aspect_ratio`. It replies with a job receipt, followed as picsart-video-rules says. It\n   takes minutes, so post a line first, and\n   start it as soon as the source and the reel's shape are known. It does not need the cut.\n   A local file or a Drive file is used by its Picsart-hosted URL, as picsart-video-rules says\n   for asset URLs; every check below reads that same URL.\n3. **Keep the result verbatim**, the whole reply: as `reframe-<source id>.json` where you run\n   commands, else in the project record. Never pass\n   `scene` and `layer_id` for this: that mode refuses a trim, and every call measures again.\n\n**One reframe per source and shape, for the whole session.** The result covers the source's whole\nlength, so every clip, every re-cut and every new running order is windowed from it by the script.\nMeasuring again for a new cut repeats minutes of work and changes nothing. Its description says\nwhether it charges credits. If it does, it is a SPEND (picsart-video-rules): quote every source's reframe in\none go.\n\nIf it fails, retry it once: it is flaky, and a later try often succeeds. If it fails again, stop\nand say the reframing is unavailable right now, with what is ready. Never estimate the subject's\nposition from a description of the video, and never frame a talking person `full` as a stand-in.\n\n## Check and correct\n\nThe tool follows a face, or else the most salient region, frame by frame. It does not know who is\nspeaking, what the story needs kept, or where the platform's buttons sit. **Check every reframe\nbefore cutting from it, and correct what fails.** Never pass a reframe on unseen, and never measure\nagain hoping for a better one: the same footage gives the same path.\n\n| Failure | What it looks like | Finding |\n|---|---|---|\n| Subject cut off | a head, a chin or the hands past the frame's edge, or under the platform's buttons | `cut-off` |\n| Wrong person | the camera on the listener, or never switching to the new speaker | `wrong-person` |\n| Late or jumpy cut | the camera reaches the speaker a second into their line, or leaps where nobody new speaks | `late-cut`, `jumpy-cut` |\n| Jitter or wander | the window trembles, or drifts across a speaker who sits still | `jitter`, `wander` |\n| Lost detail | a product, a sign or on-screen text the story needs, outside the frame | `cut-off` on a `keep` subject |\n| Soft picture | zoomed in so far the picture turns soft | `soft` |\n\n### What to read\n\n- **Where each subject is.** One `picsart_media_video_stills` sheet of the source, with `labels`,\n  at about one still per used stretch and one at each change of speaker. Read off each person's\n  box `[x, y, w, h]` in source pixels, around the head and the hands, and the box of anything that\n  must stay in frame. One box per subject is enough for a seated interview. For someone who walks,\n  `picsart_media_track_motion` with that box over the stretch gives the box over time.\n- **Who speaks when.** The transcript the footage-analysis skill made: each turn's speaker and\n  times, the speaker matched to a box on the sheet.\n\n### With a shell\n\nWrite what you read to `framing.json`, as the script's header says, and run\n`python3 scripts/reframe_fix.py check framing.json`:\n\n```json\n{\n  \"reframe\": \"reframe-talk.json\", \"width\": 1080,\n  \"subjects\": {\"ana\": {\"boxes\": [{\"t\": 0, \"box\": [300, 150, 300, 700]}]},\n               \"ben\": {\"boxes\": [{\"t\": 0, \"box\": [1300, 150, 300, 700]}]},\n               \"mug\": {\"boxes\": [{\"t\": 0, \"box\": [740, 600, 60, 80]}]}},\n  \"speakers\": [{\"who\": \"ana\", \"start\": 0.3, \"end\": 5.8}, {\"who\": \"ben\", \"start\": 6.2, \"end\": 11.5}],\n  \"keep\": [\"mug\"],\n  \"out\": \"reframe-talk.fixed.json\"\n}\n```\n\nIt prints `{ok, findings}`, each finding a kind from the table with its stretch in source seconds.\n`ok: true` means the reframe stands: cut from it as it is, and change nothing.\n\n### Without a shell\n\nRead the camera from the reframe's layer: at each keyframe, the source point at the frame's\ncentre is `srcW / 2 + (frameW / 2 - position x) / scale`, and the frame shows `frameW / scale`\nsource pixels across. A box is safe when it sits inside that window less 6% a side, 8% at the top\nand 12% at the bottom. Check the moments the sheet shows, and each change of speaker.\n\n### Correct it, smallest fix first\n\n1. **The camera path, by hand.** With a shell, `python3 scripts/reframe_fix.py fix framing.json`.\n   It holds the camera on whoever speaks, cuts to the next speaker 0.1 s before their first word\n   (a reply shorter than 1.2 s keeps the shot), smooths what moves, moves the window the least that\n   puts each kept box in the safe area, and caps the zoom. It writes `out` in the tool's own shape,\n   and prints `before`, `after` and `notes`. `spans` take over a stretch: `follow` one subject,\n   `hold` a still window, `static` for the tool's own window held, or `auto` for the tool's path.\n   Without a shell, write the same path into the kept reframe yourself: per speaker turn, two\n   keyframes with the same `position` (held), `position x = frameW / 2 - (centre - srcW / 2) *\n   scale`; the last keyframe before a cut takes `\"easing\": \"step\"`, one frame before the cut.\n2. **The tool again, only when its path is too coarse**: a fast move rounded off. Lower\n   `tolerance_px` or raise `max_keyframes`. It takes no hint of whom to follow, so a wrong person\n   or a cut-off subject is never fixed by running it again. A `wrong-person` that the path fix\n   still leaves (a multi-camera show cut between people) goes to fixed crops per shot type, as\n   [the split layout](#the-split-layout) builds them, even for a single frame.\n3. **A different layout for a stretch.** When what must be seen does not fit one window (the script\n   notes it: \"hold one subject, or stack the two\"), hold one person with a `hold` span, or stack\n   the two: above the reel's track for that stretch, two media layers of the source, each `\"fit\":\n   \"cover\"` with `\"bounds\": [1080, 960]`, a `crop` on one person and `position` `[540, 480]` or\n   `[540, 1440]`.\n\nCut from the corrected reframe from then on, and keep both in the project record (their file names,\nwhere you run commands). Run\nthe check again: what `after` still lists is either fixed in another pass or said to the user.\n\n### Show the change\n\nA correction the user did not ask for is shown, never described. Build the reel from both files\n(each build is free), and show one `picsart_scene_contact_sheet` of each at the same moments, the\ncorrected one first. When the fix was a judgment call (which person to hold, a hold or a stack),\nASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) which one to keep, with the two sheets as the options. A user who wants a stretch framed\notherwise moves it in `picsart_scene_editor`; read the window they chose back into a `hold` span\nand run the fix again, so the next re-cut keeps it.\n\nWithout a shell the reel is not built, so neither are the two sheets. Keep both reframes in the\nrecord, and show the change where the scene builder runs, before the first cut is reviewed. Until\nthen the correction is not shown, and never described in words instead.\n\n## Cut the reel\n\n`scripts/reel_cut.py` builds the scene. Write its input to a file and run\n`python3 scripts/reel_cut.py reel.json`. Where you cannot run commands, stop here as\npicsart-video-rules says for a script that builds the scene; the reframe, checked and corrected,\nstays in the record for the build there:\n\n```json\n{\n  \"width\": 1080, \"height\": 1920,\n  \"sources\": [\n    {\"id\": \"talk\", \"url\": \"<the url you reframed>\", \"reframe\": \"reframe-talk.fixed.json\"},\n    {\"id\": \"broll\", \"url\": \"<url>\", \"width\": 1920, \"height\": 1080, \"duration\": 31.5},\n    {\"id\": \"photo\", \"type\": \"image\", \"url\": \"<url>\", \"width\": 1600, \"height\": 1200}\n  ],\n  \"clips\": [\n    {\"source\": \"talk\", \"in\": 12.0, \"out\": 18.5},\n    {\"source\": \"broll\", \"in\": 3.0, \"out\": 6.0, \"frame\": \"full\", \"dim\": 0.3},\n    {\"source\": \"photo\", \"duration\": 2.0},\n    {\"source\": \"talk\", \"in\": 40.2, \"out\": 44.0}\n  ]\n}\n```\n\n- `width` and `height` are the reel's. The sizes and lengths of sources with no reframe come from\n  `picsart_media_probe`, never from memory.\n- Clips play in list order, each `in` to `out` in **its own source's** seconds. A range from one\n  source applied to another lands nowhere.\n- A reframed source's clips default to `crop`: the camera follows the subject. Others default to\n  `full`: the whole frame over a blurred copy of itself (`dim` darkens the copy), or over black\n  with `\"background\": \"black\"`.\n- A photo has no time of its own: its clip gives a `duration`, long enough to read and no longer.\n  `full` shows all of it; `\"frame\": \"crop\"` fills the frame from its centre.\n- With no `transition`, every seam is a hard cut. Keep it that way for speech: a crossfade blurs\n  the clean sentence edge the cut was placed on. Add one only when the user asks for it.\n- A channel's own end card (the record's `format.endCard`) goes in `endCard`, `{url, type, width,\n  height, duration}`, as the file was given: it closes the reel muted, its length snapped to the\n  frame grid. Never rebuild it or rewrite its words.\n\nIt prints one JSON line, `{scene, duration, clips, notes}`. Pass `scene` on as it is: it validates\nas it stands, and every clip is a plain media clip the scene editor opens. If it exits 1, its one\nline on stderr says what to change.\n\n**A re-cut is a new run.** To trim a clip, swap one, or change the order, edit the clip list and\nrun the script again. The reframe result stays as it is.\n\n## The split layout\n\nWhen the record's `format.layout.mode` is `split-v` (or `stacked`), the reel shows two people at\nonce, one above the seam and one below, each a **fixed crop** of the source. No reframe is\nmeasured: who is on screen comes from the shot, and who speaks from the locked map or the\ntranscript, never from a reframe.\n\n1. **The shots.** `picsart_media_segment_shots` on the source gives its cuts. Take one\n   `picsart_media_video_stills` frame per kind of shot (the two-shot, the host's camera, ...),\n   name each kind by eye, and write `shots`: per source, `[start, end, kind]` in its own seconds.\n2. **The crops.** Read off the sheet a crop per person and per kind of shot, `[x, y, w, h]` in\n   source pixels (`crops`); which two sit above and below the seam for each kind (`halves`); and\n   a full-frame crop per person (`full`) for emphasis. Read each face's box from the same stills.\n3. **Check the crops before anything is built.** With a shell,\n   `python3 scripts/reframe_fix.py check-crops crops.json` with `{\"crops\": {...}, \"faces\": {\"annie\":\n   [180, 130, 200, 230]}}`: each face inside its crop less 8% at the top, 6% a side and 12% at the\n   bottom. A `cut-off` finding names the edge and the pixels to move; an `unchecked` crop has no\n   face given yet. Without a shell, check the same margins by eye on the stills.\n4. **Emphasis.** A full-frame moment on one person: `{source, in, out, who, from}`, where `from` is\n   `map` (the locked map names it) or `transcript`. With `speakers` (the transcript's turns), the\n   script refuses an emphasis whose `who` is not the one speaking.\n5. **Cut it** with `reel_cut.py`, the same input plus `layout`, `shots`, `crops`, `halves`, `full`,\n   `emphasis` and `speakers` (`scripts/split_layout.py`, which reel_cut.py runs for a split and is\n   never run alone, has the shape in its header). It builds two tracks in\n   lockstep: `top` carries the sound, `bottom` is muted, and under a full-frame piece it plays\n   black. The end card closes the top track full frame. A split cuts hard: it takes no\n   `transition`. When `format` is given beside it and its layout differs, the script refuses the\n   cut: change the layout only with the user's `format:layout` approval.\n\nThe seam captions and the hook come next, from the spoken-captions skill.\n\nA source whose probe shows a frame rate other than a whole 30 (or 25, 24, 60), or that came from a\ndownload, can jump a frame in the render. Where you run commands, edit-on-your-computer re-encodes\nit per short first. Without a shell, say so in one line when the cut is first shown, and check\nthe render's seams for a jump.\n\n## Crop or full\n\n**A clip with a person talking is `crop`.** Letterboxing a face into a third of a vertical frame is\nthe defect this skill exists to prevent, not a safe choice. `full` is for a clip with nothing to\nfollow. When a crop looks wrong, fix the crop (above), never switch the clip to `full`.\n\n## When the camera swings\n\nOn a two-person shot the tool can swing from one person to the other, and the crop then lands\nbetween them. Correcting the path with the speakers' turns, as above, fixes it for every clip. For\none clip, the script measures it: `notes` names each clip whose camera crosses more of the source\nthan one person moves, with the centre to hold:\n\n```\nclips[1]: the camera crosses 42% of the source, so it may be following two people; to hold one, cut it again with \"hold\": 0.773\n```\n\nAdd that `hold` to the clip and run it again: the clip then holds one still window, as large as\nits own crop was. The transcript says who is speaking in that clip. If the hold sits on the\nlistener, give `hold` that person's side instead, from 0 (the left edge) to 1 (the right). Or\nchoose a stretch of the speech where only the speaker is in the frame. A corrected path cuts\nbetween speakers on purpose, so the script notes no swing on it.\n\n## Check the reel\n\nBefore the scene is reviewed, run `picsart_scene_validate` on it, then\n`picsart_scene_contact_sheet` at each seam and in the middle of each clip. Look for: a face in\nevery `crop` frame, not cut by the frame's edge; the speaker, not the listener, in each clip; and\nno clip that opens on a wall or a hand. Fix what fails in the framing (`framing.json` where you run commands) and cut again, as the\nquality-review skill says for one new run.\n"},"changes":[{"path":"/description","type":"changed","before":"Put the user's own footage in a frame of another shape - landscape to a vertical reel, say - with the camera following the person, measured once per source, and cut it into a reel of clips back to back with scripts/reel_cut.py, so any re-cut is free. Covers which clips follow the subject and which show the whole frame, photos held as beats, a camera that swings between two people, and hard cuts. Use when a reel or short is cut from the user's own videos and photos, when a landscape video is reposted as a vertical one, or when a vertical crop loses the subject.","after":"Put the user's own footage in a frame of another shape - landscape to a vertical reel, say - with the camera on the right person - measured once per source, checked and corrected by hand where the tool fails (a subject cut off, the wrong speaker, a late or jittery camera), then cut into a reel with scripts/reel_cut.py, so any re-cut is free. Use whenever footage is reframed or a reframe is checked - a reel or short from the user's own videos and photos, a landscape video reposted as a vertical one - or when a reframe or vertical crop misframes the subject."},{"path":"/included_files","type":"changed","before":[{"relative_path":"scripts/reel_cut.py","size_in_bytes":21516}],"after":[{"relative_path":"scripts/reel_cut.py","size_in_bytes":26168},{"relative_path":"scripts/reframe_fix.py","size_in_bytes":35018},{"relative_path":"scripts/split_layout.py","size_in_bytes":9975}]},{"path":"/skill_md_contents","type":"changed","before":"---\nname: footage-reframing\ndescription: Put the user's own footage in a frame of another shape - landscape to a vertical reel, say - with the camera following the person, measured once per source, and cut it into a reel of clips back to back with scripts/reel_cut.py, so any re-cut is free. Covers which clips follow the subject and which show the whole frame, photos held as beats, a camera that swings between two people, and hard cuts. Use when a reel or short is cut from the user's own videos and photos, when a landscape video is reposted as a vertical one, or when a vertical crop loses the subject.\n---\n\n# Reframe\n\nA vertical crop of a landscape shot keeps about a third of its width. Centred, that third is often\na wall beside the speaker. So the subject's position is measured, never guessed, and the clips are\ncut from that measurement by a script.\n\n## Measure each source once\n\n1. **Which sources need it.** A video whose shape differs from the reel's, with a person or\n   another subject in it. A source already the reel's shape, and one with nothing to follow (a\n   title card, a full-frame graphic, a wide shot with no subject), needs no reframe: its clips are\n   `full`.\n2. **Reframe it.** `picsart_media_reframe_video` with the source's Picsart-hosted `url` and the\n   reel's `aspect_ratio`. It replies with a job receipt, followed as picsart-video-rules says. It\n   takes minutes, so post a line first, and\n   start it as soon as the source and the reel's shape are known. It does not need the cut.\n3. **Save the result verbatim**, the whole reply, as `reframe-<source id>.json`. Never pass\n   `scene` and `layer_id` for this: that mode refuses a trim, and every call measures again.\n\n**One reframe per source and shape, for the whole session.** The result covers the source's whole\nlength, so every clip, every re-cut and every new running order is windowed from it by the script.\nMeasuring again for a new cut repeats minutes of work and changes nothing. Its description says\nwhether it charges credits. If it does, it is a SPEND (picsart-video-rules): quote every source's reframe in\none go.\n\nIf it fails, retry it once: it is flaky, and a later try often succeeds. If it fails again, stop\nand say the reframing is unavailable right now, with what is ready. Never estimate the subject's\nposition from a description of the video, and never frame a talking person `full` as a stand-in.\n\n## Cut the reel\n\n`scripts/reel_cut.py` builds the scene. Write its input to a file and run\n`python3 scripts/reel_cut.py reel.json`:\n\n```json\n{\n  \"width\": 1080, \"height\": 1920,\n  \"sources\": [\n    {\"id\": \"talk\", \"url\": \"<the url you reframed>\", \"reframe\": \"reframe-talk.json\"},\n    {\"id\": \"broll\", \"url\": \"<url>\", \"width\": 1920, \"height\": 1080, \"duration\": 31.5},\n    {\"id\": \"photo\", \"type\": \"image\", \"url\": \"<url>\", \"width\": 1600, \"height\": 1200}\n  ],\n  \"clips\": [\n    {\"source\": \"talk\", \"in\": 12.0, \"out\": 18.5},\n    {\"source\": \"broll\", \"in\": 3.0, \"out\": 6.0, \"frame\": \"full\", \"dim\": 0.3},\n    {\"source\": \"photo\", \"duration\": 2.0},\n    {\"source\": \"talk\", \"in\": 40.2, \"out\": 44.0}\n  ]\n}\n```\n\n- `width` and `height` are the reel's. The sizes and lengths of sources with no reframe come from\n  `picsart_media_probe`, never from memory.\n- Clips play in list order, each `in` to `out` in **its own source's** seconds. A range from one\n  source applied to another lands nowhere.\n- A reframed source's clips default to `crop`: the camera follows the subject. Others default to\n  `full`: the whole frame over a blurred copy of itself (`dim` darkens the copy), or over black\n  with `\"background\": \"black\"`.\n- A photo has no time of its own: its clip gives a `duration`, long enough to read and no longer.\n  `full` shows all of it; `\"frame\": \"crop\"` fills the frame from its centre.\n- With no `transition`, every seam is a hard cut. Keep it that way for speech: a crossfade blurs\n  the clean sentence edge the cut was placed on. Add one only when the user asks for it.\n\nIt prints one JSON line, `{scene, duration, clips, notes}`. Pass `scene` on as it is: it validates\nas it stands, and every clip is a plain media clip the scene editor opens. If it exits 1, its one\nline on stderr says what to change.\n\n**A re-cut is a new run.** To trim a clip, swap one, or change the order, edit the clip list and\nrun the script again. The reframe result stays as it is.\n\n## Crop or full\n\n**A clip with a person talking is `crop`.** Letterboxing a face into a third of a vertical frame is\nthe defect this skill exists to prevent, not a safe choice. `full` is for a clip with nothing to\nfollow. When a crop looks wrong, fix the crop (below), never switch the clip to `full`.\n\n## When the camera swings\n\nThe reframe follows *a* subject in each frame, not the one speaking. On a two-person shot it can\nswing from one to the other, and the crop then lands between them. The script measures that:\n`notes` names each clip whose camera crosses more of the source than one person moves, with the\ncentre to hold:\n\n```\nclips[1]: the camera crosses 42% of the source, so it may be following two people; to hold one, cut it again with \"hold\": 0.773\n```\n\nAdd that `hold` to the clip and run it again: the clip then holds one still window, as large as\nits own crop was. The transcript says who is speaking in that clip. If the hold sits on the\nlistener, give `hold` that person's side instead, from 0 (the left edge) to 1 (the right). Or\nchoose a stretch of the speech where only the speaker is in the frame.\n\n## Check\n\nBefore the scene is reviewed, run `picsart_scene_validate` on it, then\n`picsart_scene_contact_sheet` at each seam and in the middle of each clip. Look for: a face in\nevery `crop` frame, not cut by the frame's edge; and no clip that opens on a wall or a hand. Fix\nwhat fails in one new run, as the quality-review skill says.\n","after":"---\nname: footage-reframing\ndescription: Put the user's own footage in a frame of another shape - landscape to a vertical reel, say - with the camera on the right person - measured once per source, checked and corrected by hand where the tool fails (a subject cut off, the wrong speaker, a late or jittery camera), then cut into a reel with scripts/reel_cut.py, so any re-cut is free. Use whenever footage is reframed or a reframe is checked - a reel or short from the user's own videos and photos, a landscape video reposted as a vertical one - or when a reframe or vertical crop misframes the subject.\n---\n\n# Reframe\n\nA vertical crop of a landscape shot keeps about a third of its width. Centred, that third is often\na wall beside the speaker. So the subject's position is measured, never guessed, then checked and\ncorrected where the tool got it wrong, and the clips are cut from that path by a script.\n\nThis skill owns all reframing: the tool call, the check, the correction and the cut. A use case\nthat reframes loads it and keeps no reframing method of its own.\n\n## Measure each source once\n\n1. **Which sources need it.** A video whose shape differs from the reel's, with a person or\n   another subject in it. A source already the reel's shape, and one with nothing to follow (a\n   title card, a full-frame graphic, a wide shot with no subject), needs no reframe: its clips are\n   `full`.\n2. **Reframe it.** `picsart_media_reframe_video` with the source's Picsart-hosted `url` and the\n   reel's `aspect_ratio`. It replies with a job receipt, followed as picsart-video-rules says. It\n   takes minutes, so post a line first, and\n   start it as soon as the source and the reel's shape are known. It does not need the cut.\n   A local file or a Drive file is used by its Picsart-hosted URL, as picsart-video-rules says\n   for asset URLs; every check below reads that same URL.\n3. **Keep the result verbatim**, the whole reply: as `reframe-<source id>.json` where you run\n   commands, else in the project record. Never pass\n   `scene` and `layer_id` for this: that mode refuses a trim, and every call measures again.\n\n**One reframe per source and shape, for the whole session.** The result covers the source's whole\nlength, so every clip, every re-cut and every new running order is windowed from it by the script.\nMeasuring again for a new cut repeats minutes of work and changes nothing. Its description says\nwhether it charges credits. If it does, it is a SPEND (picsart-video-rules): quote every source's reframe in\none go.\n\nIf it fails, retry it once: it is flaky, and a later try often succeeds. If it fails again, stop\nand say the reframing is unavailable right now, with what is ready. Never estimate the subject's\nposition from a description of the video, and never frame a talking person `full` as a stand-in.\n\n## Check and correct\n\nThe tool follows a face, or else the most salient region, frame by frame. It does not know who is\nspeaking, what the story needs kept, or where the platform's buttons sit. **Check every reframe\nbefore cutting from it, and correct what fails.** Never pass a reframe on unseen, and never measure\nagain hoping for a better one: the same footage gives the same path.\n\n| Failure | What it looks like | Finding |\n|---|---|---|\n| Subject cut off | a head, a chin or the hands past the frame's edge, or under the platform's buttons | `cut-off` |\n| Wrong person | the camera on the listener, or never switching to the new speaker | `wrong-person` |\n| Late or jumpy cut | the camera reaches the speaker a second into their line, or leaps where nobody new speaks | `late-cut`, `jumpy-cut` |\n| Jitter or wander | the window trembles, or drifts across a speaker who sits still | `jitter`, `wander` |\n| Lost detail | a product, a sign or on-screen text the story needs, outside the frame | `cut-off` on a `keep` subject |\n| Soft picture | zoomed in so far the picture turns soft | `soft` |\n\n### What to read\n\n- **Where each subject is.** One `picsart_media_video_stills` sheet of the source, with `labels`,\n  at about one still per used stretch and one at each change of speaker. Read off each person's\n  box `[x, y, w, h]` in source pixels, around the head and the hands, and the box of anything that\n  must stay in frame. One box per subject is enough for a seated interview. For someone who walks,\n  `picsart_media_track_motion` with that box over the stretch gives the box over time.\n- **Who speaks when.** The transcript the footage-analysis skill made: each turn's speaker and\n  times, the speaker matched to a box on the sheet.\n\n### With a shell\n\nWrite what you read to `framing.json`, as the script's header says, and run\n`python3 scripts/reframe_fix.py check framing.json`:\n\n```json\n{\n  \"reframe\": \"reframe-talk.json\", \"width\": 1080,\n  \"subjects\": {\"ana\": {\"boxes\": [{\"t\": 0, \"box\": [300, 150, 300, 700]}]},\n               \"ben\": {\"boxes\": [{\"t\": 0, \"box\": [1300, 150, 300, 700]}]},\n               \"mug\": {\"boxes\": [{\"t\": 0, \"box\": [740, 600, 60, 80]}]}},\n  \"speakers\": [{\"who\": \"ana\", \"start\": 0.3, \"end\": 5.8}, {\"who\": \"ben\", \"start\": 6.2, \"end\": 11.5}],\n  \"keep\": [\"mug\"],\n  \"out\": \"reframe-talk.fixed.json\"\n}\n```\n\nIt prints `{ok, findings}`, each finding a kind from the table with its stretch in source seconds.\n`ok: true` means the reframe stands: cut from it as it is, and change nothing.\n\n### Without a shell\n\nRead the camera from the reframe's layer: at each keyframe, the source point at the frame's\ncentre is `srcW / 2 + (frameW / 2 - position x) / scale`, and the frame shows `frameW / scale`\nsource pixels across. A box is safe when it sits inside that window less 6% a side, 8% at the top\nand 12% at the bottom. Check the moments the sheet shows, and each change of speaker.\n\n### Correct it, smallest fix first\n\n1. **The camera path, by hand.** With a shell, `python3 scripts/reframe_fix.py fix framing.json`.\n   It holds the camera on whoever speaks, cuts to the next speaker 0.1 s before their first word\n   (a reply shorter than 1.2 s keeps the shot), smooths what moves, moves the window the least that\n   puts each kept box in the safe area, and caps the zoom. It writes `out` in the tool's own shape,\n   and prints `before`, `after` and `notes`. `spans` take over a stretch: `follow` one subject,\n   `hold` a still window, `static` for the tool's own window held, or `auto` for the tool's path.\n   Without a shell, write the same path into the kept reframe yourself: per speaker turn, two\n   keyframes with the same `position` (held), `position x = frameW / 2 - (centre - srcW / 2) *\n   scale`; the last keyframe before a cut takes `\"easing\": \"step\"`, one frame before the cut.\n2. **The tool again, only when its path is too coarse**: a fast move rounded off. Lower\n   `tolerance_px` or raise `max_keyframes`. It takes no hint of whom to follow, so a wrong person\n   or a cut-off subject is never fixed by running it again. A `wrong-person` that the path fix\n   still leaves (a multi-camera show cut between people) goes to fixed crops per shot type, as\n   [the split layout](#the-split-layout) builds them, even for a single frame.\n3. **A different layout for a stretch.** When what must be seen does not fit one window (the script\n   notes it: \"hold one subject, or stack the two\"), hold one person with a `hold` span, or stack\n   the two: above the reel's track for that stretch, two media layers of the source, each `\"fit\":\n   \"cover\"` with `\"bounds\": [1080, 960]`, a `crop` on one person and `position` `[540, 480]` or\n   `[540, 1440]`.\n\nCut from the corrected reframe from then on, and keep both in the project record (their file names,\nwhere you run commands). Run\nthe check again: what `after` still lists is either fixed in another pass or said to the user.\n\n### Show the change\n\nA correction the user did not ask for is shown, never described. Build the reel from both files\n(each build is free), and show one `picsart_scene_contact_sheet` of each at the same moments, the\ncorrected one first. When the fix was a judgment call (which person to hold, a hold or a stack),\nASK (with the host's own choice tool where it offers one, such as request_user_input in Codex's Plan mode, so the user taps an option; a Picsart board the step names asks there instead; only where neither works, the options numbered in one message, the recommended one first; in unattended pace, never ask: write it to the project record's openDecisions with the answer you assumed, as picsart-video-rules says) which one to keep, with the two sheets as the options. A user who wants a stretch framed\notherwise moves it in `picsart_scene_editor`; read the window they chose back into a `hold` span\nand run the fix again, so the next re-cut keeps it.\n\nWithout a shell the reel is not built, so neither are the two sheets. Keep both reframes in the\nrecord, and show the change where the scene builder runs, before the first cut is reviewed. Until\nthen the correction is not shown, and never described in words instead.\n\n## Cut the reel\n\n`scripts/reel_cut.py` builds the scene. Write its input to a file and run\n`python3 scripts/reel_cut.py reel.json`. Where you cannot run commands, stop here as\npicsart-video-rules says for a script that builds the scene; the reframe, checked and corrected,\nstays in the record for the build there:\n\n```json\n{\n  \"width\": 1080, \"height\": 1920,\n  \"sources\": [\n    {\"id\": \"talk\", \"url\": \"<the url you reframed>\", \"reframe\": \"reframe-talk.fixed.json\"},\n    {\"id\": \"broll\", \"url\": \"<url>\", \"width\": 1920, \"height\": 1080, \"duration\": 31.5},\n    {\"id\": \"photo\", \"type\": \"image\", \"url\": \"<url>\", \"width\": 1600, \"height\": 1200}\n  ],\n  \"clips\": [\n    {\"source\": \"talk\", \"in\": 12.0, \"out\": 18.5},\n    {\"source\": \"broll\", \"in\": 3.0, \"out\": 6.0, \"frame\": \"full\", \"dim\": 0.3},\n    {\"source\": \"photo\", \"duration\": 2.0},\n    {\"source\": \"talk\", \"in\": 40.2, \"out\": 44.0}\n  ]\n}\n```\n\n- `width` and `height` are the reel's. The sizes and lengths of sources with no reframe come from\n  `picsart_media_probe`, never from memory.\n- Clips play in list order, each `in` to `out` in **its own source's** seconds. A range from one\n  source applied to another lands nowhere.\n- A reframed source's clips default to `crop`: the camera follows the subject. Others default to\n  `full`: the whole frame over a blurred copy of itself (`dim` darkens the copy), or over black\n  with `\"background\": \"black\"`.\n- A photo has no time of its own: its clip gives a `duration`, long enough to read and no longer.\n  `full` shows all of it; `\"frame\": \"crop\"` fills the frame from its centre.\n- With no `transition`, every seam is a hard cut. Keep it that way for speech: a crossfade blurs\n  the clean sentence edge the cut was placed on. Add one only when the user asks for it.\n- A channel's own end card (the record's `format.endCard`) goes in `endCard`, `{url, type, width,\n  height, duration}`, as the file was given: it closes the reel muted, its length snapped to the\n  frame grid. Never rebuild it or rewrite its words.\n\nIt prints one JSON line, `{scene, duration, clips, notes}`. Pass `scene` on as it is: it validates\nas it stands, and every clip is a plain media clip the scene editor opens. If it exits 1, its one\nline on stderr says what to change.\n\n**A re-cut is a new run.** To trim a clip, swap one, or change the order, edit the clip list and\nrun the script again. The reframe result stays as it is.\n\n## The split layout\n\nWhen the record's `format.layout.mode` is `split-v` (or `stacked`), the reel shows two people at\nonce, one above the seam and one below, each a **fixed crop** of the source. No reframe is\nmeasured: who is on screen comes from the shot, and who speaks from the locked map or the\ntranscript, never from a reframe.\n\n1. **The shots.** `picsart_media_segment_shots` on the source gives its cuts. Take one\n   `picsart_media_video_stills` frame per kind of shot (the two-shot, the host's camera, ...),\n   name each kind by eye, and write `shots`: per source, `[start, end, kind]` in its own seconds.\n2. **The crops.** Read off the sheet a crop per person and per kind of shot, `[x, y, w, h]` in\n   source pixels (`crops`); which two sit above and below the seam for each kind (`halves`); and\n   a full-frame crop per person (`full`) for emphasis. Read each face's box from the same stills.\n3. **Check the crops before anything is built.** With a shell,\n   `python3 scripts/reframe_fix.py check-crops crops.json` with `{\"crops\": {...}, \"faces\": {\"annie\":\n   [180, 130, 200, 230]}}`: each face inside its crop less 8% at the top, 6% a side and 12% at the\n   bottom. A `cut-off` finding names the edge and the pixels to move; an `unchecked` crop has no\n   face given yet. Without a shell, check the same margins by eye on the stills.\n4. **Emphasis.** A full-frame moment on one person: `{source, in, out, who, from}`, where `from` is\n   `map` (the locked map names it) or `transcript`. With `speakers` (the transcript's turns), the\n   script refuses an emphasis whose `who` is not the one speaking.\n5. **Cut it** with `reel_cut.py`, the same input plus `layout`, `shots`, `crops`, `halves`, `full`,\n   `emphasis` and `speakers` (`scripts/split_layout.py`, which reel_cut.py runs for a split and is\n   never run alone, has the shape in its header). It builds two tracks in\n   lockstep: `top` carries the sound, `bottom` is muted, and under a full-frame piece it plays\n   black. The end card closes the top track full frame. A split cuts hard: it takes no\n   `transition`. When `format` is given beside it and its layout differs, the script refuses the\n   cut: change the layout only with the user's `format:layout` approval.\n\nThe seam captions and the hook come next, from the spoken-captions skill.\n\nA source whose probe shows a frame rate other than a whole 30 (or 25, 24, 60), or that came from a\ndownload, can jump a frame in the render. Where you run commands, edit-on-your-computer re-encodes\nit per short first. Without a shell, say so in one line when the cut is first shown, and check\nthe render's seams for a jump.\n\n## Crop or full\n\n**A clip with a person talking is `crop`.** Letterboxing a face into a third of a vertical frame is\nthe defect this skill exists to prevent, not a safe choice. `full` is for a clip with nothing to\nfollow. When a crop looks wrong, fix the crop (above), never switch the clip to `full`.\n\n## When the camera swings\n\nOn a two-person shot the tool can swing from one person to the other, and the crop then lands\nbetween them. Correcting the path with the speakers' turns, as above, fixes it for every clip. For\none clip, the script measures it: `notes` names each clip whose camera crosses more of the source\nthan one person moves, with the centre to hold:\n\n```\nclips[1]: the camera crosses 42% of the source, so it may be following two people; to hold one, cut it again with \"hold\": 0.773\n```\n\nAdd that `hold` to the clip and run it again: the clip then holds one still window, as large as\nits own crop was. The transcript says who is speaking in that clip. If the hold sits on the\nlistener, give `hold` that person's side instead, from 0 (the left edge) to 1 (the right). Or\nchoose a stretch of the speech where only the speaker is in the frame. A corrected path cuts\nbetween speakers on purpose, so the script notes no swing on it.\n\n## Check the reel\n\nBefore the scene is reviewed, run `picsart_scene_validate` on it, then\n`picsart_scene_contact_sheet` at each seam and in the middle of each clip. Look for: a face in\nevery `crop` frame, not cut by the frame's edge; the speaker, not the listener, in each clip; and\nno clip that opens on a wall or a hand. Fix what fails in the framing (`framing.json` where you run commands) and cut again, as the\nquality-review skill says for one new run.\n"}],"summary":"Fields changed: 3. /description, /included_files, /skill_md_contents.","summary_kind":"deterministic","summary_metadata":{}}