Documentación de la API

Referencia completa de ChiptuneSynth — Sintetizador chiptune de 4 pistas para la API de audio web

Inicio rápido

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

Constructor e inicialización

new ChiptuneSynth()

Crea una nueva instancia del sintetizador con 4 pistas (Lead, Bass, Drums, FX), envolventes predeterminadas y ajustes de vibrato vacíos.

const synth = new ChiptuneSynth();

synth.init() async

Inicializa el contexto de la API de Web Audio, crea la ganancia maestra, el analizador, los nodos de ganancia por pista y el búfer de ruido. Debe llamarse una vez antes de cualquier reproducción.

await synth.init();

synth.dispose()

Detiene todas las notas y cierra el AudioContext. Llámalo cuando hayas terminado de usar el sintetizador.

Métodos de reproducción

synth.playNote(frecuencia, índiceDePista, duración, horaDeInicio) → idDeNota

Reproduce una nota a la frecuencia dada (Hz) en la pista especificada.

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

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

Reproduce una nota por su nombre 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)

Detiene una nota específica con su envolvente de liberación. Utiliza el noteId devuelto por playNote() o playNoteByName().

synth.stopAllNotes()

Detiene inmediatamente todas las notas activas en todas las pistas.

Presets e instrumentos

synth.playPreset(name)

Carga y reproduce un preset SFX integrado en una sola llamada. Perfecto para efectos de sonido de juegos.

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

Presets de SFX disponibles (10)

synth.loadPreset(nombre)

Carga la configuración de un preset (forma de onda, envolvente, efectos) en una pista sin reproducirlo. Útil para configurar una pista antes de activar las notas manualmente.

synth.loadInstrument(nombre, índiceDePista) → booleano

Carga un preset de instrumento completo en la pista especificada, configurando la forma de onda, la envolvente, el vibrato y la modulación.

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

Instrumentos disponibles (12)

Configuración de pista

synth.updateTrack(trackIndex, settings)

Actualiza una o más propiedades de una pista. Los cambios se aplican en tiempo real a las notas que se están reproduciendo actualmente.

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

Propiedades de la pista

También puedes configurar directamente las propiedades de los objetos de la pista:

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

Envolventes (ADSR)

synth.updateEnvelope(trackIndex, settings)

Establece la envolvente de amplitud de una pista. Controla cómo las notas aparecen, se mantienen y desaparecen.

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

Envolventes predeterminadas

Vibrato

synth.updateVibrato(trackIndex, settings)

Configura la modulación de tono (vibrato) para una pista.

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

Filtro

Cada pista cuenta con un filtro opcional para modelar el contenido de frecuencia del sonido.

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

Unison y Desintonización

Apila varios osciladores desafinados para obtener un sonido denso y amplio. Imprescindible para pads y leads.

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

LFO (trémolo y modulación de filtro)

Tremolo (LFO de amplitud)

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

LFO de filtro

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

Compatibilidad con MIDI

synth.enableMIDI(options) async→ inputNames[]

Habilita la entrada MIDI desde controladores conectados. Devuelve una matriz con los nombres de los dispositivos de entrada MIDI detectados.

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

Opciones

CC MIDI compatible

synth.disableMIDI()

Desactiva la entrada MIDI y detiene todas las notas MIDI activas.

synth.setMIDITrack(trackIndex)

Cambia la pista que recibe la entrada MIDI.

synth.setMIDIChannel(ch)

Establece el filtro de canal MIDI (0 = todos los canales).

synth.isMIDIEnabled() → booleano

Devuelve si MIDI está activo actualmente.

Datos del visualizador

synth.getWaveformData() → Uint8Array

Devuelve datos de forma de onda en el dominio del tiempo para dibujar visualizaciones de tipo osciloscopio. Los valores oscilan entre 0 y 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

Devuelve datos del dominio de la frecuencia (FFT) para visualizaciones del espectro. Los valores oscilan entre 0 y 255.

synth.setMasterVolume(valor)

Establece el volumen de salida principal (0-1).

synth.getMasterVolume() → número

Devuelve el volumen maestro actual.

synth.resetToDefaults()

Restablece todas las pistas, envolventes y vibrato a sus valores predeterminados.

Métodos estáticos

ChiptuneSynth.noteToFrequency(note, octave) estático→ número

Convierte el nombre de una nota y la octava en frecuencia en Hz.

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

ChiptuneSynth.midiToFrequency(midi) estático→ número

Convierte un número de nota MIDI (0-127) en frecuencia en Hz.

ChiptuneSynth.frequencyToMidi(freq) estático→ número

Convierte una frecuencia en el número de nota MIDI más cercano.

ChiptuneSynth.getPresetNames() estático→ string[]

Devuelve una matriz con todos los nombres de presets de efectos de sonido disponibles.

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

ChiptuneSynth.getInstrumentNames() estático→ string[]

Devuelve una matriz con todos los nombres de presets de instrumentos disponibles.

ChiptuneSynth.getInstruments() estático→ objeto

Devuelve un objeto indexado por nombre de instrumento, donde cada valor contiene la definición completa (ajustes de pista, envolvente, vibrato, filtro, 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'

Creación de instrumentos personalizados

Puedes crear tus propios instrumentos combinando ajustes de pista, envolventes, vibrato y filtros. A continuación te explicamos cómo crear sonidos desde cero.

Sonido personalizado básico

Configura una pista manualmente y, a continuación, toca notas en ella:

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

Efectos de sonido personalizados (estilo preajuste)

Replica el patrón preestablecido: configura una pista, toca una nota y deja que la envolvente se encargue 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!

Instrumento rico con efectos

Combina múltiples funciones para crear instrumentos expresivos:

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

Sonido en capas multipista

Superpón varias pistas para crear sonidos complejos:

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

Patrón de objeto de instrumento reutilizable

Organiza tus instrumentos personalizados como objetos de configuración:

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

Valores predeterminados

Valores predeterminados de pista

Nota sobre la arquitectura

El «gainNode» por nota solo gestiona la envolvente ADSR (normalizada 0→1→sostenido). El volumen de la pista se controla mediante un nodo independiente de «_trackGains[]». Esta arquitectura permite cambios de parámetros en tiempo real sin interrumpir la secuencia ADSR de las notas que se están reproduciendo.