soundfont-player

A soundfont loader/player to play MIDI sounds using WebAudio API.

It loads Benjamin Gleitzman's package of pre-rendered sound fonts by default with no server setup. Just a few lines of javascript:

Soundfont.instrument(new AudioContext(), 'acoustic_grand_piano').then(function (piano) {
  piano.play('C4')
})

It is a much simpler and lightweight replacement for MIDI.js soundfont loader (MIDI.js is much bigger, capable of play midi files, for example, but it weights an order of magnitude more).

Features

• Load soundfont files in MIDI.js format or json format.
• Unlimited poliphony (and stop all sounds with a single function call)
• Use midi note numbers. Accepts decimal points to detune.
• Easily connect to a Web MIDI API MidiInput
• Schedule a list of notes

It uses audio-loader to load soundfont files and sample-player to play the sounds.

Install

Via npm: npm install --save soundfont-player

Or download the minified code and include it in your html:

<script src="soundfont-player.js"></script>
<script>
  Soundfont.instrument(new AudioContext(), 'marimba').then(function (marimba) {
  })
</script>

Usage

The soundfont loader

Out of the box are two Soundfonts available: MusyngKite and FluidR3_GM (MusyngKite by default: has more quality, but also weights more). You can load them with instrument function:

Soundfont.instrument(ac, 'clavinet').then(function (clavinet) {
  clavinet.play('C4')
})
// or use FluidR3_GM
Soundfont.instrument(ac, 'clavinet', { soundfont: 'FluidR3_GM' }).then(function (clavinet) {
  clavinet.play('C4')
})

You can load your own Soundfont files passing the .js path or url:

Soundfont.instrument(ac, '/soundfonts/clavinet-mp3.js').then(...)
// or
Soundfont.instrument(ac, 'clavinet-mp3.js', { from: 'server.com/soundfonts/' })

The soundfont player

Once you have an instrument you can:

// The first step is always create an instrument:
Soundfont.instrument(ac, 'clavinet').then(function (clavinet) {
  // Then you can play a note using names or midi numbers:
  clavinet.play('C4')
  clavinet.play(69)
  // float point midi numbers are accepted (and notes are detuned):
  clavinet.play(60.5) // => 500 cents over C4

  // you can stop all playing notes
  clavinet.stop()
  // or stop only one
  clavinet.play('C4').stop(ac.currentTime + 0.5)
  // or pass a duration argument to `play`
  clavinet.play('C4', ac.currentTime, { duration: 0.5})


  // You can connect the instrument to a midi input:
  window.navigator.requestMIDIAccess().then(function (midiAccess) {
    midiAccess.inputs.forEach(function (midiInput) {
      clavinet.listenToMidi(midiInput)
    })
  })

  // Or schedule events at a given time
  clavinet.schedule(ac.currentTime + 5, [ { time: 0, note: 60}, { time: 0.5, note: 61}, ...])
})

API

< 0.9.x users: The API in the 0.9.x releases has been changed and some features are going to be removed (like oscillators). While 0.9.0 adds warnings to the deprecated API, the 1.0.0 will remove the support.

instrument(ac, name, options) ⇒ Promise

Load a soundfont instrument. It returns a promise that resolves to a instrument object.

The instrument object returned by the promise has the following properties:

• name: the instrument name
• play: A function to play notes from the buffer with the signature play(note, time, duration, options)

The valid options are:

• format: can be 'mp3' or 'ogg'
• soundfont: can be 'FluidR3_GM' or 'MusyngKite'
• nameToUrl: a function to convert from instrument names to URL
• destination: by default Soundfont uses the audioContext.destination but you can override it.
• gain: the gain (volume) of the player (1 by default)
• 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: the amplitude envelope as array of [attack, decay, sustain, release]. It overrides other options.
• loop: set to true to loop audio buffers
• notes: an array of the notes to decode. It can be an array of strings with note names or an array of numbers with midi note numbers. This is a performance option: since decoding mp3 is a cpu intensive process, you can limit limit the number of notes you want and reduce the time to load the instrument.

Example

