lutzk/sample-player

A web audio audio sample player

sample-player

Flexible audio sample player for browser:

var player = require('sample-player')
var ac = new AudioContext()

var sample = player(ac, <AudioBuffer>)
sample.start()
sample.start() // can start several samples at the same time
sample.stop() // stop all playing sounds

## Features

Create multi-sample player

Pass a map of names to audio buffers to create a multi-sample player:

var player = require('sample-player')
var ac = new AudioContext()
var drums = player(ac, {
  kick: <AudioBuffer>,
  snare: <AudioBuffer>,
  hihat: <AudioBuffer>
})
drums.start('kick')
drums.start('snare', ac.currentTime, { gain: 0.5 })

Map note names to midi (and oposite)

If the buffers are mapped to note names, you can pass note names (including enharmonics) or midi numbers:

var samples = { 'C2': <AudioBuffer>, 'Db2': <AudioBuffer>, ... }
var piano = player(ac, samples)
piano.start(69) // => Plays 'A4'
piano.start('C#2') // => Plays 'Db2'

Decimal midi note numbers can be used to detune the notes:

piano.start(69.5) // => Plays a note in the middle of 'A4' and 'Bb4'

Events

You can register event handlers with the on function:

var drums = player(ac, { kick: ..., snare: ..., hihat ... })
drums.on('start', function (when, name) {
  console.log('start', name)
})
drums.on('ended', function (when, name) {
  console.log('ended', name)
})
drums.start('kick')
// console logs 'start kick'
// console.logs 'ended kick' when sound ends

To add a listener to all events use: player.on(function (eventName, when, obj, opts)).

Currently it fires: start, started, stop, ended, scheduled

Amplitude envelope control

You can apply an amplitude envelope control player-wide or shot-wide. You can pass a signle adsr option with an array of [attack, decay, sustain, release] or add each parameter to the options object:

// using a single option to set all envelop
var longSound = player(ac, <AudioBuffer>, { adsr: [1.2, 0.5, 0.8, 1.3] })
longSound.start()
// override only the attack
longSound.start(ac.currentTime + 10, { attack: 3 })

#### Listen to midi inputs

Easily attach the player to a Web MIDI API MidiInput:

var piano = player(...)
window.navigator.requestMIDIAccess().then(function (midiAccess) {
  midiAccess.inputs.forEach(function (midiInput) {
    piano.listenToMidi(midiInput)
  })
})

#### Schedule to play buffers at given times

var buffers = { 'C2': <AudioBuffer>, 'Db2': <AudioBuffer>, ... }
var marimba = player(ac, buffers)
marimba.schedule(ac.currentTime, [
  { note: 'c2', time: 0, gain: 0.9 },
  { note: 'e2', time: 0.25, gain: 0.7 },
  { note: 'g2', time: 0.5, gain: 0.5 },
  { note: 'c3', time: 0.75, gain: 0.3 }
])

## Install

Via npm: npm i --save sample-player or grab the browser ready file which exports SamplePlayer as window global.

Options

The options can be passed to the SamplePlayer function to apply to all buffers, or to start function to apply to one shot.

• gain: float between 0 to 1
• attack: the attack time of the amplitude envelope
• decay: the decay time of the amplitude envelope
• sustain: the sustain gain value of the amplitude envelope
• release: the release time of the amplitude envelope
• adsr: an array of [attack, decay, sustain, release]. Overrides other parameters.
• duration: set the playing duration in seconds of the buffer(s)
• loop: set to true to loop the audio buffer

API

SamplePlayer(ac, source, options) ⇒ player

Create a sample player.

Returns: player - the player

Param	Type	Description
ac	AudioContext	the audio context
source	ArrayBuffer | Object.<String, ArrayBuffer>
options	Onject	(Optional) an options object

Example

var SamplePlayer = require('sample-player')
var ac = new AudioContext()
var snare = SamplePlayer(ac, <AudioBuffer>)
snare.start()

