API-Dokumentation

Vollständige Referenz für ChiptuneSynth – 4-Spur-Chiptune-Synthesizer für die Web Audio API

Schnellstart

// 1. Include the library
<script src="chiptune-synth.js"></script>

// 2. Create and initialize
const synth = new ChiptuneSynth();
await synth.init();

// 3. Play a note
synth.playNoteByName('C', 4, 0, 0.5);

// 4. Or play a sound effect
synth.playPreset('coin');

// 5. Load an instrument
synth.loadInstrument('violin', 0);
synth.playNoteByName('A', 4, 0, 1.0);

Konstruktor & Initialisierung

new ChiptuneSynth()

Erstellt eine neue Synthesizer-Instanz mit 4 Spuren (Lead, Bass, Drums, FX), Standard-Hüllkurven und leeren Vibrato-Einstellungen.

const synth = new ChiptuneSynth();

synth.init() async

Initialisiert den Web-Audio-API-Kontext, erstellt Master-Gain, Analysator, Gain-Knoten pro Spur und einen Rauschpuffer. Muss einmal vor jeder Wiedergabe aufgerufen werden.

await synth.init();

synth.dispose()

Stoppt alle Noten und schließt den AudioContext. Rufen Sie diese Methode auf, wenn Sie mit dem Synthesizer fertig sind.

Wiedergabemethoden

synth.playNote(frequency, trackIndex, duration, startTime) → noteId

Spielt eine Note mit der angegebenen Frequenz (Hz) auf der angegebenen Spur ab.

const noteId = synth.playNote(440, 0, 0.5);  // A4, Lead, 0.5s

synth.playNoteByName(note, octave, trackIndex, duration) → noteId

Spielt eine Note anhand ihres musikalischen Namens ab.

synth.playNoteByName('C', 4, 0, 0.5);  // Middle C on Lead
synth.playNoteByName('Eb', 3, 1, 1.0); // Eb3 on Bass

synth.stopNote(noteId)

Stoppt eine bestimmte Note mit ihrer Release-Hüllkurve. Verwende die von `playNote()` oder `playNoteByName()` zurückgegebene `noteId`.

synth.stopAllNotes()

Stoppt sofort alle aktiven Noten in allen Spuren.

Presets & Instrumente

synth.playPreset(name)

Lädt und spielt ein integriertes SFX-Preset in einem Aufruf ab. Perfekt für Soundeffekte in Spielen.

synth.playPreset('coin');
synth.playPreset('explosion');
synth.playPreset('jump');

Verfügbare SFX-Presets (10)

synth.loadPreset(name)

Lädt die Konfiguration eines Presets (Wellenform, Hüllkurve, Effekte) auf eine Spur, ohne sie abzuspielen. Nützlich zum Einrichten einer Spur, bevor Noten manuell ausgelöst werden.

synth.loadInstrument(name, trackIndex) → boolean

Lädt ein vollständiges Instrumenten-Preset auf die angegebene Spur und konfiguriert Wellenform, Hüllkurve, Vibrato und Modulation.

synth.loadInstrument('violin', 0);
synth.playNoteByName('A', 4, 0, 2.0);

Verfügbare Instrumente (12)

Spurkonfiguration

synth.updateTrack(trackIndex, settings)

Aktualisiert eine oder mehrere Eigenschaften einer Spur. Änderungen werden in Echtzeit auf die aktuell gespielten Noten angewendet.

synth.updateTrack(0, {
  type: 'sawtooth',
  volume: 0.4,
  unisonVoices: 4,
  unisonDetune: 20
});

Spureigenschaften

Du kannst die Eigenschaften auch direkt an den Track-Objekten einstellen:

synth.tracks[0].type = 'sawtooth';
synth.tracks[0].volume = 0.4;
synth.updateLiveNotes(0); // Apply to active notes

Hüllkurven (ADSR)

synth.updateEnvelope(trackIndex, settings)

Legt die Amplituden-Hüllkurve für eine Spur fest. Steuert, wie Noten einblenden, gehalten werden und ausblenden.

synth.updateEnvelope(0, {
  attack:  0.1,   // Fade-in time (seconds)
  decay:   0.2,   // Decay to sustain level
  sustain: 0.6,   // Held level (0-1)
  release: 0.5    // Fade-out after note stops
});

Standard-Hüllkurven

Vibrato

synth.updateVibrato(trackIndex, settings)

Konfiguriert die Tonhöhenmodulation (Vibrato) für eine Spur.

synth.updateVibrato(0, {
  rate:  5,   // Speed in Hz
  depth: 12   // Amount in cents
});

Filter

Jede Spur verfügt über einen optionalen Filter zur Gestaltung des Frequenzspektrums des Klangs.

synth.tracks[0].filterEnabled = true;
synth.tracks[0].filterType = 'lowpass';
synth.tracks[0].filterCutoff = 2000;
synth.tracks[0].filterQ = 5;
synth.updateLiveNotes(0);

Unison & Detune

