====== Ardule Drum Pattern System 설계서 ======
**최종 작성일:** — Haeyoung Jeong, 2025/10/22 08:45  

{{:nano_ardule_midi_controller:drum_patterm_grid.png?400|}}


그려놓고 보니 전혀 말이 되지 않는 드럼 패턴이다.

----

===== 1. 목적(Goal) =====
Arduino Nano 기반의 **Ardule Drum Pattern System**은 SD 카드에 저장된 **2마디(2-bar) 단위의 드럼 패턴 데이터 파일**을 읽어 반복 재생하는 시스템이다.

  * MIDI 파일을 직접 파싱하지 않고, 사전 변환된 **Ardule Pattern Data (.APD)** 또는 **Drum Pattern (.DRP)** 파일을 이용한다.
  * APD는 **2바이트/스텝 구조**의 메모리 효율적 포맷으로, 2마디(4/4 기준 32스텝) 패턴을 완전하게 표현한다.
  * LCD UI를 통해 패턴, 드럼킷, BPM을 선택하고 루프 재생한다.
  * 장르별 프로필(12슬롯 노트맵) + 델타 구조로 다양한 악기 조합을 유연하게 지원한다.
  * 텍스트 파일(Ardule Pattern Text or Ardule Patterm eXtended Text, .APT or .APX)을 이용하여 데이터 입력을 쉽게 할 수 있다.

> ※ 2025년 10월 21일 이후, SD 카드에는 MIDI 파일 대신 **양자화·인코딩된 2마디 패턴 파일(.APD)**을 저장하고, Ardule 본체는 이를 직접 읽어 루프 재생하는 구조로 변경되었다.

----

===== 2. 시스템 개요(System Overview) =====
^ 항목 | 사양 |
| MCU | Arduino Nano (ATmega328P, 16 MHz, Flash 32KB, SRAM 2KB, EEPROM 1KB) |
| 표시 | 16×2 I²C LCD (0x27/0x3F) |
| 입력 | 최소한 3개의 버튼 (UP / DOWN / SELECT, INPUT_PULLUP), 인코더는 옵션 |
| MIDI OUT | DIN-5, 31,250 bps (HW UART 또는 SoftwareSerial) |
| 저장소 | SD 카드(FAT), EEPROM/PROGMEM |
| 대상 음원 | GM/GS 호환 모듈(표준/록/재즈/라틴/전자/808 등) *Dream SAM9703 + GMS963200-B 사운드 롬*을 사용한 도터보드 활용에 최우선 적용 |


**동작 흐름**
  - SD 카드에서 APD/DRP 파일 선택
  - 파일의 헤더 파싱 및 장르 프로필 로드
  - 로컬 노트맵 생성 및 델타 적용
  - 32스텝 스텝워드(2B/스텝) 로딩
  - LCD UI로 패턴/BPM/킷 선택 후 루프 재생

----

===== 3. 데이터 포맷(Data Format) =====
**기본 단위:** 2마디(4/4) = 32스텝 (16분음표 기준)

스텝 워드 구조 (16bit = 2B):

<code>
+----------------+----------------+----------------+
| bit15..12      | bit11..10      | bit9..0        |
| Reserved       | Accent(2bit)   | Note Mask(≤12) |
+----------------+----------------+----------------+
</code>

**예시:** %%0x0405%% → Accent=%%01%% (L1=%%64%%), NoteMask=%%0b0000000101%% (슬롯0,2 활성화)

**패턴 파일 구성 요소**
  * 스텝 본체: %%32 × 2B = 64B%%
  * 로컬 노트맵: 최대 %%12B%% (slot → MIDI note)
  * 패턴 헤더:
    * 장르 ID, BPM, 델타 개수 및 데이터
    * (선택) 변형 슬롯, 페이지 스위치, 예외 이벤트
  * 파일 확장자: %%*.APD%% 또는 %%*.DRP%%

**APD 헤더 구조 (예시)**
<code>
struct PatternHeader {
  uint8_t  genre_id;
  uint16_t bpm;
  uint8_t  delta_count;
  // 이어서 (slot_index, midi_note) * delta_count
};
</code>

**로컬 노트맵/장르 프로필 구조 (예시)**
<code>
struct GenreProfile {
  uint8_t kit_id;        // 권장 GS/GM 드럼킷
  uint8_t note_map[12];  // 기본 12슬롯
  uint8_t accent_lut[4]; // 예: {48, 64, 96, 112}
  char    name[12];      // "Latin", "Rock" ...
};
</code>

----

===== 4. 장르 프로필 + 델타 구조(Genre Profile + Delta) =====
장르별로 자주 쓰는 12슬롯 노트맵을 **PROGMEM**에 저장하고, 패턴별 변동만 델타로 기술한다.  
→ 장르별 악기 차이를 몇 바이트의 델타로 처리하므로, 평균 헤더 크기가 3~12B 수준에 머문다.  

