etro 0.9.1 → 0.10.0

package/dist/event.d.ts

@@ -6,19 +6,24 @@ export interface Event {
     target: EtroObject;
     type: string;
 }
+export declare function deprecate(type: string, newType: string, message?: string): void;
 /**
- * Listen for an event or category of events
+ * Listen for an event or category of events.
  *
- * @param target - a etro object
+ * @param target - an etro object
  * @param type - the id of the type (can contain subtypes, such as
  * "type.subtype")
  * @param listener
+ * @param options - options
+ * @param options.once - if true, the listener will only be called once
  */
-export declare function subscribe(target: EtroObject, type: string, listener: <T extends Event>(T: any) => void): void;
+export declare function subscribe(target: EtroObject, type: string, listener: <T extends Event>(T: any) => void, options?: {
+    once?: boolean;
+}): void;
 /**
  * Remove an event listener
  *
- * @param target - a etro object
+ * @param target - an etro object
  * @param type - the id of the type (can contain subtypes, such as
  * "type.subtype")
  * @param listener
@@ -27,7 +32,7 @@ export declare function unsubscribe(target: EtroObject, listener: <T extends Eve
 /**
  * Emits an event to all listeners
  *
- * @param target - a etro object
+ * @param target - an etro object
  * @param type - the id of the type (can contain subtypes, such as
  * "type.subtype")
  * @param event - any additional event data

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

@@ -1,18 +1,23 @@
 import { Base, BaseOptions } from './base';
 declare type Constructor<T> = new (...args: unknown[]) => T;
 interface AudioSource extends Base {
-    readonly source: HTMLMediaElement;
+    /** HTML media element (an audio or video element) */
+    readonly source: HTMLAudioElement;
+    /** Audio source node for the media */
     readonly audioNode: AudioNode;
     playbackRate: number;
-    /** The audio source node for the media */
+    /** Seconds to skip ahead by */
     sourceStartTime: number;
 }
-interface AudioSourceOptions extends BaseOptions {
+interface AudioSourceOptions extends Omit<BaseOptions, 'duration'> {
+    duration?: number;
+    /** HTML media element (an audio or video element) */
     source: HTMLMediaElement;
+    /** Seconds to skip ahead by */
     sourceStartTime?: number;
     muted?: boolean;
     volume?: number;
-    playbackRate: number;
+    playbackRate?: number;
     onload?: (source: HTMLMediaElement, options: AudioSourceOptions) => void;
 }
 /**

package/dist/layer/audio.d.ts

@@ -1,14 +1,27 @@
 import { AudioSourceOptions } from './audio-source';
-declare type AudioOptions = AudioSourceOptions;
+interface AudioOptions extends Omit<AudioSourceOptions, 'source'> {
+    /**
+     * The raw html `<audio>` element
+     */
+    source: string | HTMLAudioElement;
+}
 declare const Audio_base: new (...args: unknown[]) => import("./audio-source").AudioSource;
 /**
+ * Layer for an HTML audio element
  * @extends AudioSource
  */
 declare class Audio extends Audio_base {
+    /**
+     * The raw html `<audio>` element
+     */
+    source: HTMLAudioElement;
     /**
      * Creates an audio layer
      */
     constructor(options: AudioOptions);
-    getDefaultOptions(): AudioOptions;
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
+    getDefaultOptions(): any;
 }
 export { Audio, AudioOptions };

package/dist/layer/base.d.ts

@@ -25,6 +25,7 @@ declare class Base implements EtroObject {
     private _occurrenceCount;
     private _startTime;
     private _duration;
+    private _currentTime;
     private _movie;
     /**
      * Creates a new empty layer
@@ -36,47 +37,92 @@ declare class Base implements EtroObject {
      * movie's timeline
      */
     constructor(options: BaseOptions);
+    /**
+     * Wait until this layer is ready to render
+     */
+    whenReady(): Promise<void>;
     /**
      * Attaches this layer to `movie` if not already attached.
      * @ignore
      */
     tryAttach(movie: Movie): void;
+    /**
+     * Attaches this layer to `movie`
+     *
+     * Called when the layer is added to a movie's `layers` array.
+     *
+     * @param movie The movie to attach to
+     */
     attach(movie: Movie): void;
     /**
-     * Dettaches this layer from its movie if the number of times `tryDetach` has
+     * Detaches 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;
+    /**
+     * Detaches this layer from its movie
+     *
+     * Called when the layer is removed from a movie's `layers` array.
+     */
     detach(): void;
     /**
      * Called when the layer is activated
      */
     start(): void;
+    /**
+     * Update {@link currentTime} when seeking
+     *
+     * This method is called when the movie seeks to a new time at the request of
+     * the user. {@link progress} is called when the movie's `currentTime` is
+     * updated due to playback.
+     *
+     * @param time - The new time in the layer
+     */
+    seek(time: number): void;
+    /**
+     * Update {@link currentTime} due to playback
+     *
+     * This method is called when the movie's `currentTime` is updated due to
+     * playback. {@link seek} is called when the movie seeks to a new time at the
+     * request of the user.
+     *
+     * @param time - The new time in the layer
+     */
+    progress(time: number): void;
     /**
      * Called when the movie renders and the layer is active
      */
     render(): void;
     /**
-    * Called when the layer is deactivated
+     * Called when the layer is deactivated
      */
     stop(): void;
     get parent(): Movie;
     /**
+     * The time in the movie at which this layer starts (in seconds)
      */
     get startTime(): number;
     set startTime(val: number);
     /**
-     * The current time of the movie relative to this layer
+     * The current time of the movie relative to this layer (in seconds)
      */
     get currentTime(): number;
     /**
+     * The duration of this layer (in seconds)
      */
     get duration(): number;
     set duration(val: number);
+    /**
+     * `true` if this layer is ready to be rendered, `false` otherwise
+     */
+    get ready(): boolean;
     get movie(): Movie;
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
     getDefaultOptions(): BaseOptions;
 }
 export { Base, BaseOptions };

