Configure Tone.GrainPlayer Grain Size and Overlap

This article explains how to configure the grainSize and overlap parameters of the Tone.GrainPlayer class in Tone.js to control granular synthesis. You will learn what these parameters do, how they affect your audio playback, and how to adjust them both during initialization and dynamically during runtime.

Understanding the Parameters

Tone.GrainPlayer works by splitting an audio buffer into tiny segments called “grains” and playing them back sequentially. To control the texture and behavior of this playback, you primarily manipulate two parameters:

• grainSize: The duration of each individual audio grain, measured in seconds.
• overlap: The amount of time two consecutive grains overlap with each other, also measured in seconds. This parameter is crucial for smoothing out the transitions between grains.

Setting Parameters During Initialization

You can set the grainSize and overlap directly in the options object when creating a new instance of Tone.GrainPlayer.

const player = new Tone.GrainPlayer({
  url: "https://tonejs.github.io/audio/bermee/gong.mp3",
  onload: () => {
    player.start();
  },
  grainSize: 0.2,  // Each grain is 200 milliseconds long
  overlap: 0.1     // Grains overlap by 100 milliseconds
}).toDestination();

Modifying Parameters Dynamically

To change the grain behavior in real-time (for example, in response to user input or an automated modulation source), you can assign new values directly to the properties of your Tone.GrainPlayer instance.

// Change grain size to 500 milliseconds
player.grainSize = 0.5;

// Change overlap to 50 milliseconds for a more stuttered effect
player.overlap = 0.05;

Tips for Tweaking the Sound

• Smooth Textures: For a smooth, continuous sound, keep the overlap high relative to the grainSize (e.g., an overlap that is 50% or more of the grain size).
• Stutter and Glitch Effects: For glitchy, rhythmic, or disjointed sounds, decrease the overlap close to 0 or set a very small grainSize (e.g., 0.05 seconds).
• Time Stretching: When using Tone.GrainPlayer for time-stretching (by changing the .playbackRate), adjusting these parameters is essential to minimize metallic artifacts or audible “clicks” between grain boundaries.