예) Latin 장르에서 Conga → Agogo로 바뀐 경우, (slot5, 67) 1개만 델타로 기록.

----

===== 5. 메모리 전략(Memory Strategy) =====
* 로컬 노트맵(12슬롯): 패턴별 실제 사용 악기만 채택 (2B/스텝 유지)
* 예외 이벤트(13슬롯 이상): `(step, note, accent)` 2~3B/건
* 페이지드 키트: 드물게 페이지 전환(1B/회)
* 변형 슬롯(선택): Crash/China/Splash 등 1슬롯 4변형(2bit)
* 평균 용량: 약 80~100B/패턴

----

===== 6. SD→APD 변환 파이프라인 (PC 전처리) =====
MIDI Type-0 파일을 사전에 변환하여 `.APD`로 저장한다.

  - 헤더 파싱: `ppqn`, Tempo(0x51), TimeSig(0x58)
  - 2마디 틱 범위 계산: `2 bars = 8 * ppqn`
  - 채널 10 NoteOn 이벤트 추출
  - 32스텝 양자화: `ticks_per_step = ppqn/4`
  - 상위 10~12개 노트 선택 → 슬롯 매핑
  - 벨로시티 → 4단계 Accent 매핑 (48/64/96/112)
  - 스텝 워드 구성: NoteMask + Accent
  - 장르 프로필 선택 및 델타 계산
  - `.APD` 헤더 + 노트맵 + 스텝 데이터로 저장

----

===== 7. 패턴 파일 검증 단계 (Pattern File Validation) =====
APD 파일은 단순 구조이지만, 로딩 시 다음 항목을 확인한다.

1. 파일 헤더 매직(`"APD"` or `"DRP"`) 존재 여부  
2. 패턴 길이(32스텝 = 64B) 일치 여부  
3. 장르 ID / BPM 유효성  
4. 델타 개수(0–12) 범위 확인  
5. 로컬 노트맵과 실제 스텝 마스크 일관성  
6. Accent 값이 0–3 범위인지 검증  

**오류 처리**
  * 구조 이상: `ERR_BAD_FORMAT`
  * 데이터 불일치: `WARN_CORRUPT`
  * 정상: `OK_PATTERN_READY`

> 검증은 **재생 중이 아닐 때** 수행해야 하며, SD I/O 중단이 ISR을 방해하지 않도록 한다.

----

===== 8. 재생 엔진(Playback Engine) =====
**타이밍:** 16분음표 틱(ms) = %%60000 / (BPM × 4)%%  
**권장 구현:** Timer1 CTC ISR로 스텝 틱 발생 → 메인 루프는 UI/입출력 전용

<code>
ISR(TIMER1_COMPA_vect){
  uint16_t w   = stepWords[step];
  uint8_t  acc = (w >> 10) & 0x03;
  uint16_t mask=  w        & 0x03FF;

  // 예: {48, 64, 96, 112}
  uint8_t vel = ACC_LUT[acc];

  for(uint8_t s = 0; s < 12; s++){
    if(mask & (1 << s)){
      uint8_t n = noteMap[s];
      if(n){ // 0은 비활성
        // ch10 Note On
        Serial.write(0x90 | 9);
        Serial.write(n);
        Serial.write(vel);
      }
    }
  }

  step = (step + 1) % 32;
}
</code>

  * **스윙/트리플렛:** ISR 비교값이나 다음 틱의 오프셋을 가변 적용(데이터 증가 없이 재생 파라미터로 처리).


----

===== 9. UI 설계(16×2 LCD) =====
모드 순환: **Pattern → Kit → BPM → Play → Pattern**

예시 표시:

<code>
P12: Latin A
Latin 118 BPM
</code>

조작:
  * UP/DOWN: 값 변경  
  * SELECT: 모드 전환 / 재생 토글  
  * 장르 선택 시 즉시 미리듣기 가능

----

===== 10. 저장소 설계 =====  
  * **SD 카드:** `.APD` 또는 `.DRP` 파일 저장  
  * **EEPROM (1KB):** 사용자 패턴 8~12개 영구 저장  
  * **PROGMEM:** 기본 장르 프로필 및 내장 패턴

<code cpp>
savePattern(base, header, deltas, steps);
loadPattern(base);
</code>

----

===== 11. APT 파일 (Ardule Pattern Text) =====
**목적(Purpose)**  
APT 파일은 `.APD`의 내용을 **사람이 읽고 편집하기 쉬운 2차원 그리드 형태**로 표현한 텍스트 포맷이다.  
`.APD`가 스텝(시간) 중심의 이진 구조라면, `.APT`는 **각 악기(파트)** 를 행(row)으로, **시간(스텝)** 을 열(column)로 표현한다.  
즉, 사람이 직접 리듬 구조를 시각적으로 파악하거나 수정하기 위한 **시각화/편집용 포맷**이다.