package/dist/layer/image.d.ts

@@ -1,6 +1,20 @@
 import { VisualSourceOptions } from './visual-source';
-declare type ImageOptions = VisualSourceOptions;
+interface ImageOptions extends Omit<VisualSourceOptions, 'source'> {
+    /**
+     * The raw html `<img>` element
+     */
+    source: string | HTMLImageElement;
+}
 declare const Image_base: new (...args: unknown[]) => import("./visual-source").VisualSource;
+/**
+ * Layer for an HTML image element
+ * @extends VisualSource
+ */
 declare class Image extends Image_base {
+    /**
+     * The raw html `<img>` element
+     */
+    source: HTMLImageElement;
+    constructor(options: ImageOptions);
 }
 export { Image, ImageOptions };

package/dist/layer/text.d.ts

@@ -55,6 +55,9 @@ declare class Text extends Visual {
      */
     constructor(options: TextOptions);
     doRender(): void;
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
     getDefaultOptions(): TextOptions;
 }
 export { Text, TextOptions };

package/dist/layer/video.d.ts

@@ -1,11 +1,23 @@
 import { VisualSourceOptions } from './visual-source';
 import { AudioSourceOptions } from './audio-source';
-declare type VideoOptions = VisualSourceOptions & AudioSourceOptions;
+interface VideoOptions extends Omit<AudioSourceOptions & VisualSourceOptions, 'duration' | 'source'> {
+    duration?: number;
+    /**
+     * The raw html `<video>` element
+     */
+    source: string | HTMLVideoElement;
+}
 declare const Video_base: new (...args: unknown[]) => import("./audio-source").AudioSource;
 /**
+ * Layer for an HTML video element
  * @extends AudioSource
  * @extends VisualSource
  */
 declare class Video extends Video_base {
+    /**
+     * The raw html `<video>` element
+     */
+    source: HTMLVideoElement;
+    constructor(options: VideoOptions);
 }
 export { Video, VideoOptions };

package/dist/layer/visual.d.ts

