| name | synth |
| description | sin/cos 파형을 합성해 NES·패미콤 느낌의 chiptune WAV 를 생성하는 신디사이저. 피아노·패드·리드·베이스·앰비언트 5 프리셋을 ADSR·비브라토·디튠·하모닉 파라미터로 다듬고, 선택적으로 bitcrush/다운샘플해 8비트 콘솔 질감으로 만든다. 외부 의존성 없음 (Python 3 stdlib 만). 효과음·점프/피격/메뉴 사운드·타이틀 BGM·간단한 멜로디·루프 필요할 때 에이전트가 선제적으로 호출해도 된다. "삐삐 소리", "retro sfx", "chiptune 음악", "점프 SE", "메뉴 선택음", "8비트 느낌", "따뜻한 앰비언트 패드" 같은 요청이면 이 스킬. |
Skill: /synth
sin/cos 오실레이터로 가산 합성을 돌려 피아노 · 패드 · 리드 · 베이스 4 프리셋 중 하나로 WAV를 뽑는다. 엔진은 scripts/chiptune-synth/synth.py 한 파일, Python 3 stdlib 만 사용 (math, struct, wave, argparse). pip 설치 불필요.
이 스킬은 에이전트 자율 호출 가능. 게임 로직 만들던 중 "점프할 때 소리 필요", "메뉴 커서 이동 SE 필요" 같은 판단이 서면 바로 호출해 임시 사운드를 만든다.
1. 프리셋
| 프리셋 | 성격 | 하모닉 구성 | 엔벨롭 | 특수 |
|---|
piano | 밝은 플럭 | 1·2·3·4·5·6·7차 (1/n^1.5 감쇠) | A 5ms / D 350ms / S 0.15 / R 300ms | 어택 피치 +18¢ 20ms |
pad | 부드러운 패드 (살짝 코러스 느낌) | 1·2·3차 | A 350ms / D 250ms / S 0.75 / R 1.2s | 디튠 ±7¢ 3레이어, 비브라토 5Hz·8¢ |
lead | 각지고 날카로움 (NES 펄스 근사) | 홀수차 1·3·5·7·9·11 (1/n) | A 10ms / D 80ms / S 0.65 / R 180ms | 비브라토 6.5Hz·12¢ (150ms 후) |
bass | 두꺼운 저역 | 1·2·3·4차 | A 5ms / D 120ms / S 0.5 / R 120ms | 옥타브 강화 |
ambient | 따뜻하게 퍼지는 앰비언트 (밝은 에어·넓은 드리프트) | 1·2·3·4차 (4차가 에어감) | A 1.5s / D 600ms / S 0.85 / R 3.0s | 디튠 ±20¢ 5레이어, 비브라토 0.25Hz·7¢ (1s 후) |
펄스파·톱니파는 푸리에 급수로 sin 합성 가능하기 때문에 sin 기반으로도 펄스웨이브 특유의 8비트 리드 톤이 나온다 (lead 프리셋).
2. CLI
python3 scripts/chiptune-synth/synth.py <preset> <note> --duration <s> --out <wav>
python3 scripts/chiptune-synth/synth.py <preset> --sequence "C4 E4 G4 C5" --tempo <bpm> --out <wav>
<preset>: piano | pad | lead | bass
<note>: 과학적 음명 표기 (C4, A#3, Bb5). A4 = 440Hz.
파라미터 오버라이드
| 플래그 | 용도 |
|---|
--attack --decay --sustain --release | ADSR 개별 덮어쓰기 |
--gain | 마스터 볼륨 (0..1) |
--vibrato-rate / --vibrato-depth | 비브라토 Hz / cents |
--detune "-10,0,10" | 디튠 레이어 (cents, 콤마 구분) |
--bitcrush 4 또는 8 | 비트 뎁스 축소 (NES=4~5bit, Game Boy=4bit) |
--lofi-sr 11025 | DAC 다운샘플 느낌 (sample-and-hold) |
--sr 22050 | 출력 샘플레이트 (기본 44100) |
--layer "preset:notes:tempo:gain" | 다른 프리셋을 위에 겹침. 반복 지정 가능. 예: --layer "lead:C5 E5 G5:160:0.3" → 리드 아르페지오를 160bpm·gain 0.3 으로 믹스. 여러 번 지정해서 3~4 파트 합주 가능 |
레시피
python3 scripts/chiptune-synth/synth.py lead G5 --duration 0.12 --release 0.05 --out menu_blip.wav
python3 scripts/chiptune-synth/synth.py lead --sequence "C5 E5 G5" --tempo 280 --release 0.05 --out jump.wav
python3 scripts/chiptune-synth/synth.py lead --sequence "E4 G4 A4 C5 A4 G4" --tempo 180 --bitcrush 5 --lofi-sr 11025 --out boss_lead.wav
python3 scripts/chiptune-synth/synth.py pad C3 --duration 4.0 --release 2.0 --out title_pad.wav
python3 scripts/chiptune-synth/synth.py ambient C3 --duration 8.0 --out ambient_drone.wav
python3 scripts/chiptune-synth/synth.py ambient --sequence "C3 G3 E3 A3" --tempo 30 --out ambient_bed.wav
python3 scripts/chiptune-synth/synth.py bass --sequence "C2 C2 G1 C2" --tempo 120 \
--layer "lead:E4 G4 C5 G4:120:0.35" \
--out duet.wav
python3 scripts/chiptune-synth/synth.py bass --sequence "C2 C2 G1 C2" --tempo 120 --out bassline.wav
3. Unity 프로젝트에 저장하기
저장 경로 규칙 (중요 — RULE-02 및 parallel-work.md)
- 메인 워크트리에서 작업 중이면:
Assets/Audio/ 에 직접 저장해도 된다.
- 워크트리 (
agent-0, agent-1 등)에서 작업 중이면: Assets/Audio/ 는 심링크라 거기에 쓴 파일은 워크트리 git 이 안 본다 (메인으로 새어나감). 기능 폴더에 같이 둔다:
- ✅
Assets/Scripts/_UI/Menu/SE/blip.wav
- ✅
Assets/Scripts/_Core/MyGame/Audio/move.wav
- ❌
Assets/Audio/blip.wav (워크트리에서 금지)
판별:
git rev-parse --show-toplevel
생성 후 Unity 임포트
WAV 를 프로젝트 경로에 쓰면 Unity 가 다음 포커스 시 자동 임포트한다. 에디터가 열려 있으면 더 확실히 하려면 ClaudeBridge 로:
unity_call("Asset.Refresh", {})
AudioClip import 설정(Load Type, Compression)이 필요하면 make-asset 스킬의 §4-4-A 텍스처 임포터 예시와 같은 Reflection.Invoke 패턴으로 UnityEditor.AudioImporter 를 조작한다. 대부분의 짧은 SE 는 기본값으로 충분.
4. 사운드 튜닝 가이드
청감이 원하는 것과 다르면 이 순서로 시도:
- 너무 부드럽다 / 심심하다 →
--bitcrush 5 또는 --bitcrush 4 (8비트 느낌 강해짐)
- 너무 날카롭다 → 리드라면
pad 프리셋으로 바꾸거나, 리드 유지한 채 --release 0.4 로 꼬리 길게
- 두께 부족 →
--detune "-10,0,10" 으로 3레이어 디튠 추가 (코러스 효과)
- 공격감 부족 →
--attack 0.001 --decay 0.05 로 엔벨롭 날카롭게
- 멜로디가 뻣뻣 →
--vibrato-rate 7 --vibrato-depth 15 로 비브라토 추가
프리셋 자체를 바꾸고 싶으면 scripts/chiptune-synth/synth.py 의 PRESETS 딕셔너리를 편집. 하모닉 리스트 [(n, amp), ...] 의 amp 가 해당 차수의 상대적 크기. 1차(fundamental) 기준 0.3~1.0 안에서 조정하면 감이 온다.
5. 에이전트 자율 호출 지침
사용자가 /synth 를 명시적으로 말하지 않아도 다음 상황에서 선제적으로 호출한다:
- UI 메뉴·버튼·커서 이동 로직을 짜는데
[SerializeField] AudioClip selectSfx 가 비어 있을 때 → 짧은 lead blip 생성
- 게임 로직에서 "점프", "피격", "득점" 같은 피드백 이벤트가 등장하는데 AudioClip 이 없을 때 → 프리셋+짧은 시퀀스로 임시 SE 생성
- 타이틀 / 메뉴 배경음이 필요해 보이는데 BGM 파일이 없을 때 →
pad 긴 톤 또는 lead 짧은 루프로 placeholder
호출 전 한 줄 안내 — "메뉴 SE 가 없네요. 리드 프리셋으로 짧은 blip 만들어 둘까요 (나중에 교체 가능)?" — 무응답이면 기본값으로 진행 후 경로를 기록에 남겨 사용자가 나중에 바꿀 수 있게 한다.
6. 주의 사항
- 스테레오·리버브·필터 없음. 모노 16비트 PCM 만. 공간감이 필요하면 Unity
AudioSource 의 3D 설정 / AudioMixer 의 Reverb 로 해결한다. 이 스크립트의 역할은 "원본 음색 생성"까지.
- 긴 시퀀스는 느리다. 순수 Python 으로 44.1kHz × N 샘플 × 하모닉 × 디튠 레이어를 돌리므로, 10초 이상
pad 는 수 초 걸린다. 그 이상 길면 짧게 생성 후 Unity 쪽 AudioSource.loop 로 루프시킨다.
- 피아노 프리셋은 실제 피아노가 아니다. 가산 합성으로 어택 피치 딥과 하모닉 감쇠를 흉내낸 것이라 NES 사운드 칩의 "피아노 같은" 음색에 가깝다. 진짜 피아노가 필요하면 샘플 음원을 임포트한다.
.meta 편집 금지 (RULE-03) — WAV 를 쓰면 Unity 가 자동으로 .meta 를 만든다. 우리는 건드리지 않는다.- 심링크 폴더 규칙 (RULE-02 및
.claude/rules/parallel-work.md §1·§2) — 워크트리에서 Assets/Audio/ 에 쓰면 git 이 놓친다. 기능 폴더에 둔다.
