API 문서

ChiptuneSynth에 대한 전체 참조 — Web Audio API용 4트랙 칩튠 신디사이저

빠른 시작

// 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(frequency, trackIndex, duration, startTime) → noteId

지정된 트랙에서 주어진 주파수(Hz)의 노트를 재생합니다.

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)

지정된 음표와 그 릴리스 엔벨로프를 중지합니다. playNote() 또는 playNoteByName()에서 반환된 noteId를 사용하십시오.

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() → number

현재 마스터 볼륨을 반환합니다.

synth.resetToDefaults()

모든 트랙, 엔벨로프 및 비브라토를 기본값으로 재설정합니다.

정적 메서드

ChiptuneSynth.noteToFrequency(note, octave) static→ number

음표 이름과 옥타브를 Hz 단위의 주파수로 변환합니다.

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

ChiptuneSynth.midiToFrequency(midi) static→ number

MIDI 노트 번호(0-127)를 Hz 단위의 주파수로 변환합니다.

ChiptuneSynth.frequencyToMidi(freq) static→ number

주파수를 가장 가까운 MIDI 음표 번호로 변환합니다.

ChiptuneSynth.getPresetNames() static→ string[]

사용 가능한 모든 SFX 프리셋 이름의 배열을 반환합니다.

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

ChiptuneSynth.getInstrumentNames() static→ string[]

사용 가능한 모든 악기 프리셋 이름의 배열을 반환합니다.

ChiptuneSynth.getInstruments() static→ object

악기 이름을 키로 하는 객체를 반환하며, 각 값에는 전체 정의(트랙 설정, 엔벨로프, 비브라토, 필터 등)가 포함됩니다.

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

사용자 정의 SFX (프리셋 스타일)

프리셋 패턴을 재현해 보세요 — 트랙을 구성하고, 음을 연주하면 나머지는 엔벨로프가 처리합니다:

// 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→서스테인)만 처리합니다. 트랙 볼륨은 별도의 '_trackGains[]' 노드로 제어됩니다. 이 아키텍처는 연주 중인 노트의 ADSR 일정을 방해하지 않고도 실시간으로 파라미터를 변경할 수 있게 해줍니다.