@@ -34,11 +34,11 @@ declare class Visual extends Base {
      */
     readonly cctx: CanvasRenderingContext2D;
     readonly effects: VisualEffect[];
-    private _effectsBack;
     /**
      * Creates a visual layer
      */
     constructor(options: VisualOptions);
+    whenReady(): Promise<void>;
     /**
      * Render visual output
      */
@@ -48,11 +48,15 @@ declare class Visual extends Base {
     endRender(): void;
     _applyEffects(): void;
     /**
-     * Convienence method for <code>effects.push()</code>
+     * Convenience method for <code>effects.push()</code>
      * @param effect
      * @return the layer (for chaining)
      */
     addEffect(effect: VisualEffect): Visual;
+    get ready(): boolean;
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
     getDefaultOptions(): VisualOptions;
 }
 export { Visual, VisualOptions };

package/dist/movie/effects.d.ts

@@ -0,0 +1,6 @@
+import { CustomArray } from '../custom-array';
+import { Visual as VisualEffect } from '../effect/index';
+import { Movie } from './movie';
+export declare class MovieEffects extends CustomArray<VisualEffect> {
+    constructor(target: VisualEffect[], movie: Movie);
+}

package/dist/movie/index.d.ts

@@ -0,0 +1 @@
+export * from './movie';

package/dist/movie/layers.d.ts

@@ -0,0 +1,6 @@
+import { CustomArray } from '../custom-array';
+import { Base as BaseLayer } from '../layer/index';
+import { Movie } from './movie';
+export declare class MovieLayers extends CustomArray<BaseLayer> {
+    constructor(target: BaseLayer[], movie: Movie);
+}

package/dist/movie/movie.d.ts

@@ -0,0 +1,260 @@
+/**
+ * @module movie
+ */
+import { Dynamic, Color } from '../util';
+import { Base as BaseLayer } from '../layer/index';
+import { Base as BaseEffect } from '../effect/index';
+import { MovieEffects } from './effects';
+import { MovieLayers } from './layers';
+declare global {
+    interface Window {
+        webkitAudioContext: typeof AudioContext;
+    }
+    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<Color>;
+    /**
+     * If set to true, the movie will repeat when it reaches the end (unless it's
+     * recording)
+     */
+    repeat?: boolean;
+}
+/**
+ * The movie contains everything included in the render.
+ *
+ * Implements a pub/sub system.
+ */
+export declare class Movie {
+    type: string;
+    /**
+     * @deprecated Auto-refresh will be removed in the future. If you want to
+     * refresh the canvas, call `refresh`. See
+     * {@link https://github.com/etro-js/etro/issues/130}
+     */
+    publicExcludes: string[];
+    propertyFilters: Record<string, <T>(value: T) => T>;
+    repeat: boolean;
+    /** The background color of the movie as a cSS string */
+    background: Dynamic<Color>;
+    /** The audio context to which audio output is sent during playback */
+    readonly actx: AudioContext;
+    readonly effects: MovieEffects;
+    readonly layers: MovieLayers;
+    /** The canvas that we are currently rendering to */
+    private _canvas;
+    private _visibleCanvas;
+    private _cctx;
+    private _recorder;
+    private _currentTime;
+    private _paused;
+    private _ended;
+    private _renderingFrame;
+    private _recording;
+    private _currentStream;
+    private _endTime;
+    private _lastPlayed;
+    private _lastPlayedOffset;
+    /**
+     * Creates a new movie.
+     */
+    constructor(options: MovieOptions);
+    private _whenReady;
+    /**
+     * Plays the movie
+     *
+     * @param [options]
+     * @param [options.onStart] Called when the movie starts playing
+     *
+     * @return Fulfilled when the movie is done playing, never fails
+     */
+    play(options?: {
+        onStart?: () => void;
+    }): Promise<void>;
+    /**
+     * Updates the rendering canvas and audio destination to the visible canvas
+     * and the audio context destination.
+     */
+    private _show;
+    /**
+     * Streams the movie to a MediaStream
+     *
+     * @param options Options for the stream
+     * @param options.frameRate The frame rate of the stream's video
+     * @param options.duration The duration of the stream in seconds
+     * @param options.video Whether to stream video. Defaults to true.
+     * @param options.audio Whether to stream audio. Defaults to true.
+     * @param options.onStart Called when the stream is started
+     * @return Fulfilled when the stream is done, never fails
+     */
+    stream(options: {
+        frameRate: number;
+        duration?: number;
+        video?: boolean;
+        audio?: boolean;
+        onStart(stream: MediaStream): void;
+    }): Promise<void>;
+    /**
+     * Plays the movie in the background and records it
+     *
+     * @param options
+     * @param [options.frameRate] - Video frame rate
+     * @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
+     * `MediaRecorder` constructor
+     * @param [options.type='video/webm'] - MIME type for exported video
+     * @param [options.onStart] - Called when the recording starts
+     * @return Resolves when done recording, rejects when media recorder errors
+     */
+    record(options: {
+        frameRate: number;
+        duration?: number;
+        type?: string;
+        video?: boolean;
+        audio?: boolean;
+        mediaRecorderOptions?: Record<string, unknown>;
+        onStart?: (recorder: MediaRecorder) => void;
+    }): Promise<Blob>;
+    /**
+     * Stops the movie without resetting the playback position
+     * @return The movie
+     */
+    pause(): Movie;
+    /**
+     * Stops playback and resets the playback position
+     * @return The movie
+     */
+    stop(): Movie;
+    /**
+     * @param [timestamp=performance.now()]
+     * @param [done=undefined] - Called when done playing or when the current
+     * frame is loaded
+     */
+    private _render;
+    private _updateCurrentTime;
+    private _renderBackground;
+    /**
+     * @param [timestamp=performance.now()]
+     */
+    private _renderLayers;
+    private _applyEffects;
+    /**
+     * Refreshes the screen
+     *
+     * Only use this if auto-refresh is disabled
+     *
+     * @return - Promise that resolves when the frame is loaded
+     */
+    refresh(): Promise<null>;
+    /**
+     * Convienence method (TODO: remove)
+     */
+    private _publishToLayers;
+    /**
+     * `true` if the movie is playing, recording or refreshing
+     */
+    get rendering(): boolean;
+    /**
+     * `true` if the movie is refreshing the current frame
+     */
+    get renderingFrame(): boolean;
+    /**
+     * `true` if the movie is recording
+     */
+    get recording(): boolean;
+    /**
+     * The duration of the movie in seconds
+     *
+     * Calculated from the end time of the last layer
+     */
+    get duration(): number;
+    /**
+     * Convenience method for `layers.push()`
+     * @param layer
+     * @return The movie
+     */
+    addLayer(layer: BaseLayer): Movie;
+    /**
+     * Convenience method for `effects.push()`
+     * @param effect
+     * @return the movie
+     */
+    addEffect(effect: BaseEffect): Movie;
+    /**
+     * `true` if the movie is paused
+     */
+    get paused(): boolean;
+    /**
+     * `true` if the playback position is at the end of the movie
+     */
+    get ended(): boolean;
+    /**
+     * Skips to the provided playback position, updating {@link currentTime}.
+     *
+     * @param time - The new playback position (in seconds)
+     */
+    seek(time: number): void;
+    /**
+     * The current playback position in seconds
+     */
+    get currentTime(): number;
+    /**
+     * Skips to the provided playback position, updating {@link currentTime}.
+     *
+     * @param time - The new playback position (in seconds)
+     *
+     * @deprecated Use `seek` instead
+     */
+    set currentTime(time: number);
+    /**
+     * Skips to the provided playback position, updating {@link currentTime}.
+     *
+     * @param time - The new time (in seconds)
+     * @param [refresh=true] - Render a single frame?
+     * @return Promise that resolves when the current frame is rendered if
+     * `refresh` is true; otherwise resolves immediately.
+     *
+     * @deprecated Call {@link seek} and {@link refresh} separately
+     */
+    setCurrentTime(time: number, refresh?: boolean): Promise<void>;
+    /**
+     * `true` if the movie is ready for playback
+     */
+    get ready(): boolean;
+    /**
+     * The HTML canvas element used for rendering
+     */
+    get canvas(): HTMLCanvasElement;
+    /**
+     * The canvas context used for rendering
+     */
+    get cctx(): CanvasRenderingContext2D;
+    /**
+     * The width of the output canvas
+     */
+    get width(): number;
+    set width(width: number);
+    /**
+     * The height of the output canvas
+     */
+    get height(): number;
+    set height(height: number);
+    /**
+     * @return The movie
+     */
+    get movie(): Movie;
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
+    getDefaultOptions(): MovieOptions;
+}

package/dist/object.d.ts

@@ -1,16 +1,19 @@
 import { Movie } from './movie';
 /** A movie, layer or effect  */
 export default interface EtroObject {
+    currentTime: number;
     /** Used in etro internals */
     type: string;
-    /**
-     * Which properties to not watch for changes, for `Movie#autoRefresh`
-     *
-     * @deprecated `Movie#autoRefresh` is deprecated
-     */
-    publicExcludes: string[];
     /** Map of property name to function to run on result of `val` */
     propertyFilters: Record<string, <T>(value: T) => T>;
+    /**
+     * `true` if this object is ready to be played/rendered/applied, `false`
+     * otherwise
+     */
+    ready: boolean;
     movie: Movie;
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
     getDefaultOptions(): object;
 }

package/dist/util.d.ts

@@ -7,6 +7,10 @@ import { Movie } from './movie';
  * Merges `options` with `defaultOptions`, and then copies the properties with
  * the keys in `defaultOptions` from the merged object to `destObj`.
  *
+ * @deprecated Each option should be copied individually, and the default value
+ * should be set in the constructor. See
+ * {@link https://github.com/etro-js/etro/issues/131} for more info.
+ *
  * @return
  */
 export declare function applyOptions(options: object, destObj: EtroObject): void;
@@ -115,13 +119,3 @@ export declare function parseFont(str: string): Font;
  * @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.
- *
- * @deprecated Will be removed in the future (see issue #130)
- *
- * @param target - object to watch
- */
-export declare function watchPublic(target: EtroObject): EtroObject;

package/eslint.conf.js

@@ -17,7 +17,7 @@ module.exports = {
     sourceType: 'module'
   },
   rules: {
-    'brace-style': ['error', '1tbs', { allowSingleLine: false }],
-    curly: ['error', 'multi', 'consistent']
+    'brace-style': ['error', '1tbs'],
+    curly: ['error', 'all']
   },
 }

package/karma.conf.js

@@ -63,7 +63,10 @@ module.exports = function (config) {
     },
 
     client: {
-      captureConsole: true
+      captureConsole: true,
+      jasmine: {
+        timeoutInterval: 20000
+      }
     },
 
     browserConsoleLogOptions: {
@@ -77,11 +80,5 @@ module.exports = function (config) {
     // Concurrency level
     // how many browser should be started simultaneous
     concurrency: Infinity,
-
-    client: {
-      jasmine: {
-        timeoutInterval: 10000
-      }
-    }
   })
 }