**파일 확장자:** `.APT`  
**표준 헤더 문자열:** `# Ardule Pattern Text v2.1`

**기본 구조(Basic Layout) - 8 비트 Rock 예시**

<code>
STEPS=32 BPM=109 MIDI_CH=9 TIME_SIG=4/4
SLOTS=Kick:36,Snare:38,CHH:42,OHH:46,Crash:49,HighTom:50,LowTom:45,Ride:51
Ride:     .... .... .... .... || .... .... .... ....
HighTom:  .... .... .... .... || .... .... .... ....
Crash:    .... .... .... .... || .... .... .... ....
OHH:      .... .... .... .... || .... .... .... ....
LowTom:   .... .... .... .... || .... .... .... ....
CHH:      o.o. o.o. o.o. o.o. || o.o. o.o. o.o. o.o.
Snare:    .... o... .... o... || .... o... .... o...
Kick:     o.o. ..o. o.o. ..o. || o.o. ..o. o.o. ..o.

# row = 파트(악기), column = 스텝(시간)
# 32스텝 = 2마디 (4/4 × 2)
# 기호(대소문자 무시):
#   ^   = ACC3 (강박)
#   X/x = ACC2 (중간강)
#   O/o = ACC1 (약박)
#   .   = ACC0 (무음)

</code>

**악센트(Accent) 표현 규칙**
  * 각 문자는 대소문자를 구별하지 않는다. (`X`=`x`, `O`=`o`)
  * 4단계 악센트(ACC=3~0)는 다음과 같이 매핑된다.

^ 기호(Symbol) ^ ACC ^ Velocity 예시 ^ 의미(Meaning) ^
| ^ | 3 | 112 | 강박 (forte) |
| X / x | 2 | 96  | 중간강 (mezzo forte) |
| O / o | 1 | 64  | 약박 (mezzo piano) |
| -     | 0 | — | 무음 (rest) |

  * `.APD` 변환 시 각 스텝의 전체 ACC는 그 스텝 내 모든 슬롯의 **최대 ACC**로 계산된다.

**변환 규칙(Conversion Notes)**
  * 한 행(row)은 하나의 악기 슬롯을 의미한다.  
  * 열(column)은 시간(스텝)이며, 일반적으로 32열 = 2마디(4/4 기준).  
  * `[NOTE MAP]` 블록은 `.APD`의 로컬 노트맵과 동일하다.  
  * 주석(`#`)은 변환 시 무시된다.  
  * APT → APD 변환기는 각 기호를 해석하여 bitmask + 공통 ACC 구조로 압축한다.

**요약(Summary)**  
APT는 사람이 직관적으로 읽고 편집할 수 있는 드럼 패턴 표현 형식으로,  
각 악기별 행(row)과 32스텝의 열(column)로 구성된다.  
기호(`X/x`, `O/o`, `.`, `-`)를 통해 강약(Accent)을 표현하며,  
변환기(`apt2apd.py`)를 통해 `.APD` 실행 포맷으로 자동 변환된다.

----



===== 12. 향후 확장 =====
  * **Song Mode:** 다수 패턴 체인 구성  
  * **스윙/트리플렛 UI:** 실시간 가감  
  * **SD 브라우저:** 패턴 검색, 미리듣기  
  * **패턴 편집 기능:** 간단한 스텝 수정 및 저장  
  * **MCU 확장:** ESP32/Teensy 기반으로 SD 스트리밍 지원

----

===== 13. 요약 =====
Ardule Drum Pattern System은 **APD(Ardule Pattern Data)** 파일을 기반으로 동작하는 32스텝 드럼 루퍼이다.  
장르 프로필과 델타 구조를 활용하여 GM/GS 드럼킷의 폭넓은 호환성을 유지하면서도, Nano 환경에서 실시간 재생이 가능한 최소한의 데이터 구조를 갖춘다.  
SD→APD 변환 파이프라인을 통해 PC에서 사전 처리된 데이터를 안정적으로 로드하고, LCD UI를 통해 간편하게 패턴, 킷, BPM을 제어할 수 있다.

----

**(C) 2025 Haeyoung Jeong — Ardule Project**


  * {{ :nano_ardule_midi_controller:drum_pattern_format_v1_1_with_diagram.docx |}} <- 위 본문보다 이전에 작성되었음
  * {{ :nano_ardule_midi_controller:apt_v2.1_specification.docx |}}
  * {{ :nano_ardule_midi_controller:adx_tools.zip |}}