var Soundfont = require('sounfont-player')
var ac = new AudioContext()
Soundfont.instrument(ac, 'marimba', { soundfont: 'MusyngKite' }).then(function (marimba) {
  marimba.play('C4')
})

The player

The player object returned by the promise has the following functions:

player.play

An alias for player.start

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

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

Valid options are:

• 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

player.stop(when, nodes) ⇒ Array

Stop some or all samples

player.on(event, callback) ⇒ player

Adds a listener of an event

player.connect(destination) ⇒ AudioPlayer

Connect the player to a destination node

player.schedule(when, events) ⇒ Array

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

player.listenToMidi(input, options) ⇒ player

Connect a player to a midi input

See soundfont-player for more information.

nameToUrl(name, soundfont, format) ⇒ String

Given an instrument name returns a URL to to the Benjamin Gleitzman's package of pre-rendered sound fonts

Returns: String - the Soundfont file url

Example

var Soundfont = require('soundfont-player')
Soundfont.nameToUrl('marimba', null, 'ogg') // => http://gleitz.github.io/midi-js-soundfonts/FluidR3_GM/marimba-ogg.js

Run the tests, examples and build the library distribution file

First clone this repo and install dependencies: npm i

To run tests use npm: npm test

The dist folder contains ready to use file for browser. You can use the dist file from the repo, but if you want to build you own run: npm run dist

To run the html example start a local http server. For example:

npm install -g http-server
http-server

And open http://localhost:8080/examples

To run pure javascript examples npm install -g beefy then beefy examples/marimba.js and navigate to http://localhost:9966/

Available instruments

By default it loads Benjamin Gleitzman's pre-rendered SoundFonts.

Instrument names

You can download the names of the instruments as a .json file:

• FluidR3_GM
• MusyngKite

Or require them:

var fluidNames = require('soundfont-player/names/fuildR3.json')
var musyngNames = require('soundfont-player/names/musyngkite.json')

Resources

• SoundFont technical specification: http://freepats.zenvoid.org/sf2/sfspec24.pdf

License

MIT License

CHANGELOG

0.10.7

• Add typescript definitions (thanks @rakannimer)

  0.10.6

• Chenage MusyngKite names to follow Gleitz renames (thanks @kirlen)

• Add yarn.lock
• Update dependencies

[0.10.4] Update sample-player (gain: 0 option is not ignored, start and play are the same function) [0.10.1] Update sample-player: add adsr individual parameters to options. New started event. [0.10.0]

• Add support to MusyngKite soundfonts.
• instrument can be partially applied with an AudioContext instance
• Deprecate noteToMidi

[0.9.2] Update sample-player [0.9.1] Use sample-player [0.9.0]

• Load soundfonts directly from github.io (https://github.com/gleitz/midi-js-soundfonts/issues/9)
• New API
• Deprecate old API [0.8.4]
• Use audio-loader
• Use note-parser instead of note-midi and note-freq [0.8.3]
• Use Ramp up to value functions for enabling and disabling the gain, when note duration is set. [0.8.2]
• Standard JS style support
• Add notes options

[0.8.1]

• Use duration parameter from AudioBufferSourceNode start function instead of stop. Thanks @frankbaele
• Add REAME notes about iOS usage and production usage
• Fix gh-pages links

[0.8.0]

• Add optional options parameter to play() that overrides the defaultOptions of instrument(). Thanks @mattbierner

[0.6.1]

• Update dependencies
• Remove unused code
• Use mocha instead of vows

[0.6.0]

• On ready callback now receives the instrument
• You can pass a midi value to play function
• Split functionality in files

[0.5.0]

• Duration no longer required (thanks @benwiley4000).

[0.4.0]

• Add soundfont.onready
• Fix a bug with vco oscillator
• Amplitude of oscillator is now similar to soundfont notes

[0.3.0]

• Move to a class based library
• Default instrument with a sine oscillator
• Instruments play notes before the soundfont is loaded
• Use note-parser to parase notes
• Use midi numbers to map buffer notes

[0.2.0]

• Altered notes are correctly assigned to the buffer (issue #1)
• Simplify lib structure
• Add soundfont.noteToBufferName function

[0.1.0]

• First version