How to use OscillatorNode in JavaScript

Creating and manipulating sound in a web application can seem overwhelming. However, with JavaScript and the Web Audio API, you can craft an immersive audio experience easily. In this article, we’re going to reveal how to use the OscillatorNode interface to generate sounds directly in the browser. Whether you’re interested in making music, games, or just want to play a tone for 345 Hz for 1000 milliseconds, understanding the OscillatorNode is key. Let’s dive in and explore this dynamic interface!

What is an OscillatorNode?

An OscillatorNode is a versatile component of the Web Audio API capable of generating periodic waveforms – in other words, it can create sound waves. Utilized in various web development projects, this interface represents the foundation for producing synthetic sounds that can be precisely controlled through JavaScript.

The OscillatorNode allows developers to select the waveform shape they would like to create, with several common types to choose from, such as sine, square, sawtooth, and triangle waves. It also gives you the creative flexibility to define custom waveforms, meaning the possibilities for sound design are virtually limitless.

Setup and Basic Usage

To start using an OscillatorNode, you need an instance of an AudioContext. First, let’s establish this context, which serves as the container for all your audio nodes:

const audioContext = new AudioContext();

Next, you’ll want to create an OscillatorNode using the createOscillator method on the audio context:

const oscillator = audioContext.createOscillator();

From there, you can set the desired waveform type and frequency:

oscillator.type = 'sine'; // or 'square', 'sawtooth', 'triangle'
oscillator.frequency.setValueAtTime(345, audioContext.currentTime); // Set to 345 Hz

To actually hear the sound, you need to connect your oscillator node to the context’s destination (your speakers or headphones):


Finally, you can start and stop the oscillator to make it produce sound:

window.setTimeout(() => oscillator.stop(), 1000); // Stop after 1000 milliseconds

Controlling Frequency and Detuning

An OscillatorNode’s frequency is the number of times a waveform repeats in one second, which determines the pitch of the sound. You can set the frequency of an oscillator with the frequency property, which is an instance of AudioParam. This allows for both immediate value setting and scheduled changes that can be applied smoothly over time.

Detuning is a similar concept, allowing you to alter the frequency slightly, typically measured in cents (hundredths of a semitone). This can be useful for creating vibrato effects, slightly adjusting pitch for harmony, or emulating the natural imperfections of instruments.

oscillator.frequency.value = 345; // set directly to 345 Hz
oscillator.detune.setValueAtTime(100, audioContext.currentTime); // detune by 100 cents, or one semitone

Custom Waveforms and PeriodicWave

While the default waveforms are powerful, you may want to specify a custom waveform for your OscillatorNode. This is where setPeriodicWave comes into play, allowing you to define a custom periodic waveform using an instance of PeriodicWave.

First, you define the shape of the waveform with arrays of real and imaginary coefficients, then create a PeriodicWave object:

const real = new Float32Array([0, 1, 0.5, 0.333]);
const imag = new Float32Array(real.length);
const customWave = audioContext.createPeriodicWave(real, imag);

Then, you can assign this custom waveform to your oscillator:


The OscillatorNode Constructor

While the createOscillator method is common, there’s also an experimental OscillatorNode() constructor available in the Web Audio API. This constructor provides a way to create a new OscillatorNode object directly, providing all the capabilities we’ve discussed but possibly with a more updated or future-facing syntax.

const oscillator = new OscillatorNode(audioContext, { frequency: 345 });

Keep in mind that as an experimental feature, it’s essential to check browser support and be ready for changes in the API.

Event Handling: The ‘ended’ Event

OscillatorNodes also dispatch events. The ‘ended’ event, for instance, signals that the tone generation has concluded. You can add an event listener to the oscillator to trigger actions when the sound has stopped:

oscillator.onended = () => {
    console.log('The tone has finished playing.');

Browser Compatibility

Details regarding browser support for the OscillatorNode are crucial. While most modern web browsers support the Web Audio API, including the OscillatorNode interface, some properties or methods, especially experimental ones, may not be universally supported. Always refer to compatibility tables or resources such as Can I Use for the most up-to-date information.

Conclusion and Call to Action

Creating sounds with JavaScript and the OscillatorNode in the Web Audio API opens up a world of creative possibilities. We’ve only scratched the surface here, but with these core principles, you can begin experimenting with generating and manipulating sound in your web applications.

Don’t forget to check your browser’s compatibility with the OscillatorNode features, experiment with different waveform types, and maybe try crafting a unique sound with a custom PeriodicWave! And remember, practice is key to mastering the OscillatorNode.

For those hungry to dive even deeper into audio manipulation, continue your journey on the MDN Web Docs, where a wealth of information and live examples await. Ready to play with sound on the web? Start coding and make some noise!