@pixerate/editor 0.252.0 → 0.254.0

package/dist/effects/conformance.d.cts

@@ -22,4 +22,5 @@ export interface EffectConformanceOptions {
     /** Also check sequence templates when supportsTemplates is true (default true). */
     templates?: boolean;
 }
+/** Runs the contract checks against `provider` and returns every issue found (empty when it conforms). */
 export declare function checkEffectProvider(provider: EffectProvider, options?: EffectConformanceOptions): Promise<EffectConformanceIssue[]>;

package/dist/effects/conformance.d.ts

@@ -22,4 +22,5 @@ export interface EffectConformanceOptions {
     /** Also check sequence templates when supportsTemplates is true (default true). */
     templates?: boolean;
 }
+/** Runs the contract checks against `provider` and returns every issue found (empty when it conforms). */
 export declare function checkEffectProvider(provider: EffectProvider, options?: EffectConformanceOptions): Promise<EffectConformanceIssue[]>;

package/dist/effects/fake.d.cts

@@ -17,6 +17,10 @@
  * With `camera: true` it also has camera moves (no pixels): `glide` and `whip` (transitions; the
  * whip cuts halfway) and `drift` (a hold that zooms in slowly).
  *
+ * With `timing: true` it also has timing effects (no pixels; they retime video footage): `speed`
+ * (slow or fast, blending frames), `freeze` (holds one frame, then plays on) and `echo` (fading
+ * copies of the frames before, averaged or lightened).
+ *
  * With `templates: true` it also has two sequence templates (see `fake-templates.ts`):
  * `fake.title-sequence` and `fake.picture-reveal`.
  */
@@ -30,8 +34,10 @@ export interface FakeEffectProviderOptions {
     authoring?: boolean;
     /** Adds the camera moves and `cameraView` / `sampleCameraMove` (default false). */
     camera?: boolean;
+    /** Adds the timing effects and `timingLength` / `timingSample` (default false). */
+    timing?: boolean;
     /** Adds two sequence templates and `listTemplates` / `describeTemplate` / `instantiateTemplate` (default false). */
     templates?: boolean;
 }
-/** A deterministic CPU effects provider with seven effects, and camera moves and templates on request (see the module comment). */
+/** A deterministic CPU effects provider with nine effects, and camera moves, timing effects and templates on request (see the module comment). */
 export declare function createFakeEffectProvider(options?: FakeEffectProviderOptions): EffectProvider;

package/dist/effects/fake.d.ts

@@ -17,6 +17,10 @@
  * With `camera: true` it also has camera moves (no pixels): `glide` and `whip` (transitions; the
  * whip cuts halfway) and `drift` (a hold that zooms in slowly).
  *
+ * With `timing: true` it also has timing effects (no pixels; they retime video footage): `speed`
+ * (slow or fast, blending frames), `freeze` (holds one frame, then plays on) and `echo` (fading
+ * copies of the frames before, averaged or lightened).
+ *
  * With `templates: true` it also has two sequence templates (see `fake-templates.ts`):
  * `fake.title-sequence` and `fake.picture-reveal`.
  */
@@ -30,8 +34,10 @@ export interface FakeEffectProviderOptions {
     authoring?: boolean;
     /** Adds the camera moves and `cameraView` / `sampleCameraMove` (default false). */
     camera?: boolean;
+    /** Adds the timing effects and `timingLength` / `timingSample` (default false). */
+    timing?: boolean;
     /** Adds two sequence templates and `listTemplates` / `describeTemplate` / `instantiateTemplate` (default false). */
     templates?: boolean;
 }
-/** A deterministic CPU effects provider with seven effects, and camera moves and templates on request (see the module comment). */
+/** A deterministic CPU effects provider with nine effects, and camera moves, timing effects and templates on request (see the module comment). */
 export declare function createFakeEffectProvider(options?: FakeEffectProviderOptions): EffectProvider;

package/dist/effects/helpers.d.cts

@@ -3,7 +3,7 @@
  * and a provider slot editors hold.
  */
 import { type SchemaValidationError } from '../tools/schema.cjs';
