OscillatorNode — Schnittstelle · JavaScript-Referenz

Signatur

interface OscillatorNode extends AudioScheduledSourceNode

Beschreibung

OscillatorNode gehört zur Web Audio API. Der Knoten ist eine Tonquelle: Er hat keinen Eingang, aber einen Ausgang, und erzeugt einen konstanten, periodischen Ton. Die Form der Welle legt man über type fest ("sine", "square", "sawtooth", "triangle") oder über setPeriodicWave() mit einer eigenen Wellenform, woraufhin type den Wert "custom" hat.

Die Tonhöhe steuern zwei AudioParam-Eigenschaften: frequency (in Hertz, Standardwert 440) und detune (Verstimmung in Cent, Standardwert 0). Da beide AudioParams sind, kann man sie zeitgenau automatisieren (z. B. mit setValueAtTime(), linearRampToValueAtTime()) oder mit anderen Knoten modulieren, etwa für Vibrato oder FM-Synthese.

Man erzeugt einen Oszillator entweder mit new OscillatorNode(context, options) oder mit context.createOscillator(). Die Methoden start(when) und stop(when) sowie das Ereignis ended stammen von AudioScheduledSourceNode. Typische Einsatzgebiete sind Synthesizer, Signaltöne, Testtöne, Metronome und LFOs zur Modulation anderer Parameter.

Ein Oszillator ist ein Einweg-Objekt: Nach stop() lässt er sich nicht mehr starten. Für jeden neuen Ton erstellt man einen neuen Knoten. Das kostet wenig, weil Oszillatoren genau dafür gedacht sind.

Parameter

Name	Typ	Default	Beschreibung
$context Pflicht	BaseAudioContext		Der `AudioContext` oder `OfflineAudioContext`, zu dem der Knoten gehört (Konstruktor-Parameter).
$options	OscillatorOptions	{}	Optionales Objekt für den Konstruktor mit folgenden Feldern: `type`: Wellenform, Standardwert `"sine"` `frequency`: Frequenz in Hz, Standardwert `440` `detune`: Verstimmung in Cent, Standardwert `0` `periodicWave`: eigene `PeriodicWave`, setzt `type` auf `"custom"` Dazu kommen die allgemeinen `AudioNodeOptions` wie `channelCount`.

Rückgabewert

Typ

OscillatorNode

Beschreibung

Eine neue OscillatorNode-Instanz. Eigenschaften: type (string), frequency (AudioParam), detune (AudioParam). Methoden: setPeriodicWave(), start(), stop(). Ereignis: ended.

Beispiele

Einfachen Signalton abspielen (nach Klick)

const ctx = new AudioContext();

document.querySelector('#beep').addEventListener('click', async () => {
  // Autoplay-Sperre: Kontext erst nach einer Nutzeraktion fortsetzen
  if (ctx.state === 'suspended') await ctx.resume();

  const osc = new OscillatorNode(ctx, { type: 'sine', frequency: 880 });
  const gain = new GainNode(ctx, { gain: 0.2 });

  osc.connect(gain).connect(ctx.destination);
  osc.start();
  osc.stop(ctx.currentTime + 0.3); // 300 ms Ton

  osc.addEventListener('ended', () => console.log('Ton beendet'));
});

Ton beendet

Ton ohne Knacken mit Hüllkurve und Frequenzverlauf

const ctx = new AudioContext();

const playSweep = () => {
  const now = ctx.currentTime;
  const osc = ctx.createOscillator();
  const gain = ctx.createGain();

  osc.type = 'sawtooth';
  osc.frequency.setValueAtTime(220, now);
  osc.frequency.exponentialRampToValueAtTime(880, now + 1);

  // Lautstärke ein- und ausblenden, damit es nicht knackt
  gain.gain.setValueAtTime(0.0001, now);
  gain.gain.exponentialRampToValueAtTime(0.3, now + 0.05);
  gain.gain.exponentialRampToValueAtTime(0.0001, now + 1);

  osc.connect(gain).connect(ctx.destination);
  osc.start(now);
  osc.stop(now + 1.05);
};

document.addEventListener('click', playSweep, { once: true });

Vibrato per LFO und eigene Wellenform

const ctx = new AudioContext();

const carrier = new OscillatorNode(ctx, { frequency: 440 });
// LFO: 5 Hz, moduliert die Tonhöhe um ±10 Hz
const lfo = new OscillatorNode(ctx, { frequency: 5 });
const lfoDepth = new GainNode(ctx, { gain: 10 });
lfo.connect(lfoDepth).connect(carrier.frequency);

// Eigene Wellenform: Grundton plus 3. Oberton
const real = new Float32Array([0, 0, 0, 0]);
const imag = new Float32Array([0, 1, 0, 0.5]);
carrier.setPeriodicWave(ctx.createPeriodicWave(real, imag));
console.log(carrier.type);

carrier.connect(new GainNode(ctx, { gain: 0.2 })).connect(ctx.destination);
carrier.start();
lfo.start();
carrier.stop(ctx.currentTime + 2);
lfo.stop(ctx.currentTime + 2);

custom

// Wichtig · Fallstricke

Nur einmal startbar: Ruft man start() ein zweites Mal auf, wirft das einen InvalidStateError. Für jeden Ton einen neuen Oszillator erzeugen.
Autoplay-Sperre: Browser starten einen AudioContext meist im Zustand "suspended". Ton gibt es erst, wenn nach einer Nutzeraktion ctx.resume() aufgerufen wurde.
Knacken: Wenn der Ton hart startet oder stoppt, knackt es hörbar. Die Lautstärke über einen GainNode kurz ein- und ausblenden. exponentialRampToValueAtTime() akzeptiert keinen Zielwert 0, stattdessen z. B. 0.0001 verwenden.
type = "custom" darf man nicht direkt setzen, das wirft einen InvalidStateError. Eine eigene Wellenform nur über setPeriodicWave() oder die Option periodicWave festlegen.
Lautstärke: Oszillatoren geben mit voller Amplitude (±1) aus, besonders square und sawtooth klingen dann sehr laut. Immer über einen GainNode leiser regeln.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Der Konstruktor new OscillatorNode() fehlt in sehr alten Safari-Versionen, dort createOscillator() verwenden. Ganz alte WebKit-Versionen brauchten das Präfix webkitAudioContext.

Siehe auch

IIRFilterNode AnalyserNode AudioNode ConvolverNode DelayNode