@pixerate/editor 0.86.0 → 0.88.0

package/package.json

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

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

@@ -116,8 +116,18 @@ For errors, namespaced tool names and undo conventions, see `pixerate-agent-tool
 - **Grade in two passes: correct, then look.** First balance each shot so a scene matches
   (`update_video_clip` `grade`: fix exposure and white balance against the best shot, then
   `copy_video_grade` from it to the rest of the scene), then add a look with
-  `apply_video_grade_preset` at a modest `amount` (0.3-0.6). Check with `render_video_frame` at a
+  `apply_video_grade_preset` at a modest `amount` (0.3-0.6), or a `.cube` look the user has with
+  `set_video_lut` (often at `strength` 0.5-0.8: film emulation and creative LUTs are strong at
+  full strength). A LUT runs after the grade's settings, so correct exposure and white balance
+  first; LUTs built for log footage expect a flat picture and look crushed on normal video. Check with `render_video_frame` at a
   few times side by side. Skin tones are the reference: avoid strong `hue` or `tint` on people.
+- **Measure, don't eyeball.** Where the host shows a preview, `get_video_scopes` reads the real
+  picture: keep `clipped.highlights` under about 1% and `clipped.shadows` under about 2% unless
+  the look calls for it, and aim for a mean luma of roughly 0.35-0.55 for ordinary scenes. A
+  balanced shot's `average` colour is close to grey, so a strong tint there is a cast to fix
+  with `temperature` and `tint`. Measure before and after each grade, and compare shots in a
+  scene by their `stats` rather than by eye. The figures are of the rendered frame, after
+  grades, blends and titles.
 - **Blend overlays, don't key them.** Light leaks, flares, film burns and glows shot on black go on
   a higher video track with `blend: "screen"` (or `add` for a hotter look), so the black drops
   out; textures, paper and dust on white use `multiply`. Lower the clip's `opacity` to taste.
@@ -146,6 +156,7 @@ For errors, namespaced tool names and undo conventions, see `pixerate-agent-tool
 | `find_video_gaps` | List empty stretches between clips (and before the first) as `{ track, start, end }` ms, on every track or one `track`. Then `close_video_gaps` or ripple. |
 | `check_video_project` | After every batch and before export. Lists issues errors first with a code (`missing-asset`, `wrong-track`, `overlap`, `source-overrun`, `transition-without-cut`, `transition-too-long`, `transition-handles`, `fades-too-long`, `unknown-duration`, `unused-asset`, `marker-past-end`, `empty`), what it is about and how to fix it. |
 | `render_video_frame` | Look at the picture at `time`, or at 2-16 `times` as one labelled contact sheet (`columns` 1-8). SVG by default; `format: "png"` only when the host can rasterize. Video without a `poster` shows as a labelled box with its source timecode. |
+| `get_video_scopes` | Measure the rendered picture at `time` (default the playhead; another time is shown briefly and the playhead put back) as colour scopes do: luma `stats` (0-1 mean, median, min, max, p1, p99), the share `clipped` to black or white (and per channel), saturation, the `average` colour, a `histogram` of `bins` steps (default 16), the luma spread of `columns` strips left to right (`waveform`, default 8), the main `vectorscope` hue (red ≈ 103°, skin ≈ 123°) and `notes` on what to fix. Call it before and after grading. Fails with a reason when the host shows no preview (then use `render_video_frame`). |
 | `export_video_ffmpeg` | Get the ffmpeg command that renders the project: `args` (for spawn), `command` (one shell line), `filterComplex`, duration and notes on approximations. `output` default output.mp4, `crf` x264 quality 0-51 (default 18, lower is better). `loudness` normalises the mix (`integrated` LUFS default -14, `truePeak` dBTP default -1, `range`); with `loudness.measured` from `export_video_loudness_measure` it applies one fixed gain. Fails when there are no clips. |
 | `export_video_loudness_measure` | First pass of loudness normalisation: the ffmpeg command that mixes only the sound and prints its loudness as JSON at the end of stderr. Takes the same target (`integrated` LUFS, `truePeak`, `range`) as the export. Map `input_i`, `input_tp`, `input_lra`, `input_thresh`, `target_offset` to `loudness.measured` for `export_video_ffmpeg`. |
 | `export_video_edl` | Get one `track` (default the bottom video track) as a CMX 3600 EDL with source and record timecode, dissolves, speed changes and clip names, for conforming in another editor. `title` defaults to the project name. At 29.97 and 59.94 fps it writes drop-frame timecode (`HH:MM:SS;FF`, `FCM: DROP FRAME`), as other editors expect; `dropFrame: false` forces non-drop. |
