@pixerate/editor 0.160.0 → 0.162.0

package/dist/video-editor/transcript.d.ts

@@ -85,3 +85,43 @@ export declare function videoWordsRange(words: readonly VideoTimelineWord[], a:
 export declare function videoTranscriptEdit(assetId: string, text: string): VideoEdit;
 /** The word playing at a timeline time, as its index in `words`, or -1. */
 export declare function videoWordAt(words: readonly VideoTimelineWord[], time: number): number;
+export interface VideoRepetitionOptions {
+    /** Longest phrase to look for repeated (words, default 3). */
+    maxPhrase?: number;
+    /** Longest gap between a phrase and its repeat that still counts as a stutter (ms, default 1000). */
+    maxGap?: number;
+}
+/**
+ * Words said twice in a row ("I I think", "we should we should"), as timeline ranges covering the
+ * first saying and the gap up to the repeat, so cutting them leaves the phrase said once. Longer
+ * phrases are tried first; "I I I" gives two ranges. Some repeats are meant ("very very"): check them.
+ */
+export declare function findVideoRepetitions(words: readonly VideoTimelineWord[], options?: VideoRepetitionOptions): VideoTranscriptRange[];
+export type VideoDisfluencyKind = 'filler' | 'pause' | 'repetition';
+export declare const VIDEO_DISFLUENCY_KINDS: readonly ["filler", "pause", "repetition"];
+/** Something to tidy out of speech: where it is (timeline ms), what kind and what was said. */
+export interface VideoDisfluency extends VideoTranscriptRange {
+    kind: VideoDisfluencyKind;
+    /** Indexes in the word list of the first and last word it covers (for a pause: the words either side). */
+    words: [number, number];
+}
+export interface VideoDisfluencyOptions {
+    /** Which kinds to look for (default all). */
+    kinds?: readonly VideoDisfluencyKind[];
+    /** Filler words and phrases (default `VIDEO_DEFAULT_FILLERS`). */
+    fillers?: readonly string[];
+    /** How pauses are measured (default: over 700 ms, keeping 150 ms of breath either side). */
+    pauses?: VideoPauseOptions;
+    repetitions?: VideoRepetitionOptions;
+}
+/**
+ * Fillers, long pauses and stutters in one pass, in time order, each with the words it covers, so
+ * a transcript can mark them and an agent can review them before cutting. Overlapping finds are
+ * all kept (a filler inside a repetition): `mergeVideoRanges` joins them when they are cut.
+ */
+export declare function detectVideoDisfluencies(words: readonly VideoTimelineWord[], options?: VideoDisfluencyOptions): VideoDisfluency[];
+/** Cut ranges shrunk by `keep` ms at each end, so a little breath stays either side; ranges that vanish are dropped. */
+export declare function videoCutsWithMargin<T extends {
+    from: number;
+    to: number;
+}>(ranges: readonly T[], keep: number): T[];

package/dist/video-editor/types.d.cts

@@ -160,6 +160,12 @@ export interface VideoGradeLut {
     strength?: number;
     /** A label for the look (default the file's TITLE or name). */
     name?: string;
+    /**
+     * How much of the LUT's change to hold back on skin tones, 0–1 (default 0): at 1 a pixel that
+     * looks like skin keeps its graded-but-un-LUT'd colour, so a heavy creative look leaves faces
+     * natural. Skin is found by chroma (see `videoSkinToneWeight`), with a soft edge.
+     */
+    preserveSkinTones?: number;
 }
 /**
  * Colour correction for a clip's picture (see `VIDEO_GRADE_CONTROLS` for ranges). Applied in a fixed
@@ -222,6 +228,41 @@ interface VideoClipBase {
     transition?: VideoTransition;
     /** Provider effects on the picture, applied in order (see `VideoClipEffect`). */
     effects?: VideoClipEffect[];
+    /** A shape that cuts the picture out (see `VideoClipMask`). */
+    mask?: VideoClipMask;
+}
+/**
+ * The shape of a clip mask: `rectangle` (with `cornerRadius`), `ellipse`, `linear` (a straight
+ * split: what is on the side the angle points away from shows) or `polygon` (`points`).
+ */
+export type VideoMaskShape = 'rectangle' | 'ellipse' | 'linear' | 'polygon';
+export declare const VIDEO_MASK_SHAPES: readonly ["rectangle", "ellipse", "linear", "polygon"];
+/**
+ * A parametric mask on a clip's picture: only the inside of the shape shows (the outside with
+ * `inverted`). Positions and sizes are fractions of the clip's placed picture (0–1 across its
+ * width and height), so the mask moves, scales and turns with the clip.
+ */
+export interface VideoClipMask {
+    shape: VideoMaskShape;
+    /** Centre of the shape (or a point on a linear split's edge), as fractions of the picture (default 0.5, 0.5). */
+    x?: number;
+    y?: number;
+    /** Size as fractions of the picture's width and height (default 0.5 each; unused by linear). */
+    width?: number;
+    height?: number;
+    /** Degrees clockwise (default 0). For linear, 0 shows the top half. */
+    rotation?: number;
+    /** Soft edge width, in frame pixels (default 0). */
+    feather?: number;
+    /** Rectangle corners, as a fraction of half the shorter side (0–1, default 0). */
+    cornerRadius?: number;
+    /** Show the outside of the shape instead. */
+    inverted?: boolean;
+    /** For polygon: at least 3 points, as fractions of the picture. */
+    points?: {
+        x: number;
+        y: number;
+    }[];
 }
 /**
  * The shape of a sound fade, the same curves ffmpeg's `afade` draws, so previews and exports agree.
@@ -306,7 +347,26 @@ export interface VideoSequenceClip extends VideoClipBase {
 export interface VideoEffectClip extends VideoClipBase, VideoEffectRef {
     type: 'effect';
 }
-export type VideoClip = VideoMediaClip | VideoTextClip | VideoColorClip | VideoSequenceClip | VideoEffectClip;
+/**
+ * Which pictures an adjustment clip changes: `underneath` (every video track below its own, the
+ * default, as adjustment layers work in most editors), `all` (the whole frame, tracks above it
+ * included) or `track` (only the pictures of `targetTrack`).
+ */
+export type VideoAdjustmentScope = 'underneath' | 'all' | 'track';
+export declare const VIDEO_ADJUSTMENT_SCOPES: readonly ["underneath", "all", "track"];
+/**
+ * An adjustment clip: no picture of its own, but while it plays its grade, provider effects and
+ * mask apply to the composite of the pictures in its scope (see `VideoAdjustmentScope`). Its
+ * opacity (and fades) mix the adjusted picture over the unadjusted one. Lives on a video track.
+ */
+export interface VideoAdjustmentClip extends VideoClipBase {
+    type: 'adjustment';
+    /** Default `underneath`. */
+    scope?: VideoAdjustmentScope;
+    /** For scope `track`: the id of the track whose pictures it changes. */
+    targetTrack?: string;
+}
+export type VideoClip = VideoMediaClip | VideoTextClip | VideoColorClip | VideoSequenceClip | VideoEffectClip | VideoAdjustmentClip;
 export type VideoClipType = VideoClip['type'];
 /**
  * How a clip is placed where others already are: `refuse` an overlap (the default), `overwrite`
@@ -315,7 +375,7 @@ export type VideoClipType = VideoClip['type'];
  */
 export type VideoPlacementMode = 'refuse' | 'overwrite' | 'insert';
 export declare const VIDEO_PLACEMENT_MODES: readonly ["refuse", "overwrite", "insert"];
