Documentation de l'API

Référence complète pour ChiptuneSynth — Synthétiseur chiptune 4 pistes pour l'API Web Audio

Démarrage rapide

// 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);

Constructeur et initialisation

new ChiptuneSynth()

Crée une nouvelle instance de synthétiseur avec 4 pistes (Lead, Bass, Drums, FX), des enveloppes par défaut et des paramètres de vibrato vides.

const synth = new ChiptuneSynth();

synth.init() async

Initialise le contexte de l'API Web Audio, crée le gain principal, l'analyseur, les nœuds de gain par piste et le tampon de bruit. Doit être appelé une fois avant toute lecture.

await synth.init();

synth.dispose()

Arrête toutes les notes et ferme l'AudioContext. À appeler lorsque vous avez terminé d'utiliser le synthétiseur.

Méthodes de lecture

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

Joue une note à la fréquence donnée (Hz) sur la piste spécifiée.

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

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

Joue une note par son nom musical.

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

synth.stopNote(noteId)

Arrête une note spécifique avec son enveloppe de relâchement. Utilisez l'identifiant de note renvoyé par playNote() ou playNoteByName().

synth.stopAllNotes()

Arrête immédiatement toutes les notes actives sur toutes les pistes.

Préréglages et instruments

synth.playPreset(name)

Charge et lit un préréglage SFX intégré en un seul appel. Idéal pour les effets sonores de jeux.

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

Préréglages SFX disponibles (10)

synth.loadPreset(name)

Charge la configuration d'un préréglage (forme d'onde, enveloppe, effets) sur une piste sans la lire. Utile pour configurer une piste avant de déclencher manuellement des notes.

synth.loadInstrument(name, trackIndex) → boolean

Charge un préréglage d'instrument complet sur la piste spécifiée, en configurant la forme d'onde, l'enveloppe, le vibrato et la modulation.

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

Instruments disponibles (12)

Configuration de piste

synth.updateTrack(trackIndex, settings)

Met à jour une ou plusieurs propriétés d'une piste. Les modifications s'appliquent en temps réel aux notes en cours de lecture.

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

Propriétés de la piste

Vous pouvez également définir directement les propriétés des objets de la piste :

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

Enveloppes (ADSR)

synth.updateEnvelope(trackIndex, settings)

Définit l'enveloppe d'amplitude d'une piste. Contrôle la façon dont les notes apparaissent, sont maintenues et s'éteignent.

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
});

Enveloppes par défaut

Vibrato

synth.updateVibrato(trackIndex, settings)

Configure la modulation de hauteur (vibrato) pour une piste.

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

Filtre

Chaque piste dispose d'un filtre optionnel permettant de modeler le spectre de fréquences du son.

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

Unison & Détunage

Empilez plusieurs oscillateurs désaccordés pour obtenir un son riche et ample. Indispensable pour les pads et les leads.

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

LFO (Tremolo et modulation de filtre)

Tremolo (LFO d'amplitude)

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

LFO de filtre

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

Prise en charge MIDI

synth.enableMIDI(options) async→ inputNames[]

Active l'entrée MIDI à partir des contrôleurs connectés. Renvoie un tableau contenant les noms des périphériques d'entrée MIDI détectés.

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 */ }
});

Options

CC MIDI pris en charge

synth.disableMIDI()

Désactive l'entrée MIDI et arrête toutes les notes MIDI maintenues.

synth.setMIDITrack(trackIndex)

Modifie la piste qui reçoit l'entrée MIDI.

synth.setMIDIChannel(ch)

Définit le filtre de canal MIDI (0 = tous les canaux).

synth.isMIDIEnabled() → booléen

Indique si le MIDI est actuellement actif.

Données du visualiseur

synth.getWaveformData() → Uint8Array

Renvoie les données de forme d'onde dans le domaine temporel pour dessiner des visualisations de type oscilloscope. Les valeurs vont de 0 à 255 (128 = centre).

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

Renvoie les données du domaine fréquentiel (FFT) pour les visualisations de spectre. Les valeurs vont de 0 à 255.

synth.setMasterVolume(value)

Définit le volume de sortie principal (0-1).

synth.getMasterVolume() → nombre

Renvoie le volume principal actuel.

synth.resetToDefaults()

Réinitialise toutes les pistes, les enveloppes et le vibrato à leurs valeurs par défaut.

Méthodes statiques

ChiptuneSynth.noteToFrequency(note, octave) statique→ nombre

Convertit un nom de note et une octave en fréquence en Hz.

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

ChiptuneSynth.midiToFrequency(midi) statique→ nombre

Convertit un numéro de note MIDI (0-127) en fréquence en Hz.

ChiptuneSynth.frequencyToMidi(freq) statique→ nombre

Convertit une fréquence en numéro de note MIDI le plus proche.

ChiptuneSynth.getPresetNames() statique→ chaîne[]

Renvoie un tableau contenant tous les noms de préréglages SFX disponibles.

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

ChiptuneSynth.getInstrumentNames() statique→ chaîne[]

Renvoie un tableau contenant tous les noms de préréglages d'instruments disponibles.

ChiptuneSynth.getInstruments() statique→ objet

Renvoie un objet indexé par nom d'instrument, chaque valeur contenant la définition complète (paramètres de piste, enveloppe, vibrato, filtre, etc.).

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'

Création d'instruments personnalisés

Vous pouvez créer vos propres instruments en combinant les paramètres de piste, les enveloppes, le vibrato et les filtres. Voici comment créer des sons à partir de zéro.

Son personnalisé de base

Configurez une piste manuellement, puis jouez des notes dessus :

// 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);

Effets sonores personnalisés (de type préréglage)

Reproduisez le motif prédéfini : configurez une piste, jouez une note et laissez l'enveloppe s'occuper du reste :

// 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!

Instrument riche avec effets

Combinez plusieurs fonctionnalités pour créer des instruments expressifs :

// 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);

Son multicouche

Superposez plusieurs pistes pour créer des sons complexes :

// 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);
}

Modèle d'objet d'instrument réutilisable

Organisez vos instruments personnalisés sous forme d'objets de configuration :

// 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);

Valeurs par défaut

Paramètres par défaut des pistes

Remarque sur l'architecture

L'gainNodee par note ne gère que l'enveloppe ADSR (normalisée 0→1→sustain). Le volume de la piste est contrôlé par un nœud d'_trackGains[] distinct. Cette architecture permet de modifier les paramètres en temps réel sans interrompre le déroulement ADSR des notes jouées.