@@ -179,7 +190,9 @@ For errors, namespaced tool names and undo conventions, see `pixerate-agent-tool
 | `extract_video_range` | Remove `from`..`to` ms and close it up: as lift, then later material moves earlier on those and every sync-locked track. Refused (naming the clip) when a sync-locked track outside `tracks` has material there. Use to cut a section out of a finished sequence. |
 | `delete_video_clips` | Remove `clips`; `ripple: true` pulls later clips up to close the gaps (a ripple delete). |
 | `update_video_clip` | Change properties via `set`: opacity, transform (`x`, `y` px from centre, `scale`, `rotation`), `fit` (contain default for media, cover, fill, none), `animateIn` / `animateOut` (`{ effect: fade, rise, drop, slide-left, slide-right, zoom or pop, duration ms default 500 }`), `grade` (`exposure` stops -3-3, `contrast`, `saturation`, `temperature`, `tint` -1-1, `hue` degrees; replaces the whole grade), `blend` (normal, multiply, screen, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, add), `fadeIn` / `fadeOut`, name; media `volume` (0-4), `muted`, `fadeInCurve` / `fadeOutCurve` (the sound's fade shape: linear, equal-power, s-curve, exponential, logarithmic), `speed` (0.05-20, keeps the source range so the length changes), `asset`; title text and style; colour. `remove` resets to defaults. Not for timing. |
-| `apply_video_grade_preset` | Give `clips` (on video tracks) a named look at an `amount` 0-1 (default 1), replacing their grades: warm, cool, punchy, faded, black-and-white, bleach-bypass, day-for-night. One undo step; returns each clip's grade to fine-tune with `update_video_clip`. |
+| `set_video_lut` | Give `clips` (on video tracks) a 3D LUT: `src` a `.cube` file the host can load and ffmpeg can read, `strength` 0-1 (default 1). Reads the file first and fails without changing anything if it cannot be loaded or is not a 3D `.cube`. Keeps the clips' other grade settings; the LUT runs after them. One undo step; returns the LUT's `title` and `size` and each clip's grade. Copies with `copy_video_grade`. |
+| `remove_video_lut` | Take the LUT off `clips`' grades, keeping their other settings (one undo step). Fails if none has one. |
+| `apply_video_grade_preset` | Give `clips` (on video tracks) a named look at an `amount` 0-1 (default 1), replacing their grade settings (a LUT stays): warm, cool, punchy, faded, black-and-white, bleach-bypass, day-for-night. One undo step; returns each clip's grade to fine-tune with `update_video_clip`. |
 | `copy_video_grade` | Match shots: give the `to` clips the grade of the `from` clip (one undo step; a source with no grade clears theirs). Returns the grade copied. |
 | `set_video_speed_ramp` | Play a video or audio `clip` through `segments` of speed from its first frame: `[{ duration ms, speed, toSpeed? }]`; `toSpeed` glides evenly to a new speed over the stretch, speed 0 is a freeze. The clip's length becomes the segments' total; `ripple` (default true) moves later material. Returns the clip with its `timeRemap` and source range. |
 | `add_video_freeze_frame` | Hold the frame a clip shows at timeline time `at` for `duration` ms, then play on; the clip gets longer and (with `ripple`, default) later material moves along. Works with or without a ramp. |
@@ -233,5 +246,13 @@ For errors, namespaced tool names and undo conventions, see `pixerate-agent-tool
   wants that track changed.
 - **Read-only**: when `get_video_project` says the project cannot be edited, write tools are
   hidden; read, render and export still work. Tell the user rather than working around it.
+- **LUTs are files.** `set_video_lut` needs a `src` both the preview (a URL it can fetch) and
+  ffmpeg (a local path; the host maps it with `resolveLut`) can read; the export notes a URL it
+  cannot. SVG frames from `render_video_frame` draw a LUT approximately (curves and a colour
+  matrix), so judge a LUT's exact colours with `get_video_scopes` or the preview.
+- **Scopes need real pixels.** `get_video_scopes` reads what the host's preview draws, so it
+  fails when nothing is showing the project or the media cannot load in time, and a canvas
+  with media from another origin served without CORS cannot be read. Video drawn as a
+  placeholder box is never measured: the tool waits for every picture to load.
 - **Exports are commands, not files.** `export_video_ffmpeg` returns a command for the host to
   run; the EDL covers one track only. Report the notes on anything approximated.