-import type { CameraMoveRole, CameraMoveSpec, CameraMoveSample, CameraMoveSampleRequest, CameraStage, CameraView, EffectDescription, EffectImageSource, EffectPixels, EffectProvider, EffectSearchOptions, EffectSummary, EffectUse, EffectValues } from './types.cjs';
+import type { CameraMoveRole, CameraMoveSpec, CameraMoveSample, CameraMoveSampleRequest, CameraStage, CameraView, EffectDescription, EffectImageSource, EffectPixels, EffectProvider, EffectSearchOptions, EffectSummary, EffectUse, EffectValues, TimingBlend, TimingFrame, TimingSample, TimingSampleRequest } from './types.cjs';
 /** Problems with `values` against an effect's control schema (unknown controls, types, ranges). Partial values are fine. */
 export declare function effectValueErrors(description: Pick<EffectDescription, 'controls'>, values: unknown): SchemaValidationError[];
 /**
@@ -13,9 +13,9 @@ export declare function effectValueErrors(description: Pick<EffectDescription, '
  */
 export declare function resolveEffectValues(description: Pick<EffectDescription, 'id' | 'controls' | 'defaults'>, values?: EffectValues): Record<string, EffectValues[string]>;
 /**
- * Whether an editor offering `uses` should offer `e` (in a picker or an `effect` enum). Motion
- * and camera effects draw no picture of their own, so they are offered only where `uses` names
- * them (`motion`, `camera`); with no `uses`, every other effect is.
+ * Whether an editor offering `uses` should offer `e` (in a picker or an `effect` enum). Motion,
+ * camera and timing effects draw no picture of their own, so they are offered only where `uses`
+ * names them (`motion`, `camera`, `timing`); with no `uses`, every other effect is.
  */
 export declare function effectOffered(e: Pick<EffectSummary, 'kind' | 'uses'>, uses?: readonly EffectUse[]): boolean;
 /** A tag as tags are compared: trimmed, lower case, spaces and underscores as single hyphens (`"Game Boy"` → `game-boy`). */
