etro 0.7.0 → 0.8.0

package/.github/workflows/nodejs.yml

@@ -9,7 +9,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [8.x, 10.x, 12.x]
+        node-version: [10.x, 12.x]
 
     steps:
     - uses: actions/checkout@v1

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [0.8.0] - 2021-04-11
+### Added
+- Type declarations.
+- `duration` option for `Movie#record`, to only record a subsection of the movie.
+- `'movie.recordended'` event. This does not affect the behavior of `'movie.ended'`.
+- Grayscale effect.
+- `etro.event.unsubscribe` to remove event listeners.
+- Image and video layers' `destX`, `destY`, `destWidth` and `destHeight`.
+  - Previously `imageX`, `imageY`, `imageWidth`, `imageHeight`, ...
+  - Allows for rotating these layers without cropping out parts.
+
+### Changed
+- All constructor arguments are now supplied through an `options` object.
+- Now `Movie#record` also accepts its arguments through an `options` object.
+- Keyframes are now entered as `new etro.KeyFrame([time1, val1, interp],
+  [time2, val2])`
+- Rename `clip*` to `source*` for image layers.
+  - `clipX` is now `sourceX`, etc.
+- Rename `image` to `source` for image layers.
+- Rename `source` to `audioNode` and `media` to `source` for audio and video layers.
+  - And `mediaStartTime` to `sourceStartTime`
+- For image and video layers, `width` now defaults to `destWidth`, which defaults to `sourceWidth`, which defaults to the width of the image or video.
+- The `movie.audiodestinationupdate` event is now published on the movie instead of each layer.
+- The movie's `audioContext` option is now `actx` (to match the property).
+
+### Deprecated
+- `etro.mapPixels` - use `etro.effect.Shader` instead, because it supports
+  hardware-acceleration
+- `audioContext` option for `Movie` - use `actx` instead.
+
+### Removed
+- Video files for examples (can now be downloaded with `npm run assets`).
+
+### Fixed
+- Browsers that do not implement `AudioContext` are now supported.
+- Movie not rendering with no layers.
+- Issues with modifying `Movie#layers` and `Movie#effects`.
+- Layers no longer error on 'movie.seek' event.
+- Property filters' `this` is now set to the owner of the property.
+- Visual layers' `width` and `height` property filters now default to the movie's width and height.
+- Visual layers' `border` property not being processed correctly.
+- Effects' and layers' `attach()` and `detach()` methods not being called when replaced by another effect or layer.
+
 ## [0.7.0] - 2020-12-17
 ### Added
 - Importing with CommonJS syntax.
@@ -128,7 +171,8 @@
   - Gaussian blur
   - Transform
 
-[Unreleased]: https://github.com/etro-js/etro/compare/v0.7...HEAD
+[Unreleased]: https://github.com/etro-js/etro/compare/v0.8...HEAD
+[0.8.0]: https://github.com/etro-js/etro/compare/v0.7...v0.8
 [0.7.0]: https://github.com/etro-js/etro/compare/v0.6...v0.7
 [0.6.0]: https://github.com/etro-js/etro/compare/v0.5...v0.6
 [0.5.0]: https://github.com/etro-js/etro/compare/v0.4...v0.5

package/CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 Thank you for considering contributing to Etro! There are many ways you can contribute to Etro, like creating issues for features or bugs, improving the docs or wiki, or writing the actual code for the library. This page covers how to make changes to the repository files (either code or docs).
 
