etro 0.13.0 → 0.14.0

package/dist/util.d.ts

@@ -1,123 +1,128 @@
-/**
- * @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`.
- *
- * @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;
-export declare function clearCachedValues(movie: Movie): void;
-declare type Interpolate = <U = number | object>(startValue: U, endValue: U, percentProgress: number, interpolationKeys: string[]) => U;
-/**
- * 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: (number | T | Interpolate)[][];
-    /** Keys to interpolate, or all keys if undefined */
-    interpolationKeys: string[];
-    constructor(...value: (number | 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;
-export {};
+/**
+ * @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`.
+ *
+ * @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;
+export declare function clearCachedValues(movie: Movie): void;
+type Interpolate = <U = number | object>(startValue: U, endValue: U, percentProgress: number, interpolationKeys: string[]) => U;
+/**
+ * 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: (number | T | Interpolate)[][];
+    /** Keys to interpolate, or all keys if undefined */
+    interpolationKeys: string[];
+    constructor(...value: (number | T)[][]);
+    withKeys(keys: string[]): KeyFrame<T>;
+    toJSON(): object;
+    evaluate(time: number): T;
+}
+/** A dynamic property. Supports simple values, keyframes and functions */
+export 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;
+    toJSON(): object;
+}
+/**
+ * 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;
+    toJSON(): object;
+}
+/**
+ * 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;
+export declare function serializeProperty(val: any): any;
+export declare function deserializeProperty(val: any): any;
+export {};

package/karma.conf.js

@@ -1,7 +1,40 @@
 // Karma configuration
 // Generated on Thu Sep 19 2019 02:05:06 GMT-0400 (Eastern Daylight Time)
 
-process.env.CHROME_BIN = require('puppeteer').executablePath()
+const { BrowserFinder } = require('@agent-infra/browser-finder')
+
+const finder = new BrowserFinder()
+
+// Detect which browsers are installed locally. Honor an explicit *_BIN
+// override if one is already set, otherwise ask the finder to locate it.
+function locateBrowser (type, envVar) {
+  if (process.env[envVar]) {
+    return process.env[envVar]
+  }
+  try {
+    return finder.findBrowser(type).path
+  } catch (e) {
+    return undefined
+  }
+}
+
+const browsers = []
+
+const chromeBin = locateBrowser('chrome', 'CHROME_BIN')
+if (chromeBin) {
+  process.env.CHROME_BIN = chromeBin
+  browsers.push('ChromeHeadlessWebGL')
+}
+
+const firefoxBin = locateBrowser('firefox', 'FIREFOX_BIN')
+if (firefoxBin) {
+  process.env.FIREFOX_BIN = firefoxBin
+  browsers.push('FirefoxHeadless')
+}
+
+if (browsers.length === 0) {
+  throw new Error('No supported browsers (Chrome or Firefox) found locally. Install one or set CHROME_BIN / FIREFOX_BIN.')
+}
 
 // Make sure TEST_SUITE is set
 if (!process.env.TEST_SUITE) {
@@ -56,7 +89,8 @@ module.exports = function (config) {
 
     // start these browsers
     // available browser launchers: https://npmjs.org/browse/keyword/karma-launcher
-    browsers: ['FirefoxHeadless'],
+    // Only the browsers detected as installed locally.
+    browsers,
 
     customLaunchers: {
       'FirefoxHeadless': {
@@ -64,8 +98,28 @@ module.exports = function (config) {
         flags: ['-headless'],
         prefs: {
           'network.proxy.type': 0,
-          'media.autoplay.default': 0  // Allow all autoplay
+          'media.autoplay.default': 0,  // Allow all autoplay
+          // Mute the speaker output only. The Web Audio graph still runs, so
+          // analyser-based assertions stay valid. Applies to karma's throwaway
+          // temp profile, so it won't affect a normal Firefox install.
+          'media.volume_scale': '0.0',
+          // Force WebGL on under software rendering (e.g. llvmpipe in CI),
+          // which Firefox would otherwise blocklist for lacking a GPU.
+          'webgl.force-enabled': true,
+          'webgl.disabled': false,
+          'webgl.disable-fail-if-major-performance-caveat': true
         }
+      },
+      'ChromeHeadlessWebGL': {
+        base: 'ChromeHeadless',
+        flags: [
+          '--use-gl=angle',
+          '--use-angle=swiftshader',
+          '--no-sandbox',
+          '--autoplay-policy=no-user-gesture-required',
+          // Mute the speaker output only; the Web Audio graph still runs.
+          '--mute-audio'
+        ]
       }
     },
 
@@ -89,6 +143,10 @@ module.exports = function (config) {
     concurrency: Infinity,
 
     karmaTypescriptConfig: {
+      compilerOptions: {
+        // Avoid type-checking third-party declaration packages in browser tests.
+        skipLibCheck: true
+      },
       bundlerOptions: {
         // Resemblejs only references the `canvas` dependency in the node
         // runtime. Since the tests are run in a browser, we need to exclude it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "etro",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "An extendable video-editing framework for the browser",
   "main": "dist/etro-cjs.js",
   "types": "dist/index.d.ts",
@@ -10,12 +10,11 @@
     "test": "spec"
   },
   "devDependencies": {
-    "@commitlint/cli": "^17.6.6",
-    "@commitlint/format": "^17.4.4",
+    "@agent-infra/browser-finder": "^0.2.2",
     "@rollup/plugin-eslint": "^9.2.0",
     "@types/jest": "^29.0.0",
-    "@typescript-eslint/eslint-plugin": "^5.30.7",
-    "@typescript-eslint/parser": "^5.30.7",
+    "@typescript-eslint/eslint-plugin": "^5.62.0",
+    "@typescript-eslint/parser": "^5.62.0",
     "cross-env": "^7.0.3",
     "docdash": "^1.1.1",
     "ecstatic": ">=4.1.3",
@@ -27,27 +26,26 @@
     "eslint-plugin-promise": "^6.0.0",
     "eslint-plugin-standard": "^5.0.0",
     "ev": "0.0.7",
-    "gitmoji-cli": "^9.0.0",
     "http-server": "^14.1.1",
     "husky": "^8.0.3",
     "jasmine": "^3.4.0",
-    "jasmine-ts": "^0.4.0",
-    "karma": "^6.1.1",
+    "karma": "^6.4.4",
+    "karma-chrome-launcher": "^3.2.0",
     "karma-firefox-launcher": "^2.1.2",
-    "karma-jasmine": "^2.0.1",
+    "karma-jasmine": "^5.1.0",
     "karma-super-dots-reporter": "^0.2.0",
-    "karma-typescript": "^5.5.3",
+    "karma-typescript": "^5.5.4",
     "keep-a-changelog": "^0.10.4",
     "puppeteer": "^2.0.0",
     "resemblejs": "^4.1.0",
-    "rollup": "^4.53.3",
+    "rollup": "^4.61.1",
     "rollup-plugin-cleaner": "^1.0.0",
     "rollup-plugin-node-resolve": "^5.2.0",
-    "rollup-plugin-typescript2": "^0.29.0",
+    "rollup-plugin-typescript2": "^0.37.0",
     "rollup-plugin-uglify-es": "^0.0.1",
-    "shipjs": "^0.27.0",
-    "typedoc": "^0.23.8",
-    "typescript": "^4.7.4"
+    "shipjs": "^0.28.3",
+    "typedoc": "^0.28.19",
+    "typescript": "^5.0.4"
   },
   "scripts": {
     "build": "rollup -c",

package/ship.config.js

@@ -25,17 +25,15 @@ module.exports = {
     const newChangelog = parsed.toString()
     fs.writeFileSync(changelogFile, newChangelog, 'utf8')
   },
-  releases: [
-    {
-      extractChangelog: ({ version, dir }) => {
-        const changelogFile = `${dir}/CHANGELOG.md`
-        const changelog = fs.readFileSync(changelogFile, 'utf8')
-        const parsed = parser(changelog)
-        const release = parsed.findRelease(version)
-        return `${release.toString()}\n${release.getCompareLink()}`
-      },
-    }
-  ]
+  releases: {
+    extractChangelog: ({ version, dir }) => {
+      const changelogFile = `${dir}/CHANGELOG.md`
+      const changelog = fs.readFileSync(changelogFile, 'utf8')
+      const parsed = parser(changelog)
+      const release = parsed.findRelease(version)
+      return `${release.toString()}\n${release.getCompareLink()}`
+    },
+  }
 }
 
 class Changelog {

package/src/effect/base.ts

@@ -1,6 +1,7 @@
 import { Movie } from '../movie'
 import { Base as BaseLayer } from '../layer/index'
 import BaseObject from '../object'
+import { serializeProperty } from '../util'
 
 /**
  * @deprecated All visual effects now inherit from `Visual` instead
@@ -108,6 +109,21 @@ export class Base implements BaseObject {
   getDefaultOptions (): Record<string, unknown> {
     return {}
   }
+
+  toJSON (): object {
+    const json: any = { type: `effect.${this.constructor.name}` }
+    const exclude = ['type', 'publicExcludes', 'propertyFilters', 'movie', 'ready', 'parent', 'currentTime', ...this.publicExcludes]
+    for (const key in this) {
+      if (key.startsWith('_') || exclude.indexOf(key) !== -1 || typeof (this as any)[key] === 'function') {
+        continue
+      }
+      json[key] = serializeProperty((this as any)[key])
+    }
+    if ((this as any).effects && (this as any).effects.length > 0) {
+      json.effects = (this as any).effects.map((e: any) => e.toJSON())
+    }
+    return json
+  }
 }
 // id for events (independent of instance, but easy to access when on prototype
 // chain)

package/src/layer/base.ts

@@ -1,5 +1,5 @@
 import EtroObject from '../object'
-import { applyOptions } from '../util'
+import { applyOptions, serializeProperty } from '../util'
 import { Movie } from '../movie'
 
 interface BaseOptions {
@@ -219,6 +219,24 @@ class Base implements EtroObject {
       duration: undefined // required
     }
   }
+
+  toJSON (): object {
+    const json: any = { type: `layer.${this.constructor.name}` }
+    const exclude = ['type', 'publicExcludes', 'propertyFilters', 'movie', 'ready', 'parent', 'currentTime', 'effects', ...this.publicExcludes]
+    for (const key in this) {
+      if (key.startsWith('_') || exclude.indexOf(key) !== -1 || typeof (this as any)[key] === 'function') {
+        continue
+      }
+      json[key] = serializeProperty((this as any)[key])
+    }
+    json.startTime = this.startTime
+    json.duration = this.duration
+
+    if ((this as any).effects && (this as any).effects.length > 0) {
+      json.effects = (this as any).effects.map((e: any) => e.toJSON())
+    }
+    return json
+  }
 }
 // id for events (independent of instance, but easy to access when on prototype
 // chain)

package/src/movie/movie.ts

@@ -3,9 +3,11 @@
  */
 
 import { publish, deprecate } from '../event'
