waveplayer

An HTML5 based audio player with a waveform view.

Author: Michael Dzjaparidze

License: MIT

Table of Contents

• Requirements
• Installation
• API
  • Factory
  • Player
  • Playlist
  • View
  • Strategies
• Examples
  • Player
  • Playlist
  • View

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 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 | The HTML audio element associated with the player instance. If not passed in as an option when creating a new player instance it will be created internally. | | 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 promi