@pixerate/flair 0.24.0 → 0.26.0

package/dist/embed/index.d.ts

@@ -0,0 +1,215 @@
+import { C as ControlValue } from '../controls-Ec6P0Vpy.js';
+import { b as SvgPlayer } from '../svg-BhRboN9q.js';
+import { E as EffectDefinition } from '../types-DUOMxZaq.js';
+import { L as LiveSource, S as ShaderRenderer } from '../renderer-teaa98RE.js';
+import { R as RenderOptions } from '../frames-VEcqa40g.js';
+
+/** What {@link recordEffect} makes: a video (`mp4`, `webm`), an animated `gif`, or `png` frames in a ZIP. */
+type RecordFormat = "mp4" | "webm" | "gif" | "png";
+/** The pointer for one frame of a shader: `iPointer`, `iMouse`, and clicks and trail so far (times in seconds). */
+type RecordPointer = Pick<RenderOptions, "pointer" | "mouse" | "clicks" | "trail">;
+interface RecordOptions {
+    /** What to apply the effect to (see {@link EffectSubject}); several fill several controls in order. */
+    subject?: EffectSubject | readonly EffectSubject[];
+    /** A preset by name, then these values, over the effect's defaults. */
+    preset?: string;
+    values?: Record<string, ControlValue>;
+    /**
+     * The file to make (default `mp4` where the browser encodes H.264, else
+     * `webm`; `webm` when `alpha` is on).
+     */
+    format?: RecordFormat;
+    /** Pixels (default 1280 × 720). Videos round them up to even numbers, as their encoders need. */
+    width?: number;
+    height?: number;
+    /** Frames per second (default 30). GIF delays are whole hundredths of a second, so 10, 20, 25 and 50 play back exactly there. */
+    fps?: number;
+    /**
+     * Seconds to record (default: a shader's `loop`, or a vector effect's
+     * picture plus its `hold`, else 4).
+     */
+    duration?: number;
+    /** The time of the first frame, in seconds (default 0). */
+    start?: number;
+    /** Bits per second for `mp4` and `webm` (default `width × height × fps × 0.15`). */
+    bitrate?: number;
+    /**
+     * Keep transparency (default: the effect's `transparent`): `webm` (VP9
+     * or VP8 with an alpha channel, which Chrome, Edge and Firefox play),
+     * `png`, and `gif` (one see-through colour). `mp4` cannot, so it lays the
+     * picture over `background` unless `alpha: true` was asked for. Without
+     * it, transparent pixels are laid over `background`.
+     */
+    alpha?: boolean;
+    /** A CSS colour under the picture when `alpha` is off (default black for shaders, white for vector effects). */
+    background?: string;
+    /**
+     * The pointer, for shaders that answer it: the same every frame, or a
+     * function of the frame's time in seconds. Without it, interactive
+     * effects play their idle demos, as on a page nobody has touched.
+     *
+     * ```ts
+     * pointer: { clicks: [{ x: 640, y: 360, time: 0.5 }] }
+     * pointer: (t) => ({ pointer: [640 + 200 * Math.sin(t), 360, 1, 0] })
+     * ```
+     */
+    pointer?: RecordPointer | ((time: number) => RecordPointer);
+    /** A vector effect's step start times in ms, for pictures that change on steps (default none). */
+    steps?: readonly number[];
+    /**
+     * Called before each frame is drawn, with its time in seconds: draw a
+     * canvas subject for that time here. (A `<video>` subject is paused and
+     * sought to each frame's time for you.)
+     */
+    beforeFrame?: (time: number, index: number) => void | Promise<void>;
+    /** Called after each frame with the share done, 0–1. */
+    onProgress?: (fraction: number) => void;
+    /** Aborting rejects with an `AbortError` `DOMException`. */
+    signal?: AbortSignal;
+}
+/** What a recording will be, worked out from the options before any frame is drawn (see {@link recordingPlan}). */
+interface RecordingPlan {
+    effect: EffectDefinition;
+    format: RecordFormat;
+    width: number;
+    height: number;
+    fps: number;
+    duration: number;
+    start: number;
+    frames: number;
+    alpha: boolean;
+    /** For `mp4` and `webm`: the encoder's settings. */
+    encoder?: VideoEncoderConfig;
+}
+/**
+ * What {@link recordEffect} would make of these options, without drawing a
+ * frame: the format (after falling back where the browser cannot encode
+ * one), size, length, frame count, whether it keeps transparency, and the
+ * encoder settings. Rejects with a sentence when the effect is unknown, an
+ * option is out of range, or the browser cannot make the format asked for.
+ */
+declare function recordingPlan(effect: EffectDefinition | string, options?: RecordOptions): Promise<RecordingPlan>;
+/**
+ * Records a catalog effect (by id or definition), applied to `subject`, to a
+ * file in the browser: an `mp4` or `webm` video (WebCodecs, muxed here with
+ * no dependencies), an animated `gif`, or `png` frames.
+ *
+ * Frames are drawn off screen at exact times (`start + i / fps`), so the
+ * result is smooth whatever the page's frame rate, and the same on every
+ * machine. Shaders render with `ShaderFrames` (a `<video>` subject is paused
+ * and sought to each frame, and put back after); vector effects are drawn
+ * with `svgView` and rasterised. Shaders that answer the pointer play their
+ * idle demos unless `pointer` scripts it.
+ *
+ * `png` resolves to a ZIP of numbered frames (`frame-0001.png`, …), so every
+ * format is one `Blob` to save or upload.
+ *
+ * Rejects with a sentence when the effect is unknown, takes no such
+ * subject, or the browser cannot make the format (naming the formats that
+ * would work); with a `ShaderCompileError` or `ImageLoadError` as
+ * `ShaderFrames` does; and with an `AbortError` when `signal` aborts.
+ *
+ * ```ts
+ * const mp4 = await recordEffect("image-duotone", { subject: { image: "/team.jpg" }, preset: "Spotify" });
+ * const gif = await recordEffect("typewriter", { subject: { text: "Hello" }, format: "gif", width: 640, height: 360, fps: 25 });
+ * const webm = await recordEffect("click-ripple", { format: "webm", alpha: true, pointer: { clicks: [{ x: 640, y: 360, time: 0.2 }] } });
+ * ```
+ */
+declare function recordEffect(effect: EffectDefinition | string, options?: RecordOptions): Promise<Blob>;
+
+/**
+ * Catalog effects on a page in one call: pick an effect, give it what it
+ * takes (a picture, a video, an SVG, words or a path) and get it running.
+ *
+ * - Pairing: `subjectValues` turns a subject into the control values (and
+ *   live sources) an effect needs, using `effectInputs`.
+ * - Embedding: `mountEffect` runs a shader effect (`ShaderRenderer`) or a
+ *   vector effect (`SvgPlayer`) in an element, with its subject.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * What an effect is applied to:
+ * - `{ image }`: a picture's URL (or `data:` URL).
+ * - `{ video }`: a playing `<video>` (or a canvas), shown live.
+ * - `{ svg }`: an SVG, as markup (`"<svg …>"`) or a URL; drawn as a picture, keeping its transparency.
+ * - `{ text }`: words, for a vector effect's text, or drawn with `textImage` for a shader's text or mask.
+ * - `{ path }`: SVG path data (`d`), for a shape control.
+ */
+type EffectSubject = {
+    image: string;
+} | {
+    video: LiveSource;
+} | {
+    svg: string;
+} | {
+    text: string;
+    font?: string;
+    weight?: number | string;
+} | {
+    path: string;
+};
+/** What a subject becomes for an effect: control values, and live sources by image control. */
+interface SubjectValues {
+    values: Record<string, ControlValue>;
+    live: Record<string, LiveSource>;
+}
+/**
+ * The control values (and live sources) that put `subject` in `effect`,
+ * into the control named `slot` or the first that suits it: a picture or
+ * SVG into an image control, a video into a picture control as a live
+ * source, words into a vector effect's text or (drawn by `textImage`) a
+ * shader's text or mask control, path data into a shape control. Several
+ * subjects fill several controls in order (a transition's from and to).
+ * Throws a sentence when the effect takes no such thing.
+ */
+declare function subjectValues(effect: EffectDefinition, subject: EffectSubject | readonly EffectSubject[], slot?: string): SubjectValues;
+interface MountOptions {
+    /** What to apply the effect to (see {@link EffectSubject}); several fill several controls in order. */
+    subject?: EffectSubject | readonly EffectSubject[];
+    /** A preset by name, then these values, over the effect's defaults. */
+    preset?: string;
+    values?: Record<string, ControlValue>;
+    /** Start playing at once (default true). */
+    autoplay?: boolean;
+    /** Class for the canvas (shaders) or the player's element (vector effects). */
+    className?: string;
+    /** Pause while scrolled out of view (default true). */
+    pauseWhenHidden?: boolean;
+}
+/** A running effect, from {@link mountEffect}. */
+interface MountedEffect {
+    readonly effect: EffectDefinition;
+    /** What it draws into: the shader's canvas, or the vector player's element. */
+    readonly element: HTMLElement;
+    /** The shader renderer, for a shader effect. */
+    readonly renderer?: ShaderRenderer;
+    /** The vector player, for a vector effect (replaced when values change). */
+    readonly player?: SvgPlayer;
+    /** Applies it to something else. */
+    setSubject(subject: EffectSubject | readonly EffectSubject[]): void;
+    /** Changes control values (merged over the current ones). */
+    setValues(values: Record<string, ControlValue>): void;
+    play(): void;
+    pause(): void;
+    /** Stops it and removes what it drew. */
+    dispose(): void;
+}
+/**
+ * Runs a catalog effect (by id or definition) in `host`, applied to
+ * `subject`: a shader on a canvas (transparent for overlays, so it lays over
+ * the page), or a vector effect in an SVG player that answers its trigger
+ * (hover, press, click). Throws a sentence when the effect is unknown or
+ * takes no such subject.
+ *
+ * ```ts
+ * mountEffect(el, "image-duotone", { subject: { image: "/team.jpg" }, preset: "Spotify" });
+ * mountEffect(el, "crt", { subject: { video: videoElement } });
+ * mountEffect(el, "typewriter", { subject: { text: "Hello there" } });
+ * mountEffect(el, "neon-outline", { subject: { svg: logoMarkup } });
+ * ```
+ */
+declare function mountEffect(host: HTMLElement, effect: EffectDefinition | string, options?: MountOptions): MountedEffect;
+
+export { type EffectSubject, type MountOptions, type MountedEffect, type RecordFormat, type RecordOptions, type RecordPointer, type RecordingPlan, type SubjectValues, mountEffect, recordEffect, recordingPlan, subjectValues };

