etro 0.6.0 → 0.8.1

package/dist/etro.d.ts

@@ -0,0 +1,7 @@
+import * as layer from './layer/index';
+import * as effect from './effect/index';
+import * as event from './event';
+import EtroObject from './object';
+export * from './movie';
+export * from './util';
+export { EtroObject, layer, effect, event };

package/dist/event.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module event
+ */
+import EtroObject from './object';
+export interface Event {
+    target: EtroObject;
+    type: string;
+}
+/**
+ * Listen for an event or category of events
+ *
+ * @param target - a etro object
+ * @param type - the id of the type (can contain subtypes, such as
+ * "type.subtype")
+ * @param listener
+ */
+export declare function subscribe(target: EtroObject, type: string, listener: <T extends Event>(T: any) => void): void;
+/**
+ * Remove an event listener
+ *
+ * @param target - a etro object
+ * @param type - the id of the type (can contain subtypes, such as
+ * "type.subtype")
+ * @param listener
+ */
+export declare function unsubscribe(target: EtroObject, listener: <T extends Event>(T: any) => void): void;
+/**
+ * Emits an event to all listeners
+ *
+ * @param target - a etro object
+ * @param type - the id of the type (can contain subtypes, such as
+ * "type.subtype")
+ * @param event - any additional event data
+ */
+export declare function publish(target: EtroObject, type: string, event: Record<string, unknown>): Event;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The entry point
+ * @module index
+ */
+import * as etro from './etro';
+export default etro;

package/dist/layer/audio-source.d.ts

@@ -0,0 +1,24 @@
+import { AudioContext, IAudioNode } from 'standardized-audio-context';
+import { Base, BaseOptions } from './base';
+declare type Constructor<T> = new (...args: unknown[]) => T;
+interface AudioSource extends Base {
+    readonly source: HTMLMediaElement;
+    readonly audioNode: IAudioNode<AudioContext>;
+    playbackRate: number;
+    /** The audio source node for the media */
+    sourceStartTime: number;
+}
+interface AudioSourceOptions extends BaseOptions {
+    source: HTMLMediaElement;
+    sourceStartTime?: number;
+    muted?: boolean;
+    volume?: number;
+    playbackRate: number;
+    onload?: (source: HTMLMediaElement, options: AudioSourceOptions) => void;
+}
+/**
+ * A layer that gets its audio from an HTMLMediaElement
+ * @mixin AudioSourceMixin
+ */
+declare function AudioSourceMixin<OptionsSuperclass extends BaseOptions>(superclass: Constructor<Base>): Constructor<AudioSource>;
+export { AudioSource, AudioSourceOptions, AudioSourceMixin };

package/dist/layer/audio.d.ts

@@ -0,0 +1,14 @@
+import { AudioSourceOptions } from './audio-source';
+declare type AudioOptions = AudioSourceOptions;
+declare const Audio_base: new (...args: unknown[]) => import("./audio-source").AudioSource;
+/**
+ * @extends AudioSource
+ */
+declare class Audio extends Audio_base {
+    /**
+     * Creates an audio layer
+     */
+    constructor(options: AudioOptions);
+    getDefaultOptions(): AudioOptions;
+}
+export { Audio, AudioOptions };

package/dist/layer/base.d.ts

@@ -0,0 +1,82 @@
+import EtroObject from '../object';
+import { Movie } from '../movie';
+interface BaseOptions {
+    /** The time in the movie at which this layer starts */
+    startTime: number;
+    duration: number;
+}
+/**
+ * A layer outputs content for the movie
+ */
+declare class Base implements EtroObject {
+    type: string;
+    publicExcludes: string[];
+    propertyFilters: Record<string, <T>(value: T) => T>;
+    enabled: boolean;
+    /**
+     * If the attached movie's playback position is in this layer
+     */
+    active: boolean;
+    /**
+     * The number of times this layer has been attached to a movie minus the
+     * number of times it's been detached. (Used for the movie's array proxy with
+     * `unshift`)
+     */
+    private _occurrenceCount;
+    private _startTime;
+    private _duration;
+    private _movie;
+    /**
+     * Creates a new empty layer
+     *
+     * @param options
+     * @param options.startTime - when to start the layer on the movie's
+     * timeline
+     * @param options.duration - how long the layer should last on the
+     * movie's timeline
+     */
+    constructor(options: BaseOptions);
+    /**
+     * Attaches this layer to `movie` if not already attached.
+     * @ignore
+     */
+    tryAttach(movie: Movie): void;
+    attach(movie: Movie): void;
+    /**
+     * Dettaches this layer from its movie if the number of times `tryDetach` has
+     * been called (including this call) equals the number of times `tryAttach`
+     * has been called.
+     *
+     * @ignore
+     */
+    tryDetach(): void;
+    detach(): void;
+    /**
+     * Called when the layer is activated
+     */
+    start(): void;
+    /**
+     * Called when the movie renders and the layer is active
+     */
+    render(): void;
+    /**
+    * Called when the layer is deactivated
+     */
+    stop(): void;
+    get parent(): Movie;
+    /**
+     */
+    get startTime(): number;
+    set startTime(val: number);
+    /**
+     * The current time of the movie relative to this layer
+     */
+    get currentTime(): number;
+    /**
+     */
+    get duration(): number;
+    set duration(val: number);
+    get movie(): Movie;
+    getDefaultOptions(): BaseOptions;
+}
+export { Base, BaseOptions };

