waveplayer
TypeScript icon, indicating that this package has built-in type declarations

2.0.0 • Public • Published

NPM Version downloads Build Status dependencies tested with jest codecov Quality Gate Status License

waveplayer

An HTML5 based audio player with a waveform view.

Screenshot

Author: Michael Dzjaparidze

License: MIT

Table of Contents

Requirements

In order to minimise waveform drawing times it is adviced to supply waveform amplitude data yourself using either the data or JSON strategies. There exist a number of tools for extracting waveform data in JSON format from an audio file; wav2json or py-wav2json can be used for instance. It is enough to provide a single array of floating point values. If the JSON contains a collection of name / value pairs only the first name / value pair will be used.

Installation

This package is available through npm:

npm install --save waveplayer

After that the package may be directly included using a <script> tag:

<script src="path-to-waveform-js/waveplayer.js"></script>

or may be imported (ES6) in your own scripts files:

import { Player, Playlist, View } from 'waveplayer';

API

The constructor of each class takes an option object as an argument. See the Options section for more information on which options are available. Some options are required (currently only the container option).

Factory

A convenience class for building player or playlist instances without having to explicitly specify any dependencies yourself.

player = Factory.createPlayer(options);

Create a new player instance.

Argument Example Type Required Description
options { container: '#container' } Object Yes An object where each key / value pair represents a valid player or view option.
Returns

A fully initialised Player instance that can be used to load and play audio files.

playlist = Factory.createPlaylist(tracks, options);

Create a new playlist instance.

Argument Example Type Required Description
tracks [ { url: 'path-to-audio.mp3', strategy: { type: 'data', data: [0.1, -0.4, ...] } } ] Array<{ url: string; strategy: Strategy }> Yes An array of objects, where each object references an URL or path to an audio file and a strategy data object that instructs how to resolve the amplitude data associated with the audio file. See the Strategies section for more information on the available strategies and how to use them.
options { container: '#container' } Object Yes An object where each key / value pair represents a valid player or view option.
Returns

A fully initialised Playlist instance that can be used to load and play multiple audio files in succession.

Player

player = new Player(view, options);

Create a new player instance.

Argument Example Type Required Description
view new View([], { container: '#container' }) View Yes A view instance used for drawing the waveform associated with the audio file that will be loaded.
options { audioElement: '#audio' } Object No An object where each key / value pair represents a valid player option.
Returns

A fully initialised Player instance that can be used to load and play audio files.

const player = await player.load(url, strategy);

Load an audio track using a specific strategy.

Argument Example Type Required Description
url 'path-to-audio.mp3' string Yes A path or URL to an audio file
strategy { type: 'json', url: 'path-to-amplitude-data.json' } Strategy Yes A strategy data object that instructs how to resolve the amplitude data associated with the audio file.
Returns

A promise that resolves to the player instance on which the method was called.

const player = await player.play();

Start playback of the currently loaded audio file.

Returns

A promise that resolves to the player instance on which the method was called.

const player = player.pause();

Pause playback of the currently loaded audio file.

Returns

The player instance on which the method was called.

player.destroy();

Destroy the player instance and do the appropriate clean up. This will pause audio playback, remove all internally registered event handlers, remove the HTML audio element from the DOM if it was created by the player instance, and lastly call view.destroy().

player.volume = 0.5;

Get / set the volume of the currently playing audio file.

Argument Example Type
volume 0.5 number

player.currentTime = 1;

Get / set the current playback time in seconds.

Argument Example Type
currentTime 1 number

player.duration;

Get the duration of the currently playing audio file.

player.paused;

Get the flag that checks if audio playback is currently paused.

player.view;

Get the view instance associated with the player.

player.audioElement;

Get the HTML audio element associated with the player.

Options

Option Type Default Required Description
audioElement `string HTMLAudioElement` undefined No
preload string metadata No The value of the preload attribute of the HTML audio element. Note: will only be used when the player instance creates the HTML audio element internally.

Playlist

playlist = new Playlist(player, tracks);

Create a new playlist instance.

Argument Example Type Required Description
player new Player(new View([], { container: '#container' })) Player Yes A player instance used for playing back all the tracks / audio files that make up the playlist.
tracks [ { url: 'path-to-audio.mp3', strategy: { type: 'data', data: [0.1, -0.4, ...] } } ] Array<{ url: string; strategy: Strategy }> Yes An array of objects, where each object references an URL or path to an audio file and a strategy data object that instructs how to resolve the amplitude data associated with the audio file. See the Strategies section for more information on the available strategies and how to use them.
Returns

A fully initialised Playlist instance that can be used to load and play multiple audio files in succession.

