etro 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [0.10.0] - 2023-04-18
+### Added
+- `Movie#stream()` to stream the movie to a `MediaStream`.
+- New `onStart` option for `Movie#play()` and `Movie#record()`.
+- Image, audio and video layers' `source` properties now accept urls ([#153](https://github.com/etro-js/etro/pull/153)).
+- Movies, layers and effects have a new `ready` getter, indicating if they are ready to play.
+- Layers and effects now have an async `whenReady` method.
+- `Movie#seek()` method.
+- Layers have new `seek()` and `progress()` methods.
+- `once` option for `subscribe`.
+
+### Changed
+- The (deprecated) `'movie.pause'` event is now published every time playback stops, regardless of the reason.
+- `source` properties of `Image`, `Audio` and `Video` have been retyped to `HTMLImageElement`, `HTMLAudioElement` and `HTMLVideoElement` respectively.
+
+### Deprecated
+- `etro.applyOptions()` and `EtroObject#getDefaultOptions()` are deprecated. Instead, set each option in the constructor ([#131](https://github.com/etro-js/etro/issues/131)).
+- The `Movie#currentTime` setter is deprecated. Use `Movie#seek()` instead.
+- `Movie#setCurrentTime()` is deprecated. Instead, call `seek()` and `refresh()` separately.
+- The `'movie.seek'` event is deprecated. Override the `seek()` method on layers instead.
+- The `'movie.timeupdate'` event is deprecated. Override the `progress()` method on layers instead.
+- The `'movie.loadeddata'` event is deprecated.
+- The `'movie.play'` event is deprecated. Provide the `onStart` option to `play()`, `stream()` or `record()` instead.
+- The `'movie.pause'` event is deprecated. Wait for `play()`, `stream()` or `record()` to resolve instead.
+- The `'movie.record'` event is deprecated. Provide the `onStart` option to `record()` instead.
+- The `'movie.recordended'` event is deprecated. Wait for `record()` to resolve instead.
+- The `'movie.ended'` event is deprecated.
+
+### Removed
+- `Movie#autoRefresh` (see [#130](https://github.com/etro-js/etro/issues/130)).
+- `change` events (see [#130](https://github.com/etro-js/etro/issues/130)).
+- `watchPublic()` and `publicExcludes` (see [#130](https://github.com/etro-js/etro/issues/130)).
+
+### Fixed
+- `Movie#currentTime` is now reset to 0 when the movie ends.
+- `Movie#play()` and `Movie#record()` now wait until all resources are loaded before starting.
+- `Movie#pause()` no longer stops inactive layers ([#203](https://github.com/etro-js/etro/issues/203)).
+- Array methods like `unshift` for `etro.layer.Visual#effects` and `etro.effect.Stack#effects` work properly.
+- `AudioSource#playbackRate` is now optional.
+- `duration` option for `Audio` and `Video` layers is now optional.
+- `Video` constructor now accepts missing options.
+
+## [0.9.1] - 2022-09-18
+### Fixed
+- Update color types from `string` to `Color` ([#135](https://github.com/etro-js/etro/pull/135)).
+- `Image` and `Video` classes now include missing properties.
+- `Movie#currentTime` no longer exceeds the stop time.
+
 ## [0.9.0] - 2022-07-17
 ### Changed
 - Methods in the `Base` effect now accept `Base` layers instead of `Visual` layers.
@@ -227,6 +275,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   - Gaussian blur
   - Transform
 
+[0.10.0]: https://github.com/etro-js/etro/compare/v0.9.1...v0.10.0
+[0.9.1]: https://github.com/etro-js/etro/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/etro-js/etro/compare/v0.8.5...v0.9.0
 [0.8.5]: https://github.com/etro-js/etro/compare/v0.8.4...v0.8.5
 [0.8.4]: https://github.com/etro-js/etro/compare/v0.8.3...v0.8.4

package/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-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).
+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 code for the library. This page covers how to make changes to the repository files (either code or jsdocs).
 
 [Join our Discord](https://discord.gg/myrBsQ8Cht)
 
@@ -10,52 +10,54 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 
 #### Step 0: Dependencies
 
-- You will need Git, Node, NPM (at least 7.x) and Firefox (for headless unit testing) installed
+- You will need Git, Node, NPM (at least 7.x) and Firefox (for headless functional testing) installed.
 
 #### Step 1: Fork
 
 - Create your own fork of Etro. Then run
 
   ```
-  git clone -b master --single-branch https://github.com/username/etro.git
+  git clone https://github.com/YOUR_USERNAME/etro.git
   cd etro
   npm install
-  node node_modules/puppeteer/install.js
+  npm test
   ```
 
 ## Making your changes
 
 #### Step 2: Code
 
-- Make some changes
+- Make some changes and update tests
 - If you are writing code, the linter uses [StandardJS](https://standardjs.com/rules.html) for style conventions
+- If you're adding or updating an effect:
+  - Add your effect to **scripts/gen-effect-samples.html**
+  - Run `npm run effects`
+  - Briefly review the images in **spec/integration/assets/effect/**
 - When you're ready to submit, 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. It may be helpful to put these commands in a pre-commit hook.
+  to lint the code, generate the [dist](dist) files and run unit tests on them. It's 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 atomic commits.
-  - Please follow these commit message guidelines:
-    - Optionally, prefix each commit message with [an appropriate emoji](https://gitmoji.dev)
-    - Write in the imperative tense
-    - Wrap lines after 72 characters (for Vim add `filetype indent plugin on` to ~/.vimrc, it's enabled by default in Atom).
-    - Example:
+#### Step 3: Commit
 
-      ```
-      :emoji: One-liner
+- Please follow these commit message guidelines:
+  - Optionally, prefix each commit message with [an appropriate emoji](https://gitmoji.dev), such as `:bug:` for fixes.
+  - Write in the imperative tense
+  - Wrap lines after 72 characters (for Vim add `filetype indent plugin on` to ~/.vimrc, it's enabled by default in Atom).
+  - Format:
+    ```
+    :emoji: One-liner
 
-      Optional description
-      ```
+    Optional description
+    ```
 
 ## Submitting your changes
 
-#### Step 3: Push
+#### Step 4: Push
 
 - First, rebase (please avoid merging) to integrate your work with any new changes in the main repository
 
@@ -66,12 +68,12 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 
 - Push to the fork
 
-#### Step 4: Pull request
+#### Step 5: Pull request
 
 - Open a pull request from the branch in your fork to the main repository
 - If you changed any core functionality, make sure you explain your motives for those changes
 
-#### Step 5: Feedback
+#### Step 6: Feedback
 
 - 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.
 
@@ -79,20 +81,9 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 
 ### Etro Overview
 
-Check out [the overview guide](https://etrojs.dev/docs/overview) for usage information
-
-### API Structure
-
-* `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**)
-
-### Etro concepts
+Check out [the user docs](https://etrojs.dev/docs/intro) for a high-level overview of Etro.
 
-#### Pub/sub system
+### Events
 
 Events emitted by Etro objects use a [pub/sub system](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern). To emit an event, use `event.publish(target, type, event)`. For instance,
 

package/README.md

@@ -3,14 +3,10 @@
 [![](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)
 
-> Etro was previously known as Etro, but it had to be renamed to avoid
-> confusion with an existing software product.
-
-Etro is a typescript framework for programmatically editing videos. Similar to
-GUI-based video-editing software, it lets you composite layers and add effects.
-Etro comes shipped with text, video, audio and image layers, along with a bunch
-of GLSL effects. You can also define your own layers and effects with javascript
-and GLSL.
+Etro is a typescript framework for programmatically editing videos. It lets you
+composite layers and add filters (effects). Etro comes shipped with text, video,
+audio and image layers, along with a bunch of GLSL effects. You can also define
+your own layers and effects with javascript and GLSL.
 
 [Join our Discord](https://discord.gg/myrBsQ8Cht)
 
@@ -74,16 +70,12 @@ To use Etro in Node, see the [wrapper](https://github.com/etro-js/etro-node):
 
 ## 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):
+Start the development server (only used for convenience while developing; you
+don't need a server to use Etro):
 
 ```
+npm i
+npm run build
 npm start
 ```
 
@@ -92,7 +84,7 @@ http://127.0.0.1:8080/examples/introduction/hello-world1.html).
 
 ## Further Reading
 
-- [Documentation](https://etrojs.dev/docs)
+- [Documentation](https://etrojs.dev/docs/intro)
 
 ## Contributing
 

package/dist/custom-array.d.ts

@@ -0,0 +1,10 @@
+export declare abstract class CustomArrayListener<T> {
+    abstract onAdd(item: T): void;
+    abstract onRemove(item: T): void;
+}
+/**
+ * An array that notifies a listener when items are added or removed.
+ */
+export declare class CustomArray<T> extends Array<T> {
+    constructor(target: T[], listener: CustomArrayListener<T>);
+}

package/dist/effect/base.d.ts

@@ -17,6 +17,10 @@ export declare class Base implements BaseObject {
      */
     private _occurrenceCount;
     constructor();
+    /**
+     * Wait until this effect is ready to be applied
+     */
+    whenReady(): Promise<void>;
     /**
      * Attaches this effect to `target` if not already attached.
      * @ignore
@@ -24,7 +28,7 @@ export declare class Base implements BaseObject {
     tryAttach(target: Movie | BaseLayer): void;
     attach(movie: Movie | BaseLayer): void;
     /**
-     * Dettaches this effect from its target if the number of times `tryDetach`
+     * Detaches 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.
      *
@@ -45,7 +49,12 @@ export declare class Base implements BaseObject {
      * The current time of the target
      */
     get currentTime(): number;
+    /** `true` if this effect is ready to be applied */
+    get ready(): boolean;
     get parent(): Movie | BaseLayer;
     get movie(): Movie;
+    /**
+     * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+     */
     getDefaultOptions(): Record<string, unknown>;
 }

package/dist/effect/shader.d.ts

@@ -2,6 +2,9 @@ import { Visual as VisualLayer } from '../layer/index';
 import { Movie } from '../movie';
 import { Visual } from './visual';
 export interface UniformOptions {
+    /**
+     * The type of the uniform.
+     */
     type?: string;
     defaultFloatComponent?: number;
 }
@@ -63,16 +66,23 @@ export declare class Shader extends Visual {
     private _enablePositionAttrib;
     private _enableTexCoordAttrib;
     private _prepareTextures;
+    /**
+     * Set the shader's uniforms.
+     * @param target The movie or layer to apply the shader to.
+     * @param reltime The relative time of the movie or layer.
+     */
     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
+     * @param [options]
+     * @returns the prepared value
      */
     private _prepareValue;
     private static _initRectBuffers;

package/dist/effect/stack.d.ts

@@ -1,6 +1,10 @@
 import { Movie } from '../movie';
 import { Visual } from './visual';
 import { Visual as VisualLayer } from '../layer';
+import { CustomArray } from '../custom-array';
+declare class StackEffects extends CustomArray<Visual> {
+    constructor(target: Visual[], stack: Stack);
+}
 export interface StackOptions {
     effects: Visual[];
 }
@@ -9,8 +13,7 @@ export interface StackOptions {
  * for defining reused effect sequences as one effect.
  */
 export declare class Stack extends Visual {
-    readonly effects: Visual[];
-    private _effectsBack;
+    readonly effects: StackEffects;
     constructor(options: StackOptions);
     attach(movie: Movie): void;
     detach(): void;
@@ -21,3 +24,4 @@ export declare class Stack extends Visual {
      */
     addEffect(effect: Visual): Stack;
 }
+export {};