package/dist/embed/index.js

@@ -0,0 +1,21 @@
+import {
+  mountEffect,
+  recordEffect,
+  recordingPlan,
+  subjectValues
+} from "../chunk-UCZ43ARE.js";
+import "../chunk-H6VDFBIO.js";
+import "../chunk-RDU63CDO.js";
+import "../chunk-HVXWNGTW.js";
+import "../chunk-EHDJ3CPJ.js";
+import "../chunk-VYOMXE6I.js";
+import "../chunk-PFGGPIMT.js";
+import "../chunk-WMZQCUFJ.js";
+import "../chunk-ORAFCHX3.js";
+export {
+  mountEffect,
+  recordEffect,
+  recordingPlan,
+  subjectValues
+};
+//# sourceMappingURL=index.js.map

package/dist/{export-DH2HMACO.js → export-QVW474KM.js}

@@ -7,8 +7,8 @@ import {
   exportMotn,
   framesToTimecode,
   timecodeToFrames
-} from "./chunk-GTIAOYOK.js";
-import "./chunk-WAMA45G3.js";
+} from "./chunk-74ZLCZOG.js";
+import "./chunk-5USSDEQL.js";
 import "./chunk-WMZQCUFJ.js";
 export {
   calculateShotTimings,
@@ -20,4 +20,4 @@ export {
   framesToTimecode,
   timecodeToFrames
 };
-//# sourceMappingURL=export-DH2HMACO.js.map
+//# sourceMappingURL=export-QVW474KM.js.map

package/dist/export-QVW474KM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/frames-VEcqa40g.d.ts

@@ -0,0 +1,161 @@
+import { a as ControlDef, C as ControlValue } from './controls-Ec6P0Vpy.js';
+import { L as LiveSource } from './renderer-teaa98RE.js';
+
+/**
+ * The pointer as shaders see it, beyond Shadertoy's `iMouse`: where it is
+ * while it is over the canvas, how hovered the canvas is (eased in and out),
+ * how long it has been pressed, the last few clicks, and where it has just
+ * been (its trail), so effects can answer hovers, presses, taps and moves.
+ * Times are in `iTime` seconds, so a recording can script them (see
+ * `ShaderFrames`' `pointer`, `clicks` and `trail`).
+ */
+/** How many clicks `iClicks` holds; older ones drop off. */
+declare const MAX_CLICKS = 8;
+/** How many of the pointer's recent positions `iTrail` holds; older ones drop off. */
+declare const MAX_TRAIL = 32;
+/**
+ * The least time between two positions in the trail, in seconds: moves in
+ * between update the newest. With {@link MAX_TRAIL}, about a second of path.
+ */
+declare const TRAIL_SECONDS: number;
+/** How long hovering eases in or out, in seconds. */
+declare const HOVER_SECONDS = 0.25;
+/** A click, or a point of the trail: where (pixels from the bottom left, like `iMouse`) and when (`iTime` seconds). */
+interface ShaderClick {
+    x: number;
+    y: number;
+    time: number;
+}
+/**
+ * `iClicks` from a list of clicks, newest first: `vec4(x, y, time, 1)` for
+ * each click at or before `time`, zeros for the rest.
+ */
+declare function clicksUniform(clicks: readonly ShaderClick[], time: number): Float32Array;
+/**
+ * `iTrail` from the pointer's positions, oldest first in the list: the
+ * newest {@link MAX_TRAIL} at or before `time`, newest first, as
+ * `vec4(x, y, time, 1)`, zeros for the rest.
+ */
+declare function trailUniform(trail: readonly ShaderClick[], time: number): Float32Array;
+/**
+ * Follows one canvas's pointer for `iPointer` and `iClicks`: feed it pointer
+ * events with the `iTime` they happen at, and read the uniforms for a frame.
+ */
+declare class PointerTracker {
+    private x;
+    private y;
+    private over;
+    private hoverFrom;
+    private changedAt;
+    private pressedAt;
+    private releasedAt;
+    private clicks;
+    private trail;
+    /**
+     * The pointer moved to (x, y), in pixels from the bottom left. With a
+     * `time`, the move joins the trail: a new point at most every
+     * {@link TRAIL_SECONDS}, the newest point following the pointer between.
+     */
+    move(x: number, y: number, time?: number): void;
+    /** The pointer came over the canvas (`true`) or left it. */
+    hover(over: boolean, time: number): void;
+    /** A press at (x, y): counts as a click. */
+    down(x: number, y: number, time: number): void;
+    up(time: number): void;
+    /** Forgets clicks, presses and the trail (when time jumps back, say). */
+    clear(): void;
+    /** How hovered the canvas is at `time`, 0–1, eased. */
+    hovered(time: number): number;
+    /**
+     * `iPointer` at `time`: x, y, how hovered (0–1), and the press: seconds
+     * held while pressed, minus the seconds since it was let go after, 0
+     * before the first press.
+     */
+    pointer(time: number): [number, number, number, number];
+    /** `iClicks` at `time` (see {@link clicksUniform}). */
+    clicksAt(time: number): Float32Array;
+    /** `iTrail` at `time` (see {@link trailUniform}). */
+    trailAt(time: number): Float32Array;
+}
+
+interface ShaderFramesOptions {
+    source: string;
+    values?: Record<string, ControlValue>;
+    width: number;
+    height: number;
+    /** Draw on this canvas instead of a new, detached one. It is resized to `width` × `height`. */
+    canvas?: HTMLCanvasElement;
+    /** Keep the shader's alpha (`fragColor.a`) in the frames, for transparent recordings (default false: opaque). */
+    alpha?: boolean;
+}
+interface RenderOptions {
+    /** `iFrame` (default: the number of frames rendered so far). */
+    frame?: number;
+    /** `iTimeDelta` in seconds (default: the time since the previous `render`, else 0). */
+    delta?: number;
+    /** `iMouse` (default: all zero, as on a page nobody has touched). */
+    mouse?: [number, number, number, number];
+    /** `iPointer`: x, y, how hovered (0–1), the press (seconds held, or minus seconds since release; default all zero). */
+    pointer?: [number, number, number, number];
+    /** Clicks so far, for `iClicks` (the latest `MAX_CLICKS` at or before the frame's time count). */
+    clicks?: readonly ShaderClick[];
+    /** Where the pointer has been, oldest first, for `iTrail` (the latest `MAX_TRAIL` at or before the frame's time count). */
+    trail?: readonly ShaderClick[];
+}
+/**
+ * Renders a shader at exact times you choose, off screen. There is no
+ * animation loop and no clock: frame `n` of a recording at `fps` is
+ * `render(start + n / fps)`, so the output is the same on any machine. It
+ * suits recorders, video pipelines and anything else stepped by its own
+ * clock. The constructor throws a {@link ShaderCompileError} when the source
+ * does not compile.
+ *
+ * Image controls load in the background: `await frames.ready()` before the
+ * first `render`, or the frames show black where the images go.
+ *
+ * A video in an image control (see `setLiveSource`) is drawn at whatever
+ * frame it is on. To step it with the shader, seek it first: `await
+ * seekVideo(video, t); frames.render(t)`.
+ */
+declare class ShaderFrames {
+    readonly canvas: HTMLCanvasElement;
+    readonly width: number;
+    readonly height: number;
+    readonly controls: ControlDef[];
+    private gl;
+    private shader;
+    private textures;
+    private values;
+    private rendered;
+    private lastTime;
+    private pixels;
+    constructor(options: ShaderFramesOptions);
+    /** Changes control values for the frames that follow. */
+    setValues(values: Record<string, ControlValue> | undefined): void;
+    /**
+     * Draws a `<video>` (or a canvas) in the image control `name` instead of
+     * its URL, at the frame it is on when `render` runs; `null` goes back to
+     * the URL. See `ShaderRenderer.setLiveSource`.
+     */
+    setLiveSource(name: string, source: LiveSource | null): void;
+    /**
+     * Settles once every image the controls show has loaded, and every live
+     * video has a frame. Rejects with an {@link ImageLoadError} when one
+     * cannot be.
+     */
+    ready(): Promise<void>;
+    /** Draws the frame at `time` seconds onto `canvas`. */
+    render(time: number, options?: RenderOptions): void;
+    /**
+     * The last rendered frame as RGBA bytes, rows top down (as in `ImageData`;
+     * WebGL itself reads bottom up). Pass `out` to reuse a buffer of
+     * `width * height * 4` bytes.
+     */
+    readPixels(out?: Uint8Array | Uint8ClampedArray): Uint8Array | Uint8ClampedArray;
+    /** Releases the GL context now rather than at garbage collection (browsers cap live contexts). */
+    dispose(): void;
+    private syncTextures;
+    private context;
+}
+
+export { HOVER_SECONDS as H, MAX_CLICKS as M, PointerTracker as P, type RenderOptions as R, type ShaderClick as S, TRAIL_SECONDS as T, MAX_TRAIL as a, ShaderFrames as b, type ShaderFramesOptions as c, clicksUniform as d, trailUniform as t };