etro 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ 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)).
@@ -233,6 +275,7 @@ 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

package/CONTRIBUTING.md

@@ -17,44 +17,47 @@ Thank you for considering contributing to Etro! There are many ways you can cont
 - 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 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:
+#### 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
 
@@ -65,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.
 
@@ -78,9 +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
+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

@@ -70,11 +70,12 @@ To use Etro in Node, see the [wrapper](https://github.com/etro-js/etro-node):
 
 ## Running the Examples
 
-Start the development server (only used for convience while developing; you
+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
 ```
 
@@ -83,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 {};