-export declare const VIDEO_CLIP_TYPES: readonly ["media", "text", "color", "sequence", "effect"];
+export declare const VIDEO_CLIP_TYPES: readonly ["media", "text", "color", "sequence", "effect", "adjustment"];
 export interface VideoMarker {
     id: string;
     time: number;

package/dist/video-editor/types.d.ts

@@ -160,6 +160,12 @@ export interface VideoGradeLut {
     strength?: number;
     /** A label for the look (default the file's TITLE or name). */
     name?: string;
+    /**
+     * How much of the LUT's change to hold back on skin tones, 0–1 (default 0): at 1 a pixel that
+     * looks like skin keeps its graded-but-un-LUT'd colour, so a heavy creative look leaves faces
+     * natural. Skin is found by chroma (see `videoSkinToneWeight`), with a soft edge.
+     */
+    preserveSkinTones?: number;
 }
 /**
  * Colour correction for a clip's picture (see `VIDEO_GRADE_CONTROLS` for ranges). Applied in a fixed
@@ -222,6 +228,41 @@ interface VideoClipBase {
     transition?: VideoTransition;
     /** Provider effects on the picture, applied in order (see `VideoClipEffect`). */
     effects?: VideoClipEffect[];
+    /** A shape that cuts the picture out (see `VideoClipMask`). */
+    mask?: VideoClipMask;
+}
+/**
+ * The shape of a clip mask: `rectangle` (with `cornerRadius`), `ellipse`, `linear` (a straight
+ * split: what is on the side the angle points away from shows) or `polygon` (`points`).
+ */
+export type VideoMaskShape = 'rectangle' | 'ellipse' | 'linear' | 'polygon';
+export declare const VIDEO_MASK_SHAPES: readonly ["rectangle", "ellipse", "linear", "polygon"];
+/**
+ * A parametric mask on a clip's picture: only the inside of the shape shows (the outside with
+ * `inverted`). Positions and sizes are fractions of the clip's placed picture (0–1 across its
+ * width and height), so the mask moves, scales and turns with the clip.
+ */
+export interface VideoClipMask {
+    shape: VideoMaskShape;
+    /** Centre of the shape (or a point on a linear split's edge), as fractions of the picture (default 0.5, 0.5). */
+    x?: number;
+    y?: number;
+    /** Size as fractions of the picture's width and height (default 0.5 each; unused by linear). */
+    width?: number;
+    height?: number;
+    /** Degrees clockwise (default 0). For linear, 0 shows the top half. */
+    rotation?: number;
+    /** Soft edge width, in frame pixels (default 0). */
+    feather?: number;
+    /** Rectangle corners, as a fraction of half the shorter side (0–1, default 0). */
+    cornerRadius?: number;
+    /** Show the outside of the shape instead. */
+    inverted?: boolean;
+    /** For polygon: at least 3 points, as fractions of the picture. */
+    points?: {
+        x: number;
+        y: number;
+    }[];
 }
 /**
  * The shape of a sound fade, the same curves ffmpeg's `afade` draws, so previews and exports agree.
@@ -306,7 +347,26 @@ export interface VideoSequenceClip extends VideoClipBase {
 export interface VideoEffectClip extends VideoClipBase, VideoEffectRef {
     type: 'effect';
 }
-export type VideoClip = VideoMediaClip | VideoTextClip | VideoColorClip | VideoSequenceClip | VideoEffectClip;
+/**
+ * Which pictures an adjustment clip changes: `underneath` (every video track below its own, the
+ * default, as adjustment layers work in most editors), `all` (the whole frame, tracks above it
+ * included) or `track` (only the pictures of `targetTrack`).
+ */
+export type VideoAdjustmentScope = 'underneath' | 'all' | 'track';
+export declare const VIDEO_ADJUSTMENT_SCOPES: readonly ["underneath", "all", "track"];
+/**
+ * An adjustment clip: no picture of its own, but while it plays its grade, provider effects and
+ * mask apply to the composite of the pictures in its scope (see `VideoAdjustmentScope`). Its
+ * opacity (and fades) mix the adjusted picture over the unadjusted one. Lives on a video track.
+ */
+export interface VideoAdjustmentClip extends VideoClipBase {
+    type: 'adjustment';
+    /** Default `underneath`. */
+    scope?: VideoAdjustmentScope;
+    /** For scope `track`: the id of the track whose pictures it changes. */
+    targetTrack?: string;
+}
+export type VideoClip = VideoMediaClip | VideoTextClip | VideoColorClip | VideoSequenceClip | VideoEffectClip | VideoAdjustmentClip;
 export type VideoClipType = VideoClip['type'];
 /**
  * How a clip is placed where others already are: `refuse` an overlap (the default), `overwrite`
@@ -315,7 +375,7 @@ export type VideoClipType = VideoClip['type'];
  */
 export type VideoPlacementMode = 'refuse' | 'overwrite' | 'insert';
 export declare const VIDEO_PLACEMENT_MODES: readonly ["refuse", "overwrite", "insert"];
