pixi-effects 0.3.0 → 0.5.0

package/dist/{types-3c8Vymgw.d.ts → types-7VtTEKUW.d.cts}

@@ -174,6 +174,12 @@ interface SequenceCommon {
      * Routed through PIXI's native `setMask({ inverse: true })`.
      */
     maskInverted?: boolean;
+    /**
+     * How this layer blends with what is behind it. `'add'` and `'screen'` brighten (glows, light leaks,
+     * overlapping halos add up instead of covering each other), `'multiply'` darkens. Default `'normal'`.
+     * On a composition the mode is inherited by its children: each one blends with what is behind it.
+     */
+    blendMode?: 'normal' | 'add' | 'screen' | 'multiply';
     /**
      * Opt this layer into 2.5D: it can then use `z`, `rotationX`, `rotationY`
      * (in `initial` / keyframes) and is projected through the composition's
@@ -211,7 +217,8 @@ interface TextSequenceSpec extends SequenceCommon {
     /** How `{value}` is printed: `decimals` (default 0) and thousands `grouping` (default false). */
     format?: {
         decimals?: number;
-        grouping?: boolean;
+        grouping?: boolean; /** Zero-pad the whole part to this many digits (`pad: 2` → `05`; a clock `18:42:05`). */
+        pad?: number;
     };
     /** Subset of PIXI v8 TextStyleOptions. String values may be exprs (e.g. fontSize: 'GW * 0.05'). */
     style?: Record<string, PropValue | {
@@ -226,12 +233,71 @@ interface TextSequenceSpec extends SequenceCommon {
      */
     colorSpace?: 'rgb' | 'oklab' | 'oklch';
 }
-interface AudioSequenceSpec extends SequenceCommon {
+type SfxPreset = 'click' | 'pop' | 'swoosh' | 'swipe' | 'hit' | 'riser' | 'chime' | 'beep' | 'coin' | 'glitch' | 'typewriter';
+/** The intent-level knobs shared by presets and custom sounds. */
+interface SfxKnobs {
+    /** Semitones up (+) or down (−); 12 = one octave. Default 0, range ±24. */
+    pitch?: number;
+    /** −1 = dark / muffled … 0 = as designed … 1 = bright / crisp. Default 0. */
+    brightness?: number;
+    /** Another take of the random parts (noise grain, glitch pattern, typewriter key). Same seed ⇒ same sound. Default 0. */
+    seed?: number;
+}
+/**
+ * One layer of a custom sound. Most sounds are one or two voices: noise through a moving band-pass
+ * (whooshes, air, impacts) or a tone with a pitch sweep (blips, zaps, drops).
+ */
+interface SfxVoice {
+    /** `'noise'` for air, hiss and impacts; a waveform for tones. */
+    wave: 'sine' | 'triangle' | 'square' | 'saw' | 'noise';
+    /** Tone frequency in Hz, or `[from, to]` to sweep (exponentially). Ignored for noise. Default 440. */
+    freq?: number | [number, number];
+    /** Keeps part of the spectrum; `freq` may sweep: `{ type: 'bandpass', freq: [500, 5000] }` = a band of noise rising. `q` default 0.7 (≥ 0.7). */
+    filter?: {
+        type: 'lowpass' | 'highpass' | 'bandpass';
+        freq: number | [number, number];
+        q?: number;
+    };
+    /** Level over the voice: `'fall'` (default) hit then decay · `'bell'` swell then fade · `'swell'` grow to the end · `'hold'` steady. */
+    envelope?: 'fall' | 'bell' | 'swell' | 'hold';
+    /** −1 left … 1 right, or `[from, to]` to move. Default 0. */
+    pan?: number | [number, number];
+    /** The part of the sound this voice plays, as fractions 0–1 of its length. Default 0 and 1. */
+    from?: number;
+    to?: number;
+    /** Level relative to the other voices. Default 1. */
+    gain?: number;
+}
+/** A preset with knobs, or a custom sound made of `voices` (length = the layer's duration, default 0.5 s). */
+type SfxOptions = (SfxKnobs & {
+    preset: SfxPreset;
+    voices?: never;
+}) | (SfxKnobs & {
+    voices: SfxVoice[];
+    preset?: never;
+});
+interface AudioBase extends SequenceCommon {
     type: 'audio';
+    /** Level. 1 = the file as recorded, or the sfx preset's standard level (peaks at −12 dBFS). Animatable. */
+    volume?: number;
+}
+/** Plays an audio file from `assets`. `duration` defaults to the file's length (with `loop`: to the composition's end). */
+interface AudioAssetSpec extends AudioBase {
     asset: string;
+    sfx?: never;
+    /** Repeat the file for the whole `duration`. Without it the layer goes silent when the file ends. */
     loop?: boolean;
-    volume?: number;
 }
+/**
+ * Plays a synthesised sound effect. `duration` IS the sound's length: omitted, it is the preset's own
+ * length; given, the sound is stretched or shortened to it. `at` is where the sound starts.
+ */
+interface AudioSfxSpec extends AudioBase {
+    sfx: SfxPreset | SfxOptions;
+    asset?: never;
+    loop?: never;
+}
+type AudioSequenceSpec = AudioAssetSpec | AudioSfxSpec;
 interface CompositionSequenceSpec extends SequenceCommon {
     type: 'composition';
     width?: number;
@@ -287,6 +353,10 @@ interface ShapeBase extends SequenceCommon {
      *   sweeps; `oklab` is straight-line in the chromaticity plane.
      */
     colorSpace?: 'rgb' | 'oklab' | 'oklch';
+    /** How an open stroke ends: `'butt'` (default), `'round'` (a friendly progress-ring end) or `'square'`. Top level or in `initial`. */
+    strokeCap?: 'butt' | 'round' | 'square';
+    /** How stroke corners join: `'miter'` (default; sharp points can poke out), `'round'` or `'bevel'`. Top level or in `initial`. */
+    strokeJoin?: 'miter' | 'round' | 'bevel';
 }
 interface RectShapeSpec extends ShapeBase {
     shape: 'rect';
@@ -318,6 +388,22 @@ interface EllipseShapeSpec extends ShapeBase {
     anchorX?: PropValue;
     anchorY?: PropValue;
 }
+/**
+ * An arc around the local origin (its centre). Angles are in degrees: 0 = 3 o'clock, positive = clockwise,
+ * so a progress ring starts at `startAngle: -90` (12 o'clock) and animates `endAngle` from -90 to 270.
+ * With a stroke and no fill it is an open arc line (`strokeCap: 'round'` for rounded ends); with a fill it is a
+ * sector (a pie slice), and with `innerRadius` a ring segment (a donut slice). A sweep of 360° or more is a full circle.
+ */
+interface ArcShapeSpec extends ShapeBase {
+    shape: 'arc';
+    radius: PropValue;
+    /** Hole radius of a filled ring segment. Default 0 (a pie slice to the centre). Animatable. */
+    innerRadius?: PropValue;
+    /** Degrees. Default 0. Animatable. */
+    startAngle?: PropValue;
+    /** Degrees. Default 360. Animatable. */
+    endAngle?: PropValue;
+}
 interface LineShapeSpec extends ShapeBase {
     shape: 'line';
     /** Line endpoints relative to the shape's local origin. */
@@ -336,7 +422,7 @@ interface PathShapeSpec extends ShapeBase {
     /** SVG path data (`d` attribute). Goes through PIXI's GraphicsContext.svg(). */
     d: string;
 }
-type ShapeSequenceSpec = RectShapeSpec | CircleShapeSpec | EllipseShapeSpec | LineShapeSpec | PolygonShapeSpec | PathShapeSpec;
+type ShapeSequenceSpec = RectShapeSpec | CircleShapeSpec | EllipseShapeSpec | ArcShapeSpec | LineShapeSpec | PolygonShapeSpec | PathShapeSpec;
 type SequenceSpec = VideoSequenceSpec | ImageSequenceSpec | TextSequenceSpec | AudioSequenceSpec | CompositionSequenceSpec | CameraSequenceSpec | ShapeSequenceSpec;
 /** Top-level composition (root node) — same as `CompositionSequenceSpec` minus the discriminant. */
 interface CompositionSpec extends SequenceCommon {
@@ -353,7 +439,17 @@ interface CompositionShape {
 }
 /** Audio descriptor pushed to the mixdown queue by AudioSequence/VideoSequence. */
 interface AudioDescriptor {
-    buffer: AudioBuffer;
+    /** Decoded audio (a file or a video's soundtrack). Exactly one of `buffer` / `synth` is set. */
+    buffer?: AudioBuffer;
+    /** Stereo samples (left, right) made on demand at the mix's sample rate (a synthesised sfx). Equal keys render equal samples. */
+    synth?: {
+        key: string;
+        render: (sampleRate: number) => [Float32Array, Float32Array];
+    };
+    /** Who made it, for warnings and inspectAudio: `layer "pop-1"`. */
+    layer?: string;
+    /** What it plays: `sfx "pop"`, `asset "bgm"`, `video "green"`. */
+    source?: string;
     loop: boolean;
     start: number;
     end: number;
@@ -364,4 +460,4 @@ interface AudioDescriptor {
     }[];
 }
 
-export type { AssetSpec as A, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AudioSequenceSpec as c, ChromaKeyFilterSpec as d, CircleShapeSpec as e, CompositionSequenceSpec as f, CompositionSpec as g, CrossfadeTransition as h, CustomFilterSpec as i, DissolveTransition as j, Expr as k, IrisTransition as l, PolygonShapeSpec as m, PropValue as n, Props as o, ShapeSequenceSpec as p, SlideTransition as q, TransitionCommon as r, TransitionSpec as s, AudioDescriptor as t };
+export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };

package/dist/{types-3c8Vymgw.d.cts → types-7VtTEKUW.d.ts}

@@ -174,6 +174,12 @@ interface SequenceCommon {
      * Routed through PIXI's native `setMask({ inverse: true })`.
      */
     maskInverted?: boolean;
+    /**
+     * How this layer blends with what is behind it. `'add'` and `'screen'` brighten (glows, light leaks,
+     * overlapping halos add up instead of covering each other), `'multiply'` darkens. Default `'normal'`.
+     * On a composition the mode is inherited by its children: each one blends with what is behind it.
+     */
+    blendMode?: 'normal' | 'add' | 'screen' | 'multiply';
     /**
      * Opt this layer into 2.5D: it can then use `z`, `rotationX`, `rotationY`
      * (in `initial` / keyframes) and is projected through the composition's
@@ -211,7 +217,8 @@ interface TextSequenceSpec extends SequenceCommon {
     /** How `{value}` is printed: `decimals` (default 0) and thousands `grouping` (default false). */
     format?: {
         decimals?: number;
-        grouping?: boolean;
+        grouping?: boolean; /** Zero-pad the whole part to this many digits (`pad: 2` → `05`; a clock `18:42:05`). */
+        pad?: number;
     };
     /** Subset of PIXI v8 TextStyleOptions. String values may be exprs (e.g. fontSize: 'GW * 0.05'). */
     style?: Record<string, PropValue | {
@@ -226,12 +233,71 @@ interface TextSequenceSpec extends SequenceCommon {
      */
     colorSpace?: 'rgb' | 'oklab' | 'oklch';
 }
-interface AudioSequenceSpec extends SequenceCommon {
+type SfxPreset = 'click' | 'pop' | 'swoosh' | 'swipe' | 'hit' | 'riser' | 'chime' | 'beep' | 'coin' | 'glitch' | 'typewriter';
+/** The intent-level knobs shared by presets and custom sounds. */
+interface SfxKnobs {
+    /** Semitones up (+) or down (−); 12 = one octave. Default 0, range ±24. */
+    pitch?: number;
+    /** −1 = dark / muffled … 0 = as designed … 1 = bright / crisp. Default 0. */
+    brightness?: number;
+    /** Another take of the random parts (noise grain, glitch pattern, typewriter key). Same seed ⇒ same sound. Default 0. */
+    seed?: number;
+}
+/**
+ * One layer of a custom sound. Most sounds are one or two voices: noise through a moving band-pass
+ * (whooshes, air, impacts) or a tone with a pitch sweep (blips, zaps, drops).
+ */
+interface SfxVoice {
+    /** `'noise'` for air, hiss and impacts; a waveform for tones. */
+    wave: 'sine' | 'triangle' | 'square' | 'saw' | 'noise';
+    /** Tone frequency in Hz, or `[from, to]` to sweep (exponentially). Ignored for noise. Default 440. */
+    freq?: number | [number, number];
+    /** Keeps part of the spectrum; `freq` may sweep: `{ type: 'bandpass', freq: [500, 5000] }` = a band of noise rising. `q` default 0.7 (≥ 0.7). */
+    filter?: {
+        type: 'lowpass' | 'highpass' | 'bandpass';
+        freq: number | [number, number];
+        q?: number;
+    };
+    /** Level over the voice: `'fall'` (default) hit then decay · `'bell'` swell then fade · `'swell'` grow to the end · `'hold'` steady. */
+    envelope?: 'fall' | 'bell' | 'swell' | 'hold';
+    /** −1 left … 1 right, or `[from, to]` to move. Default 0. */
+    pan?: number | [number, number];
+    /** The part of the sound this voice plays, as fractions 0–1 of its length. Default 0 and 1. */
+    from?: number;
+    to?: number;
+    /** Level relative to the other voices. Default 1. */
+    gain?: number;
+}
+/** A preset with knobs, or a custom sound made of `voices` (length = the layer's duration, default 0.5 s). */
+type SfxOptions = (SfxKnobs & {
+    preset: SfxPreset;
+    voices?: never;
+}) | (SfxKnobs & {
+    voices: SfxVoice[];
+    preset?: never;
+});
+interface AudioBase extends SequenceCommon {
     type: 'audio';
+    /** Level. 1 = the file as recorded, or the sfx preset's standard level (peaks at −12 dBFS). Animatable. */
+    volume?: number;
+}
+/** Plays an audio file from `assets`. `duration` defaults to the file's length (with `loop`: to the composition's end). */
+interface AudioAssetSpec extends AudioBase {
     asset: string;
+    sfx?: never;
+    /** Repeat the file for the whole `duration`. Without it the layer goes silent when the file ends. */
     loop?: boolean;
-    volume?: number;
 }
+/**
+ * Plays a synthesised sound effect. `duration` IS the sound's length: omitted, it is the preset's own
+ * length; given, the sound is stretched or shortened to it. `at` is where the sound starts.
+ */
+interface AudioSfxSpec extends AudioBase {
+    sfx: SfxPreset | SfxOptions;
+    asset?: never;
+    loop?: never;
+}
+type AudioSequenceSpec = AudioAssetSpec | AudioSfxSpec;
 interface CompositionSequenceSpec extends SequenceCommon {
     type: 'composition';
     width?: number;
@@ -287,6 +353,10 @@ interface ShapeBase extends SequenceCommon {
      *   sweeps; `oklab` is straight-line in the chromaticity plane.
      */
     colorSpace?: 'rgb' | 'oklab' | 'oklch';
+    /** How an open stroke ends: `'butt'` (default), `'round'` (a friendly progress-ring end) or `'square'`. Top level or in `initial`. */
+    strokeCap?: 'butt' | 'round' | 'square';
+    /** How stroke corners join: `'miter'` (default; sharp points can poke out), `'round'` or `'bevel'`. Top level or in `initial`. */
+    strokeJoin?: 'miter' | 'round' | 'bevel';
 }
 interface RectShapeSpec extends ShapeBase {
     shape: 'rect';
@@ -318,6 +388,22 @@ interface EllipseShapeSpec extends ShapeBase {
     anchorX?: PropValue;
     anchorY?: PropValue;
 }
+/**
+ * An arc around the local origin (its centre). Angles are in degrees: 0 = 3 o'clock, positive = clockwise,
+ * so a progress ring starts at `startAngle: -90` (12 o'clock) and animates `endAngle` from -90 to 270.
+ * With a stroke and no fill it is an open arc line (`strokeCap: 'round'` for rounded ends); with a fill it is a
+ * sector (a pie slice), and with `innerRadius` a ring segment (a donut slice). A sweep of 360° or more is a full circle.
+ */
+interface ArcShapeSpec extends ShapeBase {
+    shape: 'arc';
+    radius: PropValue;
+    /** Hole radius of a filled ring segment. Default 0 (a pie slice to the centre). Animatable. */
+    innerRadius?: PropValue;
+    /** Degrees. Default 0. Animatable. */
+    startAngle?: PropValue;
+    /** Degrees. Default 360. Animatable. */
+    endAngle?: PropValue;
+}
 interface LineShapeSpec extends ShapeBase {
     shape: 'line';
     /** Line endpoints relative to the shape's local origin. */
@@ -336,7 +422,7 @@ interface PathShapeSpec extends ShapeBase {
     /** SVG path data (`d` attribute). Goes through PIXI's GraphicsContext.svg(). */
     d: string;
 }
-type ShapeSequenceSpec = RectShapeSpec | CircleShapeSpec | EllipseShapeSpec | LineShapeSpec | PolygonShapeSpec | PathShapeSpec;
+type ShapeSequenceSpec = RectShapeSpec | CircleShapeSpec | EllipseShapeSpec | ArcShapeSpec | LineShapeSpec | PolygonShapeSpec | PathShapeSpec;
 type SequenceSpec = VideoSequenceSpec | ImageSequenceSpec | TextSequenceSpec | AudioSequenceSpec | CompositionSequenceSpec | CameraSequenceSpec | ShapeSequenceSpec;
 /** Top-level composition (root node) — same as `CompositionSequenceSpec` minus the discriminant. */
 interface CompositionSpec extends SequenceCommon {
@@ -353,7 +439,17 @@ interface CompositionShape {
 }
 /** Audio descriptor pushed to the mixdown queue by AudioSequence/VideoSequence. */
 interface AudioDescriptor {
-    buffer: AudioBuffer;
+    /** Decoded audio (a file or a video's soundtrack). Exactly one of `buffer` / `synth` is set. */
+    buffer?: AudioBuffer;
+    /** Stereo samples (left, right) made on demand at the mix's sample rate (a synthesised sfx). Equal keys render equal samples. */
+    synth?: {
+        key: string;
+        render: (sampleRate: number) => [Float32Array, Float32Array];
+    };
+    /** Who made it, for warnings and inspectAudio: `layer "pop-1"`. */
+    layer?: string;
+    /** What it plays: `sfx "pop"`, `asset "bgm"`, `video "green"`. */
+    source?: string;
     loop: boolean;
     start: number;
     end: number;
@@ -364,4 +460,4 @@ interface AudioDescriptor {
     }[];
 }
 
-export type { AssetSpec as A, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AudioSequenceSpec as c, ChromaKeyFilterSpec as d, CircleShapeSpec as e, CompositionSequenceSpec as f, CompositionSpec as g, CrossfadeTransition as h, CustomFilterSpec as i, DissolveTransition as j, Expr as k, IrisTransition as l, PolygonShapeSpec as m, PropValue as n, Props as o, ShapeSequenceSpec as p, SlideTransition as q, TransitionCommon as r, TransitionSpec as s, AudioDescriptor as t };
+export type { ArcShapeSpec as A, AudioDescriptor as B, CompositionShape as C, DipTransition as D, EllipseShapeSpec as E, FilterSpec as F, GradientSpec as G, ImageSequenceSpec as I, Keyframe as K, LineShapeSpec as L, PathShapeSpec as P, RectShapeSpec as R, SequenceSpec as S, TextSequenceSpec as T, VideoSequenceSpec as V, WipeTransition as W, ZoomTransition as Z, CameraSequenceSpec as a, SequenceCommon as b, AssetSpec as c, AudioAssetSpec as d, AudioSequenceSpec as e, AudioSfxSpec as f, ChromaKeyFilterSpec as g, CircleShapeSpec as h, CompositionSequenceSpec as i, CompositionSpec as j, CrossfadeTransition as k, CustomFilterSpec as l, DissolveTransition as m, Expr as n, IrisTransition as o, PolygonShapeSpec as p, PropValue as q, Props as r, SfxKnobs as s, SfxOptions as t, SfxPreset as u, SfxVoice as v, ShapeSequenceSpec as w, SlideTransition as x, TransitionCommon as y, TransitionSpec as z };

package/docs/api.md

@@ -89,6 +89,21 @@ contactSheet(options?: {
 
 Many frames on **one** PNG, each labelled `frame N · T s`. The cheapest way to check a whole animation by eye (include the middle of every transition and the last second). Restores the current frame afterwards.
 
+### `measureText(text, style?): { width, height, lines }` and `splitText(text, style?, options?): TextPiece[]`
+
+Text layout helpers, exported from `pixi-effects`. They measure with the renderer's own font metrics (the same numbers a text layer with that `style` has), so a layout built from them matches what is drawn. `style` is a text layer's `style` with numbers (no expressions). A web font must be loaded first.
+
+```ts
+measureText('Hello', { fontSize: 72 });                       // { width: 187.4, height: 81.3, lines: 1 }
+
+interface SplitOptions { by?: 'chars' | 'words' | 'lines'; x?: number; y?: number; align?: 'left' | 'center' | 'right' }
+interface TextPiece { text: string; x: number; y: number; width: number; index: number; line: number }
+splitText('Hello world', style, { by: 'words', x: 640, y: 300, align: 'center' });
+// → [{ text: 'Hello', x, y, width, index: 0, line: 0 }, { text: 'world', ... }]
+```
+
+`x` is the line's left edge, or its centre / right edge with `align` (each line of a `\n` text is aligned on its own width); `y` is the top of the first line, and further lines go down by the line height. Whitespace takes its room but is not returned as a piece. Use one text layer per piece with the same `style` and the default top-left anchor: `{ type: 'text', text: p.text, style, initial: { x: p.x, y: p.y } }`. Kerning is kept (a piece's x is the measured width of everything before it).
+
 ### `movie.inspect(frame?, options?): Promise<InspectReport>`
 
 Where every layer is drawn at `frame`, as JSON — for checking layout without eyes. Seeks there and stays there. `options.layers`: `'visible'` (default, only layers drawn at this frame), `'all'`, or `'none'` (just `summary` and `issues`). Faint layers (alpha < 0.3) and text whose x / y is animated (tickers) are not reported.
@@ -109,6 +124,27 @@ interface InspectReport {
 }
 ```
 
+### `movie.inspectAudio(options?): AudioReport`
+
+The soundtrack as numbers — for checking sound without listening. Every sound is also measured on its own, so overlaps do not blur it. `options.window`: seconds per row of `windows` (default 0.1).
+
+```ts
+interface AudioReport {
+  duration: number; sampleRate: number;
+  peakDb: number; peakAt: number;          // the mix before limiting; > 0 dBFS means it was limited
+  sources: Array<{
+    layer: string; source: string;         // 'layer "hit"', 'sfx "hit"' | 'asset "bgm"' | 'video "clip"'
+    start: number; end: number;            // movie time
+    peakDb: number;                        // the MIX while it plays
+    sound: { length: number; peakDb: number; loudestAt: number; brightnessHz: number };   // the sound alone
+  }>;
+  windows: Array<{ t: number; rmsDb: number; peakDb: number; brightnessHz: number }>;
+  issues: string[];                        // limited mix, inaudible layer, sfx cut off by the end, no audio — read first
+}
+```
+
+`render()` encodes this same mix: AAC in mp4 / mov (the encoder delay is trimmed with an edit list), Opus in webm / mkv.
+
 ### `movie.render(options?): Promise<Blob>`
 
 Renders the entire timeline to a single video file. Pauses playback first.

package/docs/dsl.md

@@ -59,7 +59,7 @@ interface SequenceCommon {
 | Layer | Where `x, y` land by default | To change it |
 |---|---|---|
 | `shape` rect / circle / ellipse | the **centre** of the shape | `anchorX` / `anchorY` (0–1). A bar growing from its base: `anchorY: 1`; left to right: `anchorX: 0` |
-| `shape` line / polygon / path | the centre of the shape's bounds | — |
+| `shape` line / polygon / path | the centre of the shape's bounds | `pivotX` / `pivotY` (in the shape's own canvas coordinates): the point that sits at `x, y` and that rotation / scale turn about. **`anchorX` / `anchorY` do nothing on these.** |
 | `text`, `image`, `video` | the **top-left** corner | `anchorX` / `anchorY: 0.5` to centre |
 | `composition` | its top-left corner | `pivotX` / `pivotY` = the point that sits at `x, y` and that rotation / scale turn about |
 
@@ -71,7 +71,7 @@ A layer is **not removed** when its lifespan `[at, at + duration)` ends: it is o
 
 ### `text`
 
-Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content cannot change over time (for a count-up, show one text layer per value). In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
+Renders a [PIXI.Text](https://pixijs.com/8.x/guides/components/scene-objects/text/text). Animatable position, rotation, scale, opacity and `fill`. `style` accepts any PixiJS `TextStyle` field and is applied once at build time — notably `fontSize fontFamily fontWeight fill letterSpacing lineHeight align wordWrap wordWrapWidth stroke dropShadow padding` (numbers may be expressions). A `dropShadow` glow is clipped unless `padding` is at least twice its `blur`. Text content cannot change over time, with one exception: a `{value}` placeholder in `text` prints an animatable number (`text: '{value} users'`, `initial: { value: 0 }`, a keyframe `to: { value: 2480 }`; `format: { decimals, grouping }`) — that is how counters work. Any other change of wording is a second layer (stack layers with `at` / `duration`). Multi-line text is centre-aligned unless `style.align` says otherwise. In expressions `w` / `h` are the size of the styled text, so `x: '-w'` places it just off the left edge.
 
 ```ts
 {
@@ -116,7 +116,7 @@ A text layer has one animatable number, `value`, printed wherever the text conta
 }
 ```
 
-`format`: `decimals` (default 0) and thousands `grouping` (default false). Put prefixes and suffixes in the text (`'${value}'`, `'{value}%'`). If `value` is animated but the text has no `{value}`, a warning says so.
+`format`: `decimals` (default 0), thousands `grouping` (default false) and `pad` (zero-pad the whole part to that many digits: `pad: 2` gives `05`, so a clock is `text: '18:42:{value}'` with `format: { pad: 2 }`). Put prefixes and suffixes in the text (`'${value}'`, `'{value}%'`). If `value` is animated but the text has no `{value}`, a warning says so.
 
 ### `image`
 
@@ -179,10 +179,40 @@ Audio-only sequence. No visual. Volume is animatable via keyframes.
 
 Audio is mixed during `Movie.init()` and during `Movie.render()`. Volume keyframes interpolate linearly.
 
+#### Sound effects without files: `sfx`
+
+```ts
+{ type: 'audio', sfx: 'swoosh', at: 2 }                                          // a preset at its own length
+{ type: 'audio', sfx: { preset: 'hit', pitch: -3, brightness: -0.5 }, at: 4 }    // lower and darker
+{ type: 'audio', sfx: 'riser', at: 3, duration: 1.5, volume: 0.7 }              // duration IS the sound's length (stretched)
+{ type: 'audio', at: 6, duration: 0.3,                                          // a custom sound
+  sfx: { voices: [{ wave: 'square', freq: [1600, 200], filter: { type: 'lowpass', freq: 3000 }, envelope: 'fall' }] } }
+```
+
+The sound is synthesised from data at init (no asset, no network), deterministic, and the same mix in playback and in the exported file (encoded there: AAC / Opus are lossy). `at` is where it starts; `volume` and volume keyframes work as for files; `loop` is not available (one layer per hit). Knobs: `pitch` (semitones, ±24), `brightness` (−1 dark … 1 bright), `seed` (another take of the random parts). `volume: 1` is the preset's standard level, peaking at −12 … −18 dBFS depending on the preset; the finished mix is soft-limited above 0.9 with a warning naming the layers. A custom sound has up to 16 `voices`: `wave` (`sine` `triangle` `square` `saw` `noise`), `freq` (Hz or `[from, to]`), `filter` (`{ type: 'lowpass' | 'highpass' | 'bandpass', freq, q }`), `envelope` (`fall` `bell` `swell` `hold`), `pan`, `from` / `to` (part of the sound, 0–1), `gain`; its default length is 0.5 s.
+
+| Preset | Default length | Loudest at | Brightness | Use for |
+|---|---|---|---|---|
+| `click` | 0.04 s | start | ≈ 12780 Hz | UI click, tick |
+| `pop` | 0.12 s | start | ≈ 390 Hz | an element appearing |
+| `swoosh` | 0.5 s | 0.16 s | ≈ 3070 Hz | transitions, fly-pasts (moves left → right) |
+| `swipe` | 0.22 s | start | ≈ 13190 Hz | quick UI swipe |
+| `hit` | 0.7 s | start | ≈ 150 Hz | impact, slam |
+| `riser` | 1 s | its end | ≈ 11850 Hz | build-up into a hit |
+| `chime` | 1.4 s | start | ≈ 1400 Hz | success, reveal |
+| `beep` | 0.16 s | flat | ≈ 1030 Hz | countdown, alert |
+| `coin` | 0.4 s | 0.07 s | ≈ 1870 Hz | reward, collect |
+| `glitch` | 0.35 s | 0.22 s | ≈ 3970 Hz | digital error |
+| `typewriter` | 0.06 s | start | ≈ 3260 Hz | one key (vary `seed` per key) |
+
+Brightness is the spectral centroid that `movie.inspectAudio()` reports (`sound.brightnessHz`), at 48 kHz with no knobs.
+
 ### `composition`
 
 Nested composition. Same shape as the root spec but with `type: 'composition'` and an explicit `width`/`height`. Children animate within the local coordinate system; the composition itself can be positioned, scaled, and rotated as a unit.
 
+**Size, clipping and culling** (measured): a 2D composition does **not** clip its children — a child far outside `width × height` is still drawn. But the rectangle `width × height` is what the renderer uses to decide the group is on screen: when that whole rectangle is off the canvas the group is skipped even if a child is placed back on screen. So keep the rectangle around what it draws (or make it canvas-sized). A `threeD: true` composition (a card) is rendered into a texture of exactly `width × height`, so it **does** clip its children there; size it for soft shadows too.
+
 ```ts
 {
   type: 'composition',
@@ -223,10 +253,21 @@ Every primitive draws centred on its local origin (so `anchorX`/`anchorY` and `p
 | `rect`    | `width`, `height`                        | `cornerRadius`         |
 | `circle`  | `radius`                                 | —                      |
 | `ellipse` | `radiusX`, `radiusY`                     | —                      |
+| `arc`     | `radius`                                 | `innerRadius`, `startAngle` (0), `endAngle` (360) |
 | `line`    | `from: [x,y]`, `to: [x,y]` (canvas coordinates; stroke in `initial`) | — |
 | `polygon` | `points: [[x,y], …]`                     | `open` (default false) |
 | `path`    | `d` (SVG path data)                      | —                      |
 
+**`arc`** is an arc around its local origin (the centre). Angles are in **degrees: 0° is 3 o'clock and positive is clockwise**, so a progress ring starts at `startAngle: -90` (12 o'clock) and animates `endAngle` from `-90` to `270`. With a stroke and no fill it is an open arc line (`strokeCap: 'round'` for rounded ends); with a fill it is a sector (a pie slice), and with `innerRadius` a ring segment (a donut slice). A sweep of 360° or more is a full circle; `endAngle < startAngle` sweeps counter-clockwise. `radius`, `innerRadius`, `startAngle` and `endAngle` are all animatable.
+
+```ts
+{ type: 'shape', shape: 'arc', radius: 120, startAngle: -90, endAngle: -90, strokeCap: 'round',
+  initial: { x: 'GW/2', y: 'GH/2', strokeColor: '#ffd166', strokeWidth: 24 },
+  keyframes: [{ at: 0, to: { endAngle: 270 }, duration: 2, ease: 'power3.out' }] }   // a progress ring filling clockwise from the top
+```
+
+`strokeCap` (`'butt'`, `'round'`, `'square'`) and `strokeJoin` (`'miter'`, `'round'`, `'bevel'`) work on every shape, at the top level or in `initial`; they are not animated. Sharp corners (the apex of an M in outlined text, a thin polygon) poke out with the default `miter` join: use `'round'`.
+
 **Style** is set on `initial` and animatable via keyframes:
 
 | Key           | Notes                                                        |
@@ -309,7 +350,7 @@ Per-shape choice of how colour keyframes are interpolated. Default `'rgb'` (line
 
 **Scalar geometry is animatable.** `width`, `height`, `cornerRadius` (rect), `radius` (circle), `radiusX` / `radiusY` (ellipse) all flow through the same per-frame redraw and can be tweened via keyframes — useful for progress bars (animate `width`), pulsing icons (animate `radius`), or shape-morph callouts. Array geometry (polygon `points`, line endpoints, path `d`) is baked at build time; use `scale` / `scaleX` / `scaleY` for those.
 
-`anchorX` / `anchorY` (default `0.5` each) control which point on the bbox sits at the local origin — `0` is left/top, `1` is right/bottom. They're animatable too. Critical for "grow from one edge" effects:
+For rect / circle / ellipse, `anchorX` / `anchorY` (default `0.5` each; not available on line / polygon / path, which use `pivotX` / `pivotY`) control which point on the bbox sits at the local origin — `0` is left/top, `1` is right/bottom. They're animatable too. Critical for "grow from one edge" effects:
 
 ```ts
 // Left-anchored progress bar — width animates 0 → W, left edge stays at x
@@ -546,6 +587,17 @@ When `true`, flip the mask sense: pixels INSIDE the mask shape become transparen
 
 Routed through PIXI v8's native `setMask({ inverse: true })`.
 
+#### `blendMode`
+
+How a layer blends with what is behind it: `'normal'` (default), `'add'`, `'screen'` or `'multiply'`. `add` and `screen` brighten, so overlapping glows, halos and light leaks add up instead of covering each other; `multiply` darkens. It works on every layer type, on `threeD` layers, and on a composition (its children inherit the mode, each blending with what is behind it). Any other value warns and is ignored.
+
+```ts
+// A soft white glow that brightens whatever it overlaps
+{ type: 'shape', shape: 'circle', radius: 120, blendMode: 'add',
+  fillGradient: { type: 'radial', stops: [[0, 'rgba(255,255,255,0.9)'], [1, 'rgba(255,255,255,0)']] },
+  initial: { x: 'W/2', y: 'H/2' } }
+```
+
 ---
 
 ## Assets