Ardule Drum Pattern System 설계서

최종 작성일: — Haeyoung Jeong, 2025/10/22 08:45

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

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 본체는 이를 직접 읽어 루프 재생하는 구조로 변경되었다.

동작 흐름

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

기본 단위: 2마디(4/4) = 32스텝 (16분음표 기준)

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

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

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

패턴 파일 구성 요소

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

APD 헤더 구조 (예시)

struct PatternHeader {
  uint8_t  genre_id;
  uint16_t bpm;
  uint8_t  delta_count;
  // 이어서 (slot_index, midi_note) * delta_count
};

로컬 노트맵/장르 프로필 구조 (예시)

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" ...
};

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

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

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

MIDI Type-0 파일을 사전에 변환하여 `.APD`로 저장한다.

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

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을 방해하지 않도록 한다.

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

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

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

모드 순환: Pattern → Kit → BPM → Play → Pattern

예시 표시:

P12: Latin A
Latin 118 BPM

조작:

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

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

savePattern(base, header, deltas, steps);
loadPattern(base);

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

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

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

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 (무음)

악센트(Accent) 표현 규칙

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

• `.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` 실행 포맷으로 자동 변환된다.

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

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

(C) 2025 Haeyoung Jeong — Ardule Project

• drum_pattern_format_v1_1_with_diagram.docx ← 위 본문보다 이전에 작성되었음
• apt_v2.1_specification.docx
• adx_tools.zip