@pixerate/editor 0.222.2 → 0.222.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.222.2",
+  "version": "0.222.3",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -50,6 +50,9 @@ request like "clean up this export" finds it.
 | [`pixerate-paint-watercolour`](pixerate-paint-watercolour/SKILL.md) | Paint (`pixerate-paint-editor`) | Watercolour paper, light to dark with the paper's white kept, wet-in-wet and wet-on-dry washes, drying before glazing, steering the water. |
 | [`pixerate-paint-oil-impasto`](pixerate-paint-oil-impasto/SKILL.md) | Paint (`pixerate-paint-editor`) | A toned ground, thin block-in to thick paint, pigment mixing, impasto relief and its light. |
 | [`pixerate-paint-sketch-to-finish`](pixerate-paint-sketch-to-finish/SKILL.md) | Paint (`pixerate-paint-editor`) | Sketch, ink, flats under the lines, clipped shading and light, one named layer per pass. |
+| [`pixerate-video-social-cut`](pixerate-video-social-cut/SKILL.md) | Video (`pixerate-video-editor`) | Vertical or square reframes that fill the frame, the hook first, platform lengths, titles in the safe area. |
+| [`pixerate-video-colour-grade`](pixerate-video-colour-grade/SKILL.md) | Video (`pixerate-video-editor`) | Correct and match shots, then one look on an adjustment clip; LUTs at moderate strength with skin protected. |
+| [`pixerate-video-montage`](pixerate-video-montage/SKILL.md) | Video (`pixerate-video-editor`) | Selects on the beat, varied pacing, short transitions with handles, music under everything and a clean ending. |
 | [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Video (`pixerate-video-editor`) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. Owns the dialogue tools. |
 | [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Video (`pixerate-video-editor`) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. Owns the music tools. |
 
@@ -113,8 +116,8 @@ same change.
   `packages/core/tests/agent-skill-evals.test.ts`. An eval has a `prompt` (the task, in the
   user's words), a `fixture` (the starting document: `{ "editor": "spreadsheet", "rows" }`,
   `{ "editor": "image", "width", "height", "background", "shapes" }` or `{ "editor":
-  "vector", "width", "height", "setup" }` with commands that draw the starting art, or
-  `{ "editor": "paint", "width", "height", "setup" }` with tool calls), `checks` (a read-only
+  "vector", "width", "height", "setup" }` with commands that draw the starting art, 
+  `{ "editor": "paint", "width", "height", "setup" }` or `{ "editor": "video", "setup" }` with tool calls), `checks` (a read-only
   tool, or `run_command` with a read-only command such as `vector.list`, its `args`, what its result must match in `expect`, and `why`) and a `solution` (the
   tool calls an expert would make). The test proves each eval: some check fails on the fixture,
   and all pass after the solution. A model harness runs the same file with the model in place

package/skills/pixerate-paint-watercolour/evals/sky-wash.json

@@ -12,7 +12,7 @@
 		{ "tool": "set_brush", "args": { "id": "watercolor-wash" } },
 		{ "tool": "set_color", "args": { "color": "#6fa8dc" } },
 		{ "tool": "paint_stroke", "args": { "points": [{ "x": 0, "y": 6 }, { "x": 64, "y": 6 }, { "x": 64, "y": 14 }, { "x": 0, "y": 14 }] } },
-		{ "tool": "advance_wet_paint", "args": { "seconds": 30 } },
+		{ "tool": "advance_wet_paint", "args": { "seconds": 3 } },
 		{ "tool": "dry_paint" },
 		{ "tool": "get_wet_paint" }
 	]

package/skills/pixerate-video-colour-grade/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: pixerate-video-colour-grade
+description: The colour grading workflow in the Pixerate video editor - correcting each shot first (exposure, contrast, white balance) so a scene matches, then one look over the whole piece on an adjustment clip, LUTs at a sensible strength with skin tones protected, masks for spot changes, and checking with scopes and frames. Use when asked to colour correct, colour grade, match shots, fix exposure or white balance in a video, add a look, a LUT, a film or cinematic look, warm or cool a video, or protect skin tones, or when update_video_clip grade, add_video_adjustment_clip, set_video_lut or get_video_scopes are available. Load with pixerate-video-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-video-editor
+---
+
+# Grading a video
+
+A grade has two passes. **Correction** makes each shot right and makes shots in a scene match:
+exposure, contrast and white balance on the clip's own `grade`. **The look** is one creative
+decision over everything: an adjustment clip above the timeline with its own grade or a LUT,
+so it is changed in one place. Faces are the reference: people notice skin that is wrong before
+anything else.
+
+This skill is the method. `pixerate-video-editor` has the full tool reference.
+
+## Goal and quality bar
+
+- Shots in a scene match in brightness and colour; cuts between them do not jump.
+- Corrections are moderate: exposure within about ±1 stop, contrast and saturation within
+  ±0.3, white balance within ±0.3, unless a shot is badly off.
+- One look, in one place: an adjustment clip over the whole timeline (or one per scene), not
+  the same settings pasted on every clip.
+- Skin stays natural under strong looks (skin protection 0.5-0.8 on LUTs).
+- The original corrections are not overwritten by the look.
+
+## Inputs to confirm
+
+- **The look:** natural, warm, cool, desaturated, high contrast, a named LUT; or a reference.
+- **Which shot is the reference** for matching (the best-exposed, or the one the user likes).
+- **Where the LUT file is** (a `.cube` path or URL the host can load).
+
+## Working method
+
+1. **Read.** `get_video_project` for clips and their `grade`; where the host has a preview,
+   `get_video_scopes` at a frame of each shot reads levels and colour in numbers.
+   **Check:** you know which shots are off and by how much.
+2. **Correct the reference shot** (`update_video_clip` `set.grade`): exposure first, then
+   contrast, then white balance (`temperature`, `tint`). The grade object replaces the clip's
+   whole grade, so pass every setting you want to keep.
+3. **Match the others to it.** A shot one stop under gets `exposure: 1`; a cooler shot more
+   `temperature`. `copy_video_grade` when shots from one camera setup need the same correction;
+   `apply_video_grade_preset` for a common starting point.
+   **Check:** the clip `grade` values; scopes or `get_video_frame` at both sides of each cut.
+4. **The look over everything.** `add_video_track` at the top (`at: 0`) and
+   `add_video_adjustment_clip` on it from 0 for the whole duration with the look's `grade`
+   (`scope: "underneath"`).
+   **Check:** one adjustment clip covering the timeline; media clips keep their corrections.
+5. **LUTs.** `set_video_lut` with `strength` 0.3-0.7 for a look (1 only for a technical
+   conversion LUT) and skin protection (`preserve_skin_tones: 0.7`, 0.5-0.8) when people are on screen;
+   `set_video_skin_protection` to change the protection later.
+   **Check:** each clip's `grade.lut` has the strength and protection you meant.
+6. **Spot changes.** `set_video_clip_mask` on a duplicate clip or an adjustment clip for a sky,
+   a face or a vignette.
+7. **Review.** `render_video_frame` with `times` across the piece for a contact sheet; fix any
+   shot that stands out.
+
+## Decision table
+
+| Problem | Fix |
+| --- | --- |
+| Shot too dark or bright | `grade.exposure` in stops (+1 doubles the light) |
+| Flat, low contrast | `grade.contrast` +0.1-0.3 |
+| Blue or orange cast | `grade.temperature` against it |
+| Green or magenta cast | `grade.tint` against it |
+| Same correction on many shots from one setup | `copy_video_grade` |
+| One look for the whole piece | Adjustment clip on a top track |
+| A LUT look | `set_video_lut`, strength 0.3-0.7 |
+| Faces off under the look | Skin protection 0.5-0.8 (`set_video_lut` or `set_video_skin_protection`), or lower the strength |
+| Change only part of the frame | `set_video_clip_mask` |
+
+## Recipes
+
+**Match an underexposed shot.** `update_video_clip` `{ clip, set: { grade: { exposure: 1 } } }`
+for one stop under; check with scopes or frames on both sides of the cut.
+
+**Warm, slightly desaturated look.** `add_video_track` `{ kind: "video", at: 0 }` →
+`add_video_adjustment_clip` `{ track, start: 0, duration: <project duration>, grade:
+{ temperature: 0.2, saturation: -0.15 } }`.
+
+**Tame a LUT.** `set_video_lut` `{ clips, src, strength: 0.6, preserve_skin_tones: 0.7 }`.
+
+## Pitfalls
+
+- **Grading before correcting.** A look over unmatched shots makes the mismatch stronger.
+- **Partial grade objects.** `set.grade` replaces the whole grade; read it first and include
+  the settings you keep.
+- **The look on every clip.** Pasting it per clip means every change is many edits; use an
+  adjustment clip.
+- **Full-strength creative LUTs** turn faces orange or green and crush detail.
+- **ffmpeg and skin protection.** The export's `lut3d` cannot protect skin; the export notes
+  it, and the preview differs from the file. Lower the strength when that matters.
+- **Judging on one frame.** Check several frames per shot; light changes within shots.
+
+## Tools used
+
+- `get_video_project`, `get_video_scopes`, `get_video_frame`, `render_video_frame`: read grades, measure and look
+- `update_video_clip`: each shot's correction (`set.grade`)
+- `copy_video_grade`, `apply_video_grade_preset`: match and start from a preset
+- `add_video_track`, `add_video_adjustment_clip`: one look over the timeline
+- `set_video_lut`, `remove_video_lut`, `set_video_skin_protection`: LUT looks and skin
+- `set_video_clip_mask`, `remove_video_clip_mask`: spot changes
+- `undo_video`: take back a step

package/skills/pixerate-video-colour-grade/evals/look-in-one-place.json

@@ -0,0 +1,16 @@
+{
+	"prompt": "Give the whole piece a warm, slightly desaturated look that I can tweak in one place later, on top of the shot corrections.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "a", "kind": "video", "src": "shot-a.mp4", "duration": 8000 } },
+			{ "tool": "add_video_asset", "args": { "id": "b", "kind": "video", "src": "shot-b.mp4", "duration": 8000 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "a", "id": "c1", "start": 0, "duration": 6000 } } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "b", "id": "c2", "start": 6000, "duration": 6000 } } }] },
+	"checks": [
+		{ "why": "one adjustment clip over the whole timeline", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "adjustment", "start": 0, "duration": { "$min": 12000 } } } } } } },
+		{ "why": "warm and a little desaturated", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "adjustment", "grade": { "temperature": { "$min": 0.05, "$max": 0.5 }, "saturation": { "$min": -0.4, "$max": -0.02 } } } } } } } },
+		{ "why": "the shots' own grades are left alone", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$expr": "v.filter((c) => c.type === 'media').every((c) => !c.grade)" } } } } }
+	],
+	"solution": [
+		{ "tool": "add_video_track", "args": { "kind": "video", "id": "v0", "at": 0 } },
+		{ "tool": "add_video_adjustment_clip", "args": { "track": "v0", "start": 0, "duration": 12000, "grade": { "temperature": 0.2, "saturation": -0.15 } } }
+	]
+}

package/skills/pixerate-video-colour-grade/evals/lut-keep-skin.json

@@ -0,0 +1,132 @@
+{
+	"prompt": "The teal-and-orange LUT on both shots is too strong and turns the faces orange. Tone the look down to a moderate strength and keep the skin tones natural.",
+	"fixture": {
+		"editor": "video",
+		"setup": [
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "a",
+					"kind": "video",
+					"src": "shot-a.mp4",
+					"duration": 8000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "b",
+					"kind": "video",
+					"src": "shot-b.mp4",
+					"duration": 8000
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "a",
+						"id": "c1",
+						"start": 0,
+						"duration": 6000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "b",
+						"id": "c2",
+						"start": 6000,
+						"duration": 6000
+					}
+				}
+			},
+			{
+				"tool": "set_video_lut",
+				"args": {
+					"clips": [
+						"c1",
+						"c2"
+					],
+					"src": "data:text/plain,TITLE%20%22Teal%20orange%22%0ALUT_3D_SIZE%202%0A0%200.1%200.1%0A1%200.5%200.2%0A0%201%200.9%0A1%201%200.6%0A0%200.2%201%0A1%200.4%200.9%0A0%201%201%0A1%201%201%0A",
+					"strength": 1
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the LUT is still on both shots, at a moderate strength",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"clips": {
+							"$length": 2,
+							"$every": {
+								"grade": {
+									"lut": {
+										"src": {
+											"$match": "^data:"
+										},
+										"strength": {
+											"$min": 0.3,
+											"$max": 0.85
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "skin tones protected",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"clips": {
+							"$every": {
+								"grade": {
+									"lut": {
+										"preserveSkinTones": {
+											"$min": 0.4
+										}
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "get_video_project"
+		},
+		{
+			"tool": "set_video_lut",
+			"args": {
+				"clips": [
+					"c1",
+					"c2"
+				],
+				"src": {
+					"$read": "get_video_project",
+					"path": "tracks.0.clips.0.grade.lut.src"
+				},
+				"strength": 0.6,
+				"preserve_skin_tones": 0.7
+			}
+		}
+	]
+}

package/skills/pixerate-video-colour-grade/evals/match-exposure.json

@@ -0,0 +1,14 @@
+{
+	"prompt": "Shot two (c2) was filmed one stop underexposed compared with shot one. Match it to shot one without touching shot one.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "a", "kind": "video", "src": "shot-a.mp4", "duration": 8000 } },
+			{ "tool": "add_video_asset", "args": { "id": "b", "kind": "video", "src": "shot-b.mp4", "duration": 8000 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "a", "id": "c1", "start": 0, "duration": 6000 } } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "b", "id": "c2", "start": 6000, "duration": 6000 } } }] },
+	"checks": [
+		{ "why": "c2 brought up by about one stop", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "id": "c2", "grade": { "exposure": { "$min": 0.8, "$max": 1.2 } } } } } } } },
+		{ "why": "shot one is untouched", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "id": "c1", "$expr": "!v.grade || Object.values(v.grade).every((x) => x === 0)" } } } } } }
+	],
+	"solution": [
+		{ "tool": "update_video_clip", "args": { "clip": "c2", "set": { "grade": { "exposure": 1 } } } }
+	]
+}

package/skills/pixerate-video-editor/SKILL.md

@@ -33,6 +33,9 @@ the pitfalls, and uses the tools below.
 
 - `pixerate-talking-head-edit`: dialogue cleanup by transcript: fillers, pauses, stutters.
 - `pixerate-bgm-alignment`: cutting to the beat, ducking music under speech, loudness.
+- `pixerate-video-social-cut`: vertical reframes, the hook first, platform lengths, titles in the safe area.
+- `pixerate-video-colour-grade`: correct and match shots, one look on an adjustment clip, LUTs and skin.
+- `pixerate-video-montage`: selects on the beat, pacing, transitions, music and the ending.
 
 ## Working method
 

package/skills/pixerate-video-montage/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: pixerate-video-montage
+description: The montage workflow in the Pixerate video editor - choosing selects and their best moments, assembling them on beats or a rhythm, varying shot length for pacing, cutting on action, short transitions where they help, music under the whole sequence, and a clean start and end. Use when asked to make a montage, a highlight reel, a sizzle reel, a recap, a music video edit, a slideshow of clips or photos, or to cut a set of clips to music or a rhythm, or when edit_video, add_video_marker, set_video_transition or find_video_gaps are available. Load with pixerate-video-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-video-editor
+---
+
+# Cutting a montage
+
+A montage tells its story through rhythm: the best moment of each shot, in an order that
+builds, cut to a beat. The work is choosing (selects and their best seconds), then placing
+(on the beat, with shot lengths that breathe and quicken), then finishing (transitions only
+where they help, music under everything, a clear ending).
+
+This skill is the method. `pixerate-video-editor` has the full tool reference; for beats in a
+music track and cutting to them, see `pixerate-bgm-alignment`.
+
+## Goal and quality bar
+
+- Each shot is its best moment: taken from the middle of the action, not its first frames
+  (`in` past the camera's settle).
+- Cuts land on beats or on action, on frame boundaries, with no gaps (`find_video_gaps` empty).
+- Pacing varies: longer shots to establish, shorter to build, a held shot to land.
+- Straight cuts by default; short crossfades (300-600 ms) or dips only for a reason (time
+  passing, a change of section), each with enough media on both sides (no handle errors).
+- Music runs under the whole sequence and ends with it (a fade out or a musical ending), and
+  the picture ends cleanly (a fade to black or a held final frame).
+
+## Inputs to confirm
+
+- **Selects and order:** which clips, in what order (story, chronology, energy).
+- **Rhythm:** music with beats, markers, or a shot length (e.g. 1 s per shot).
+- **Length** of the finished piece.
+
+## Working method
+
+1. **Read.** `get_video_project`: assets (with durations), markers (beats), music.
+   With music, `find_video_beats` (`pixerate-bgm-alignment`) marks the beats.
+   **Check:** you have a beat grid or a shot length, and each select's usable range.
+2. **Pick the moments.** For each select, the `in` point of its best stretch (skip the first
+   second or two, where the camera settles).
+3. **Assemble in one batch.** `edit_video` with one add-clip op per shot (`asset`, `id`, `in`,
+   `start` on a beat, `duration` to the next beat), `dry_run: true` first.
+   **Check:** the clips are in order, each `start` on a beat; `find_video_gaps` is empty.
+4. **Refine the rhythm.** `roll_video_edit` to move a cut to a beat or onto action without
+   shifting anything else; `slip_video_clip` to change what a shot shows without moving it.
+   Vary lengths: build up with shorter shots before the peak.
+5. **Transitions, sparingly.** `set_video_transition` `crossfade` 300-600 ms (or `dip` for a
+   section change); every type but dip needs half its length in media past the cut on both sides.
+   **Check:** `check_video_project` has no errors.
+6. **Music and ending.** The music clip on an audio track from 0 for the whole duration, with a
+   `fadeOut` of 1-3 s (or cut on its last beat); the last picture clip `fadeOut` 300-1000 ms to
+   black.
+   **Check:** `get_video_project` shows both, ending together.
+7. **Review.** `render_video_frame` with `times` at each cut for a contact sheet; watch the
+   rhythm in the preview where available.
+
+## Decision table
+
+| Want | Approach |
+| --- | --- |
+| Energy, a build | Shorter shots toward the peak, cuts on every beat |
+| Calm, reflective | Longer shots, cuts every 2-4 beats, crossfades |
+| Time passing | Crossfade or dip between shots |
+| A section change | Dip to black or a held shot, then a new rhythm |
+| Continuity of motion | Cut on action (`roll_video_edit` onto the movement) |
+| Photos in a slideshow | Image assets, a slow push-in (`set_video_keyframes` scale 1 to 1.08) |
+
+## Recipes
+
+**On the beat.** Beats every `b` ms from 0: `edit_video` with `{ op: "add_clip", track: "v1", clip:
+{ type: "media", asset, id, in, start: k * b, duration: b } }` for each shot `k`; then `find_video_gaps`.
+
+**Crossfades.** `edit_video` with `{ op: "set_transition", clip, transition: { type: "crossfade",
+duration: 400 } }` for every clip after the first; then `check_video_project`.
+
+**Music and fade-out.** `add_video_clip` on the audio track `{ type: "media", asset: music,
+start: 0, duration: <sequence>, fadeOut: 2000 }`; `update_video_clip` on the last shot
+`{ set: { fadeOut: 500 } }`.
+
+## Pitfalls
+
+- **First frames of a clip** are often the camera settling; take `in` later.
+- **Transitions everywhere** soften the rhythm and look dated; cut straight by default.
+- **Missing handles.** A transition needs media past the cut on both sides; trimmed-to-the-edge
+  clips fail `check_video_project`.
+- **Music that stops dead** at the end of the picture; fade it or end on a musical phrase.
+- **Uniform shot lengths** for a long montage feel mechanical; vary them.
+
+## Tools used
+
+- `get_video_project`, `find_video_gaps`, `check_video_project`, `render_video_frame`: read and check
+- `add_video_marker`: beats and sections
+- `edit_video`, `add_video_clip`: assemble in one batch
+- `roll_video_edit`, `slip_video_clip`, `trim_video_clip`, `close_video_gaps`: refine the rhythm
+- `set_video_transition`: crossfades and dips
+- `update_video_clip`, `set_video_keyframes`: fades, volume and push-ins
+- `undo_video`: take back a step

package/skills/pixerate-video-montage/evals/assemble-on-beats.json

@@ -0,0 +1,231 @@
+{
+	"prompt": "Assemble the five selects s1 to s5 in order on V1, one shot per beat: each cut lands on the next beat marker (they are 1 s apart, from 0). Use the middle of each select (from 2 s in). No gaps.",
+	"fixture": {
+		"editor": "video",
+		"setup": [
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s1",
+					"kind": "video",
+					"src": "select-1.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s2",
+					"kind": "video",
+					"src": "select-2.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s3",
+					"kind": "video",
+					"src": "select-3.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s4",
+					"kind": "video",
+					"src": "select-4.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s5",
+					"kind": "video",
+					"src": "select-5.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_marker",
+				"args": {
+					"time": 0,
+					"label": "beat"
+				}
+			},
+			{
+				"tool": "add_video_marker",
+				"args": {
+					"time": 1000,
+					"label": "beat"
+				}
+			},
+			{
+				"tool": "add_video_marker",
+				"args": {
+					"time": 2000,
+					"label": "beat"
+				}
+			},
+			{
+				"tool": "add_video_marker",
+				"args": {
+					"time": 3000,
+					"label": "beat"
+				}
+			},
+			{
+				"tool": "add_video_marker",
+				"args": {
+					"time": 4000,
+					"label": "beat"
+				}
+			},
+			{
+				"tool": "add_video_marker",
+				"args": {
+					"time": 5000,
+					"label": "beat"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "five shots in order on V1",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"id": "v1",
+						"clips": {
+							"$length": 5,
+							"$expr": "v.every((c, i) => c.asset === 's' + (i + 1))"
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "every cut on a beat",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"id": "v1",
+						"clips": {
+							"$every": {
+								"$expr": "v.start % 1000 === 0 && v.duration === 1000"
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "from the middle of each select",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"id": "v1",
+						"clips": {
+							"$every": {
+								"in": {
+									"$min": 1500,
+									"$max": 3000
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "no gaps",
+			"tool": "find_video_gaps",
+			"expect": {
+				"gaps": {
+					"$length": 0
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "get_video_project"
+		},
+		{
+			"tool": "edit_video",
+			"args": {
+				"ops": [
+					{
+						"op": "add_clip",
+						"track": "v1",
+						"clip": {
+							"type": "media",
+							"asset": "s1",
+							"id": "c1",
+							"in": 2000,
+							"start": 0,
+							"duration": 1000
+						}
+					},
+					{
+						"op": "add_clip",
+						"track": "v1",
+						"clip": {
+							"type": "media",
+							"asset": "s2",
+							"id": "c2",
+							"in": 2000,
+							"start": 1000,
+							"duration": 1000
+						}
+					},
+					{
+						"op": "add_clip",
+						"track": "v1",
+						"clip": {
+							"type": "media",
+							"asset": "s3",
+							"id": "c3",
+							"in": 2000,
+							"start": 2000,
+							"duration": 1000
+						}
+					},
+					{
+						"op": "add_clip",
+						"track": "v1",
+						"clip": {
+							"type": "media",
+							"asset": "s4",
+							"id": "c4",
+							"in": 2000,
+							"start": 3000,
+							"duration": 1000
+						}
+					},
+					{
+						"op": "add_clip",
+						"track": "v1",
+						"clip": {
+							"type": "media",
+							"asset": "s5",
+							"id": "c5",
+							"in": 2000,
+							"start": 4000,
+							"duration": 1000
+						}
+					}
+				]
+			}
+		},
+		{
+			"tool": "find_video_gaps"
+		}
+	]
+}

package/skills/pixerate-video-montage/evals/music-and-ending.json

@@ -0,0 +1,210 @@
+{
+	"prompt": "Lay the music under the whole montage, fade the music out over the last two seconds, and end the picture with a fade to black.",
+	"fixture": {
+		"editor": "video",
+		"setup": [
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s1",
+					"kind": "video",
+					"src": "select-1.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s2",
+					"kind": "video",
+					"src": "select-2.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s3",
+					"kind": "video",
+					"src": "select-3.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s4",
+					"kind": "video",
+					"src": "select-4.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s5",
+					"kind": "video",
+					"src": "select-5.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s1",
+						"id": "c1",
+						"in": 2000,
+						"start": 0,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s2",
+						"id": "c2",
+						"in": 2000,
+						"start": 1000,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s3",
+						"id": "c3",
+						"in": 2000,
+						"start": 2000,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s4",
+						"id": "c4",
+						"in": 2000,
+						"start": 3000,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s5",
+						"id": "c5",
+						"in": 2000,
+						"start": 4000,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "music",
+					"kind": "audio",
+					"src": "music.mp3",
+					"duration": 60000
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "music under the whole montage, ending with it",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"kind": "audio",
+						"clips": {
+							"$some": {
+								"asset": "music",
+								"start": 0,
+								"duration": 5000
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "the music fades out over about two seconds",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"kind": "audio",
+						"clips": {
+							"$some": {
+								"asset": "music",
+								"fadeOut": {
+									"$min": 1500,
+									"$max": 2500
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "the last shot fades to black",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"id": "v1",
+						"clips": {
+							"$expr": "v[v.length - 1].fadeOut >= 300"
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "add_video_clip",
+			"args": {
+				"track": "a1",
+				"clip": {
+					"type": "media",
+					"asset": "music",
+					"start": 0,
+					"duration": 5000,
+					"fadeOut": 2000
+				}
+			}
+		},
+		{
+			"tool": "update_video_clip",
+			"args": {
+				"clip": "c5",
+				"set": {
+					"fadeOut": 500
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-video-montage/evals/short-crossfades.json

@@ -0,0 +1,190 @@
+{
+	"prompt": "Join the shots of this montage with short crossfades of about 400 ms, and make sure every transition has enough media for it.",
+	"fixture": {
+		"editor": "video",
+		"setup": [
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s1",
+					"kind": "video",
+					"src": "select-1.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s2",
+					"kind": "video",
+					"src": "select-2.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s3",
+					"kind": "video",
+					"src": "select-3.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s4",
+					"kind": "video",
+					"src": "select-4.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_asset",
+				"args": {
+					"id": "s5",
+					"kind": "video",
+					"src": "select-5.mp4",
+					"duration": 6000
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s1",
+						"id": "c1",
+						"in": 2000,
+						"start": 0,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s2",
+						"id": "c2",
+						"in": 2000,
+						"start": 1000,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s3",
+						"id": "c3",
+						"in": 2000,
+						"start": 2000,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s4",
+						"id": "c4",
+						"in": 2000,
+						"start": 3000,
+						"duration": 1000
+					}
+				}
+			},
+			{
+				"tool": "add_video_clip",
+				"args": {
+					"track": "v1",
+					"clip": {
+						"type": "media",
+						"asset": "s5",
+						"id": "c5",
+						"in": 2000,
+						"start": 4000,
+						"duration": 1000
+					}
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "a short crossfade into every shot after the first",
+			"tool": "get_video_project",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"id": "v1",
+						"clips": {
+							"$expr": "v.slice(1).every((c) => c.transition && c.transition.type === 'crossfade' && c.transition.duration >= 300 && c.transition.duration <= 600)"
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "no errors (every transition has handles)",
+			"tool": "check_video_project",
+			"expect": {
+				"errors": 0
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "edit_video",
+			"args": {
+				"ops": [
+					{
+						"op": "set_transition",
+						"clip": "c2",
+						"transition": {
+							"type": "crossfade",
+							"duration": 400
+						}
+					},
+					{
+						"op": "set_transition",
+						"clip": "c3",
+						"transition": {
+							"type": "crossfade",
+							"duration": 400
+						}
+					},
+					{
+						"op": "set_transition",
+						"clip": "c4",
+						"transition": {
+							"type": "crossfade",
+							"duration": 400
+						}
+					},
+					{
+						"op": "set_transition",
+						"clip": "c5",
+						"transition": {
+							"type": "crossfade",
+							"duration": 400
+						}
+					}
+				]
+			}
+		},
+		{
+			"tool": "check_video_project"
+		}
+	]
+}

package/skills/pixerate-video-social-cut/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: pixerate-video-social-cut
+description: The social video workflow in the Pixerate video editor - reframing for vertical (9:16) or square, opening on the hook in the first seconds, cutting to platform length, titles and captions inside the safe area, pacing for the feed, loudness for mobile and an export for Reels, TikTok, Shorts or a feed post. Use when asked to make a social cut, a vertical, Reels, TikTok, Shorts or story version, a teaser or trailer for social, a short clip from a longer video, or to reframe, caption or title a video for social, or when set_video_settings, update_video_clip and add_video_marker are available. Load with pixerate-video-editor, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-video-editor
+---
+
+# Cutting for social
+
+A social cut is watched on a phone, often without sound, by someone who decides in the first
+second or two whether to stay. So the frame is vertical or square and filled, the strongest
+moment comes first, every shot earns its place, and words are on screen. Build it as its own
+project or sequence from the long edit, never by damaging the original.
+
+This skill is the method. `pixerate-video-editor` has the full tool reference; for music and
+loudness see `pixerate-bgm-alignment`.
+
+## Goal and quality bar
+
+- The frame suits the platform: 1080 × 1920 (9:16) for Reels, TikTok, Shorts and stories;
+  1080 × 1080 or 1080 × 1350 for a feed post. The picture fills it (no black bars).
+- The hook plays in the first 1-3 seconds: the most striking image or line, not a logo or a
+  slow build.
+- The length fits the platform and the content: 7-15 s for a loop or teaser, up to 60 s for
+  most short-form, cut tight (no dead air, `find_video_gaps` empty).
+- Text is readable without sound: titles and captions large, high-contrast, inside the safe
+  area (away from the top 250 px and bottom 350 px of a 1920-high frame, where the app's
+  interface sits).
+- `check_video_project` has no errors; the mix is at the delivery loudness (-14 LUFS).
+
+## Inputs to confirm
+
+- **Platform(s)** and so the frame and length.
+- **The hook:** a moment, a line or a marker; ask when nothing in the footage stands out.
+- **Words on screen:** captions of the speech, a title, a call to action.
+
+## Working method
+
+1. **Read.** `get_video_project`: frame size, clips, markers (a "Hook" marker or the user's
+   notes), duration. With speech, `get_video_transcript` to find the best lines.
+   **Check:** you know where the hook is in the source and how long the cut should be.
+2. **Set the frame.** `set_video_settings` `width` / `height`; then each clip `fit: "cover"`
+   (`update_video_clip`), and `transform` `x` to keep the subject in frame when it is off-centre.
+   **Check:** `get_video_project` frame size; `get_video_frame` at a few times shows the subject.
+3. **Open on the hook.** Trim and move so the first clip's `in` is at the hook (`edit_video`
+   with its trim and move ops, or `extract_video_range` for what goes). Then the context, then
+   the payoff.
+   **Check:** the clip at 0 starts at the hook's source time.
+4. **Cut to length.** Remove everything that does not move the story: `remove_video_ranges` for
+   pauses and fillers (`pixerate-talking-head-edit`), `extract_video_range` for whole passages.
+   Keep shots short (1-3 s for montage, as long as the line for speech).
+   **Check:** `get_video_project` `duration` is in range; `find_video_gaps` is empty.
+5. **Words.** A video track above the footage (`add_video_track` with `at: 0`), then text clips
+   (`add_video_clip` `type: "text"`) with `transform.y` in the upper or lower safe area,
+   `animateIn` / `animateOut` for motion. Captions follow the transcript's sentences.
+   **Check:** text clips are on the top track and inside the safe area.
+6. **Sound.** Music under, dialogue on top (`pixerate-bgm-alignment`); the first second should
+   work without sound and with it.
+7. **Check and export.** `check_video_project`; `export_video_ffmpeg` with the loudness target.
+
+## Decision table
+
+| Platform | Frame | Length |
+| --- | --- | --- |
+| Reels, TikTok, Shorts, stories | 1080 × 1920 | 7-60 s; under 15 s loops |
+| Feed post | 1080 × 1350 or 1080 × 1080 | 15-60 s |
+| Landscape (YouTube, web) | 1920 × 1080 | The content's length |
+
+| Source | Reframe |
+| --- | --- |
+| Subject centred | `fit: "cover"` |
+| Subject off-centre | `fit: "cover"` plus `transform.x` toward the subject |
+| Subject moves across the frame | Keyframe `transform.x` (`set_video_keyframes`), or split and reposition per shot |
+| Wide shot that loses everything when cropped | A blurred, scaled copy behind a `contain` copy, or choose another shot |
+
+## Recipes
+
+**Vertical from landscape.** `set_video_settings` `{ width: 1080, height: 1920 }` → for each
+picture clip `update_video_clip` `{ set: { fit: "cover" } }` → `get_video_frame` to check.
+
+**Hook first.** Source hook at `h` ms: `edit_video` `[{ op: "trim_clip", clip, edge: "start",
+to: h }, { op: "trim_clip", clip, edge: "end", to: h + length }, { op: "move_clip", clip,
+start: 0 }]`.
+
+**Opening title.** `add_video_track` `{ kind: "video", at: 0 }` → `add_video_clip` on it with
+`{ type: "text", text, start: 0, duration: 3000, transform: { y: -600 } }`.
+
+## Pitfalls
+
+- **Letterboxing.** A landscape clip in a vertical frame with `contain` shows black bars.
+- **Slow openings.** A logo, a fade-in or a wide establishing shot loses the viewer.
+- **Text in the interface zones** is covered by captions, buttons and the username.
+- **Relying on sound.** Most feeds autoplay muted; put the message on screen too.
+- **Editing the master.** Make the social cut separately so the long version stays intact.
+
+## Tools used
+
+- `get_video_project`, `get_video_transcript`, `get_video_frame`, `find_video_gaps`, `check_video_project`: read and check
+- `set_video_settings`: the frame size
+- `update_video_clip`, `set_video_keyframes`: fit, reframe and move the picture
+- `edit_video`, `trim_video_clip`, `move_video_clip`, `extract_video_range`, `remove_video_ranges`: cut to the hook and to length
+- `add_video_track`, `add_video_clip`: titles and captions on a track above
+- `add_video_marker`: mark the hook and beats
+- `export_video_ffmpeg`: deliver

package/skills/pixerate-video-social-cut/evals/hook-first.json

@@ -0,0 +1,19 @@
+{
+	"prompt": "Cut this interview down to a 15-second clip for social that opens on the moment marked 'Hook' and runs on from there. No gaps.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "interview", "kind": "video", "src": "interview.mp4", "duration": 40000, "width": 1920, "height": 1080 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "interview", "id": "c1", "start": 0, "duration": 40000 } } }, { "tool": "add_video_marker", "args": { "time": 22000, "label": "Hook" } }] },
+	"checks": [
+		{ "why": "about 15 seconds long", "tool": "get_video_project", "expect": { "duration": { "$min": 12000, "$max": 15500 } } },
+		{ "why": "the first frame is the hook", "tool": "get_video_project", "expect": { "tracks": { "$some": { "id": "v1", "clips": { "$some": { "start": 0, "in": { "$min": 21500, "$max": 22500 } } } } } } },
+		{ "why": "no gaps", "tool": "find_video_gaps", "expect": { "gaps": { "$length": 0 } } }
+	],
+	"solution": [
+		{ "tool": "get_video_project" },
+		{ "tool": "edit_video", "args": { "ops": [
+			{ "op": "trim_clip", "clip": "c1", "edge": "start", "to": 22000 },
+			{ "op": "trim_clip", "clip": "c1", "edge": "end", "to": 37000 },
+			{ "op": "move_clip", "clip": "c1", "start": 0 }
+		] } },
+		{ "tool": "find_video_gaps" }
+	]
+}

package/skills/pixerate-video-social-cut/evals/opening-title.json

@@ -0,0 +1,14 @@
+{
+	"prompt": "Add a title saying 'New drop Friday' over the first three seconds, in the upper part of the frame, on top of the video.",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "interview", "kind": "video", "src": "interview.mp4", "duration": 40000, "width": 1920, "height": 1080 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "interview", "id": "c1", "start": 0, "duration": 40000 } } }] },
+	"checks": [
+		{ "why": "a text clip with the words, from 0 for about 3 s", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "text", "text": { "$match": ["new drop friday", "i"] }, "start": 0, "duration": { "$min": 2500, "$max": 4000 } } } } } } },
+		{ "why": "in the upper part of the frame", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "type": "text", "transform": { "y": { "$max": -100 } } } } } } } },
+		{ "why": "on a video track above the footage (tracks are listed top first)", "tool": "get_video_project", "expect": { "tracks": { "$expr": "(() => { const t = v.findIndex((tr) => tr.clips.some((c) => c.type === 'text')); const m = v.findIndex((tr) => tr.clips.some((c) => c.id === 'c1')); return t >= 0 && t < m; })()" } } }
+	],
+	"solution": [
+		{ "tool": "add_video_track", "args": { "kind": "video", "id": "v2", "at": 0 } },
+		{ "tool": "add_video_clip", "args": { "track": "v2", "clip": { "type": "text", "text": "New drop Friday", "start": 0, "duration": 3000, "transform": { "y": -600 } } } }
+	]
+}

package/skills/pixerate-video-social-cut/evals/vertical-reframe.json

@@ -0,0 +1,15 @@
+{
+	"prompt": "Make this a vertical video for Reels and TikTok: 1080 by 1920, with the picture filling the whole frame (no black bars).",
+	"fixture": { "editor": "video", "setup": [{ "tool": "add_video_asset", "args": { "id": "interview", "kind": "video", "src": "interview.mp4", "duration": 40000, "width": 1920, "height": 1080 } },
+			{ "tool": "add_video_clip", "args": { "track": "v1", "clip": { "type": "media", "asset": "interview", "id": "c1", "start": 0, "duration": 40000 } } }] },
+	"checks": [
+		{ "why": "a 9:16 frame at 1080 × 1920", "tool": "get_video_project", "expect": { "width": 1080, "height": 1920 } },
+		{ "why": "the picture covers the frame", "tool": "get_video_project", "expect": { "tracks": { "$some": { "clips": { "$some": { "id": "c1", "$expr": "v.fit === 'cover' || (v.transform && v.transform.scale >= 3.15)" } } } } } },
+		{ "why": "no errors", "tool": "check_video_project", "expect": { "errors": 0 } }
+	],
+	"solution": [
+		{ "tool": "set_video_settings", "args": { "width": 1080, "height": 1920 } },
+		{ "tool": "update_video_clip", "args": { "clip": "c1", "set": { "fit": "cover" } } },
+		{ "tool": "check_video_project" }
+	]
+}