Stapeln Sie mehrere verstimmte Oszillatoren für einen dichten, breiten Klang. Unverzichtbar für Pads und Leads.

synth.tracks[0].unisonVoices = 8;
synth.tracks[0].unisonDetune = 25;  // cents between voices
synth.tracks[0].unisonSpread = 80;  // stereo spread %

LFOs (Tremolo & Filtermodulation)

Tremolo (Amplituden-LFO)

synth.tracks[0].tremoloRate = 6;    // Hz
synth.tracks[0].tremoloDepth = 50;   // 0-100

Filter-LFO

synth.tracks[0].filterEnabled = true;
synth.tracks[0].filterCutoff = 1000;
synth.tracks[0].lfoFilterRate = 3;     // Hz
synth.tracks[0].lfoFilterDepth = 2000;  // Hz range

MIDI-Unterstützung

synth.enableMIDI(options) async→ inputNames[]

Aktiviert den MIDI-Eingang von angeschlossenen Controllern. Gibt ein Array mit den Namen der erkannten MIDI-Eingabegeräte zurück.

const inputs = await synth.enableMIDI({
  track: 0,
  channel: 0,              // 0 = all channels
  onConnect: (name) => console.log('Connected:', name),
  onDisconnect: (name) => console.log('Disconnected:', name),
  onNoteOn: (note, vel, ch) => { /* MIDI note 0-127 */ },
  onNoteOff: (note, ch) => { /* ... */ },
  onCC: (cc, value, ch) => { /* CC 0-127 */ }
});

Optionen

Unterstützte MIDI-CC

synth.disableMIDI()

Deaktiviert den MIDI-Eingang und stoppt alle gehaltenen MIDI-Noten.

synth.setMIDITrack(trackIndex)

Ändert, welcher Track MIDI-Eingaben empfängt.

synth.setMIDIChannel(ch)

Legt den MIDI-Kanalfilter fest (0 = alle Kanäle).

synth.isMIDIEnabled() → boolean

Gibt zurück, ob MIDI derzeit aktiv ist.

Visualisiererdaten

synth.getWaveformData() → Uint8Array

Gibt Zeitbereichs-Wellenformdaten für die Darstellung von Visualisierungen im Oszilloskop-Stil zurück. Die Werte reichen von 0 bis 255 (128 = Mitte).

function draw() {
  const data = synth.getWaveformData();
  // Draw on canvas...
  ctx.beginPath();
  data.forEach((v, i) => {
    const x = (i / data.length) * width;
    const y = (v / 255) * height;
    i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y);
  });
  ctx.stroke();
  requestAnimationFrame(draw);
}

synth.getFrequencyData() → Uint8Array

Gibt Frequenzbereichsdaten (FFT) für Spektrumvisualisierungen zurück. Die Werte liegen im Bereich von 0 bis 255.

synth.setMasterVolume(value)

Stellt die Master-Ausgangslautstärke ein (0–1).

synth.getMasterVolume() → number

Gibt die aktuelle Master-Lautstärke zurück.

synth.resetToDefaults()

Setzt alle Spuren, Hüllkurven und das Vibrato auf ihre Standardwerte zurück.

Statische Methoden

ChiptuneSynth.noteToFrequency(note, octave) statisch→ Zahl

Konvertiert einen Notennamen und eine Oktave in eine Frequenz in Hz.

ChiptuneSynth.noteToFrequency('A', 4);  // → 440
ChiptuneSynth.noteToFrequency('C', 4);  // → 261.63

ChiptuneSynth.midiToFrequency(midi) statisch→ Zahl

Konvertiert eine MIDI-Notennummer (0–127) in eine Frequenz in Hz.

ChiptuneSynth.frequencyToMidi(freq) statisch→ Zahl

Konvertiert eine Frequenz in die nächstgelegene MIDI-Notennummer.

ChiptuneSynth.getPresetNames() statisch→ string[]

Gibt ein Array mit allen verfügbaren SFX-Preset-Namen zurück.

ChiptuneSynth.getPresetNames();
// → ['laser','coin','jump','explosion','powerup','hit','blip','bass','shoot','1up']

ChiptuneSynth.getInstrumentNames() statisch→ string[]

Gibt ein Array aller verfügbaren Instrumenten-Preset-Namen zurück.

ChiptuneSynth.getInstruments() statisch→ Objekt

Gibt ein Objekt zurück, das nach Instrumentennamen sortiert ist, wobei jeder Wert die vollständige Definition enthält (Spureinstellungen, Hüllkurve, Vibrato, Filter usw.).

const instruments = ChiptuneSynth.getInstruments();
// { piano: { name, label, icon, type, volume, ... }, violin: { ... }, ... }

// Access a specific instrument definition
const piano = instruments.piano;
console.log(piano.type);  // 'triangle'
console.log(piano.label); // 'Piano'

Erstellen benutzerdefinierter Instrumente

Sie können Ihre eigenen Instrumente erstellen, indem Sie Track-Einstellungen, Hüllkurven, Vibrato und Filter kombinieren. So erstellen Sie Sounds von Grund auf neu.

