Tone.GrainPlayer and Granular Synthesis in Tone.js

This article explains how Tone.GrainPlayer works within the Tone.js web audio framework to perform granular synthesis. You will learn the core concepts of granular synthesis, the specific parameters used by Tone.GrainPlayer to manipulate audio, and how to implement this powerful tool to stretch, pitch-shift, and texture your sound samples.

What is Granular Synthesis?

Granular synthesis is an audio synthesis method that splits an audio sample into tiny, microscopic segments called “grains.” These grains are typically between 10 and 100 milliseconds long.

By layering, overlapping, and playing these grains back at various speeds, pitches, and intervals, you can radically transform the original sound. Unlike traditional sampler playback—where speeding up a sample raises its pitch and slowing it down lowers its pitch—granular synthesis allows you to control the playback speed (time-stretching) and the pitch (pitch-shifting) independently.

Understanding Tone.GrainPlayer

Tone.GrainPlayer is a specialized node in the Tone.js library designed to automate the process of granular synthesis. It takes an audio buffer (such as an MP3 or WAV file) and continuously schedules and plays overlapping grains from that buffer.

Because of how it slices and reconstructs the audio, Tone.GrainPlayer is ideal for creating ambient pads, cloud-like textures, glitch effects, or simply stretching an audio file without changing its key.

Key Parameters of Tone.GrainPlayer

To manipulate the sound within Tone.GrainPlayer, you adjust several key properties:

grainSize: This determines the duration of each individual grain, measured in seconds. Smaller grain sizes (e.g., 0.05 seconds) produce a smoother, more synthetic sound, while larger grain sizes (e.g., 0.2 seconds) retain more of the original audio’s characteristics.
overlap: This defines the amount of time that grains overlap with one another. It is measured in seconds. Higher overlap values result in a thicker, smoother sound, while lower values can introduce a pulsing or tremolo-like stutter effect.
playbackRate: This controls the speed at which the playhead moves through the buffer. A playbackRate of 1 is normal speed, 0.5 is half speed, and 2 is double speed. Crucially, changing the playbackRate in a Tone.GrainPlayer does not alter the pitch of the output.
detune: This alters the pitch of the grains in cents (100 cents equal one semitone). Adjusting this value pitch-shifts the audio up or down without changing the speed of the playback.
loop: A boolean value (true or false) that determines whether the audio buffer should loop continuously when it reaches the end.

How to Implement Tone.GrainPlayer

To use Tone.GrainPlayer in your Tone.js application, you must first load an audio file, configure the parameters, connect it to the master output, and start the player.

Here is a basic implementation structure:

// Create and configure the GrainPlayer
const player = new Tone.GrainPlayer({
  url: "path/to/your/audio.mp3",
  onload: () => {
    // Start playback once the audio file is loaded
    player.start();
  },
  grainSize: 0.08, // Grains are 80 milliseconds long
  overlap: 0.1,    // Grains overlap by 100 milliseconds
  playbackRate: 0.5, // Play back at half speed
  detune: 1200,    // Pitch shift up by one octave (1200 cents)
  loop: true       // Loop the playback
}).toDestination();

As the player runs, you can dynamically update these parameters in real-time in response to user interactions or automated modulators, allowing you to morph a simple vocal or instrument sample into an evolving acoustic landscape.