Documentação da API

Referência completa para o ChiptuneSynth — sintetizador chiptune de 4 faixas para a Web Audio API

Início 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);

Construtor e inicialização

new ChiptuneSynth()

Cria uma nova instância do sintetizador com 4 faixas (Lead, Bass, Drums, FX), envelopes padrão e configurações de vibrato vazias.

const synth = new ChiptuneSynth();

synth.init() async

Inicializa o contexto da API Web Audio, cria o ganho mestre, o analisador, os nós de ganho por faixa e o buffer de ruído. Deve ser chamado uma vez antes de qualquer reprodução.

await synth.init();

synth.dispose()

Interrompe todas as notas e fecha o AudioContext. Chame quando terminar de usar o sintetizador.

Métodos de reprodução

synth.playNote(frequência, índiceDaFaixa, duração, horaInicial) → idDaNota

Reproduz uma nota na frequência fornecida (Hz) na faixa especificada.

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

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

Reproduz uma nota pelo seu nome 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)

Interrompe uma nota específica com seu envelope de liberação. Use o noteId retornado por playNote() ou playNoteByName().

synth.stopAllNotes()

Interrompe imediatamente todas as notas ativas em todas as faixas.

Predefinições e instrumentos

synth.playPreset(name)

Carrega e reproduz uma predefinição de SFX integrada em uma única chamada. Perfeito para efeitos sonoros de jogos.

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

Predefinições de SFX disponíveis (10)

synth.loadPreset(nome)

Carrega a configuração de uma predefinição (forma de onda, envelope, efeitos) em uma faixa sem reproduzi-la. Útil para configurar uma faixa antes de acionar notas manualmente.

synth.loadInstrument(nome, índiceDaFaixa) → booleano

Carrega uma predefinição completa de instrumento na faixa especificada, configurando forma de onda, envelope, vibrato e modulação.

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

Instrumentos disponíveis (12)

Configuração da faixa

synth.updateTrack(índiceDaFaixa, configurações)

Atualiza uma ou mais propriedades de uma faixa. As alterações são aplicadas em tempo real às notas que estão sendo reproduzidas no momento.

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

Propriedades da faixa

Você também pode definir propriedades diretamente nos objetos da faixa:

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

Envelopes (ADSR)

synth.updateEnvelope(trackIndex, settings)

Define o envelope de amplitude para uma faixa. Controla como as notas entram, se mantêm e saem.

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

Envelopes padrão

Vibrato

synth.updateVibrato(índiceDaFaixa, configurações)

Configura a modulação de tom (vibrato) para uma faixa.

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

Filtro

Cada faixa possui um filtro opcional para moldar o conteúdo de frequência do som.

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

Uníssono e Desafinação

Empilhe vários osciladores desafinados para obter um som denso e amplo. Essencial para pads e leads.

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

LFOs (Tremolo e modulação de filtro)

Tremolo (LFO de amplitude)

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

LFO do filtro

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

Suporte a MIDI

synth.enableMIDI(options) async→ inputNames[]

Habilita a entrada MIDI de controladores conectados. Retorna uma matriz com os nomes dos 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 */ }
});

Opções

MIDI CC suportado

synth.disableMIDI()

Desativa a entrada MIDI e interrompe todas as notas MIDI mantidas.

synth.setMIDITrack(trackIndex)

Altera a faixa que recebe a entrada MIDI.

synth.setMIDIChannel(ch)

Define o filtro de canal MIDI (0 = todos os canais).

synth.isMIDIEnabled() → boolean

Retorna se o MIDI está ativo no momento.

Dados do visualizador

synth.getWaveformData() → Uint8Array

Retorna dados de forma de onda no domínio do tempo para desenhar visualizações no estilo osciloscópio. Os valores variam de 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

Retorna dados no domínio da frequência (FFT) para visualizações de espectro. Os valores variam de 0 a 255.

synth.setMasterVolume(valor)

Define o volume de saída principal (0-1).

synth.getMasterVolume() → número

Retorna o volume principal atual.

synth.resetToDefaults()

Redefine todas as faixas, envelopes e vibrato para seus valores padrão.

Métodos estáticos

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

Converte um nome de nota e uma oitava em frequência em Hz.

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

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

Converte um número de nota MIDI (0-127) em frequência em Hz.

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

Converte uma frequência no número de nota MIDI mais próximo.

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

Retorna uma matriz com todos os nomes de predefinições de efeitos sonoros disponíveis.

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

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

Retorna uma matriz com todos os nomes de predefinições de instrumentos disponíveis.

ChiptuneSynth.getInstruments() estático→ objeto

Retorna um objeto indexado pelo nome do instrumento, cada valor contendo a definição completa (configurações de faixa, envelope, 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'

Criação de instrumentos personalizados

Você pode criar seus próprios instrumentos combinando configurações de faixa, envelopes, vibrato e filtros. Veja como construir sons do zero.

Som personalizado básico

Configure uma faixa manualmente e, em seguida, toque notas nela:

// 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 personalizado (estilo predefinido)

Reproduza o padrão predefinido — configure uma faixa, toque uma nota e deixe o envelope cuidar do 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 com efeitos

Combine vários recursos para criar instrumentos expressivos:

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

Som em camadas com várias faixas

Sobreponha várias faixas para sons complexos:

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

Padrão de objeto de instrumento reutilizável

Organize seus instrumentos personalizados como objetos de configuração:

// 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 Padrão

Padrões da faixa

Nota sobre a arquitetura

O "gainNode" por nota lida apenas com o envelope ADSR (normalizado 0→1→sustentação). O volume da faixa é controlado por um nó "_trackGains[]" separado. Essa arquitetura permite alterações de parâmetros em tempo real sem interromper a sequência ADSR das notas tocadas.