diff --git a/audioshowkit/.esdoc.json b/audioshowkit/.esdoc.json deleted file mode 100644 index 9052304..0000000 --- a/audioshowkit/.esdoc.json +++ /dev/null @@ -1,27 +0,0 @@ -{ - "source": "./src", - "destination": "./docs", - "plugins": [ - { - "name": "esdoc-standard-plugin", - "option": { - "test": { - "source": "./tests/", - "interfaces": [ - "describe", - "it", - "context", - "suite", - "test" - ], - "includes": [ - "(spec|Spec|test|Test)\\.js$" - ], - "excludes": [ - "\\.config\\.js$" - ] - } - } - } - ] -} \ No newline at end of file diff --git a/audioshowkit/src/mapping/dimensions.js b/audioshowkit/src/mapping/dimensions.js index 519ffaa..6987677 100644 --- a/audioshowkit/src/mapping/dimensions.js +++ b/audioshowkit/src/mapping/dimensions.js @@ -1,6 +1,7 @@ import VisualizerUpdateManager from "../visualization/VisualizerUpdateManager.js"; import { mapBinNumerical, mapRangedAvgNumerical } from "./numeric.js"; + /** * Maps the width of an element to frequency bin(s). * @@ -16,7 +17,7 @@ import { mapBinNumerical, mapRangedAvgNumerical } from "./numeric.js"; * @param {boolean} [conf.reversed=false] If true, then high amplitudes are mapped to lower values and vice versa. * @returns {{bin: number, listener: VisualizerUpdateManager.visualizerBinUpdateListener}|{lower: number, upper: number, listener: VisualizerUpdateManager.visualizerRangedUpdateListener}} The listener that was added (ranged if an upper bound was provided, binned otherwise). */ -export function mapWidth({ element, growLower, growUpper, unit, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { +function mapWidth({ element, growLower, growUpper, unit, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { const getter = () => element.style.width; const setter = (value) => element.style.width = value + unit; const conf = { @@ -54,7 +55,7 @@ export function mapWidth({ element, growLower, growUpper, unit, lowerBin, visUpd * @param {boolean} [conf.reversed=false] If true, then high amplitudes are mapped to lower values and vice versa. * @returns {{bin: number, listener: VisualizerUpdateManager.visualizerBinUpdateListener}|{lower: number, upper: number, listener: VisualizerUpdateManager.visualizerRangedUpdateListener}} The listener that was added (ranged if an upper bound was provided, binned otherwise). */ -export function mapHeight({ element, growLower, growUpper, unit, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { +function mapHeight({ element, growLower, growUpper, unit, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { const getter = () => element.style.height; const setter = (value) => element.style.height = value + unit; const conf = { @@ -75,4 +76,7 @@ export function mapHeight({ element, growLower, growUpper, unit, lowerBin, visUp return mapRangedAvgNumerical(conf); } return mapBinNumerical(conf); -} \ No newline at end of file +} + +/**@module */ +export { mapWidth, mapHeight }; \ No newline at end of file diff --git a/audioshowkit/src/mapping/mappings.js b/audioshowkit/src/mapping/mappings.js index 799072c..6c28101 100644 --- a/audioshowkit/src/mapping/mappings.js +++ b/audioshowkit/src/mapping/mappings.js @@ -1,4 +1,5 @@ import * as dimensions from "./dimensions.js"; import * as numeric from "./numeric.js"; +/**@module */ export { dimensions, numeric }; \ No newline at end of file diff --git a/audioshowkit/src/mapping/numeric.js b/audioshowkit/src/mapping/numeric.js index 8003e11..0dd72ac 100644 --- a/audioshowkit/src/mapping/numeric.js +++ b/audioshowkit/src/mapping/numeric.js @@ -28,7 +28,7 @@ * @param {boolean} [conf.reversed = false] If true, then high amplitudes will be mapped to low values and vice versa. * @returns {{lower: number, upper: number, listener: VisualizerUpdateManager.visualizerRangedUpdateListener}} An object containing the lower and upper bounds for the range of a listener, which is also in the object. */ -export function mapRangedAvgNumerical({ minVal, maxVal, lowerBin = undefined, upperBin, getter, setter, interpolator, visUpdateManager, reversed = false }) { +function mapRangedAvgNumerical({ minVal, maxVal, lowerBin = undefined, upperBin, getter, setter, interpolator, visUpdateManager, reversed = false }) { const rangedListener = { lower: lowerBin, upper: upperBin, @@ -67,7 +67,7 @@ export function mapRangedAvgNumerical({ minVal, maxVal, lowerBin = undefined, up * @param {boolean} [conf.reversed] If true, then high amplitudes will be mapped to lower values and vice versa. * @returns {{bin: number, listener: VisualizerUpdateManager.visualizerBinUpdateListener}} The bin listener that was added. */ -export function mapBinNumerical({ minVal, maxVal, bin, getter, setter, interpolator, visUpdateManager, reversed = false }) { +function mapBinNumerical({ minVal, maxVal, bin, getter, setter, interpolator, visUpdateManager, reversed = false }) { const listener = { bin: bin, listener: (timeDelta, amp) => { @@ -81,4 +81,7 @@ export function mapBinNumerical({ minVal, maxVal, bin, getter, setter, interpola return listener; } return null; // Technically doesn't occur since the functions are anonymous? -} \ No newline at end of file +} + +/**@module */ +export { mapRangedAvgNumerical, mapBinNumerical }; \ No newline at end of file diff --git a/audioshowkit/src/mapping/text.js b/audioshowkit/src/mapping/text.js index 291c1a0..33ab4e3 100644 --- a/audioshowkit/src/mapping/text.js +++ b/audioshowkit/src/mapping/text.js @@ -15,7 +15,7 @@ import { mapBinNumerical, mapRangedAvgNumerical } from "./numeric.js"; * @param {boolean} [rgbaMapConfiguration.reversed=true] If true, then the quieter, the greater the red value. * @returns {{bin: number, listener: VisualizerUpdateManager.visualizerBinUpdateListener}|{lower: number, upper: number, listener: visualizerRangedUpdateListener}} The ranged listener that was added. */ -export function mapRgba({ element, color, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { +function mapRgba({ element, color, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { const rgbaStr = "rgba"; color = rgbaStr.indexOf(color); if (color < 0) throw new Error("Invalid color parameter provided."); @@ -58,7 +58,7 @@ export function mapRgba({ element, color, lowerBin, visUpdateManager, interpolat * @param {boolean} [fontSizeMapConfiguration.reversed=false] If true, then high amplitudes are mapped to lower values and vice versa. * @returns {{bin: number, listener: VisualizerUpdateManager.visualizerBinUpdateListener}|{lower: number, upper: number, listener: VisualizerUpdateManager.visualizerRangedUpdateListener}} The listener that was added (ranged if an upper bound was provided, binned otherwise). */ -export function mapFontSize({ element, growLower, growUpper, unit, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { +function mapFontSize({ element, growLower, growUpper, unit, lowerBin, visUpdateManager, interpolator, upperBin = undefined, reversed = false }) { const getter = () => parseInt(element.style.fontSize); const setter = (value) => element.style.fontSize = value + unit; const conf = { @@ -80,4 +80,7 @@ export function mapFontSize({ element, growLower, growUpper, unit, lowerBin, vis return mapBinNumerical(conf); } -// TODO: Future: map hue \ No newline at end of file +// TODO: Future: map hue + +/**@module */ +export { mapRgba, mapFontSize }; \ No newline at end of file diff --git a/audioshowkit/src/patterns/canvas.js b/audioshowkit/src/patterns/canvas.js index 109afa2..33bcb18 100644 --- a/audioshowkit/src/patterns/canvas.js +++ b/audioshowkit/src/patterns/canvas.js @@ -6,7 +6,7 @@ import Visualizer from "../visualization/Visualizer.js"; * @param {HTMLCanvasElement} canvasElement the canvas element to use to draw this horizontal visualizer. * @param {Visualizer} visualizer the visualizer in which the data to display is obtained. */ -export function horizontalVisualizer(canvasElement, visualizer) { +function horizontalVisualizer(canvasElement, visualizer) { let _width = canvasElement.width; let _height = canvasElement.height; let _canvasCtx = canvasElement.getContext("2d"); @@ -24,4 +24,7 @@ export function horizontalVisualizer(canvasElement, visualizer) { }); }; _visualizer.addUpdateListener(update); -} \ No newline at end of file +} + +/**@module */ +export { horizontalVisualizer }; \ No newline at end of file diff --git a/audioshowkit/src/player/PlaylistSong.js b/audioshowkit/src/player/PlaylistSong.js index d8e5373..d3f79b8 100644 --- a/audioshowkit/src/player/PlaylistSong.js +++ b/audioshowkit/src/player/PlaylistSong.js @@ -1,17 +1,17 @@ import Visualizer from "../visualization/Visualizer.js"; +/**@module */ + +/** + * @callback AudioEventCallback + * @param {HTMLAudioElement} audio + */ + /** * A song with metadata that can be used as part of a {@link SongPlaylist}. * */ export default class PlayListSong { - #displayName; - #author; - #url; - #audio; - #visualizer; - #ready = false; - /** * Constructs a song for a {@link SongPlaylist}. * @@ -24,11 +24,12 @@ export default class PlayListSong { this.#author = author; this.#url = url; } - - /** - * @callback AudioEventCallback - * @param {HTMLAudioElement} audio - */ + #displayName; + #author; + #url; + #audio; + #visualizer; + #ready = false; /** * diff --git a/audioshowkit/src/player/SongPlayer.js b/audioshowkit/src/player/SongPlayer.js index ed04ff8..c5dc1b5 100644 --- a/audioshowkit/src/player/SongPlayer.js +++ b/audioshowkit/src/player/SongPlayer.js @@ -2,6 +2,14 @@ import "../styles/songPlayer.css"; import PlayListSong from "./PlaylistSong.js"; import SongPlaylist from "./SongPlaylist.js"; +/**@module */ + +/** + * @callback changeListener + * @param {*} old the previous value. + * @param {*} current the the current (new) value. + */ + /** * A player that keeps track of global properties for playback as well as traversing a playlist. Additionally keeps track of song audio data and attempts to reduce memory usage when possible. */ @@ -240,12 +248,6 @@ export default class SongPlayer { return this.#playlist.songAtIndex(this.#current); } - /** - * @callback changeListener - * @param {*} old the previous value. - * @param {*} current the the current (new) value. - */ - /** * * @param {changeListener} listener the listener to receive the updates. @@ -323,7 +325,7 @@ export default class SongPlayer { /** * * @param {string} type the type of the listener on the {@link HTMLAudioElement}. - * @param {EventListener|EventListenerObject} eventListener the event listener. + * @param {Function} eventListener the event listener. * @returns {boolean} true if and only if successfully registered event listener. */ addEventListenerToCurrentAudio(type, eventListener) { @@ -341,7 +343,7 @@ export default class SongPlayer { /** * * @param {string} type the type of the listener on the {@link HTMLAudioElement}. - * @param {EventListener|EventListenerObject} eventListener the event listener. + * @param {Function} eventListener the event listener. * @returns {boolean} true if and only if the event listener was successfully added. */ removeEventListenerFromCurrentAudio(type, eventListener) { diff --git a/audioshowkit/src/player/SongPlaylist.js b/audioshowkit/src/player/SongPlaylist.js index c5ad755..c99ea9f 100644 --- a/audioshowkit/src/player/SongPlaylist.js +++ b/audioshowkit/src/player/SongPlaylist.js @@ -1,5 +1,7 @@ import PlaylistSong from "./PlaylistSong.js"; +/**@module */ + /** * A playlist that holds a multitude of songs in the form of {@link PlaylistSong}. */ diff --git a/audioshowkit/src/player/VisualizedSongPlayer.js b/audioshowkit/src/player/VisualizedSongPlayer.js index f09e70a..ee4040d 100644 --- a/audioshowkit/src/player/VisualizedSongPlayer.js +++ b/audioshowkit/src/player/VisualizedSongPlayer.js @@ -3,12 +3,13 @@ import VisualizerUpdateManager from "../visualization/VisualizerUpdateManager.js import SongPlayer from "./SongPlayer.js"; import SongPlaylist from "./SongPlaylist.js"; +/**@module */ + /** * A song player that provides easier access to the current songs visualizer data. - * * Additionally, automatically re-binds all the visualizer update listeners for song changes. * - * Automatically loads the songs. + * @augments SongPlayer */ export default class VisualizedSongPlayer extends SongPlayer { #fftSize = 1024; diff --git a/audioshowkit/src/player/player.js b/audioshowkit/src/player/player.js index 16ec6d8..0f7cfb5 100644 --- a/audioshowkit/src/player/player.js +++ b/audioshowkit/src/player/player.js @@ -3,49 +3,5 @@ import SongPlaylist from "./SongPlaylist.js"; import VisualizedSongPlayer from "./VisualizedSongPlayer.js"; import PlayListSong from "./PlaylistSong.js"; -/** - * Instantiates a song player with a given playlist. - * - * @see SongPlayer for more information about the returned object. - * @param {SongPlaylist} playlist the playlist this player will play through. - * @returns {SongPlayer} the instantiated song player. - */ -export function createSongPlayer(playlist) { - return new SongPlayer(playlist); -} - -/** - * Instantiates a song playlist. - * - * @see SongPlaylist for more information about the returned object. - * @param {string} name the name of the playlist. - * @returns {SongPlaylist} the instantiated song playlist. - */ -export function createSongPlaylist(name) { - return new SongPlaylist(name); -} - -/** - * Instantiates a song player that manages the visualizers for individual songs, as well as the listeners for the visualizations. - * - * @see VisualizedSongPlayer for more information about the returned object. - * @param {SongPlaylist} playlist the playlist this visualized song player will play through. - * @param {number} [fftSize=1024] the FFT window size. - * @returns {VisualizedSongPlayer} a song player capable of retrieving the visualizer for the current playing song. - */ -export function createVisualizedSongPlayer(playlist, fftSize = 1024) { - return new VisualizedSongPlayer(playlist, fftSize); -} - -/** - * Instantiates a playlist song. - * - * @see PlaylistSong for more information about the returned object. - * @param {string} url The url at which the audio for the song can be retrieved. - * @param {string} name The name of the song. - * @param {string} author The name of the author(s). - * @returns {PlayListSong} The playlist song that is instantiated. - */ -export function createPlaylistSong(url, name, author) { - return new PlayListSong(url, name, author); -} \ No newline at end of file +/**@module */ +export { SongPlayer, SongPlaylist, VisualizedSongPlayer, PlayListSong }; \ No newline at end of file diff --git a/audioshowkit/src/support/colors.js b/audioshowkit/src/support/colors.js index b8c79f6..02c2754 100644 --- a/audioshowkit/src/support/colors.js +++ b/audioshowkit/src/support/colors.js @@ -1,11 +1,11 @@ /** - * The rg + * Converts from rgba hex value to an array of four numbers representing r, g, b, and a respectively. * * @param {string} hex the hex value. * @returns {number[]} the resulting components of the hex value. */ -export function rgbaHexToRgba(hex) { +function rgbaHexToRgba(hex) { if (hex.startsWith("#")) { hex = hex.substring(1); if (hex.length > 8) { @@ -31,17 +31,18 @@ export function rgbaHexToRgba(hex) { * @param {string} hex the hex value. * @returns {number[]} the resulting r, g, and b components. */ -export function rgbHexToRgba(hex) { +function rgbHexToRgba(hex) { const result = rgbaHexToRgba(hex + "FF"); return result; } /** + * Converts from the CSS rgba call to an array of four numbers representing r, g, b and a. * * @param {string} rgba The CSS rgba(r,g,b,a) call. * @returns {number[]} the rgba components. */ -export function cssRgbaToRgba(rgba) { +function cssRgbaToRgba(rgba) { const cssRgbaRegex = /rgba\((\d+),(\d+),(\d+),(\d+)\)/; try { const matches = rgba.match(cssRgbaRegex); @@ -52,11 +53,12 @@ export function cssRgbaToRgba(rgba) { } /** + * Converts from the CSS rgb call to an array of four numbers representing r, g, b and a. * * @param {string} rgb The CSS rgb(r,g,b) call. * @returns {number[]} the rgba components. */ -export function cssRgbToRgba(rgb) { +function cssRgbToRgba(rgb) { const cssRgbRegex = /rgb\((\d+),(\d+),(\d+)\)/; try { const matches = rgb.match(cssRgbRegex); @@ -72,7 +74,7 @@ export function cssRgbToRgba(rgb) { * @param {number[]} rgba an array with red, green, blue, and alpha components in that order. * @returns {string} The resulting hex value. */ -export function rgbaToHexRgba(rgba) { +function rgbaToHexRgba(rgba) { const filler = (hex) => hex.length < 2 ? "0" + hex : hex; return "#" + filler(rgba[0].toString(16)) + filler(rgba[1].toString(16)) + filler(rgba[2].toString(16)) + filler(rgba[3].toString(16)); } @@ -86,7 +88,7 @@ export function rgbaToHexRgba(rgba) { * @param {string} color The string that contains the color information. * @returns {number[]} an array that contains the r, g, b and a components. */ -export function parseColor(color) { +function parseColor(color) { if (color.startsWith("rgba(")) { return cssRgbaToRgba(color); } else if (color.startsWith("rgb(")) { @@ -99,4 +101,7 @@ export function parseColor(color) { } } throw new Error("Could not parse to an rgba value."); -} \ No newline at end of file +} + +/**@module */ +export { rgbaHexToRgba, rgbHexToRgba, cssRgbaToRgba, cssRgbToRgba, rgbaToHexRgba, parseColor }; \ No newline at end of file diff --git a/audioshowkit/src/support/easings.js b/audioshowkit/src/support/easings.js index fbde227..931205e 100644 --- a/audioshowkit/src/support/easings.js +++ b/audioshowkit/src/support/easings.js @@ -14,7 +14,7 @@ * @param {number} rate the number of frequency values to shift by per second. * @returns {interpolator} the interpolation function with the given rate. */ -export function createEaseLinear(rate) { +function createEaseLinear(rate) { return (current, dest, frameDelta) => { let direction = 1; if (dest < current) { @@ -22,4 +22,7 @@ export function createEaseLinear(rate) { } return current + (Math.min(rate * frameDelta, dest) * direction); }; -} \ No newline at end of file +} + +/**@module */ +export { createEaseLinear }; \ No newline at end of file diff --git a/audioshowkit/src/support/support.js b/audioshowkit/src/support/support.js index 32df7c9..d5ce1d8 100644 --- a/audioshowkit/src/support/support.js +++ b/audioshowkit/src/support/support.js @@ -1,4 +1,5 @@ import * as colors from "./colors.js"; import * as easings from "./easings.js"; +/**@module */ export { colors, easings }; \ No newline at end of file diff --git a/audioshowkit/src/visualization/Visualizer.js b/audioshowkit/src/visualization/Visualizer.js index 3578370..c396be9 100644 --- a/audioshowkit/src/visualization/Visualizer.js +++ b/audioshowkit/src/visualization/Visualizer.js @@ -1,3 +1,11 @@ +/**@module */ + +/** + * @callback visualizerUpdateListener + * @param {number} delta elapsed time since last update. + * @param {Uint8Array} bins the bins with varying frequency values. + */ + /** * Provides a simplified access point to the frequency bins in the form of a visualization update listener. */ @@ -11,12 +19,6 @@ export default class Visualizer { #buffer; #lastUpdate; - /** - * @callback visualizerUpdateListener - * @param {number} delta elapsed time since last update. - * @param {Uint8Array} bins the bins with varying frequency values. - */ - /** * * @param {MediaSource|HTMLMediaElement} mediaSource a media source to analyze. diff --git a/audioshowkit/src/visualization/VisualizerUpdateManager.js b/audioshowkit/src/visualization/VisualizerUpdateManager.js index c68a471..c43d21e 100644 --- a/audioshowkit/src/visualization/VisualizerUpdateManager.js +++ b/audioshowkit/src/visualization/VisualizerUpdateManager.js @@ -1,5 +1,21 @@ import Visualizer from "./Visualizer.js"; +/**@module */ + +/** + * @callback visualizerBinUpdateListener + * @param {number} timeDelta elapsed time since last update. + * @param {number} amplitude The amplitude of the associated bin. + * @param {number} ampDelta change in amplitude of the frequency bin. + */ + +/** + * @callback visualizerRangedUpdateListener + * @param {number} timeDelta elapsed time since last update. + * @param {number} bins the bins of the range. + */ + + /** * A visualizer update manager offers an extra layer of abstraction on top of the {@link Visualizer}'s update listener. * @@ -50,19 +66,6 @@ export default class VisualizerUpdateManager { visualizer.addUpdateListener(this.#visualizerListener); } - /** - * @callback visualizerBinUpdateListener - * @param {number} timeDelta elapsed time since last update. - * @param {number} amplitude The amplitude of the associated bin. - * @param {number} ampDelta change in amplitude of the frequency bin. - */ - - /** - * @callback visualizerRangedUpdateListener - * @param {number} timeDelta elapsed time since last update. - * @param {number} bins the bins of the range. - */ - /** * Adds a listener to a specific frequency bin. diff --git a/audioshowkit/src/visualization/visualization.js b/audioshowkit/src/visualization/visualization.js index 3f19401..82286fd 100644 --- a/audioshowkit/src/visualization/visualization.js +++ b/audioshowkit/src/visualization/visualization.js @@ -1,25 +1,5 @@ import Visualizer from "./Visualizer.js"; import VisualizerUpdateManager from "./VisualizerUpdateManager.js"; -/** - * Instantiates a visualizer. - * - * @see Visualizer for information on the returned object. - * @param {HTMLMediaElement|MediaSource} mediaSource the source of audio to be visualized. - * @param {number} [fftSize=1024] the FFT window size. - * @returns {Visualizer} the visualizer with the given media source and the given FFT size. - */ -export function createVisualizer(mediaSource, fftSize = 1024) { - return new Visualizer(mediaSource, fftSize); -} - -/** - * Instantiates a VisualizerUpdateManager. - * - * @see VisualizerUpdateManager for information on the returned object. - * @param {Visualizer} visualizer the visualizer this update manager manages. - * @returns {VisualizerUpdateManager} the instantiated visualizer update manager for the given visualizer. - */ -export function createVisualizerUpdateManager(visualizer) { - return new VisualizerUpdateManager(visualizer); -} \ No newline at end of file +/**@module */ +export { Visualizer, VisualizerUpdateManager }; \ No newline at end of file diff --git a/showcase/src/js/main.js b/showcase/src/js/main.js index d39c3f4..28c7da2 100644 --- a/showcase/src/js/main.js +++ b/showcase/src/js/main.js @@ -1,6 +1,7 @@ console.log("Beginning showcase.."); - const ask = window.audioshowkit; + +// Song Player const playlist = ask.player.createSongPlaylist("Demo playlist"); playlist.add("/audio/moments.mp3", "moments", "Lost Identities x Robbie Rosen"); playlist.add("/audio/XXI.mp3", "XXI", "QR"); @@ -9,3 +10,6 @@ const playerElem = document.getElementById("player-showcase"); playerElem.appendChild(player.generatePlayElement()); playerElem.appendChild(player.generateNextElement()); playerElem.appendChild(player.generatePreviousElement()); + + +// Visualizer