Documentazione API

Riferimento completo per ChiptuneSynth — Sintetizzatore chiptune a 4 tracce per l'API Web Audio

Guida rapida

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

Costruttore e inizializzazione

new ChiptuneSynth()

Crea una nuova istanza del sintetizzatore con 4 tracce (Lead, Bass, Drums, FX), inviluppi predefiniti e impostazioni di vibrato vuote.

const synth = new ChiptuneSynth();

synth.init() async

Inizializza il contesto dell'API Web Audio, crea il guadagno master, l'analizzatore, i nodi di guadagno per traccia e il buffer di rumore. Deve essere chiamato una volta prima di qualsiasi riproduzione.

await synth.init();

synth.dispose()

Interrompe tutte le note e chiude l'AudioContext. Da chiamare quando hai finito con il sintetizzatore.

Metodi di riproduzione

synth.playNote(frequenza, indice traccia, durata, ora di inizio) → id nota

Riproduce una nota alla frequenza specificata (Hz) sulla traccia indicata.

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

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

Riproduce una nota in base al suo nome musicale.

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

synth.stopNote(noteId)

Interrompe una nota specifica con la sua inviluppo di rilascio. Utilizza il noteId restituito da playNote() o playNoteByName().

synth.stopAllNotes()

Interrompe immediatamente tutte le note attive su tutte le tracce.

Preset e strumenti

synth.playPreset(name)

Carica e riproduce un preset SFX integrato in un'unica chiamata. Perfetto per gli effetti sonori dei giochi.

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

Preset SFX disponibili (10)

synth.loadPreset(nome)

Carica la configurazione di un preset (forma d'onda, inviluppo, effetti) su una traccia senza riprodurla. Utile per impostare una traccia prima di attivare le note manualmente.

synth.loadInstrument(name, trackIndex) → boolean

Carica un preset completo dello strumento sulla traccia specificata, configurando forma d'onda, inviluppo, vibrato e modulazione.

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

Strumenti disponibili (12)

Configurazione traccia

synth.updateTrack(trackIndex, settings)

Aggiorna una o più proprietà di una traccia. Le modifiche si applicano in tempo reale alle note attualmente in riproduzione.

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

Proprietà della traccia

È inoltre possibile impostare direttamente le proprietà sugli oggetti della traccia:

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

Involucri (ADSR)

synth.updateEnvelope(trackIndex, settings)

Imposta l'inviluppo di ampiezza per una traccia. Controlla come le note entrano in scena, si mantengono e svaniscono.

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

Involucri predefiniti

Vibrato

synth.updateVibrato(trackIndex, settings)

Configura la modulazione dell'intonazione (vibrato) per una traccia.

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

Filtro

Ogni traccia dispone di un filtro opzionale per modellare il contenuto in frequenza del suono.

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

Impila più oscillatori detunati per ottenere un suono corposo e ampio. Indispensabile per pad e lead.

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

LFO (Tremolo e modulazione del filtro)

Tremolo (LFO di ampiezza)

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

LFO del filtro

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

Supporto MIDI

synth.enableMIDI(options) async→ inputNames[]

Abilita l'input MIDI dai controller collegati. Restituisce un array dei nomi dei dispositivi di input MIDI rilevati.

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

Opzioni

MIDI CC supportati

synth.disableMIDI()

Disabilita l'input MIDI e interrompe tutte le note MIDI tenute.

synth.setMIDITrack(trackIndex)

Cambia la traccia che riceve l'input MIDI.

synth.setMIDIChannel(ch)

Imposta il filtro del canale MIDI (0 = tutti i canali).

synth.isMIDIEnabled() → booleano

Restituisce se il MIDI è attualmente attivo.

Dati del visualizzatore

synth.getWaveformData() → Uint8Array

Restituisce i dati della forma d'onda nel dominio del tempo per disegnare visualizzazioni in stile oscilloscopio. I valori vanno da 0 a 255 (128 = centro).

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

Restituisce i dati nel dominio della frequenza (FFT) per le visualizzazioni dello spettro. I valori vanno da 0 a 255.

synth.setMasterVolume(valore)

Imposta il volume di uscita principale (0-1).

synth.getMasterVolume() → numero

Restituisce il volume master corrente.

synth.resetToDefaults()

Ripristina tutti i tracciati, gli inviluppi e il vibrato ai valori predefiniti.

Metodi statici

ChiptuneSynth.noteToFrequency(note, octave) statico→ numero

Converte il nome di una nota e l'ottava in frequenza in Hz.

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

ChiptuneSynth.midiToFrequency(midi) statico→ numero

Converte un numero di nota MIDI (0-127) in frequenza in Hz.

ChiptuneSynth.frequencyToMidi(freq) statico→ numero

Converte una frequenza nel numero di nota MIDI più vicino.

ChiptuneSynth.getPresetNames() statico→ string[]

Restituisce un array contenente tutti i nomi dei preset SFX disponibili.

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

ChiptuneSynth.getInstrumentNames() statico→ string[]

Restituisce un array contenente tutti i nomi dei preset di strumenti disponibili.

ChiptuneSynth.getInstruments() statico→ oggetto

Restituisce un oggetto con chiave del nome dello strumento, dove ogni valore contiene la definizione completa (impostazioni della traccia, inviluppo, vibrato, filtro, ecc.).

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'

Creazione di strumenti personalizzati

È possibile creare strumenti personalizzati combinando impostazioni della traccia, inviluppi, vibrato e filtri. Ecco come costruire suoni da zero.

Suono personalizzato di base

Configura una traccia manualmente, quindi riproduci le note su di essa:

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

SFX personalizzato (stile preset)

Replica il pattern predefinito: configura una traccia, suona una nota e lascia che l'inviluppo si occupi del resto:

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

Strumento ricco con effetti

Combina più funzioni per ottenere strumenti espressivi:

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

Suono multitraccia a strati

Sovrapponi più tracce per ottenere suoni complessi:

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

Modello di oggetto strumentale riutilizzabile

Organizza i tuoi strumenti personalizzati come oggetti di configurazione:

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

Valori predefiniti

Impostazioni predefinite della traccia

Nota sull'architettura

L'gainNodee per nota gestisce solo l'inviluppo ADSR (normalizzato 0→1→sustain). Il volume della traccia è controllato da un nodo separato _trackGains[]. Questa architettura consente modifiche dei parametri in tempo reale senza interrompere la sequenza ADSR delle note in riproduzione.