const playlist = await playlist.prepare();

Prepare a playlist for playback. This is an alias for playlist.reset().

Returns

A promise that resolves to the playlist instance on which the method was called.

const playlist = await playlist.reset();

Reset a playlist. This will pause playback and set the first track in the playlist as the current track to play.

Returns

A promise that resolves to the playlist instance on which the method was called.

const playlist = await playlist.next(forcePlay);

Skip to the next track in the playlist.

Argument Example Type Required Description
forcePlay true boolean No This will start playback of the next track regardless if the playlist is currently paused.
Returns

A promise that resolves to the playlist instance on which the method was called.

const playlist = await playlist.previous(forcePlay);

Skip to the previous track in the playlist.

Argument Example Type Required Description
forcePlay true boolean No This will start playback of the previous track regardless if the playlist is currently paused.
Returns

A promise that resolves to the playlist instance on which the method was called.

const playlist = await playlist.select(track, forcePlay);

Select a specific track in the playlist.

Argument Example Type Required Description
track 1 number Yes The index of the track in the playlist that should be selected.
forcePlay true boolean No This will start playback of the selected track regardless if the playlist is currently paused.
Returns

A promise that resolves to the playlist instance on which the method was called.

playlist.destroy();

Destroy the player instance and do the appropriate clean up. This will remove all internally registered event handlers and call player.destroy().

playlist.forcePlay = true;

Get / set the flag that indicates whether playback should start after selecting another track in the playlist, regardless if the playlist is paused or not.

Argument Example Type
forcePlay true boolean

playlist.player;

Get the player instance associated with the playlist.

playlist.current;

Get the index of the currently playing track.

playlist.ended;

Get the flag that indicates whether the playlist has finished playback.

Options

Option Type Default Required Description
forcePlay boolean true No Indicates whether playback should start after selecting another track in the playlist, regardless if the playlist is paused or not.

View

view = new View(data, options);

Create a new view instance.

Argument Example Type Required Description
data [-0.1, 0.4, ...] Array<number> Yes An array of floating point values representing the amplitude of some audio file at equally spaced intervals that will be used to draw the waveform.
options { container: '#container' } Object Yes An object where each key / value pair represents a valid view option.
Returns

A fully initialised View instance that can be used to draw the waveform associated with an audio file.

view = view.draw();

Draw the waveform on the canvas HTML element.

Returns

The view instance on which the method was called.

view = view.clear();

Clear the canvas HTML element where the waveform is drawn on.

Returns

The view instance on which the method was called.

view.destroy();

Destroy the view instance and do the appropriate clean up. This will remove all internally registered event handlers and remove the HTML canvas element from the DOM.

view.data = [-0.1, 0.4, ...];

Get / set the waveform amplitude data.

Argument Example Type
data [-0.1, 0.4, ...] Array<number>

view.progress = 0.5;

Get / set the progress of the waveform, assumed to be in the range [0-1].

Argument Example Type
progress 0.5 number

view.container = '#container';

Get / set the HTML container element for the view instance.

