web-audio-player

(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).^[1][2]

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.

Browser Support

Tested with the following browsers/devices.

Streams Audio
- Webkit Nightly
- FireFox 42.0
- Chrome 46.0
Buffers Audio
- Samsung Galaxy S6 (Chrome 46)
- iOS Safari
  - iOS 9.2, iPhone 5S
  - iOS 8.3 iPad Mini Retina
- Safari 8.0 (OSX Yosemite)
- iOS Chrome
  - iOS 8, iPhone 6, Chrome 46
  - iOS 9.2, iPhone 5S, Chrome 45 has a gotcha (can support streaming)
  - iOS 8.3 iPad Mini Retina (can support streaming)

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

`player = webAudioPlayer(src, [opt])`

Creates a generic audio player interface from the given src file path.

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:

buffer (Boolean) whether to use a Buffer source, default false
loop (Boolean) whether to loop the playback, default false
crossOrigin (String) for media element sources; optional cross origin flag
context (AudioContext) an audio context to use, defaults to a new context. You should re-use contexts, and also consider ios-safe-audio-context
element (Audio|HTMLAudioElement) an optional element to use, defaults to creating a new one. Only applicable when buffer is false.

`player.play()`

Plays the audio. If you are using a buffer source, you can only call this once.

`player.pause()`

Stops the audio. If you are using a buffer source, you will need to re-load a new player to start playing the audio again.

properties

`player.context`

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

`player.node`

The AudioNode for this WebAudio player.

`player.element`

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.duration`

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

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.

`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.