soundfont-player

A soundfont loader/player to use MIDI sounds in WebAudio API. The purpose of this library is be able to play MIDI soundfonts with little client code and no server setup.

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)

Works out of the box with Benjamin Gleitzman's package of pre-rendered sound fonts. Just load the library and play. Try the demo

Usage

Load the library...

<script src="soundfont-player.js"></script>

... or require it using a npm package compatible environment (webpack, browserify):

var Soundfont = require('soundfont-player')

Create an AudioContext and request an instrument, and play when ready:

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

That's it.

Important: This library uses Promises, so you need a browser capable or a polyfill.

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

## API

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:

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 of the player (1 by default)
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.

Param	Type	Description
ac	`AudioContext`	the audio context
name	`String`	the instrument name. For example: 'acoustic_grand_piano'
options	`Object`	(Optional) the same options as Soundfont.loadBuffers

Example

var Soundfont = require('sounfont-player')
Soundfont.instrument('marimba').then(function (marimba) {
  marimba.play('C4')
})

nameToUrl(name, format) ⇒ `String`

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

Kind: global function
Returns: String - the Soundfont file url

Param	Type	Description
name	`String`	instrument name
format	`String`	(Optional) Can be 'mp3' or 'ogg' (mp3 by default)

Example

var Soundfont = require('soundfont-player')
Soundfont.nameToUrl('marimba', 'mp3')

noteToMidi(noteName) ⇒ `Integer`

Given a note name, return the note midi number

Kind: global function
Returns: Integer - the note midi number or null if not a valid note name

Param	Type
noteName	`String`

## 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/piano.js and navigate to http://localhost:9966/

Available instruments

You can grab a json file with all the instrument names, or require it:

var instrumentNames = require('soundfont-player/instruments.json')

The complete list is here

Resources

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

License

MIT License

mcomghall / soundfont-player Goto Github PK