Pizzicato

[!NOTE]
Due to lack of time to focus on this project, I'm actively looking for maintainers who might be interested in working on Pizzicato. Don't hesitate to contact me! In the meantime, consider the project deprecated.

<img align="center" src="https://alemangui.github.io/pizzicato/img/horizontal-logo-outline.svg" alt="Pizzicato.js">

A Web Audio library

Pizzicato aims to simplify the way you create and manipulate sounds via the Web Audio API. Take a look at the demo site here.

Table of contents

• Get Pizzicato
  • npm
  • bower
  • cdnjs
  • Installing and testing
• TL;DR: How does it work?
• Create a sound
  • Sounds from a wave
  • Sounds from a file
  • Sounds from input
  • Sounds from a function
• Using sounds
  • play()
  • pause()
  • stop()
  • clone()
  • addEffect()
  • removeEffect()
  • volume
  • attack
  • release
  • frequency
  • Events
    • play
    • pause
    • stop
    • end
  • Connecting sounds to AudioNodes
• Grouping sounds
  • Create a group
  • addSound()
  • removeSound()
  • addEffect()
  • removeEffect()
  • play()
  • pause()
  • stop()
  • volume
• Effects
  • Delay
  • Ping Pong Delay
  • Dub Delay
  • Distortion
  • Quadrafuzz
  • Flanger
  • Compressor
  • Low-pass filter
  • High-pass filter
  • Stereo Panner
  • Convolver
  • Reverb
  • Ring Modulator
  • Tremolo
  • Connecting effects to and from AudioNodes
• Advanced
  • Accessing the audio context
  • Using Pizzicato objects in a web audio graph
  • General volume
  • Memory management
• Support
  • Browsers
  • Audio formats

<a name="get-pizzicato"/>

Get Pizzicato

<a name="npm"/>

npm

npm install pizzicato

<a name="bower"/>

bower

bower install pizzicato

<a name="cdnjs"/>

cdnjs

Full source code:

<script src="https://cdnjs.cloudflare.com/ajax/libs/pizzicato/0.6.4/Pizzicato.js"></script>

Minified:

<script src="https://cdnjs.cloudflare.com/ajax/libs/pizzicato/0.6.4/Pizzicato.min.js"></script>

<a name="installing-and-testing"/>

Installing and testing

Ensure you have gulp installed: npm install -g gulp.

Checkout the project and install dependencies with :

npm install

Run tests with:

npm run test

By default, Firefox is used for local testing. If you'd like to use Chrome you can use the setting active in TravisCI. To do so, go to karma.conf.js, line 5, and change the browsers array to :

browsers: ['Chrome_travis_ci'],

Build without tests with: npm run build or npm run watch

<a name="tldr"/>

TL;DR: How does it work?

Include Pizzicato in your site

<script src="./Pizzicato.js"></script>

Create a sound

var sawtoothWave = new Pizzicato.Sound({ 
    source: 'wave',
    options: {
        type: 'sawtooth'
    }
});

Add effects

var delay = new Pizzicato.Effects.Delay();
sawtoothWave.addEffect(delay);

Play it!

sawtoothWave.play();

<a name="create-a-sound"/>

Create a sound

To create a new sound, use the Pizzicato.Sound constructor, which takes an object with the sound's description as argument and a callback that will be executed when the sound is ready to be used. If an error occurs, the callback will be called with the error as a parameter.

var sound = new Pizzicato.Sound(Object description, [Function callback]);

For example:

var click = new Pizzicato.Sound({ source: 'wave' }, function(error) {
    if (!error)
        console.log('Sound ready to use!');
});

Typically, the description object contains a string source and an object options. The options object varies depending on the source of the sound being created.

For example, this objects describes a sine waveform with a frequency of 440:

{
    source: 'wave',
    options: {
        type: 'sine',
        frequency: 440
    }
}

Sounds can be created from a variety of sources.

<a name="sounds-from-a-wave"/>

Sounds from a wave (example)

To create a sound from an oscillator with a certain waveform, use the source: wave in your description. Additionally, the following optional parameters are possible inside the options object:

• type (Optional; sine, square, triangle or sawtooth, defaults to sine): Specifies the type of waveform.
• frequency (Optional; defaults to 440): Indicates the frequency of the wave (i.e., a 440 value will yield an A note).
• volume (Optional; min: 0, max: 1, defaults to 1): Loudness of the sound.
• release (Optional; defaults to 0.4): Value in seconds that indicates the fade-out time when the sound is stopped.
• attack (Optional; defaults to 0.4): Value in seconds that indicates the fade-in time when the sound is played.
• detached (Optional; defaults to false): If true, the sound will not be connected to the context's destination, and thus, will not be audible.

var sound = new Pizzicato.Sound({ 
        source: 'wave',
        options: { type: 'sawtooth', frequency: 440 }
});

Creating a Pizzicato Sound with an empty constructor will create a sound with a sine wave and a frequency of 440.

var sound = new Pizzicato.Sound();

<a name="sounds-from-a-file"/>

Sounds from a file (example)

In order to load a sound from a file, include the source: file in your description. Additionally, the following parameters are possible inside the options object:

• path (Mandatory; string or array of strings): Specifies the path of the sound file. It is also possible to have an array of paths to fallback on. Pizzicato will attempt to load the paths in order, passing on to the next one in case of failure.
• loop (Optional; boolean, defaults to false): If set, the file will start playing again after the end.
• volume (Optional; min: 0, max: 1, defaults to 1): Loudness of the sound.
• release (Optional; defaults to 0): Value in seconds that indicates the fade-out time once the sound is stopped.
• attack (Optional; defaults to 0.4): Value in seconds that indicates the fade-in time when the sound is played.
• detached (Optional; defaults to false): If true, the sound will not be connected to the context's destination, and thus, will not be audible.

var sound = new Pizzicato.Sound({ 
    source: 'file',
    options: { path: './audio/sound.wav' }
}, function() {
    console.log('sound file loaded!');
});

It is possible to pass several paths to fallback in case of error:

var sound = new Pizzicato.Sound({ 
    source: 'file',
    options: { path: ['./audio/sound-special-format.wav', './audio/sound.wav'] }
}, function() {
    console.log('sound file loaded!');
});

Alternatively, you can also simply pass a string to the constructor with the path of the sound file.

var sound = new Pizzicato.Sound('./audio/sound.wav', function() {...});

Check the supported audio files that can be played with Pizzicato.

<a name="sounds-from-input"/>

Sounds from the user input (example)

It is also possible to use the sound input from the computer. This is usually the microphone, but it could also be a line-in input. To use this, add source: input in your description. The following optional parameters are possible inside options object:

• volume (Optional; min: 0, max: 1, defaults to 1): Loudness of the sound.
• release (Optional; defaults to 0): Value in seconds that indicates the fade-out time once the sound is stopped.
• attack (Optional; defaults to 0.4): Value in seconds that indicates the fade-in time when the sound is played.
• detached (Optional; defaults to false): If true, the sound will not be connected to the context's destination, and thus, will not be audible.

var voice = new Pizzicato.Sound({
    source: 'input',
    options: { volume: 0.8 }
});

<a name="sounds-from-a-function"/>

Sounds from a function (example)

For more creative freedom, Pizzicato also allows direct audio processing. Sounds can be created from a Javascrip