Argument Example Type
container '#container' `HTMLDivElement

view.width = 512;

Get / set the width of the drawn waveform. Setting the width only has an effect if the view instance is not operating in responsive mode.

Argument Example Type
width 512 number

view.height = 128;

Get / set the height of the drawn waveform.

Argument Example Type
height 128 number

view.barWidth = 4;

Get / set the width of a bar representing an element of the waveform.

Argument Example Type
barWidth 4 number

view.barGap = 1;

Get / set the width of the gap that separates consecutive bars.

Argument Example Type
barGap 1 number

view.responsive = true;

Get / set the flag that determines if the view instance is operating in responsive mode.

Argument Example Type
responsive true boolean

view.gradient = true;

Get / set the flag that determines if the waveform should be drawn with a gradient.

Argument Example Type
gradient true boolean

view.interact = true;

Get / set the interaction state of the view instance.

Argument Example Type
interact true boolean

view.redraw = true;

Get / set the redraw flag. This flag determines whether the waveform should be redrawn when setting one of the view properties that affects the look of the waveform (e.g. width, height, gradient).

Argument Example Type
redraw true boolean

view.canvas;

Get the HTML canvas element that is used for drawing the waveform.

Options

Option Type Default Required Description
container `string HTMLDivElement` undefined Yes
width integer 512 No The width of the waveform in pixels (only relevant when the responsive option is set to false).
height integer 128 No The height of the waveform in pixels.
waveformColor string #428bca No The fill color of the waveform bars that have not been played back so far.
progressColor string #31708f No The fill color of the waveform bars that have been played back so far.
barGap integer 1 No Gap between bars in pixels.
barWidth integer 4 No Width of a bar in pixels.
responsive boolean true No If set to true, the width of the waveform view adapts to the width of the container element.
gradient boolean true No Indicates if the waveform should be drawn with a gradient or not.
interact boolean true No Enables / disables mouse interaction with the waveform view. This may be changed at any point after creation.
redraw boolean true No Indicates if the waveform will be redrawn when one of the view properties that affects the look of the waveform (e.g. width, height, gradient) is set.

Strategies

waveplayer v2 introduces the concept of strategies for providing amplitude data for an audio file that is used to draw waveforms. Each audio file you wish to load should reference a path / URL to the file and in addition specify how the amplitude data should be resolved. Currently, three strategies are available:

Data Strategy

Use this strategy if your waveform amplitude data is readily available in the form of an array of floating point values, assumed to be in the range [-1, 1].

Key Value Type Default Required Description
type 'data' string undefined Yes The strategy type identifier.
data [0.1, -0.4, ...] Array<number> undefined Yes An array of floating point values representing the amplitude of some audio file at equally spaced intervals that will be used to draw the waveform.

JSON Strategy

Use this strategy if your waveform amplitude data is stored inside a JSON file. This JSON file should either consist of a single array structure containing floating point values, assumed to be in the range [-1, 1] or key / value pairs where the value point to such an array. Currently, only the first key / value pair is used for the amplitude data. Waveform amplitude data extracted from a JSON file is cached by default

Key Value Type Default Required Description
type 'json' string undefined Yes The strategy type identifier.
url 'path-to-amplitude-data.json' string undefined Yes A path or URL to a JSON file containing amplitude data for an audio file.
cache true boolean true No Determines whether to use cached amplitude data (if it exists) or to extract the data from the JSON file.

WebAudio Strategy

Although convenient, this strategy is a bit experimental and if you can use either the JSON or data strategies it is generally adviced to use one of these. Use this strategy if you would like to extract the amplitude data of an audio file during runtime. Note that this could take a considerable amount of time depending on the duration of the audio file and the number of points you would like to extract. Also, not all audio file formats are supported, although MP3 and WAV should work just fine.

Argument Example Type Required Description
Key Value Type Default Required Description
type 'webAudio' string undefined Yes The strategy type identifier.
points 1200 number 800 No The number of equally spaced amplitude data points to extract from the audio file.
normalise false boolean true No Determines whether to normalise the extracted data points (i.e. scale them such that the absolute maximum is 1).
logarithmic true boolean true No Determines whether to compute the extracted data points on a logarithmic or linear scale.
cache false boolean true No Determines whether to use cached amplitude data (if it exists) or to extract the data from the audio file.

Note: The JSON and WebAudio strategies cache amplitude data by default in order to speed up subsequent loading of the same audio files. If this is undesired behaviour you should set the "cache" flag of the relevant strategy to false.

Examples

This section discusses a few simple examples for more worked out, fully working examples see the /examples directory.

Player

Create a player instance and pass in some (optional) options:

import { Factory } from 'waveplayer';

const player = Factory.createPlayer({
    container: '#waveform',
    barWidth: 4,
    barGap: 1,
    height: 128,
});

await player.load('url-to-some-audio-file.mp3', { type: 'data', data: [0.1, -0.4, ...] });

player.play();

If you need more control or don't like factory classes for some reason you can also create a player instance explicitly:

import { Player, View } from 'waveplayer';

const player = new Player(new View([], { 'container': '#container' }), { 'audioElement': '#audio' });

Playlist

Load some audio files from a URL and start playback when loading has finished:

import { Factory } from 'waveplayer';

playlist = await Factory.createPlaylist(
    [{ url: 'url-to-some-audio-file.mp3', strategy: { type: 'data', data: [0.1, -0.4, ...] } }],
    { container: '#waveform' },
).prepare();

playlist.play();

Similarly to the Player class you can also create a playlist instance explicitly:

import { Player, Playlist, View } from 'waveplayer';

const playlist = new Playlist(
    new Player(new View([], { container: '#waveform' })),
    [{ url: 'url-to-some-audio-file.mp3', strategy: { type: 'json', url: 'url-to-some-amplitude-data.json' } }],
);

View

It is also possible to only use the view part of waveplayer if you are interested in the drawing of waveform data only:

import { View } from 'waveplayer';

const view = new View([...], { 'container': '#container' });

view.progress = 0.5;

view.draw();

Package Sidebar

Install

npm i waveplayer

Weekly Downloads

38

Version

2.0.0

License

MIT

Unpacked Size

72.7 kB

Total Files

22

Last publish

Collaborators

  • michaeldzjap