package/dist/layer/image.d.ts

@@ -0,0 +1,6 @@
+import { VisualOptions } from './visual';
+declare type ImageOptions = VisualOptions;
+declare const Image_base: new (...args: unknown[]) => import("./visual-source").VisualSource;
+declare class Image extends Image_base {
+}
+export { Image, ImageOptions };

package/dist/layer/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module layer
+ */
+export * from './audio-source';
+export * from './audio';
+export * from './base';
+export * from './image';
+export * from './text';
+export * from './video';
+export * from './visual-source';
+export * from './visual';

package/dist/layer/text.d.ts

@@ -0,0 +1,60 @@
+import { Dynamic } from '../util';
+import { Visual, VisualOptions } from './visual';
+interface TextOptions extends VisualOptions {
+    text: Dynamic<string>;
+    font?: Dynamic<string>;
+    color?: Dynamic<string>;
+    /** The text's horizontal offset from the layer */
+    textX?: Dynamic<number>;
+    /** The text's vertical offset from the layer */
+    textY?: Dynamic<number>;
+    maxWidth?: Dynamic<number>;
+    /**
+     * @desc The horizontal alignment
+     * @see [`CanvasRenderingContext2D#textAlign<`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign)
+     */
+    textAlign?: Dynamic<string>;
+    /**
+     * @desc The vertical alignment
+     * @see [`CanvasRenderingContext2D#textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+     */
+    textBaseline?: Dynamic<string>;
+    /**
+     * @see [`CanvasRenderingContext2D#direction`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+     */
+    textDirection?: Dynamic<string>;
+}
+declare class Text extends Visual {
+    text: Dynamic<string>;
+    font: Dynamic<string>;
+    color: Dynamic<string>;
+    /** The text's horizontal offset from the layer */
+    textX: Dynamic<number>;
+    /** The text's vertical offset from the layer */
+    textY: Dynamic<number>;
+    maxWidth: Dynamic<number>;
+    /**
+     * @desc The horizontal alignment
+     * @see [`CanvasRenderingContext2D#textAlign<`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign)
+     */
+    textAlign: Dynamic<string>;
+    /**
+     * @desc The vertical alignment
+     * @see [`CanvasRenderingContext2D#textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+     */
+    textBaseline: Dynamic<string>;
+    /**
+     * @see [`CanvasRenderingContext2D#direction`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+     */
+    textDirection: Dynamic<string>;
+    private _prevText;
+    private _prevFont;
+    private _prevMaxWidth;
+    /**
+     * Creates a new text layer
+     */
+    constructor(options: TextOptions);
+    doRender(): void;
+    getDefaultOptions(): TextOptions;
+}
+export { Text, TextOptions };

package/dist/layer/video.d.ts

@@ -0,0 +1,11 @@
+import { VisualSourceOptions } from './visual-source';
+import { AudioSourceOptions } from './audio-source';
+declare type VideoOptions = VisualSourceOptions & AudioSourceOptions;
+declare const Video_base: new (...args: unknown[]) => import("./audio-source").AudioSource;
+/**
+ * @extends AudioSource
+ * @extends VisualSource
+ */
+declare class Video extends Video_base {
+}
+export { Video, VideoOptions };

package/dist/layer/visual-source.d.ts