-> Etro has a [Taiga Project](https://tree.taiga.io/project/etro-js-etro/epics) for managing issues and a [Slack workspace](https://join.slack.com/t/etrojs/shared_invite/enQtNzgxODc0ODUyMjU2LTA5MGM5YzIyOGU5NjQxY2E0YmIzYzhhZTU4ODdjNzBiY2M3MzgwZTZiYzU5ZmE2NmYyMjc0ZTE0ZWIxMjBmN2Q) for questions and casual discussion
+> Etro has a [Taiga Project](https://tree.taiga.io/project/etro-js-etro/epics) for managing issues and a [GitHub Discussion page](https://github.com/etro-js/etro/discussions) for questions, ideas and casual discussion
 
 ## Setting up your local environment
 
@@ -17,11 +17,9 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 - Create your own fork of Etro. Then run
 
   ```
-  $ git clone https://github.com/username/etro.git`
-  $ cd etro
-  $ git remote add upstream https://github.com/etro-js/etro.git
-  $ git fetch upstream
-  $ npm install
+  git clone -b master --single-branch https://github.com/username/etro.git
+  cd etro
+  npm install
   ```
 
 #### Step 2: Branch
@@ -29,7 +27,7 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 - To help organize your work, create a branch for your topic. Avoid working directly off the `master` branch
 
   ```
-  $ git checkout -b topic-branch
+  git checkout -b topic-branch
   ```
 
 ## Making your changes
@@ -38,20 +36,26 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 
 - If you are writing code, please follow the style guide [StandardJS](https://standardjs.com/rules.html)
 
-- To start the development server run
+- To download the example assets run
 
   ```
-  $ npm start
+  npm run assets
   ```
 
-  Then, you can see your changes by running some [examples](examples).
+- Then, start the development server with
+
+  ```
+  npm start
+  ```
+
+  Now you can see your changes by running some [examples](examples).
 
 - When you're ready to submit a piece of work, first run
 
   ```
-  $ npm run lint
-  $ npm run build
-  $ npm test
+  npm run lint
+  npm run build
+  npm test
   ```
 
   to lint the code, generate the [dist](dist) files and run unit tests on them. It may be helpful to put these commands in a pre-commit hook.
@@ -78,14 +82,14 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 - First, rebase (don't merge) to integrate your work with the main repository
 
   ```
-  $ git fetch upstream
-  $ git rebase upstream/master
+  git fetch upstream
+  git rebase upstream/master
   ```
 
 - Push your changes to the topic branch in your fork of the repository
 
   ```
-  $ git push origin topic-branch
+  git push origin topic-branch
   ```
 
 #### Step 4: Pull request
@@ -99,9 +103,9 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 - A large part of the submission process is receiving feedback on how you can improve you pull request. If you need change your pull request,
 
   ```
-  $ git add path/to/changes
-  $ git commit
-  $ git push origin topic-branch
+  git add path/to/changes
+  git commit
+  git push origin topic-branch
   ```
 
 ## Code overview

package/README.md

@@ -3,25 +3,30 @@
 [![](https://img.shields.io/npm/v/etro)](https://www.npmjs.com/package/etro)
 [![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fetro-js%2Fetro%2Fbadge&style=flat)](https://actions-badge.atrox.dev/etro-js/etro/goto)
 
-> A video editor for developers
+> [Version 0.8 is out](https://etrojs.dev/blog/introducing-v0-8-0)!
+> Check out [this guide](https://etrojs.dev/docs/migrating-v0-8-0)
+> for migrating.
 
-![Screenshot](screenshots/2019-08-17_0.png)
-
-Etro is a completely in-browser video-editing framework. Similar to GUI-based video-editing software, it lets you layer media and other content on a timeline. Audio, image, video and other tracks are supported, along with powerful video and audio manipulation to existing tracks. Being very flexible and extendable, you can choose to only use the core components or define your own.
+Etro is a JavaScript framework for programmatically editing videos. Similar
+to GUI-based video-editing software, it lets you layer media and other
+content on a timeline. Audio, image, video and other tracks are supported,
+along with powerful video effectts for existing tracks. Being very flexible
+and extendable, you can choose to only use the core components or define your
+own.
 
 ## Features
 
-- Export video to blob
-- Write your own layers and effects
-- Write a function for a property
-- Keyframes
-- Built-in hardware accelerated visual effects
-- More coming soon
+- Composite video and audio layers
+- Use built-in hardware accelerated effects
+- Write your own effects in JavaScript and GLSL
+- Manipulate audio with the web audio API
+- Define layer and effect properties as keyframes and functions
+- Export to a blob or file
 
 ## Installation
 
 ```
-npm install etro
+npm i etro
 ```
 
 ## Usage
@@ -31,34 +36,83 @@ You can use CommonJS syntax:
 import etro from 'etro'
 ```
 
-Or include it as a global `etro`:
-```html
+Or include it as a global etro:
+```js
 <script src="node_modules/etro/dist/etro-iife.js"></script>
 ```
 
-Then, to create a movie (a Etro "project")
+Let's look at an example:
 ```js
-var movie = new etro.Movie(canvas);
+var movie = new etro.Movie({ canvas: outputCanvas })
+var layer = new etro.layer.Video({ startTime: 0, source: videoElement })  // the layer starts at 0s
+movie.addLayer(layer)
+movie.record({ frameRate: 24 })  // or just `play` if you don't need to save it
+    .then(blob => ...)
 ```
 
-Then, add layers
+This renders `videoElement` to a blob at 24 fps. This blob can then be
+downloaded as a video file.
+
+Effects can transform the output of a layer or movie:
 ```js
-movie
-  // add a solid blue layer starting at 0s and lasting 3s and filling the entire screen
-  .addLayer(new etro.layer.Visual(0, 3, {background: 'blue'}))
-  // add a cropped video layer starting at 2.5s
-  .addLayer(new etro.layer.Video(2.5, video, {mediaX: 10, mediaY: -25}));
+var layer = new etro.layer.Video({ startTime: 0, source: videoElement })
+    .addEffect(new etro.effect.Brightness({ brightness: +100) }))
+```
+
+## Using in Node
+
+To use Etro in Node, use the [wrapper](https://github.com/etro-js/etro-node):
+```
+npm i etro-node
 ```
 
-Finally, start the movie
 ```js
-movie.play();
+var etroNode = require('etro-node')
+
+etroNode(() => {
+  // You can access inputs as html elements and pass them to Etro as usual.
+  var image = document.getElementById('input1') // <img> element
+
+  // Use etro normally ...
+
+  movie
+    .exportRaw()
+    .then(window.done)
+// Tell Etro Node what inputs to load with { id: path }
+}, { input1: 'image.png' }, 'output.mp4')
 ```
 
+`etroNode()` takes an optional Puppeteer page argument, so you can run
+multiple Etro scripts on the same movie (useful for servers). See [the
+docs](https://github.com/etro-js/etro-node#documentation).
+
+## Running the Examples
+
+First, download the assets for the examples:
+
+```
+npm run assets
+```
+
+Then, start the development server (only used for convience while developing;
+you don't need a server to use Etro):
+
+```
+npm start
+```
+
+Now you can open any example (such as
+http://127.0.0.1:8080/examples/introduction/hello-world1.html).
+
+## TypeScript
+
+Etro is written in TypeScript, so it should work out of the box with TypeScript
+projects. However, it is also compatible with projects that do not use
+TypeScript.
+
 ## Further Reading
 
-- [Documentation](https://etrojs.dev)
-- [Wiki (WIP)](https://github.com/etro-js/etro/wiki)
+- [Documentation](https://etrojs.dev/docs)
 
 ## Contributing
 
@@ -66,4 +120,5 @@ See the [contributing guide](CONTRIBUTING.md)
 
 ## License
 
-Distributed under GNU General Public License v3. See `LICENSE` for more information.
+Distributed under GNU General Public License v3. See `LICENSE` for more
+information.

package/dist/effect/base.d.ts

@@ -0,0 +1,38 @@
+import { Movie } from '../movie';
+import { Visual } from '../layer/index';
+import BaseObject from '../object';
+/**
+ * Modifies the visual contents of a layer.
+ */
+export declare class Base implements BaseObject {
+    type: string;
+    publicExcludes: string[];
+    propertyFilters: Record<string, <T>(value: T) => T>;
+    enabled: boolean;
+    private _target;
+    /**
+     * The number of times this effect has been attached to a target minus the
+     * number of times it's been detached. (Used for the target's array proxy with
+     * `unshift`)
+     */
+    private _occurrenceCount;
+    constructor();
+    attach(target: Movie | Visual): void;
+    detach(): void;
+    /**
+     * Apply this effect to a target at the given time
+     *
+     * @param target
+     * @param reltime - the movie's current time relative to the layer
+     * (will soon be replaced with an instance getter)
+     * @abstract
+     */
+    apply(target: Movie | Visual, reltime: number): void;
+    /**
+     * The current time of the target
+     */
+    get currentTime(): number;
+    get parent(): Movie | Visual;
+    get movie(): Movie;
+    getDefaultOptions(): Record<string, unknown>;
+}

package/dist/effect/brightness.d.ts

@@ -0,0 +1,16 @@
+import { Dynamic } from '../util';
+import { Shader } from './shader';
+export interface BrightnessOptions {
+    brightness?: Dynamic<number>;
+}
+/**
+ * Changes the brightness
+ */
+export declare class Brightness extends Shader {
+    brightness: Dynamic<number>;
+    /**
+     * @param [brightness=0] - the value to add to each pixel's color
+     * channels (between -255 and 255)
+     */
+    constructor(options?: BrightnessOptions);
+}

package/dist/effect/channels.d.ts

@@ -0,0 +1,23 @@
+import { Dynamic } from '../util';
+import { Shader } from './shader';
+export interface ChannelsOptions {
+    factors?: Dynamic<{
+        r?: number;
+        g?: number;
+        b?: number;
+    }>;
+}
+/**
+ * Multiplies each channel by a different factor
+ */
+export declare class Channels extends Shader {
+    factors: Dynamic<{
+        r?: number;
+        b?: number;
+        g?: number;
+    }>;
+    /**
+     * @param factors - channel factors, each defaulting to 1
+     */
+    constructor(options?: ChannelsOptions);
+}

package/dist/effect/chroma-key.d.ts

@@ -0,0 +1,23 @@
+import { Dynamic, Color } from '../util';
+import { Shader } from './shader';
+export interface ChromaKeyOptions {
+    target?: Dynamic<Color>;
+    threshold?: Dynamic<number>;
+    interpolate?: Dynamic<boolean>;
+}
+/**
+ * Reduces alpha for pixels which are close to a specified target color
+ */
+export declare class ChromaKey extends Shader {
+    target: Dynamic<Color>;
+    threshold: Dynamic<number>;
+    interpolate: Dynamic<boolean>;
+    /**
+     * @param [target={r: 0, g: 0, b: 0, a: 1}] - the color to remove
+     * @param [threshold=0] - how much error to allow
+     * @param [interpolate=false] - <code>true</code> to interpolate
+     * the alpha channel, or <code>false</code> value for no smoothing (i.e. an
+     * alpha of either 0 or 255)
+     */
+    constructor(options?: ChromaKeyOptions);
+}

package/dist/effect/contrast.d.ts

@@ -0,0 +1,15 @@
+import { Dynamic } from '../util';
+import { Shader } from './shader';
+export interface ContrastOptions {
+    contrast?: Dynamic<number>;
+}
+/**
+ * Changes the contrast by multiplying the RGB channels by a constant
+ */
+export declare class Contrast extends Shader {
+    contrast: Dynamic<number>;
+    /**
+     * @param [contrast=1] - the contrast multiplier
+     */
+    constructor(options?: ContrastOptions);
+}

package/dist/effect/elliptical-mask.d.ts

@@ -0,0 +1,31 @@
+import { Movie } from '../movie';
+import { Dynamic } from '../util';
+import { Base } from './base';
+import { Visual } from '../layer/index';
+export declare class EllipticalMaskOptions {
+    x: Dynamic<number>;
+    y: Dynamic<number>;
+    radiusX: Dynamic<number>;
+    radiusY: Dynamic<number>;
+    rotation?: Dynamic<number>;
+    startAngle?: Dynamic<number>;
+    endAngle?: Dynamic<number>;
+    anticlockwise?: Dynamic<boolean>;
+}
+/**
+ * Preserves an ellipse of the layer and clears the rest
+ */
+export declare class EllipticalMask extends Base {
+    x: Dynamic<number>;
+    y: Dynamic<number>;
+    radiusX: Dynamic<number>;
+    radiusY: Dynamic<number>;
+    rotation: Dynamic<number>;
+    startAngle: Dynamic<number>;
+    endAngle: Dynamic<number>;
+    anticlockwise: Dynamic<boolean>;
+    private _tmpCanvas;
+    private _tmpCtx;
+    constructor(options: EllipticalMaskOptions);
+    apply(target: Movie | Visual, reltime: number): void;
+}

package/dist/effect/gaussian-blur.d.ts

@@ -0,0 +1,60 @@
+import { Stack } from './stack';
+import { Shader } from './shader';
+import { Movie } from '../movie';
+import { Visual } from '../layer';
+export interface GaussianBlurOptions {
+    radius: number;
+}
+/**
+ * Applies a Gaussian blur
+ */
+export declare class GaussianBlur extends Stack {
+    constructor(options: GaussianBlurOptions);
+}
+/**
+ * Shared class for both horizontal and vertical gaussian blur classes.
+ */
+declare class GaussianBlurComponent extends Shader {
+    radius: number;
+    shape: HTMLCanvasElement;
+    private _radiusCache;
+    /**
+     * @param src - fragment source code (specific to which component -
+     * horizontal or vertical)
+     * @param radius - only integers are currently supported
+     */
+    constructor(options: {
+        fragmentSource: string;
+        radius: number;
+    });
+    apply(target: Movie | Visual, reltime: number): void;
+    /**
+     * Render Gaussian kernel to a canvas for use in shader.
+     * @param kernel
+     * @private
+     *
+     * @return
+     */
+    private static _render1DKernel;
+    private static _gen1DKernel;
+    private static _genPascalRow;
+}
+/**
+ * Horizontal component of gaussian blur
+ */
+export declare class GaussianBlurHorizontal extends GaussianBlurComponent {
+    /**
+     * @param radius
+     */
+    constructor(options: GaussianBlurOptions);
+}
+/**
+ * Vertical component of gaussian blur
+ */
+export declare class GaussianBlurVertical extends GaussianBlurComponent {
+    /**
+     * @param radius
+     */
+    constructor(options: GaussianBlurOptions);
+}
+export {};

package/dist/effect/grayscale.d.ts

@@ -0,0 +1,7 @@
+import { Shader } from './shader';
+/**
+ * Converts the target to a grayscale image
+ */
+export declare class Grayscale extends Shader {
+    constructor();
+}

package/dist/effect/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @module effect
+ */
+export * from './base';
+export * from './brightness';
+export * from './channels';
+export * from './chroma-key';
+export * from './contrast';
+export * from './elliptical-mask';
+export * from './gaussian-blur';
+export * from './grayscale';
+export * from './pixelate';
+export * from './shader';
+export * from './stack';
+export * from './transform';

package/dist/effect/pixelate.d.ts

@@ -0,0 +1,18 @@
+import { Visual } from '../layer';
+import { Movie } from '../movie';
+import { Dynamic } from '../util';
+import { Shader } from './shader';
+export interface PixelateOptions {
+    pixelSize?: Dynamic<number>;
+}
+/**
+ * Breaks the target up into squares of `pixelSize` by `pixelSize`
+ */
+export declare class Pixelate extends Shader {
+    pixelSize: Dynamic<number>;
+    /**
+     * @param pixelSize
+     */
+    constructor(options?: PixelateOptions);
+    apply(target: Movie | Visual, reltime: number): void;
+}

package/dist/effect/shader.d.ts

@@ -0,0 +1,99 @@
+import { Visual } from '../layer/index';
+import { Movie } from '../movie';
+import { Base } from './base';
+export interface UniformOptions {
+    type?: string;
+    defaultFloatComponent?: number;
+}
+export interface TextureOptions {
+    createUniform?: boolean;
+    target?: any;
+    level?: number;
+    internalFormat?: any;
+    srcFormat?: any;
+    srcType?: any;
+    wrapS?: any;
+    wrapT?: any;
+    minFilter?: any;
+    magFilter?: any;
+}
+export interface ShaderOptions {
+    fragmentSource?: string;
+    uniforms?: Record<string, (UniformOptions | string)>;
+    textures?: Record<string, TextureOptions>;
+    sourceTextureOptions?: TextureOptions;
+}
+/**
+ * A hardware-accelerated pixel mapping using WebGL
+ */
+export declare class Shader extends Base {
+    /**
+     * WebGL texture units consumed by {@link Shader}
+     */
+    static INTERNAL_TEXTURE_UNITS: number;
+    private static _DEFAULT_TEXTURE_OPTIONS;
+    private static _VERTEX_SOURCE;
+    private static _IDENTITY_FRAGMENT_SOURCE;
+    private _program;
+    private _buffers;
+    private _canvas;
+    private _gl;
+    private _uniformLocations;
+    private _attribLocations;
+    private _userUniforms;
+    private _userTextures;
+    private _sourceTextureOptions;
+    private _inputTexture;
+    /**
+     * @param fragmentSrc
+     * @param [userUniforms={}] - object mapping uniform id to an
+     * options object or a string (if you only need to provide the uniforms'
+     * type)
+     * @param [userTextures=[]]
+     * @param [sourceTextureOptions={}]
+     */
+    constructor(options?: ShaderOptions);
+    private _initGl;
+    private _initTextures;
+    private _initAttribs;
+    private _initUniforms;
+    apply(target: Movie | Visual, reltime: number): void;
+    private _checkDimensions;
+    private _refreshGl;
+    private _enablePositionAttrib;
+    private _enableTexCoordAttrib;
+    private _prepareTextures;
+    private _prepareUniforms;
+    private _draw;
+    /**
+     * Converts a value of a standard type for javascript to a standard type for
+     * GLSL
+     * @param value - the raw value to prepare
+     * @param outputType - the WebGL type of |value|; example:
+     * <code>1f</code> for a float
+     * @param reltime - current time, relative to the target
+     * @param [options] - Optional config
+     */
+    private _prepareValue;
+    private static _initRectBuffers;
+    /**
+     * Creates the quad covering the screen
+     */
+    private static _initBuffer;
+    /**
+     * Creates a webgl texture from the source.
+     * @param [options] - optional WebGL config for texture
+     * @param [options.target=gl.TEXTURE_2D]
+     * @param [options.level=0]
+     * @param [options.internalFormat=gl.RGBA]
+     * @param [options.srcFormat=gl.RGBA]
+     * @param [options.srcType=gl.UNSIGNED_BYTE]
+     * @param [options.wrapS=gl.CLAMP_TO_EDGE]
+     * @param [options.wrapT=gl.CLAMP_TO_EDGE]
+     * @param [options.minFilter=gl.LINEAR]
+     * @param [options.magFilter=gl.LINEAR]
+     */
+    private static _loadTexture;
+    private static _initShaderProgram;
+    private static _loadShader;
+}