Home

Awesome

web-audio-player

experimental

(demo)

A simplified cross-browser WebAudio wrapper with a narrow API. This repo also attempts to report and solve some "WebAudio Gotchas" for getting WebAudio working on mobile. It targets new browsers and devices, and does not attempt to provide a non-WebAudio fallback.

See caniuse.com WebAudio API.

Motivation

The main use case for this is to support WebAudio features (such as reverb and frequency analysis) across desktop and mobile browsers.

Currently (as of Nov 2015), on recent versions of Safari and Android Chrome, you can only take advantage of these features by buffering and decoding the entire audio file (rather than streaming it).<sup>[1][2]</sup>

This module provides a consistent API whether you are using a media element (Chrome/FF) or buffer (other browsers) as the audio source.

Demo

http://jam3.github.io/web-audio-player/

The demo uses web-audio-analyser and analyser-frequency-average.

The audio streams and auto-plays on desktop. On mobile, the file is buffered, then decoded, then we wait for user to initiate playback.

Detection

You can use detect-media-element-source to approximately feature detect whether createMediaElementSource will work or not, but you may be better off just using user agent strings or defaulting to a specific behaviour for all mobile browsers.

Browser Support

Tested with the following browsers/devices.

Install

Meant to be used with Browserify or Webpack.

npm install web-audio-player --save

Example

A simple example for Chrome/FF, which does not attempt to solve some of the mobile challenges.

var createPlayer = require('web-audio-player')

var audio = createPlayer('assets/audio.mp3')

audio.on('load', () => {
  console.log('Audio loaded...')
  
  // start playing audio file
  audio.play()
  
  // and connect your node somewhere, such as
  // the AudioContext output so the user can hear it!
  audio.node.connect(audio.context.destination)
})

audio.on('ended', () => {
  console.log('Audio ended...')
})

For a complete mobile/desktop demo, see demo/index.js. See Gotchas for more details.

Usage

NPM

player = webAudioPlayer(src, [opt])

Creates a generic audio player interface from the given src file path or array of sources. The src elements can be any of the following:

If opt.buffer is true, the audio node is created from a buffer source (not streamed). Otherwise, it is created from a media element source (streamed). The two have different implications.

Full list of options:

When a MediaElement is used as the source, other options will be passed to simple-media-element.

:warning: For accurate loopStart and loopEnd results, you should use a buffer source. MediaElement sources fall back to using a requestAnimationFrame timer, which is less robust, especially when the tab is out of view.

player.play()

Plays the audio, resuming it from a paused state.

player.pause()

Pauses the audio.

player.stop()

Stops the audio, settings its current time back to zero and triggering an 'end' event.

The next time play() is called, the track will start from the beginning.

properties

player.context (read-only)

The AudioContext being used for this player. You should re-use audio contexts where possible.

player.node (read-only)

The AudioNode for this WebAudio player.

This will be a GainNode that wraps the MediaElementAudioSourceNode or currently playing AudioBufferSourceNode.

player.element (read-only)

If buffer is false (the source is a media element), this will be the HTMLAudioElement or Audio object that is driving the audio.

If the source is a buffer, this will be undefined.

player.buffer (read-only)

If we are using a buffer source, this will hold the decoded AudioBuffer instance from the audio file. This will be undefined until the 'loaded' event is triggered.

If the source is a media element, this will be undefined.

player.duration (read-only)

The duration of the audio track in seconds. This will most likely only return a meaningful value after the 'load' event.

player.playing (read-only)

A read-only boolean to determine whether the audio node is currently playing.

player.volume

A getter/setter for the player.node.gain value, which allows you to adjust the volume during playback.

events

player.on('load', fn)

Called when the player has loaded, and the audio can be played. With a media element, this is after 'canplay'. With a buffer source, this is after the audio has been decoded.

player.on('end', fn)

If the audio is not looping, this is called when the audio playback ends.

This is also triggered when the stop() method is called.

player.on('error', fn)

Called with (err) parameters when there was an error loading, buffering or decoding the audio.

player.on('progress', fn)

If buffer: true, this will be called on the progress events of the XMLHttpRequest for the audio file (if the browser supports it). The parameters will be (percentage, totalBytes).

This is not called with a media element source.

player.on('decoding', fn)

If buffer: true, this will be called after the XMLHttpRequest, and before decodeAudioData starts. This alows you to provide an update to your user as the audio loads.

This is not called with a media element source.

Roadmap

Some new features may be added to this module, such as:

Please open an issue or PR if you wish to discuss a new feature.

WebAudio Gotchas

There are currently a lot of challenges with cross-platform WebAudio playback. This is likely to change soon as vendors continue fixing bugs.

See Also

Changelog

License

MIT, see LICENSE.md for details.