@@ -0,0 +1,32 @@
+import { Dynamic } from '../util';
+import { Base, BaseOptions } from './base';
+import { Visual, VisualOptions } from './visual';
+declare type Constructor<T> = new (...args: unknown[]) => T;
+interface VisualSource extends Base {
+    readonly source: HTMLImageElement | HTMLVideoElement;
+}
+interface VisualSourceOptions extends VisualOptions {
+    source: HTMLImageElement | HTMLVideoElement;
+    /** What part of {@link source} to render */
+    sourceX?: Dynamic<number>;
+    /** What part of {@link source} to render */
+    sourceY?: Dynamic<number>;
+    /** What part of {@link source} to render, or undefined for the entire width */
+    sourceWidth?: Dynamic<number>;
+    /** What part of {@link source} to render, or undefined for the entire height */
+    sourceHeight?: Dynamic<number>;
+    /** Where to render {@link source} onto the layer */
+    destX?: Dynamic<number>;
+    /** Where to render {@link source} onto the layer */
+    destY?: Dynamic<number>;
+    /** Where to render {@link source} onto the layer, or undefined to fill the layer's width */
+    destWidth?: Dynamic<number>;
+    /** Where to render {@link source} onto the layer, or undefined to fill the layer's height */
+    destHeight?: Dynamic<number>;
+}
+/**
+ * A layer that gets its image data from an HTML image or video element
+ * @mixin VisualSourceMixin
+ */
+declare function VisualSourceMixin<OptionsSuperclass extends BaseOptions>(superclass: Constructor<Visual>): Constructor<VisualSource>;
+export { VisualSource, VisualSourceOptions, VisualSourceMixin };

package/dist/layer/visual.d.ts

@@ -0,0 +1,58 @@
+import { Dynamic } from '../util';
+import { Base, BaseOptions } from './base';
+import { Base as BaseEffect } from '../effect/base';
+interface VisualOptions extends BaseOptions {
+    x?: Dynamic<number>;
+    y?: Dynamic<number>;
+    width?: Dynamic<number>;
+    height?: Dynamic<number>;
+    background?: Dynamic<string>;
+    border?: Dynamic<{
+        color: string;
+        thickness?: number;
+    }>;
+    opacity?: Dynamic<number>;
+}
+/** Any layer that renders to a canvas */
+declare class Visual extends Base {
+    x: Dynamic<number>;
+    y: Dynamic<number>;
+    width: Dynamic<number>;
+    height: Dynamic<number>;
+    background: Dynamic<string>;
+    border: Dynamic<{
+        color: string;
+        thickness: number;
+    }>;
+    opacity: Dynamic<number>;
+    /**
+     * The layer's rendering canvas
+     */
+    readonly canvas: HTMLCanvasElement;
+    /**
+     * The context of {@link Visual#canvas}
+     */
+    readonly cctx: CanvasRenderingContext2D;
+    readonly effects: BaseEffect[];
+    private _effectsBack;
+    /**
+     * Creates a visual layer
+     */
+    constructor(options: VisualOptions);
+    /**
+     * Render visual output
+     */
+    render(): void;
+    beginRender(): void;
+    doRender(): void;
+    endRender(): void;
+    _applyEffects(): void;
+    /**
+     * Convienence method for <code>effects.push()</code>
+     * @param effect
+     * @return the layer (for chaining)
+     */
+    addEffect(effect: BaseEffect): Visual;
+    getDefaultOptions(): VisualOptions;
+}
+export { Visual, VisualOptions };

