Документация по API

Полное руководство по ChiptuneSynth — 4-дорожечному чиптюн-синтезатору для Web Audio API

Быстрый старт

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

Конструктор и инициализация

new ChiptuneSynth()

Создает новый экземпляр синтезатора с 4 дорожками (Lead, Bass, Drums, FX), огибающими по умолчанию и пустыми настройками вибрато.

const synth = new ChiptuneSynth();

synth.init() async

Инициализирует контекст Web Audio API, создает мастер-гейн, анализатор, узлы гейна для каждой дорожки и буфер шума. Должно быть вызвано один раз перед любым воспроизведением.

await synth.init();

synth.dispose()

Останавливает все ноты и закрывает AudioContext. Вызывайте, когда закончите работу с синтезатором.

Методы воспроизведения

synth.playNote(частота, индекс_дорожки, продолжительность, время_начала) → noteId

Воспроизводит ноту с заданной частотой (Гц) на указанной дорожке.

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

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

Воспроизводит ноту по ее музыкальному имени.

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

synth.stopNote(noteId)

Останавливает конкретную ноту вместе с ее огибающей затухания. Используйте noteId, возвращаемый функциями playNote() или playNoteByName().

synth.stopAllNotes()

Немедленно останавливает все активные ноты на всех дорожках.

Пресеты и инструменты

synth.playPreset(name)

Загружает и воспроизводит встроенный пресет SFX за один вызов. Идеально подходит для звуковых эффектов в играх.

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

Доступные пресеты SFX (10)

synth.loadPreset(name)

Загружает настройки пресета (форма волны, огибающая, эффекты) на дорожку, не воспроизводя его. Полезно для настройки дорожки перед запуском нот вручную.

synth.loadInstrument(name, trackIndex) → boolean

Загружает полный пресет инструмента на указанный трек, настраивая форму волны, огибающую, вибрато и модуляцию.

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

Доступные инструменты (12)

Настройка трека

synth.updateTrack(trackIndex, settings)

Обновляет одно или несколько свойств дорожки. Изменения применяются в реальном времени к текущим нотам.

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

Свойства дорожки

Вы также можете напрямую настроить свойства объектов дорожки:

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

Огибающие (ADSR)

synth.updateEnvelope(trackIndex, settings)

Устанавливает огибающую амплитуды для дорожки. Управляет тем, как ноты затихают, звучат и затихают.

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

Огибающие по умолчанию

Вибрато

synth.updateVibrato(trackIndex, settings)

Настраивает модуляцию высоты тона (вибрато) для дорожки.

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

Фильтр

Каждый трек имеет опциональный фильтр для формирования частотного состава звука.

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

Унисон и расстройка

Сложите несколько расстроенных генераторов для получения плотного, широкого звучания. Незаменимо для пэдов и лидов.

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

LFO (тремоло и модуляция фильтра)

Тремоло (LFO амплитуды)

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

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

synth.enableMIDI(options) async→ inputNames[]

Включает ввод MIDI с подключенных контроллеров. Возвращает массив имен обнаруженных устройств ввода MIDI.

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

Параметры

Поддерживаемые MIDI CC

synth.disableMIDI()

Отключает MIDI-вход и останавливает все удерживаемые MIDI-ноты.

synth.setMIDITrack(trackIndex)

Изменяет дорожку, принимающую MIDI-вход.

synth.setMIDIChannel(ch)

Устанавливает фильтр MIDI-каналов (0 = все каналы).

synth.isMIDIEnabled() → boolean

Возвращает, активен ли MIDI в данный момент.

Данные визуализатора

synth.getWaveformData() → Uint8Array

Возвращает данные формы волны во временной области для рисования визуализаций в стиле осциллографа. Значения варьируются от 0 до 255 (128 = центр).

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

Возвращает данные в частотной области (FFT) для визуализации спектра. Значения находятся в диапазоне от 0 до 255.

synth.setMasterVolume(value)

Устанавливает общую громкость выхода (0–1).

synth.getMasterVolume() → число

Возвращает текущую громкость главного выхода.

synth.resetToDefaults()

Сбрасывает все дорожки, огибающие и вибрато к значениям по умолчанию.

Статические методы

ChiptuneSynth.noteToFrequency(note, octave) статический→ число

Преобразует название ноты и октаву в частоту в Гц.

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

ChiptuneSynth.midiToFrequency(midi) статический→ число

Преобразует номер MIDI-ноты (0–127) в частоту в Гц.

ChiptuneSynth.frequencyToMidi(freq) статический→ число

Преобразует частоту в ближайший номер MIDI-ноты.

ChiptuneSynth.getPresetNames() статический→ string[]

Возвращает массив всех доступных имен пресетов SFX.

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

ChiptuneSynth.getInstrumentNames() static→ string[]

Возвращает массив всех доступных имен пресетов инструментов.

ChiptuneSynth.getInstruments() статический→ объект

Возвращает объект, индексируемый по имени инструмента, каждое значение которого содержит полное определение (настройки дорожки, огибающая, вибрато, фильтр и т. д.).

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'

Создание пользовательских инструментов

Вы можете создавать собственные инструменты, комбинируя настройки дорожек, огибающие, вибрато и фильтры. Вот как создавать звуки с нуля.

Базовый пользовательский звук

Настройте дорожку вручную, а затем сыграйте на ней ноты:

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

Пользовательские звуковые эффекты (в стиле пресетов)

Воспроизведите шаблон пресета — настройте дорожку, сыграйте ноту, а остальное доверьте огибающей:

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

Насыщенный инструмент с эффектами

Объедините несколько функций для создания выразительных инструментов:

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

Многодорожечный многослойный звук

Наслаивайте несколько дорожек для создания сложных звуков:

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

Шаблон повторно используемого инструментального объекта

Организуйте свои пользовательские инструменты в виде объектов конфигурации:

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

Значения по умолчанию

Настройки по умолчанию для дорожек

Примечание по архитектуре

gainNode, настраиваемый для каждой ноты, управляет только огибающей ADSR (нормированной 0→1→sustain). Громкость трека регулируется отдельным узлом _trackGains[]. Такая архитектура позволяет изменять параметры в реальном времени, не прерывая график ADSR воспроизводимых нот.