-export declare const VIDEO_CLIP_TYPES: readonly ["media", "text", "color", "sequence", "effect"];
+export declare const VIDEO_CLIP_TYPES: readonly ["media", "text", "color", "sequence", "effect", "adjustment"];
 export interface VideoMarker {
     id: string;
     time: number;

package/dist/video-editor/ui.d.cts

@@ -1,6 +1,6 @@
 import type { VideoEdit } from './edit.cjs';
 import { type VideoKeyframeProperty } from './keyframes.cjs';
-import type { VideoClipAnimationEffect, VideoTransitionType, VideoAsset, VideoAssetKind, VideoBlendMode, VideoClip, VideoFadeCurve, VideoGradeLut, VideoPlacementMode, VideoProject, VideoSequence } from './types.cjs';
+import type { VideoAdjustmentScope, VideoClipMask, VideoMaskShape, VideoClipAnimationEffect, VideoTransitionType, VideoAsset, VideoAssetKind, VideoBlendMode, VideoClip, VideoFadeCurve, VideoGradeLut, VideoPlacementMode, VideoProject, VideoSequence } from './types.cjs';
 export interface VideoRulerTick {
     time: number;
     /** Pixels from the timeline's left edge. */
@@ -125,3 +125,23 @@ export declare function videoKeyframeToggleEdit(project: VideoProject, clipId: s
  * `null`. Clips without a grade change are left out; one `controller.apply` makes it one undo step.
  */
 export declare function videoLutEdits(project: VideoProject, clips: readonly string[], lut: VideoGradeLut | null): VideoEdit[];
+/** Labels for adjustment scopes, for inspectors. */
+export declare const VIDEO_ADJUSTMENT_SCOPE_LABELS: Readonly<Record<VideoAdjustmentScope, string>>;
+/** Labels for mask shapes, for inspectors. */
+export declare const VIDEO_MASK_SHAPE_LABELS: Readonly<Record<VideoMaskShape, string>>;
+/** What a clip is, for an inspector's heading. */
+export declare const videoClipHeading: (clip: Pick<VideoClip, "type">) => string;
+/**
+ * The edits that add an adjustment clip at `time` (default 3 s long) over everything: on the top
+ * track when it is a video track free there, else on a new video track added at the top. The clip
+ * starts with no look; give it a grade, effects or a mask.
+ */
+export declare function videoAddAdjustmentEdits(project: VideoProject, time: number, options?: {
+    duration?: number;
+    id?: string;
+    grade?: VideoClip['grade'];
+}): VideoEdit[];
+/** The edit that sets (or with `null` removes) a clip's mask. */
+export declare function videoMaskEdit(clip: string, mask: VideoClipMask | null): VideoEdit;
+/** The edits that set how much clips' LUTs hold back on skin (0 turns it off); clips without a LUT are skipped. */
+export declare function videoSkinProtectionEdits(project: VideoProject, clips: readonly string[], amount: number): VideoEdit[];

package/dist/video-editor/ui.d.ts

@@ -1,6 +1,6 @@
 import type { VideoEdit } from './edit.js';
 import { type VideoKeyframeProperty } from './keyframes.js';
-import type { VideoClipAnimationEffect, VideoTransitionType, VideoAsset, VideoAssetKind, VideoBlendMode, VideoClip, VideoFadeCurve, VideoGradeLut, VideoPlacementMode, VideoProject, VideoSequence } from './types.js';
+import type { VideoAdjustmentScope, VideoClipMask, VideoMaskShape, VideoClipAnimationEffect, VideoTransitionType, VideoAsset, VideoAssetKind, VideoBlendMode, VideoClip, VideoFadeCurve, VideoGradeLut, VideoPlacementMode, VideoProject, VideoSequence } from './types.js';
 export interface VideoRulerTick {
     time: number;
     /** Pixels from the timeline's left edge. */
@@ -125,3 +125,23 @@ export declare function videoKeyframeToggleEdit(project: VideoProject, clipId: s
  * `null`. Clips without a grade change are left out; one `controller.apply` makes it one undo step.
  */
 export declare function videoLutEdits(project: VideoProject, clips: readonly string[], lut: VideoGradeLut | null): VideoEdit[];
+/** Labels for adjustment scopes, for inspectors. */
+export declare const VIDEO_ADJUSTMENT_SCOPE_LABELS: Readonly<Record<VideoAdjustmentScope, string>>;
+/** Labels for mask shapes, for inspectors. */
+export declare const VIDEO_MASK_SHAPE_LABELS: Readonly<Record<VideoMaskShape, string>>;
+/** What a clip is, for an inspector's heading. */
+export declare const videoClipHeading: (clip: Pick<VideoClip, "type">) => string;
+/**
+ * The edits that add an adjustment clip at `time` (default 3 s long) over everything: on the top
+ * track when it is a video track free there, else on a new video track added at the top. The clip
+ * starts with no look; give it a grade, effects or a mask.
+ */
+export declare function videoAddAdjustmentEdits(project: VideoProject, time: number, options?: {
+    duration?: number;
+    id?: string;
+    grade?: VideoClip['grade'];
+}): VideoEdit[];
+/** The edit that sets (or with `null` removes) a clip's mask. */
+export declare function videoMaskEdit(clip: string, mask: VideoClipMask | null): VideoEdit;
+/** The edits that set how much clips' LUTs hold back on skin (0 turns it off); clips without a LUT are skipped. */
+export declare function videoSkinProtectionEdits(project: VideoProject, clips: readonly string[], amount: number): VideoEdit[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.160.0",
+  "version": "0.162.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",
@@ -244,6 +244,16 @@
         "default": "./dist/color/index.cjs"
       }
     },
+    "./typography": {
+      "import": {
+        "types": "./dist/typography/index.d.ts",
+        "default": "./dist/typography/index.js"
+      },
+      "require": {
+        "types": "./dist/typography/index.d.cts",
+        "default": "./dist/typography/index.cjs"
+      }
+    },
     "./gradient": {
       "import": {
         "types": "./dist/gradient/index.d.ts",

package/skills/README.md

@@ -18,11 +18,14 @@ that uses the tools can load the matching skill.
 | [`pixerate-paint-editor`](pixerate-paint-editor/SKILL.md) | Natural-media painting: paper and grain, dry-media brushes, the brush library, strokes as data, pigment mixing. |
 | [`pixerate-animation-editor`](pixerate-animation-editor/SKILL.md) | Vector animation: shots, commands, timing, Flair and Lottie. |
 | [`pixerate-video-editor`](pixerate-video-editor/SKILL.md) | Non-linear video editing: tracks, clips, transitions, export. |
+| [`pixerate-talking-head-edit`](pixerate-talking-head-edit/SKILL.md) | Talking-head cleanup by transcript: fillers, long pauses and stutters found in one pass and cut as one plan reviewed before it applies. |
+| [`pixerate-bgm-alignment`](pixerate-bgm-alignment/SKILL.md) | Background music: beats and cuts on the beat, ducking under speech, loudness in LUFS. |
 | [`pixerate-generation`](pixerate-generation/SKILL.md) | Planning, estimating and running paid media generation. |
 | [`pixerate-parameters`](pixerate-parameters/SKILL.md) | Effect parameters, presets and keyframes. |
 | [`pixerate-tokens`](pixerate-tokens/SKILL.md) | Design tokens: collections, modes, variables and aliases, through the whole-set document tools. |
 | [`pixerate-effect-authoring`](pixerate-effect-authoring/SKILL.md) | Authoring shaders and procedural effects: inspecting parameters and source code, setting values and presets, keyframing animation tracks, playback timing, and previewing. |
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
+| [`pixerate-typography`](pixerate-typography/SKILL.md) | Fonts and fallback stacks, font loading, modular type scales and hierarchies, fluid sizes, readability and type-aware contrast audits, text segmentation, the font picker. |
 
 ## Using them
 

package/skills/pixerate-bgm-alignment/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pixerate-bgm-alignment
+description: How to work with background music in the Pixerate video editor - finding a music track's tempo and beats, proposing cuts snapped to the beat as an edit plan for review, ducking music under speech with eased volume keyframes, measuring loudness in LUFS and normalising clips to streaming, podcast or broadcast targets, and shaping music outros. Use when asked to cut to the music, sync edits to a beat, lower music under dialogue, balance or normalise levels, or when find_video_beats, duck_video_music or normalize_video_loudness are available.
+---
+
+# Pixerate music and the mix
+
+Music sits on its own audio track under the picture and dialogue. Three jobs make it work:
+**cutting to it** (cuts that land on beats feel deliberate), **ducking it** (dipping it under
+speech so words stay clear) and **levelling it** (every clip at a consistent loudness, the mix
+at the delivery target). The tools here measure the sound itself, from the peaks the editor
+already decodes for waveforms, so the numbers match what the timeline shows.
+
+Loudness is in **LUFS** (ITU-R BS.1770, gated): what streaming services, podcasts and
+broadcasters measure. -14 LUFS for streaming and social, -16 for podcasts, -23 for EBU R128
+broadcast. Peaks in dBFS should stay under -1.
+
+This skill works with the video editor's own tools (`pixerate-video-editor`): tracks, clips,
+`set_video_keyframes`, `update_video_clip` fades, `apply_video_edit_plan`, `export_video_ffmpeg`
+loudness. See `pixerate-agent-tools` for errors and undo.
+
+## Working method
+
+1. **Find the music.** `get_video_project`: the music clip is usually on its own audio track.
+   Turn that track's `syncLocked` off (`update_video_track`) so ripple cuts in the dialogue do not
+   cut the music.
+2. **Find the beat.** `find_video_beats` with `clip` (timeline times) returns the `bpm`, a steady
+   `beats` grid and the `onsets` (each hit). If `bpm` is null the music has no steady pulse:
+   cut on the strongest onsets instead.
+3. **Cut on the beat.** `plan_video_beat_snap` with `music` (or `beats`) and the picture
+   `track` proposes rolling each cut to the nearest beat within `tolerance` (default 150 ms) as
+   one plan; it lists cuts it left (no beat near, already on one, not enough media). Show the
+   plan, then `apply_video_edit_plan`.
+4. **Duck under speech.** Once dialogue is final, `duck_video_music` with the music clips:
+   speech comes from the transcript (or from the dialogue track's sound with
+   `speech: "audio"`), and each music clip gets eased volume keyframes dipping `duck_db` under it.
+5. **Level.** `measure_video_loudness` on dialogue and music clips; `normalize_video_loudness`
+   sets clip volumes so each plays at a target (dialogue at -16 to -14 LUFS; music beds lower,
+   around -24 to -20 under speech). Normalise before ducking: ducking keys are relative to the
+   clip's volume when it is applied.
+6. **Finish.** A music bed ends on a fade: `update_video_clip` `fadeOut` 2000-4000 ms with
+   `fadeOutCurve` `exponential` (natural to silence) or `s-curve`. For delivery, export with
+   two-pass loudness (`export_video_loudness_measure`, then `export_video_ffmpeg` with
+   `loudness.measured`).
+
+## Best practices
+
+- **Cut on the downbeat for big changes.** Section changes land on the first beat of a bar
+  (every 4th beat in 4/4); shot changes inside a section can take any beat. Fast montages cut
+  every 1-2 beats, slower pieces every 4-8.
+- **Lead the beat slightly.** A cut a frame or two before the beat reads as on it; the eye takes
+  a moment to register a new shot.
+- **Duck by -12 to -18 dB.** -14 dB is a good default; quieter music needs less. An attack of
+  150-300 ms and a release of 300-600 ms sound natural; short releases pump.
+- **Keep gaps ducked.** `merge_gap` (default 600 ms) stops the music bobbing up between
+  sentences; raise it to 1000-1500 ms for slow, measured speech.
+- **Normalise clips, not the master.** Bring each clip to a sensible level so the mix is
+  balanced, then let the export's loudness pass set the final target.
+
+## Tool reference
+
+| Tool | When and how to use it |
+| --- | --- |
+| `find_video_beats` | Read-only. The tempo (`bpm`, null when the hits do not repeat), a steady `beats` grid and the `onsets` of a `clip` (timeline ms) or `asset` (source ms), optionally between `from` and `to`. `sensitivity` (default 1.5; lower finds more hits), `min_bpm` / `max_bpm` (default 60-200). Decodes the asset the first time. Use the beats for `plan_video_beat_snap`, markers or title timing. |
+| `plan_video_beat_snap` | Proposes rolling each cut on a `track` (default the first video track) to the nearest beat within `tolerance` ms (default 150), with beats from a `music` clip or given as `beats` (timeline ms). Roll edits keep everything else in place. Returns the plan (id, summary, `text`), how many cuts `moved` and the `skipped` ones with a reason. Nothing changes until `apply_video_edit_plan`. |
+| `duck_video_music` | Dips `music` clips under speech with volume keyframes (one undo step): `duck_db` (default -14), `attack` (default 200 ms), `release` (default 400 ms), `merge_gap` (default 600 ms). Speech from the transcript (`speech: "transcript"`, the default when there is one) or from where `dialogue_track`'s sound is above -40 dBFS (`speech: "audio"`). Refuses clips with volume keyframes unless `replace: true`. Returns the speech stretches and each clip's keys. |
+| `measure_video_loudness` | Read-only. Integrated loudness (`lufs`, null for silence) and sample `peakDb` of a `clip` or `asset` stretch, before clip volume, with `toStreaming` (the gain to -14 LUFS that keeps the peak under -1 dBFS). |
+| `normalize_video_loudness` | Sets each of `clips`' volume so it plays at `target` LUFS (default -14) with its peak under `ceiling` (default -1 dBFS) and at most 4x gain (one undo step). Skips silent clips; refuses volume keyframes unless `replace: true`. Returns each clip's `lufs`, `gain`, `gainDb` and `limitedBy` when a cap held it short. |
+
+## Pitfalls
+
+- **Ducking before the dialogue is final.** Ducking keys are placed at the speech as it is now.
+  Clean up and re-time dialogue first, then duck; if speech moves later, duck again with
+  `replace: true`.
+- **Normalising a ducked clip.** `normalize_video_loudness` sets a constant volume, which would
+  replace ducking keys; it refuses unless `replace: true`. Normalise first, then duck.
+- **Beat grids drift on live music.** A steady grid suits programmed music. For a live band, snap
+  to `onsets` (pass them as `beats`) instead of the grid.
+- **Sync-locked music gets cut.** A ripple cut or extract on dialogue cuts every sync-locked
+  track, including the music. Turn the music track's `syncLocked` off first.
+- **Peaks, not true peaks.** The tools measure sample peaks; the export's `loudnorm` limits true
+  peaks. Leave a decibel of headroom.

package/skills/pixerate-talking-head-edit/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pixerate-talking-head-edit
+description: How to clean up talking-head, interview, podcast and voiceover video in the Pixerate video editor by its transcript - finding filler words, long pauses and stutters in one pass, reviewing them, proposing the cuts as one edit plan the user previews before it applies, keeping breath around cuts, and checking the result. Use when asked to tighten dialogue, remove ums and ahs, cut dead air, clean up a talking head or make a rough cut of an interview, or when find_video_disfluencies or plan_video_dialogue_cleanup are available.
+---
+
+# Pixerate talking-head cleanup
+
+Spoken media in a video project carries a **transcript**: each word with its start and end in
+the source. The editor maps the words through the clips onto the timeline, so a word's place is
+always where it plays now, however the clips were cut. Cleaning up speech is then a matter of
+finding stretches of the timeline (fillers, long pauses, stutters) and cutting them out on every
+sync-locked track at once, so picture, sound and B-roll stay in sync.
+
+Cleanup is **plan first**: propose the cuts as one plan, let the user review it (the editor
+shows the plan with its length change and every stretch it cuts), then apply it as one undo step.
+Never cut a whole interview's disfluencies without a review.
+
+This skill works with the video editor's own tools (`pixerate-video-editor`): transcripts,
+`get_video_transcript`, `remove_video_ranges`, `apply_video_edit_plan`, `render_video_frame`.
+See `pixerate-agent-tools` for errors and undo.
+
+## Working method
+
+1. **Make sure there is a transcript.** `get_video_project` shows which assets have one; if the
+   speech has none, ask the host or user for a Whisper-style JSON, `.srt` or `.vtt` file and
+   attach it with `set_video_transcript`. Captions without word timings are approximate: cuts
+   on them may clip words, so prefer word-timed transcripts.
+2. **Read the speech.** `get_video_transcript` for the text and the word list (the indexes the
+   find tool returns refer to it).
+3. **Find what to tidy.** `find_video_disfluencies` lists fillers (um, uh, er, you know, I
+   mean…), pauses longer than `min_pause` (default 700 ms, keeping `keep` ms of breath either
+   side) and repeated words or phrases ("I I think", "we should we should"), with a total per
+   kind and how much time the cuts would remove.
+4. **Review.** Read the list against the transcript. Keep repeats that are meant ("very very"),
+   pauses that land a point, and fillers that carry meaning ("like" and "so" are not in the
+   defaults for that reason). Note the `from` times of finds to keep.
+5. **Propose.** `plan_video_dialogue_cleanup` with the same options and `exclude` (the `from`
+   times to keep) proposes the cuts as one plan; nothing changes yet. Tell the user what it does
+   (its `text`: stretches and seconds removed) and ask them to review it in the editor.
+6. **Apply.** Once they agree, `apply_video_edit_plan` with the plan id (or
+   `discard_video_edit_plan`). If they edited meanwhile, the plan is re-checked; if it no longer
+   applies, find and plan again.
+7. **Check.** `get_video_transcript` again (every time after a cut moved), listen at a few cuts
+   with `get_video_frame` (audio gains) and look with `render_video_frame` for jump cuts in the
+   picture: cover those with B-roll on a higher track or a slight push-in (`set_video_keyframes`
+   `scale` 1 to 1.05).
+
+## Best practices
+
+- **Breath matters.** Cut pauses down, not out: keep 150-250 ms either side (`keep`) so speech
+  does not sound breathless. For fillers and stutters, `margin` 20-60 ms avoids clipping the
+  words around a cut when word timings are loose.
+- **Brisk or relaxed.** For social clips and explainers, `min_pause` 500-600 ms; for
+  interviews and documentary, 900-1200 ms so thinking pauses stay.
+- **One plan, one undo.** Propose the whole cleanup as one plan rather than many small cuts:
+  the user reviews it once and can undo it in one step.
+- **Words cut with their picture.** The cut runs across every unlocked sync-locked track. A
+  music bed that should keep playing must have `syncLocked: false` (`update_video_track`)
+  before the plan is applied, or it is cut too.
+- **Duck music after cleanup.** Speech has moved, so duck background music once the dialogue
+  is final (`duck_video_music`, in `pixerate-bgm-alignment`).
+
+## Tool reference
+
+| Tool | When and how to use it |
+| --- | --- |
+| `find_video_disfluencies` | Read-only. Lists fillers, long pauses and stutters in time order as `{ kind, from, to, text, words }` (timeline ms; `words` are the first and last indexes in `get_video_transcript`'s list; for a pause, the words either side), with `totals` per kind and `removable` time once merged. Options: `track`, `kinds` (`filler`, `pause`, `repetition`), `fillers` (your own list), `min_pause` (ms, default 700), `keep` (breath either side of a pause cut, default 150), `max_phrase` (longest repeat checked, default 3 words). Review it before planning. |
+| `plan_video_dialogue_cleanup` | Proposes cutting the finds as one plan for review (nothing changes): the same options as the find tool, plus `exclude` (the `from` times of finds to keep), `margin` (ms left at each end of filler and stutter cuts, default 0) and a `title`. Returns the plan (id, title, summary with the length change, `text`) and a hint. Apply with `apply_video_edit_plan`, or `discard_video_edit_plan`. Fails when nothing is left to cut. |
+
+## Pitfalls
+
+- **Overlapping finds.** A filler inside a stutter is listed twice; the plan merges the ranges,
+  so it is cut once. Do not add the same stretch again through `remove_video_ranges`.
+- **Stale plans.** Applying a plan after other edits re-checks it; if it is refused, run the find
+  and plan again rather than applying old times by hand.
+- **Approximate transcripts.** Captions spread words evenly over each cue, so a "filler" may be a
+  neighbour's syllable. Check the find's `text` against `get_video_transcript`, and prefer
+  word-timed transcripts for cleanup.
+- **Transcripts come from the host.** Speech recognition is the host's job: the editor never sends
+  media anywhere. Ask for a transcript rather than guessing words from audio levels.

package/skills/pixerate-typography/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: pixerate-typography
+description: How to choose and load fonts, build resilient font-family fallback stacks, generate modular type scales and heading hierarchies, compute fluid clamp() sizes, audit body text for line length and line spacing, check text contrast with the real font size and weight, split text into letters, words or lines for animation, and drive a font picker. Use when asked to pick or pair fonts, set up type tokens, check readability or legibility, or animate live text.
+---
+
+# Typography tools
+
+The typography module is DOM-free: it works on numbers (px sizes, unitless line-heights, em
+tracking) and family names, never on rendered pixels. Fonts come from a **font provider** the
+host supplies (installed system fonts, a web font service, a design system's families); by
+default it is a catalog of common system fonts, which says what is *usually* installed, not
+what this machine has.
+
+## Mental model
+
+- A **font spec** is `{ family, weight, style, size (px), lineHeight (unitless), letterSpacing (em) }`.
+- A **type scale** multiplies a base size by a ratio per step (`16 × 1.25² = 25`). A **hierarchy**
+  names the steps: `caption` (−2), `body-sm`, `body` (0), `h4`, `h3`, `h2`, `h1`, `display` (5).
+- A **fallback stack** is the `font-family` value: your family, then a tested cross-platform stack
+  for its category, ending in a generic family, so text still renders when the font is missing.
+- **Large text** under WCAG 2 is 24px, or 18.67px (14pt) at weight 700+. It needs 3:1 contrast
+  for AA instead of 4.5:1. The accessibility tool decides this from the spec for you.
+
+## Working method
+
+1. **Find fonts.** `list_fonts` with `category`, `weight`, `style` or `query`. Only use families it
+   returns (or that the user names), and always ship them inside a stack from `resolve_font_stack`.
+2. **Load before rendering.** `load_font` before drawing or capturing text in a web font, so the
+   first frame does not use the fallback. `loaded: false` means the fallback will show.
+3. **Set up the scale.** `generate_type_hierarchy` for named tokens and ready CSS custom
+   properties; `suggest_type_scale` for arbitrary steps. Smaller ratios (minor/major third) suit
+   dense UI; larger ones (perfect fourth/fifth, golden) suit editorial and marketing pages.
+4. **Make it fluid (optional).** `compute_fluid_type_size` for headings that grow between two
+   viewport widths. Bounds are in rem so browser zoom and font-size settings still work.
+5. **Audit the body text.** `audit_text_readability` with the real text, `fontSize`, `lineHeight`
+   and the column `width`: fix `lineLength.status` (45–75 characters) and `lineSpacing`
+   (at least 1.5) before polishing anything else.
+6. **Check contrast with the type.** `check_typography_accessibility` with foreground, background,
+   `fontSize` and `fontWeight`. Use `suggestion` when `passesAA` is false. For pure colour work
+   (palettes, dual colours) use the `pixerate-color` tools.
+7. **Animate live text.** `segment_text` splits into `grapheme`, `word` (with `wordsOnly`),
+   `sentence` or `line` (with `maxCharacters` to wrap) and returns UTF-16 `start` / `end`
+   offsets, so letters and words can be staggered without converting text to outlines.
+8. **Drive the on-screen picker.** When a font picker is mounted, `get_font_selection` shows what
+   is chosen, `list_picker_fonts` what it offers, and `set_font_selection` changes any fields in
+   one step and returns the new selection.
+
+## Best practices
+
+- **Two families are usually enough**: one for text, optionally one for headings. Pair by contrast
+  of category (serif headings with sans text, or the reverse), not by two similar sans-serifs.
+- **Body text at 16px or more**, line-height 1.5–1.7, about 66 characters per line
+  (`max-width: 66ch`). Headings get tighter leading (1.1–1.3) and slightly negative tracking; small
+  captions slightly positive tracking. The scale tools already recommend these.
+- **Use weight 400+ below 24px.** Thin weights lower effective contrast even when the ratio passes.
+- **Avoid long runs of capitals** for body text; keep all-caps to short labels.
+- **Prefer rem and clamp()** over fixed px for type on the web, so user settings apply.
+- **Never assume a font is installed.** A system font in the catalog may be missing on Linux or
+  Android; the fallback stack is what makes that safe.
+
+## Tool reference
+
+| Tool | When to use | Returns |
+| --- | --- | --- |
+| `list_fonts` | Discover families the host offers; filter by `category`, `source`, `weight`, `style`, `query`; `limit` default 50 | `{ fonts: [{ family, category, weights, styles, isVariable?, source }], total, truncated }` |
+| `resolve_font_stack` | Turn a family (or stack) into a resilient `font-family` value for its category; also says if the provider lists it | `{ stack, families, category, available }` |
+| `suggest_type_scale` | Sizes for arbitrary integer `steps` (-12…12) from `baseSize` (px, default 16) and `ratio` (name or number, default major-third) | `{ ratio, baseSize, steps: [{ name, step, size, lineHeight, letterSpacing }] }` |
+| `generate_type_hierarchy` | Named tokens caption…display on one scale, with CSS custom properties (`prefix`, `selector`) | `{ ratio, ratioName?, baseSize, steps: { body, h1, … }, css }` |
+| `compute_fluid_type_size` | A size that grows from `minSize` at `minViewport` to `maxSize` at `maxViewport` (all px) | `{ clampCss, slope, intercept, samples }` |
+| `audit_text_readability` | Check body text: line length (own lines, or `width` + `fontSize`), line spacing, capitals, tiny or tight type, reading time | `{ lineLength, lineSpacing, allCaps, wordCount, estimatedReadingTimeSeconds, issues }` |
+| `check_typography_accessibility` | Contrast for text of a given `fontSize` (px) and `fontWeight`, deciding large text itself; suggests a passing foreground | `{ ratio, large, level, passesAA, passesAAA, required, suggestion?, largeTextMinSize, issues }` |
+| `segment_text` | Split text into graphemes, words, sentences or lines with offsets, for staggered animation | `{ segments: [{ text, start, end, index, isWordLike? }], count }` |
+| `load_font` | Load a family's face (`weight`, `style`) before rendering or capturing; only listed when the provider can load | `{ family, weight, style, loaded }` |
+| `get_font_selection` | Read the mounted font picker's value, CSS and the chosen family's weights and styles | `{ value, css, availableWeights, availableStyles }` |
+| `list_picker_fonts` | Families the mounted picker offers (by `category`, `query`), plus recent families | `{ fonts, recent, total, truncated }` |
+| `set_font_selection` | Change the picker's family, weight, style, size, lineHeight or letterSpacing in one validated step; weights snap to what the family has | `{ value, css, availableWeights, availableStyles }` |
+
+## Pitfalls
+
+- **Sizes are CSS px.** 12pt is 16px; 18pt is 24px. Convert before calling the tools.
+- **lineHeight is a multiplier**, not px: 24px leading on 16px text is `1.5`. When it is omitted
+  the audit assumes the browser's `normal` (about 1.2) and says so with `assumed: true`.
+- **`line` segmentation does not know the renderer's wrapping.** Without `maxCharacters` it only
+  splits on line breaks; with it, it wraps by character count, which approximates proportional
+  fonts.
+- **A one-line string is not a measure.** `too-short` on a single heading is expected; pass the
+  column `width` and `fontSize` to estimate how paragraphs will wrap.
+- **The system catalog is not detection.** Without the host opting into Local Font Access,
+  `list_fonts` lists commonly installed fonts. Always use `resolve_font_stack` output.
+- **Picker fonts may differ from `list_fonts`.** `set_font_selection` only accepts families the
+  picker lists; check with `list_picker_fonts`.