package/dist/movie.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @module movie
+ */
+import { AudioContext } from 'standardized-audio-context';
+import { Dynamic } from './util';
+import { Base as BaseLayer } from './layer/index';
+import { Base as BaseEffect } from './effect/index';
+declare global {
+    interface HTMLCanvasElement {
+        captureStream(frameRate?: number): MediaStream;
+    }
+}
+export declare class MovieOptions {
+    /** The html canvas element to use for playback */
+    canvas: HTMLCanvasElement;
+    /** The audio context to use for playback, defaults to a new audio context */
+    actx?: AudioContext;
+    /** @deprecated Use <code>actx</code> instead */
+    audioContext?: AudioContext;
+    /** The background color of the movie as a cSS string */
+    background?: Dynamic<string>;
+    repeat?: boolean;
+    /** Call `refresh` when the user changes a property on the movie or any of its layers or effects */
+    autoRefresh?: boolean;
+}
+/**
+ * The movie contains everything included in the render.
+ *
+ * Implements a pub/sub system.
+ */
+export declare class Movie {
+    type: string;
+    publicExcludes: string[];
+    propertyFilters: Record<string, <T>(value: T) => T>;
+    repeat: boolean;
+    /** Call `refresh` when the user changes a property on the movie or any of its layers or effects */
+    autoRefresh: boolean;
+    /** The background color of the movie as a cSS string */
+    background: Dynamic<string>;
+    /** The audio context to which audio output is sent during playback */
+    readonly actx: AudioContext;
+    readonly effects: BaseEffect[];
+    readonly layers: BaseLayer[];
+    private _canvas;
+    private _cctx;
+    private _effectsBack;
+    private _layersBack;
+    private _currentTime;
+    private _paused;
+    private _ended;
+    private _renderingFrame;
+    private _recordEndTime;
+    private _mediaRecorder;
+    private _lastPlayed;
+    private _lastPlayedOffset;
+    /**
+     * Creates a new movie.
+     */
+    constructor(options: MovieOptions);
+    /**
+     * Plays the movie
+     * @return fulfilled when the movie is done playing, never fails
+     */
+    play(): Promise<void>;
+    /**
+     * Plays the movie in the background and records it
+     *
+     * @param options
+     * @param frameRate
+     * @param [options.video=true] - whether to include video in recording
+     * @param [options.audio=true] - whether to include audio in recording
+     * @param [options.mediaRecorderOptions=undefined] - options to pass to the <code>MediaRecorder</code>
+     * @param [options.type='video/webm'] - MIME type for exported video
+     *  constructor
+     * @return resolves when done recording, rejects when internal media recorder errors
+     */
+    record(options: {
+        frameRate: number;
+        duration?: number;
+        type?: string;
+        video?: boolean;
+        audio?: boolean;
+        mediaRecorderOptions?: Record<string, unknown>;
+    }): Promise<Blob>;
+    /**
+     * Stops the movie, without reseting the playback position
+     * @return the movie (for chaining)
+     */
+    pause(): Movie;
+    /**
+     * Stops playback and resets the playback position
+     * @return the movie (for chaining)
+     */
+    stop(): Movie;
+    /**
+     * @param [timestamp=performance.now()]
+     * @param [done=undefined] - called when done playing or when the current frame is loaded
+     * @private
+     */
+    private _render;
+    private _updateCurrentTime;
+    private _renderBackground;
+    /**
+     * @return whether or not video frames are loaded
+     * @param [timestamp=performance.now()]
+     * @private
+     */
+    private _renderLayers;
+    private _applyEffects;
+    /**
+     * Refreshes the screen (only use this if auto-refresh is disabled)
+     * @return - resolves when the frame is loaded
+     */
+    refresh(): Promise<null>;
+    /**
+     * Convienence method
+     */
+    private _publishToLayers;
+    /**
+     * If the movie is playing, recording or refreshing
+     */
+    get rendering(): boolean;
+    /**
+     * If the movie is refreshing current frame
+     */
+    get renderingFrame(): boolean;
+    /**
+     * If the movie is recording
+     */
+    get recording(): boolean;
+    /**
+     * The combined duration of all layers
+     */
+    get duration(): number;
+    /**
+     * Convienence method for <code>layers.push()</code>
+     * @param layer
+     * @return the movie
+     */
+    addLayer(layer: BaseLayer): Movie;
+    /**
+     * Convienence method for <code>effects.push()</code>
+     * @param effect
+     * @return the movie
+     */
+    addEffect(effect: BaseEffect): Movie;
+    /**
+     */
+    get paused(): boolean;
+    /**
+     * If the playback position is at the end of the movie
+     */
+    get ended(): boolean;
+    /**
+     * The current playback position
+     */
+    get currentTime(): number;
+    set currentTime(time: number);
+    /**
+     * Sets the current playback position. This is a more powerful version of
+     * `set currentTime`.
+     *
+     * @param time - the new cursor's time value in seconds
+     * @param [refresh=true] - whether to render a single frame
+     * @return resolves when the current frame is rendered if
+     * <code>refresh</code> is true, otherwise resolves immediately
+     *
+     */
+    setCurrentTime(time: number, refresh?: boolean): Promise<void>;
+    /**
+     * The rendering canvas
+     */
+    get canvas(): HTMLCanvasElement;
+    /**
+     * The rendering canvas's context
+     */
+    get cctx(): CanvasRenderingContext2D;
+    /**
+     * The width of the rendering canvas
+     */
+    get width(): number;
+    set width(width: number);
+    /**
+     * The height of the rendering canvas
+     */
+    get height(): number;
+    set height(height: number);
+    get movie(): Movie;
+    getDefaultOptions(): MovieOptions & {
+        _actx: AudioContext;
+    };
+}

