etro 0.6.0 → 0.8.1

package/.github/workflows/nodejs.yml

@@ -4,12 +4,11 @@ on: [push]
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [8.x, 10.x, 12.x]
+        node-version: [10.x, 12.x]
 
     steps:
     - uses: actions/checkout@v1
@@ -17,6 +16,9 @@ jobs:
       uses: actions/setup-node@v1
       with:
         node-version: ${{ matrix.node-version }}
+    - name: Update npm
+      run: |
+        npm i -g npm@^7.x
     - name: npm install, lint, build, and test
       run: |
         npm ci

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## [0.8.1] - 2021-04-20
+### Fixed
+- `sourceStartTime` getting ignored on `'movie.seek'`.
+- Calling methods like `unshift` on `Movie#layers` and `Movie#effects`.
+- `GaussianBlur` effect throwing a `TypeError` when applied to a movie or layer.
+- Issues with audio and video layers re-attaching to a movie.
+
+## [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.
+- MIME type option for `record`.
+
+### Changed
+- Movies are no longer hidden and silent when exporting.
+- Media layers' audio nodes can now be reconnected to other audio nodes.
+- `refresh` can be called when the movie is playing or recording to force render.
+
+### Removed
+- Image layers' `imageX`, `imageY`, `imageWidth` and `imageHeight` properties. Every image is now rendered over its entire layer.
+- Video layers' `mediaX`, `mediaY`, `mediaWidth` and `mediaHeight` properties. Every video is now rendered over its entire layer.
+
+### Fixed
+- Fix recording with only video or only audio.
+- Video layers' `clipWidth` and `clipHeight` are no longer treated as invalid options.
+- Image layers' `clipWidth` and `clipHeight` are no longer set in the constructor, so if the `clipWidth` option is not supplied and the layer's `width` changes `clipWidth` uses the new `width`.
+- Video and image layers' `width` and `height` default to their `clipWidth` and `clipHeight` respectively.
+- Elliptical mask effect throwing `TypeError: path.split is not a function`.
+- In shader effects, textures whose dimensions are not powers of two accept interpolation filters.
+- No longer ignore video layers' `mediaWidth` option.
+- Treat layers' `enabled` property as dynamic (allowing for keyframes and functions).
+- Make each media layer's duration depend on its playback rate.
+
+### Security
+- Update vulnerable dependencies.
+
 ## [0.6.0] - 2019-12-26
 ### Added
 - Add [API documentation](https://etrojs.dev/).
@@ -100,10 +178,13 @@
   - Gaussian blur
   - Transform
 
-[0.6.0]: https://github.com/etro-js/etro/compare/v0.6...HEAD
-[0.5.0]: https://github.com/etro-js/etro/compare/v0.5...v0.6
-[0.4.0]: https://github.com/etro-js/etro/compare/v0.4...v0.5
-[0.3.0]: https://github.com/etro-js/etro/compare/v0.3...v0.4
+[Unreleased]: https://github.com/etro-js/etro/compare/v0.8.1...HEAD
+[0.8.1]: https://github.com/etro-js/etro/compare/v0.8...v0.8.1
+[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
+[0.4.0]: https://github.com/etro-js/etro/compare/v0.3...v0.4
 [0.3.0]: https://github.com/etro-js/etro/compare/v0.2...v0.3
 [0.2.0]: https://github.com/etro-js/etro/compare/v0.1...v0.2
 [0.1.0]: https://github.com/etro-js/etro/releases/tag/v0.1

package/CODE_OF_CONDUCT.md

@@ -55,11 +55,11 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting me at **\@etro-js** in the [Slack workspace]. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
+reported by contacting me at **\@etro-js** on Twitter. All complaints will be
+reviewed and investigated and will result in a response that is deemed necessary
+and appropriate to the circumstances. The project team is obligated to maintain
+confidentiality with regard to the reporter of an incident. Further details of
+specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good
 faith may face temporary or permanent repercussions as determined by other

package/CONTRIBUTING.md

@@ -4,66 +4,47 @@
 
 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
 
 #### Step 0: Dependencies
 
-- You will need `git`, `node` and `npm`
+- You will need Git, Node, NPM (at least 7.x) and Chrome (for headless unit testing) installed
 
 #### Step 1: Fork
 
 - 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
-  ```
-
-#### Step 2: Branch
-
-- To help organize your work, create a branch for your topic. Avoid working directly off the `master` branch
-
-  ```
-  $ git checkout -b topic-branch
+  git clone -b master --single-branch https://github.com/username/etro.git
+  cd etro
+  npm install
   ```
 
 ## Making your changes
 
-#### Step 3: Code
-
-- If you are writing code, please follow the style guide [StandardJS](https://standardjs.com/rules.html)
+#### Step 2: Code
 
-- To start the development server run
+- Make some changes.
+- If you are writing code, the linter uses [StandardJS](https://standardjs.com/rules.html) for style conventions.
+- When you're ready to submit a piece of code, first run
 
   ```
-  $ npm start
+  npm run lint
+  npm run build
+  npm test
   ```
 
-  Then, 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
-  ```
-
-  to lint the code, generate the [dist](dist) files and run unit tests on them.
+  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.
 
 - Commit your changes
-  - Please avoid squashing all your commits into one; we try to keep each commit atomic in the `master` branch
+  - Please avoid squashing all your commits into one; we try to keep atomic commits.
   - Please follow these commit message guidelines:
-    - Optionally, begin each commit message with [an appropriate emoji](https://gitmoji.carloscuesta.me/)
-    - Then, write a concise summary of your changes. If you feel you need to, bullet the main idea of your changes in the description and/or explain why you made the changes.
+    - Optionally, prefix each commit message with [an appropriate emoji](https://gitmoji.dev)
     - Write in the imperative tense
-    - The first line should be 50 characters or less. Wrap lines after around 72 characters (for Vim add `filetype indent plugin on` to ~/.vimrc, and its enabled by default in Atom).
-    - *Example:*
+    - Wrap lines after 72 characters (for Vim add `filetype indent plugin on` to ~/.vimrc, it's enabled by default in Atom).
+    - Example:
 
       ```
       :emoji: One-liner
@@ -78,61 +59,38 @@ 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
-  ```
+- Push to your fork
 
 #### Step 4: Pull request
 
-- Open a pull request from your topic-branch to the main repository
+- Open a pull request from your the branch in your fork to the main repository
 - In the PR title, include **fixes ###** for bugs and **resolves ###** for feature requests
 - If you changed any core functionality, make sure you explain your motives for those changes
 
 #### Step 5: Feedback
 
-- 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
-  ```
+- A large part of the submission process is receiving feedback on how you can improve you pull request. If you need to change your pull request, feel free to push more commits.
 
 ## Code overview
 
-*Note: To specify the ES6 module (file) that a declaration exists in, the following syntax will be used: `module.export`.*
-
-### Module Structure
+### Etro Overview
 
-If you are new to the core elements of etro, you should probably read [the *Overview* wiki page](https://github.com/etro-js/etro.wiki/Overview.md).
+If you are new to the core elements of etro, you should probably read [the overview guide](https://etrojs.dev/docs/overview).
 
-Here are the contents of **src**:
+### API Structure
 
-| Path | Contents |
-| --- | --- |
-| [**effect.js**](src/effect.js) | all (visual) effect classes |
-| [**event.js**](src/event.js) | the pub/sub mechanics |
-| [**index.js**](src/index.js) | the entry module |
-| [**layer.js**](src/layer.js) | all layer classes |
-| [**movie.js**](src/movie.js) | the `Movie` class |
-| [**util.js**](src/util.js) | general utility |
+* `etro.Movie` - the movie
+* `etro.layer.*` - all layers
+* `etro.effect.*` - all (visual) effects
+- `etro.event.publish` - emit an event
+- `etro.event.subscribe` - add an event listener
+- `etro.*` - other utility classes and methods (see **src/util.ts**)
 
-Note that most of the above files will (hopefully soon) be broken down into multiple files each.
-
-### Etro Objects
-
-The base etro objects are the following:
-* `Movie` - the movie (or entire user project)
-* `layer.Base` - the root type of layer
-* `effect.Base` - the root type of visual effect
-
-### Concepts
+### Etro concepts
 
 #### Pub/sub system
 
@@ -147,9 +105,5 @@ That will notify all listeners of `movie` for event types `'movie'`, `'movie.typ
 ```js
 event.subscribe(movie, 'movie.type', event => {
   console.log(event.target, event.type, event.additionalData) // should print the movie, 'movie.type.of.event', 'foo'
-}
+})
 ```
-
-#### Values vs. Properties
-
-In Etro objects, almost any property can be a [keyframe](https://github.com/etro-js/etro/wiki/Keyframes), [function](https://github.com/etro-js/etro/wiki/Functions), or just a constant value. To access the current value of the property at a given time, use `util.val(property, element, time)`; where `property` is the keyframe set, function or constant value, `element` is the object to which `property` belongs, and `time` is the current time relative to the element.

package/README.md

@@ -3,55 +3,122 @@
 [![](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 library. Similar to conventional 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 typescript 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 i etro
+```
 
 ## Usage
 
-```html
-<script src="https://unpkg.com/etro@latest/dist/etro.js"></script>
+You can use CommonJS syntax:
+```js
+import etro from 'etro'
 ```
 
-Then, to create a movie (which is a project)
+Or include it as a global etro:
 ```js
-const movie = new etro.Movie(canvas);
+<script src="node_modules/etro/dist/etro-iife.js"></script>
 ```
 
-Then, add layers
+Let's look at an example:
 ```js
-movie
-  // add an empty blue layer starting at 0s and lasting 3s and filling the entire screen
-  .addLayer(new etro.layer.Base(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 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 => ...)
 ```
 
-To start the movie, just like any ol' `<video>` or `<audio>`, use `.play()`
+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.play();
+var layer = new etro.layer.Video({ startTime: 0, source: videoElement })
+    .addEffect(new etro.effect.Brightness({ brightness: +100) }))
 ```
 
-## License
+## Using in Node
+
+To use Etro in Node, use the [wrapper](https://github.com/etro-js/etro-node):
+```
+npm i etro-node
+```
+
+```js
+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):
 
-Distributed under GNU General Public License v3. See `LICENSE` for more information.
+```
+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
 
 See the [contributing guide](CONTRIBUTING.md)
+
+## License
+
+Distributed under GNU General Public License v3. See `LICENSE` for more
+information.

package/dist/effect/base.d.ts

@@ -0,0 +1,51 @@
+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();
+    /**
+     * Attaches this effect to `target` if not already attached.
+     * @ignore
+     */
+    tryAttach(target: Movie | Visual): void;
+    attach(movie: Movie | Visual): void;
+    /**
+     * Dettaches this effect from its target 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;
+    /**
+     * 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;
+}