-import { Dynamic, val, clearCachedValues, applyOptions, Color, parseColor } from '../util'
+import { Dynamic, val, clearCachedValues, applyOptions, Color, parseColor, serializeProperty, deserializeProperty } from '../util'
 import { Base as BaseLayer, Audio as AudioLayer, Video as VideoLayer, Visual } from '../layer/index' // `Media` mixins
 import { Base as BaseEffect } from '../effect/index'
+import * as Layers from '../layer/index'
+import * as Effects from '../effect/index'
 import { MovieEffects } from './effects'
 import { MovieLayers } from './layers'
 
@@ -182,7 +184,7 @@ export class Movie {
    * 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.frameRate The maximum 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.
@@ -265,7 +267,7 @@ export class Movie {
    * Plays the movie in the background and records it
    *
    * @param options
-   * @param [options.frameRate] - Video frame rate
+   * @param [options.frameRate] - Maximum video frame rate (fps)
    * @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
@@ -854,6 +856,117 @@ export class Movie {
       repeat: false
     }
   }
+
+  toJSON (): object {
+    return {
+      type: 'movie',
+      canvas: this.canvas ? { width: this.canvas.width, height: this.canvas.height } : undefined,
+      background: serializeProperty(this.background),
+      repeat: this.repeat,
+      layers: this.layers.map(layer => (layer as any).toJSON()),
+      effects: this.effects.map(effect => (effect as any).toJSON())
+    }
+  }
+
+  static fromJSON (json: any, canvas?: HTMLCanvasElement, actx?: AudioContext): Movie {
+    if (!canvas) {
+      canvas = document.createElement('canvas')
+      if (json.canvas) {
+        canvas.width = json.canvas.width
+        canvas.height = json.canvas.height
+      }
+    }
+    const options: any = {
+      canvas,
+      actx,
+      background: deserializeProperty(json.background),
+      repeat: json.repeat
+    }
+    const movie = new Movie(options)
+
+    const deserializeEffect = (effectJson: any): any => {
+      const type = effectJson.type.replace('effect.', '')
+      const EffectClass = (Effects as any)[type]
+      if (!EffectClass) {
+        throw new Error(`Unknown effect type: ${type}`)
+      }
+
+      const effectOptions: any = {}
+      const defaultOptions = EffectClass.prototype.getDefaultOptions ? EffectClass.prototype.getDefaultOptions() : {}
+
+      for (const key in effectJson) {
+        if (key !== 'type' && key !== 'effects') {
+          if (key in defaultOptions) {
+            effectOptions[key] = deserializeProperty(effectJson[key])
+          }
+        }
+      }
+
+      if (effectJson.effects) {
+        effectOptions.effects = effectJson.effects.map((subEffectJson: any) => deserializeEffect(subEffectJson))
+      }
+
+      const effect = new EffectClass(effectOptions)
+      for (const key in effectJson) {
+        if (key !== 'type' && key !== 'effects' && !(key in defaultOptions)) {
+          effect[key] = deserializeProperty(effectJson[key])
+        }
+      }
+      return effect
+    }
+
+    const deserializeLayer = (layerJson: any): any => {
+      const type = layerJson.type.replace('layer.', '')
+      const LayerClass = (Layers as any)[type]
+      if (!LayerClass) {
+        throw new Error(`Unknown layer type: ${type}`)
+      }
+
+      const layerOptions: any = {}
+      const defaultOptions = LayerClass.prototype.getDefaultOptions ? LayerClass.prototype.getDefaultOptions() : {}
+      if (!('startTime' in defaultOptions)) {
+        defaultOptions.startTime = undefined
+      }
+      if (!('duration' in defaultOptions)) {
+        defaultOptions.duration = undefined
+      }
+
+      for (const key in layerJson) {
+        if (key !== 'type' && key !== 'effects') {
+          if (key in defaultOptions) {
+            layerOptions[key] = deserializeProperty(layerJson[key])
+          }
+        }
+      }
+
+      const layer = new LayerClass(layerOptions)
+      for (const key in layerJson) {
+        if (key !== 'type' && key !== 'effects' && !(key in defaultOptions)) {
+          layer[key] = deserializeProperty(layerJson[key])
+        }
+      }
+      if (layerJson.effects) {
+        for (const effectJson of layerJson.effects) {
+          layer.addEffect(deserializeEffect(effectJson))
+        }
+      }
+      return layer
+    }
+
+    if (json.layers) {
+      for (const layerJson of json.layers) {
+        movie.addLayer(deserializeLayer(layerJson))
+      }
+    }
+
+    if (json.effects) {
+      for (const effectJson of json.effects) {
+        movie.addEffect(deserializeEffect(effectJson))
+      }
+    }
+
+    return movie
+  }
 }
 
 // Id for events