Einfacher benutzerdefinierter Sound

Konfigurieren Sie eine Spur manuell und spielen Sie dann Noten darauf:

// Create a retro pluck bass
synth.updateTrack(1, {
  type: 'sawtooth',
  volume: 0.5,
  octaveOffset: -1
});
synth.updateEnvelope(1, {
  attack: 0.005,
  decay: 0.3,
  sustain: 0.0,
  release: 0.1
});
synth.playNoteByName('E', 2, 1, 0.4);

Benutzerdefinierte SFX (im Preset-Stil)

Das Preset-Muster nachbilden – eine Spur konfigurieren, eine Note spielen und den Rest der Hüllkurve überlassen:

// Custom "warp" SFX on FX track (3)
function playWarp() {
  synth.updateTrack(3, {
    type: 'square',
    volume: 0.3,
    dutyCycle: 0.25,
    pitchEnv: -24       // pitch drops 2 octaves
  });
  synth.updateEnvelope(3, {
    attack: 0.01,
    decay: 0.4,
    sustain: 0.0,
    release: 0.1
  });
  synth.playNote(880, 3, 0.5);
}
// Now call playWarp() anytime!

Vielschichtiges Instrument mit Effekten

Kombiniere mehrere Funktionen für ausdrucksstarke Instrumente:

// Dreamy synth pad with filter sweep
function setupDreamPad(track) {
  synth.updateTrack(track, {
    type: 'square',
    volume: 0.25,
    dutyCycle: 0.3,
    unisonVoices: 6,
    unisonDetune: 18,
    unisonSpread: 70
  });
  synth.updateEnvelope(track, {
    attack: 0.8,
    decay: 0.5,
    sustain: 0.6,
    release: 2.0
  });
  synth.updateVibrato(track, {
    rate: 4,
    depth: 8
  });
  // Add filter with LFO modulation
  synth.tracks[track].filterEnabled = true;
  synth.tracks[track].filterType = 'lowpass';
  synth.tracks[track].filterCutoff = 1200;
  synth.tracks[track].filterQ = 3;
  synth.tracks[track].lfoFilterRate = 0.3;
  synth.tracks[track].lfoFilterDepth = 800;
}

setupDreamPad(0);
synth.playNoteByName('C', 4, 0, 3.0);

Mehrspuriger, überlagerter Klang

Schichten Sie mehrere Spuren für komplexe Klänge:

// Layered "epic hit" — noise + bass + lead
function playEpicHit() {
  // Layer 1: noise crash
  synth.updateTrack(2, { type: 'noise', volume: 0.4 });
  synth.updateEnvelope(2, { attack:0.001, decay:0.3, sustain:0, release:0.1 });
  synth.playNote(200, 2, 0.4);

  // Layer 2: sub bass thump
  synth.updateTrack(1, { type: 'sine', volume: 0.6, pitchEnv: 12 });
  synth.updateEnvelope(1, { attack:0.001, decay:0.25, sustain:0, release:0.1 });
  synth.playNote(60, 1, 0.3);

  // Layer 3: bright accent
  synth.updateTrack(0, { type: 'square', volume: 0.2 });
  synth.updateEnvelope(0, { attack:0.001, decay:0.1, sustain:0, release:0.2 });
  synth.playNote(440, 0, 0.15);
}

Wiederverwendbares Instrumentenobjekt-Muster

Organisieren Sie Ihre benutzerdefinierten Instrumente als Konfigurationsobjekte:

// Define instrument configs
const myInstruments = {
  retroLead: {
    track: { type: 'square', dutyCycle: 0.25, volume: 0.3 },
    env:   { attack: 0.02, decay: 0.15, sustain: 0.5, release: 0.3 },
    vib:   { rate: 5.5, depth: 10 }
  },
  fatBass: {
    track: { type: 'sawtooth', volume: 0.5, unisonVoices: 3, unisonDetune: 10 },
    env:   { attack: 0.01, decay: 0.2, sustain: 0.7, release: 0.1 },
    vib:   { rate: 0, depth: 0 }
  }
};

// Apply an instrument to a track
function applyInstrument(name, trackIndex) {
  const inst = myInstruments[name];
  synth.updateTrack(trackIndex, inst.track);
  synth.updateEnvelope(trackIndex, inst.env);
  synth.updateVibrato(trackIndex, inst.vib);
}

applyInstrument('retroLead', 0);
synth.playNoteByName('C', 5, 0, 0.5);

Standardwerte

Spur-Standardwerte

Architekturhinweis

Die „Per-note-gainNode“ steuert ausschließlich die ADSR-Hüllkurve (normalisiert 0→1→Sustain). Die Lautstärke der Spur wird über einen separaten „_trackGains[]“-Knoten geregelt. Diese Architektur ermöglicht Parameteränderungen in Echtzeit, ohne den ADSR-Ablauf der gespielten Noten zu unterbrechen.