package/dist/object.d.ts

@@ -0,0 +1,12 @@
+import { Movie } from './movie';
+/** A movie, layer or effect  */
+export default interface EtroObject {
+    /** Used in etro internals */
+    type: string;
+    /** Which properties to not watch for changes, for `Movie#autoRefresh` */
+    publicExcludes: string[];
+    /** Map of property name to function to run on result of `val` */
+    propertyFilters: Record<string, <T>(value: T) => T>;
+    movie: Movie;
+    getDefaultOptions(): object;
+}

package/dist/util.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @module util
+ */
+import EtroObject from './object';
+import { Movie } from './movie';
+/**
+ * Merges `options` with `defaultOptions`, and then copies the properties with
+ * the keys in `defaultOptions` from the merged object to `destObj`.
+ *
+ * @return
+ */
+export declare function applyOptions(options: object, destObj: EtroObject): void;
+export declare function clearCachedValues(movie: Movie): void;
+/**
+ * A keyframe set.
+ *
+ * Usage:
+ * ```js
+ new etro.KeyFrame([time1, value1, interpolation1], [time2, value2])`
+ * ```
+ * TypeScript users need to specify the type of the value as a type parameter.
+ */
+export declare class KeyFrame<T> {
+    value: unknown[][];
+    /** Keys to interpolate, or all keys if undefined */
+    interpolationKeys: string[];
+    constructor(...value: T[][]);
+    withKeys(keys: string[]): KeyFrame<T>;
+    evaluate(time: number): T;
+}
+/** A dynamic property. Supports simple values, keyframes and functions */
+export declare type Dynamic<T> = T | KeyFrame<T> | ((element: EtroObject, time: number) => T);
+/**
+ * Computes a property.
+ *
+ * @param element - the etro object to which the property belongs to
+ * @param path - the dot-separated path to a property on `element`
+ * @param time - time to calculate keyframes for, if necessary
+ *
+ * Note that only values used in keyframes that are numbers or objects
+ * (including arrays) are interpolated. All other values are taken sequentially
+ * with no interpolation. JavaScript will convert parsed colors, if created
+ * correctly, to their string representations when assigned to a
+ * CanvasRenderingContext2D property.
+ */
+export declare function val(element: EtroObject, path: string, time: number): any;
+export declare function linearInterp(x1: number | object, x2: number | object, t: number, objectKeys?: string[]): number | object;
+export declare function cosineInterp(x1: number | object, x2: number | object, t: number, objectKeys?: string[]): number | object;
+/**
+ * An RGBA color, for proper interpolation and shader effects
+ */
+export declare class Color {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+    /**
+     * @param r
+     * @param g
+     * @param b
+     * @param a
+     */
+    constructor(r: number, g: number, b: number, a?: number);
+    /**
+     * Converts to a CSS color
+     */
+    toString(): string;
+}
+/**
+ * Converts a CSS color string to a {@link Color} object representation.
+ * @param str
+ * @return the parsed color
+ */
+export declare function parseColor(str: string): Color;
+/**
+ * A font, for proper interpolation
+ */
+export declare class Font {
+    size: number;
+    sizeUnit: string;
+    family: string;
+    style: string;
+    variant: string;
+    weight: string;
+    stretch: string;
+    lineHeight: string;
+    /**
+     * @param size
+     * @param family
+     * @param sizeUnit
+     */
+    constructor(size: number, sizeUnit: string, family: string, style?: string, variant?: string, weight?: string, stretch?: string, lineHeight?: string);
+    /**
+     * Converts to CSS font syntax
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/font
+     */
+    toString(): string;
+}
+/**
+ * Converts a CSS font string to a {@link Font} object
+ * representation.
+ * @param str
+ * @return the parsed font
+ */
+export declare function parseFont(str: string): Font;
+/**
+ * @param mapper
+ * @param canvas
+ * @param ctx
+ * @param x
+ * @param y
+ * @param width
+ * @param height
+ * @param flush
+ * @deprecated Use {@link effect.Shader} instead
+ */
+export declare function mapPixels(mapper: (pixels: Uint8ClampedArray, i: number) => void, canvas: HTMLCanvasElement, ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, flush?: boolean): void;
+/**
+ * <p>Emits "change" event when public properties updated, recursively.
+ * <p>Must be called before any watchable properties are set, and only once in
+ * the prototype chain.
+ *
+ * @param target - object to watch
+ */
+export declare function watchPublic(target: EtroObject): EtroObject;