From 46b7c6d37bf801212c1cea76a6733de5b0f37c9f Mon Sep 17 00:00:00 2001 From: "Michael \"Z\" Goddard" Date: Tue, 12 Jun 2018 09:40:59 -0400 Subject: [PATCH] document GreenPlayer --- src/GreenPlayer.js | 62 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/src/GreenPlayer.js b/src/GreenPlayer.js index e6d0a41..fb70e2e 100644 --- a/src/GreenPlayer.js +++ b/src/GreenPlayer.js @@ -2,9 +2,22 @@ const {EventEmitter} = require('events'); const VolumeEffect = require('./effects/VolumeEffect'); +/** + * Name of event that indicates playback has ended. + * @const {string} + */ const ON_ENDED = 'ended'; class SoundPlayer extends EventEmitter { + /** + * Play sounds that stop without audible clipping. + * + * @param {AudioEngine} audioEngine - engine to play sounds on + * @param {object} data - required data for sound playback + * @param {string} data.id - a unique id for this sound + * @param {ArrayBuffer} data.buffer - buffer of the sound's waveform to play + * @constructor + */ constructor (audioEngine, {id, buffer}) { super(); @@ -23,6 +36,7 @@ class SoundPlayer extends EventEmitter { /** * Handle any event we have told the output node to listen for. + * @param {Event} event - dom event to handle */ handleEvent (event) { if (event.type === ON_ENDED) { @@ -30,12 +44,19 @@ class SoundPlayer extends EventEmitter { } } + /** + * Event listener for when playback ends. + */ onEnded () { this.emit('stop'); this.isPlaying = false; } + /** + * Create the buffer source node during initialization or secondary + * playback. + */ _createSource () { if (this.outputNode !== null) { this.outputNode.removeEventListener(ON_ENDED, this); @@ -53,6 +74,9 @@ class SoundPlayer extends EventEmitter { } } + /** + * Initialize the player for first playback. + */ initialize () { this.initialized = true; @@ -61,6 +85,11 @@ class SoundPlayer extends EventEmitter { this._createSource(); } + /** + * Connect the player to the engine or an effect chain. + * @param {object} target - object to connect to + * @returns {object} - return this sound player + */ connect (target) { if (target === this.volumeEffect) { this.outputNode.disconnect(); @@ -79,6 +108,9 @@ class SoundPlayer extends EventEmitter { return this; } + /** + * Teardown the player. + */ dispose () { if (!this.initialized) { return; @@ -87,6 +119,7 @@ class SoundPlayer extends EventEmitter { this.stopImmediately(); this.volumeEffect.dispose(); + this.volumeEffect = null; this.outputNode.disconnect(); this.outputNode = null; @@ -96,6 +129,15 @@ class SoundPlayer extends EventEmitter { this.initialized = false; } + /** + * Take the internal state of this player and create a new player from + * that. Restore the state of this player to that before its first playback. + * + * The returned player can be used to stop the original playback or + * continue it without manipulation from the original player. + * + * @returns {SoundPlayer} - new SoundPlayer with old state + */ take () { if (this.outputNode) { this.outputNode.removeEventListener(ON_ENDED, this); @@ -131,6 +173,12 @@ class SoundPlayer extends EventEmitter { return taken; } + /** + * Start playback for this sound. + * + * If the sound is already playing it will stop playback with a quick fade + * out. + */ play () { if (this.isPlaying) { // Spawn a Player with the current buffer source, and play for a @@ -153,6 +201,9 @@ class SoundPlayer extends EventEmitter { this.emit('play'); } + /** + * Stop playback after quickly fading out. + */ stop () { if (!this.isPlaying) { return; @@ -166,6 +217,9 @@ class SoundPlayer extends EventEmitter { this.emit('stop'); } + /** + * Stop immediately without fading out. May cause audible clipping. + */ stopImmediately () { if (!this.isPlaying) { return; @@ -178,12 +232,20 @@ class SoundPlayer extends EventEmitter { this.emit('stop'); } + /** + * Return a promise that resolves when the sound next finishes. + * @returns {Promise} - resolves when the sound finishes + */ finished () { return new Promise(resolve => { this.once('stop', resolve); }); } + /** + * Set the sound's playback rate. + * @param {number} value - playback rate. Default is 1. + */ setPlaybackRate (value) { this.playbackRate = value;