• SamplePlayer(ac, source, options) ⇒ player
  • .play
  • .start(name, when, options) ⇒ AudioNode
  • .stop(when, nodes) ⇒ Array
  • .on(event, callback) ⇒ SamplePlayer
  • .connect(destination) ⇒ SamplePlayer
  • .schedule(source, map, when) ⇒ Array
  • .listenToMidi(input, options) ⇒ SamplePlayer

player.play

An alias for player.start See: player.start

player.start(name, when, options) ⇒ AudioNode

Start a sample buffer. The returned object has a function stop(when) to stop the sound.

Returns: AudioNode - an audio node with a stop function

Param	Type	Description
name	String	the name of the buffer. If the source of the SamplePlayer is one sample buffer, this parameter is not required
when	Float	(Optional) when to start (current time if by default)
options	Object	additional sample playing options

Example

// A single sample player
var sample = player(ac, <AudioBuffer>).connect(ac.destination)
var first = sample.start(ac.currentTime, { loop: true })
var second = sample.start(ac.currentTime + 0.5, { loop: true, gain: 0.7 }) // name not required since is only one AudioBuffer
first.stop(ac.currentTime + 1) // only stops first sound
sample.stop() // stop all sounds

Example

// A multi-sample player
var drums = player(ac, { snare: <AudioBuffer>, kick: <AudioBuffer>, ... }).connect(ac.destination)
drums.start('snare')
drums.start('snare', 0, { gain: 0.3 })

player.stop(when, nodes) ⇒ Array

Stop some or all samples

Returns: Array - an array of ids of the stoped samples

Param	Type	Description
when	Float	(Optional) an absolute time in seconds (or currentTime if not specified)
nodes	Array	(Optional) an array of nodes or nodes ids to stop

Example

var longSound = player(ac, <AudioBuffer>).connect(ac.destination)
longSound.start(ac.currentTime)
longSound.start(ac.currentTime + 1)
longSound.start(ac.currentTime + 2)
longSound.stop(ac.currentTime + 3) // stop the three sounds

player.connect(destination) ⇒ AudioPlayer

Connect the player to a destination node

Chainable
Returns: AudioPlayer - the player

Param	Type	Description
destination	AudioNode	the destination node

Example

var sample = player(ac, <AudioBuffer>).connect(ac.destination)

player.on(event, callback) ⇒ SamplePlayer

Adds a listener of an event

Chainable
Returns: SamplePlayer - the player

Param	Type	Description
event	String	the event name
callback	function	the event handler

Example

player.on('start', function(time, note) {
  console.log(time, note)
})

player.schedule(when, events) ⇒ Array

Schedule a list of events to be played at specific time.

It supports two formats of events:

• An array with [time, note]
• An array with objects { time: ?, [name|note|midi|key]: ? }

Returns: Array - an array of ids

Param	Type	Description
when	Float	an absolute time to start (or AudioContext's currentTime if it's less than currentTime)
source	Array	the events array

Example

// Event format: [time, note]
var piano = player(ac, ...).connect(ac.destination)
piano.schedule(0, [ [0, 'C2'], [0.5, 'C3'], [1, 'C4'] ])

Example

// Event format: object { time: , name: }
var drums = player(ac, ...).connect(ac.destination)
drums.schedule(ac.currentTime, [
  { name: 'kick', time: 0 },
  { name: 'snare', time: 0.5 },
  { name: 'kick', time: 1 },
  { name: 'snare', time: 1.5 }
])

player.listenToMidi(input, options) ⇒ SamplePlayer

Connect a player to a midi input

The options accepts:

• channel: the channel to listen to. Listen to all channels by default.

Returns: SamplePlayer - the player

Param	Type	Description
input	MIDIInput
options	Object	(Optional)

Example

var piano = player(...)
window.navigator.requestMIDIAccess().then(function (midiAccess) {
  midiAccess.inputs.forEach(function (midiInput) {
    piano.listenToMidi(midiInput)
  })
})

Run tests and examples

To run the test, clone this repo and:

npm install
npm test

To run the examples:

npm i -g budo
budo examples/microtone.js

(Take a look into examples folder)

License

MIT License