@@ -128,3 +128,35 @@ export interface CameraBox {
 export declare function cameraViewOfBox(box: CameraBox, stage: CameraStage): CameraView;
 /** The box of the scene a view shows on `stage` (its tilt, turn, roll and blur aside). */
 export declare function cameraBoxOfView(view: CameraView, stage: CameraStage): CameraBox;
+/** Throws `EffectUnsupportedError` unless `footageMs` is a footage length a timing effect takes (a number of ms > 0). */
+export declare function checkTimingFootage(footageMs: number, id?: string): void;
+/**
+ * Checks a timing request (footage, time and fps), throwing `EffectUnsupportedError` with a
+ * sentence naming the valid range, and gives its fps (default `TIMING_DEFAULT_FPS`).
+ */
+export declare function checkTimingRequest(request: TimingSampleRequest, id?: string): number;
+/**
+ * Raw footage frames (any times, any positive weights) as a `TimingSample`: each time held within
+ * the footage and moved to the start of its frame, frames on the same footage frame merged, at
+ * most `TIMING_MAX_FRAMES` (evenly spaced), weights scaled to add up to 1, earliest first. Frames
+ * with a time or weight that is not a finite number, or a weight ≤ 0, are dropped; with none left,
+ * the sample is the frame at `request.time`. Providers can build `timingSample` on it.
+ */
+export declare function normaliseTimingSample(raw: readonly TimingFrame[], request: TimingSampleRequest, blend?: TimingBlend): TimingSample;
+/**
+ * What is wrong with `sample` as the answer to `request` (see `TimingSample`), as sentences; empty
+ * when it keeps every rule. `checkEffectProvider` uses it; hosts can check a provider's samples
+ * with it.
+ */
+export declare function timingSampleProblems(sample: unknown, request: TimingSampleRequest): string[];
+/**
+ * Blends footage frames by weight as a timing sample says (see `TimingBlend`): the reference for
+ * hosts that blend in their own pipeline, and a ready blend for `EffectPixels`. Reads and writes
+ * 8-bit `data` (straight alpha, rounded); `float` is not used. Writes into `out` when given (the
+ * frames' size), else a new picture. Throws `EffectUnsupportedError` for no frames or frames of
+ * different sizes.
+ */
+export declare function blendTimingFrames(frames: readonly {
+    pixels: EffectPixels;
+    weight: number;
+}[], blend: TimingBlend, out?: EffectPixels): EffectPixels;

package/dist/effects/helpers.d.ts

@@ -3,7 +3,7 @@
  * and a provider slot editors hold.
  */
 import { type SchemaValidationError } from '../tools/schema.js';
-import type { CameraMoveRole, CameraMoveSpec, CameraMoveSample, CameraMoveSampleRequest, CameraStage, CameraView, EffectDescription, EffectImageSource, EffectPixels, EffectProvider, EffectSearchOptions, EffectSummary, EffectUse, EffectValues } from './types.js';
+import type { CameraMoveRole, CameraMoveSpec, CameraMoveSample, CameraMoveSampleRequest, CameraStage, CameraView, EffectDescription, EffectImageSource, EffectPixels, EffectProvider, EffectSearchOptions, EffectSummary, EffectUse, EffectValues, TimingBlend, TimingFrame, TimingSample, TimingSampleRequest } from './types.js';
 /** Problems with `values` against an effect's control schema (unknown controls, types, ranges). Partial values are fine. */
 export declare function effectValueErrors(description: Pick<EffectDescription, 'controls'>, values: unknown): SchemaValidationError[];
 /**
@@ -13,9 +13,9 @@ export declare function effectValueErrors(description: Pick<EffectDescription, '
  */
 export declare function resolveEffectValues(description: Pick<EffectDescription, 'id' | 'controls' | 'defaults'>, values?: EffectValues): Record<string, EffectValues[string]>;
 /**
- * Whether an editor offering `uses` should offer `e` (in a picker or an `effect` enum). Motion
- * and camera effects draw no picture of their own, so they are offered only where `uses` names
- * them (`motion`, `camera`); with no `uses`, every other effect is.
+ * Whether an editor offering `uses` should offer `e` (in a picker or an `effect` enum). Motion,
+ * camera and timing effects draw no picture of their own, so they are offered only where `uses`
+ * names them (`motion`, `camera`, `timing`); with no `uses`, every other effect is.
  */
 export declare function effectOffered(e: Pick<EffectSummary, 'kind' | 'uses'>, uses?: readonly EffectUse[]): boolean;
 /** A tag as tags are compared: trimmed, lower case, spaces and underscores as single hyphens (`"Game Boy"` → `game-boy`). */
@@ -128,3 +128,35 @@ export interface CameraBox {
 export declare function cameraViewOfBox(box: CameraBox, stage: CameraStage): CameraView;
 /** The box of the scene a view shows on `stage` (its tilt, turn, roll and blur aside). */
 export declare function cameraBoxOfView(view: CameraView, stage: CameraStage): CameraBox;
+/** Throws `EffectUnsupportedError` unless `footageMs` is a footage length a timing effect takes (a number of ms > 0). */
+export declare function checkTimingFootage(footageMs: number, id?: string): void;
+/**
+ * Checks a timing request (footage, time and fps), throwing `EffectUnsupportedError` with a
+ * sentence naming the valid range, and gives its fps (default `TIMING_DEFAULT_FPS`).
+ */
+export declare function checkTimingRequest(request: TimingSampleRequest, id?: string): number;
+/**
+ * Raw footage frames (any times, any positive weights) as a `TimingSample`: each time held within
+ * the footage and moved to the start of its frame, frames on the same footage frame merged, at
+ * most `TIMING_MAX_FRAMES` (evenly spaced), weights scaled to add up to 1, earliest first. Frames
+ * with a time or weight that is not a finite number, or a weight ≤ 0, are dropped; with none left,
+ * the sample is the frame at `request.time`. Providers can build `timingSample` on it.
+ */
+export declare function normaliseTimingSample(raw: readonly TimingFrame[], request: TimingSampleRequest, blend?: TimingBlend): TimingSample;
+/**
+ * What is wrong with `sample` as the answer to `request` (see `TimingSample`), as sentences; empty
+ * when it keeps every rule. `checkEffectProvider` uses it; hosts can check a provider's samples
+ * with it.
+ */
+export declare function timingSampleProblems(sample: unknown, request: TimingSampleRequest): string[];
+/**
+ * Blends footage frames by weight as a timing sample says (see `TimingBlend`): the reference for
+ * hosts that blend in their own pipeline, and a ready blend for `EffectPixels`. Reads and writes
+ * 8-bit `data` (straight alpha, rounded); `float` is not used. Writes into `out` when given (the
+ * frames' size), else a new picture. Throws `EffectUnsupportedError` for no frames or frames of
+ * different sizes.
+ */
+export declare function blendTimingFrames(frames: readonly {
+    pixels: EffectPixels;
+    weight: number;
+}[], blend: TimingBlend, out?: EffectPixels): EffectPixels;