• BUILD_ID: ADT22-SPEC-20251116
• Status: Stable specification (Ardule Drum Pattern Player v2.3 / v2.4 기준)
• First published: 2025-11-16
• Scope: ADT v2.2 텍스트 포맷 및 ADP v2.2 바이너리 캐시 생성 기준

Ardule Drum Pattern System에서 사용하는 2-bar 드럼 패턴의 텍스트 표현 포맷이다. ADT v2.2는 ADP v2.2 바이너리 캐시 포맷과 1:1 대응되며, 사람이 읽고 편집하기 쉬운 것을 목표로 한다.

드럼 머신이 출현하면서 드럼 연주 패턴을 그리드 형태로 표현하는 것은 매우 자연스러운 일이 되었다. ADT는 이를 텍스트로 표현한 것에 해당한다. 다음 자료의 출처인 단행본(260 Drum Machine Patterns)을 스캔한 PDF 파일은 인터넷을 잘 뒤지면 나온다. MIDI 파일로 만들어 놓은 것도 있다!(Cakewalk discussion) 아래 다이어그램에서 맨 위 row의 AC는 accent를 말하며, 특정 스텝에 전부 작용한다. 전통적인 그리드 포맷에서 각 row는 악기(slot)에 해당하지만, ADT에서는 이를 90도 돌려서 step으로 나타낼 수도 있다. 컴퓨터 입장에서는 이게 더 자연스럽다.

• 패턴 단위: 2마디(2 bars)를 기본 전제로 한다.
• TIME_SIG: 표기 및 UI용 박자표 정보. 실제 재생 타이밍 계산에는 관여하지 않는다.
• GRID / LENGTH: 패턴의 해상도(그리드)와 총 스텝 수를 정의한다.
  • 표준 조합(2-bar 기준, 4박자)
    • GRID=16, LENGTH=32 (4/4, 1 bar = 16 steps, 1 beat = 4 steps)
    • GRID=8T, LENGTH=24 (12/8, 1 bar = 12 steps, 1 beat = 3 steps)
    • GRID=16T, LENGTH=48 (4/4 triplet, 1 bar = 24 steps, 1 beat = 6 steps)
  • 다른 조합도 표현은 가능하지만, ADP v2.2 표준 플레이어와의 호환성은 보장하지 않는다.
• SLOTS: 동시에 사용할 드럼 슬롯(보통 12).
• ACC (accent level): 각 스텝의 타격 세기를 0~3의 4단계로 표현한다.
  • 0: rest (무음)
  • 1: 약박
  • 2: 중간강
  • 3: 강박
• ORIENTATION
  • STEP: 한 줄이 “한 스텝에서의 모든 슬롯 상태”를 의미한다.
  • SLOT: 한 줄이 “한 슬롯에서의 전체 스텝 패턴”을 의미한다.
  • ADP 변환 시에는 항상 STEP 오리엔테이션으로 정규화된다.

ADT v2.2 파일은 다음과 같이 구성된다.

• 첫 줄: 버전 코멘트(권장)
• 헤더: key=value 형식의 메타데이터
• SLOT 선언: SLOT0..SLOT11
• 본문 패턴: ORIENTATION에 따라 STEP 또는 SLOT 방식으로 표현된 문자 격자

예)

; ADT v2.2

NAME=ROCK01_MAIN
TIME_SIG=4/4
GRID=16
LENGTH=32
SLOTS=12
KIT=GM_STD
ORIENTATION=STEP

SLOT0=KK@36,KICK
SLOT1=SN@38,SNARE
SLOT2=CH@42,HH_CL
...
SLOT11=PH@44,HH_PED

X..X..X..X..X..X..X..X..
....X.......X..........
........................
...

모든 헤더 필드는 `KEY=VALUE` 형식이며, 대소문자를 구분하지 않는다. 미지의 키는 무시된다.

• 버전 코멘트
  • 첫 줄에 `; ADT v2.2`를 넣는 것을 권장한다.
  • 이것은 코멘트일 뿐, 별도의 `VERSION=` 필드는 존재하지 않는다.
• ORIENTATION 자동 판정 규칙
  • ORIENTATION이 누락되었을 때:
    • 본문에서 “길이 L, 폭 S”인 줄이 L개 존재하면 STEP으로 해석.
    • “길이 L, 폭 S”인 줄이 S개 존재하면 SLOT으로 해석.
    • 둘 다 아니면 STEP으로 가정한다.

각 슬롯은 MIDI 노트 번호, 약어, 이름으로 정의한다. 키 이름은 `SLOT0`부터 `SLOT11`까지를 표준으로 한다.

형식:

SLOTn=ABBR@NOTE[,NAME]

• `n`: 0~11 (정수)
• `ABBR`: 1~3자의 슬롯 약어 (예: KK, SN, CH)
• `NOTE`: 0~127 범위의 MIDI 노트 번호
• `NAME`: 인간이 읽기 위한 슬롯 이름(선택)

예)

SLOT0=KK@36,KICK
SLOT1=SN@38,SNARE
SLOT2=CH@42,HH_CL
SLOT3=OH@46,HH_OP
SLOT4=LT@45,TOM_L
SLOT5=MT@47,TOM_M
SLOT6=HT@50,TOM_H
SLOT7=RD@51,RIDE
SLOT8=CR@49,CRASH
SLOT9=RM@37,RIM
SLOT10=CL@39,CLAP
SLOT11=PH@44,HH_PED

• 어떤 SLOTn이 선언되지 않은 경우, 위의 GM 12슬롯 기본값으로 채운다.
• ADP v2.2 표준에서는 SLOTS=12, SLOT0~11이 모두 존재하는 것을 기본으로 한다.

헤더와 SLOT 선언 이후부터 파일 끝까지는 “본문 패턴” 영역이다. 빈 줄 또는 세미콜론(;)으로 시작하는 줄은 코멘트로 취급하여 무시한다.

본문에서 사용할 수 있는 문자는 다음과 같다.

• 공백, 탭, 기타 문자는 모두 무시된다(라인 정규화 과정에서 제거).
• 출력 시에는 `- . o X` 형태를 권장하지만, 파서는 위 문자 집합 전체를 허용한다.

• 한 줄이 “한 스텝에서의 모든 슬롯 상태”를 의미한다.
• 각 줄의 길이(유효 문자 수)는 `SLOTS`와 같아야 한다.
• 줄의 개수는 `LENGTH`와 같아야 한다.

예) GRID=16, LENGTH=32, SLOTS=12

X..X..X..X..X..X..X..X..
....X.......X..........
........................
...

• 위 예시에서 첫 줄은 step 0에 해당하며, 왼쪽에서 오른쪽으로 SLOT0→SLOT11 순서이다.
• 각 문자에 대응하는 ACC 값(0~3)이 ADP에 저장된다.

• 한 줄이 “한 슬롯에서의 전체 스텝 패턴”을 의미한다.
• 각 줄의 길이(유효 문자 수)는 `LENGTH`와 같아야 한다.
• 줄의 개수는 `SLOTS`와 같아야 한다.
• 줄의 순서는 SLOT0, SLOT1, …, SLOT(SLOTS-1)이다.

예) SLOTS=12, LENGTH=32

X..X..X..X..X..X..X..X..   ; SLOT0
....X.......X..........   ; SLOT1
........................   ; SLOT2
...

ADT v2.2 → ADP v2.2 변환기에서는 내부적으로 항상 STEP 오리엔테이션으로 변환한 뒤, ADP를 생성한다.

ADT v2.2는 여러 개의 패턴을 하나의 파일로 묶는 컨테이너 형식(ADX)을 지원한다.

• 파일 확장자: `.adx` 권장.
• 구조:
  • `[패턴 헤더 + SLOT 선언 + 본문]` 블록이 여러 개 연속.
  • 각 패턴은 `NAME=` 필드를 통해 고유한 이름을 가진다.
• 다른 파일에서 참조:
  • `FILE.ADX:SECTION` 형태로 참조.
  • 여기서 `SECTION`은 해당 패턴의 `NAME` 값이다.
    • 예: `ROCKPACK.ADX:ROCK01_MAIN`

ADT v2.2는 ADP v2.2 바이너리 캐시와 1:1 대응한다.

• GRID, LENGTH, SLOTS 정보는 ADP 헤더에 그대로 반영된다.
• 각 스텝의 ACC 값(0~3)과 슬롯 인덱스(0~11)가 ADP payload로 인코딩된다.
• ADP 헤더에는 다음과 같은 메타 필드가 추가된다.
  • PPQN: 재생 엔진 참고용 (표준 값 96)
  • SWING, TEMPO: 현재 버전의 ADT→ADP 변환기에서는 0으로 고정
  • CRC16: 정규화된 ADT 텍스트(ORIENTATION=STEP, SLOT0~11, 본문 STEP 격자)에 대한 CRC-CCITT(0x1021, init 0xFFFF)

ADT v2.2 사양에서는 SWING, TEMPO를 별도의 헤더 필드로 정의하지 않는다. 이 필드는 ADP v2.2 헤더 레벨에서만 존재하며, 현재 구현에서는 모두 0으로 저장된다.

ADT v2.2 파일을 생성하거나 읽을 때 다음을 확인한다.

• 첫 줄이 `; ADT v2.2`인지 확인 (권장, 필수는 아님).
• 헤더:
  • NAME, TIME_SIG, GRID, LENGTH, SLOTS, KIT 필드가 모두 존재하는가?
  • GRID는 16 / 8T / 16T 중 하나인가?
  • LENGTH는 24 / 32 / 48 중 하나인가? (표준 조합 권장)
  • SLOTS는 12인가? (ADP v2.2 표준 플레이어는 12를 가정)
• SLOT 선언:
  • SLOT0..SLOT11이 모두 정의되었는가?
  • 정의되지 않은 SLOTn은 GM 12슬롯 기본값으로 채워졌는가?
• 본문:
  • ORIENTATION=STEP인 경우
    • 본문 내 유효 라인 수가 LENGTH와 동일한가?
    • 각 라인의 유효 문자 수가 SLOTS와 동일한가?
  • ORIENTATION=SLOT인 경우
    • 본문 내 유효 라인 수가 SLOTS와 동일한가?
    • 각 라인의 유효 문자 수가 LENGTH와 동일한가?
  • 사용된 문자가 `- . o O x X ^` 범위를 벗어나지 않는가?
• 멀티-ADT(ADX)의 경우
  • 각 패턴이 고유한 NAME을 가지고 있는가?
  • 외부 참조 시 `FILE.ADX:NAME` 형식을 사용하는가?

이 사양은 현재 제공되는 `mid2adt.py` 및 `adt2adp.py` 스크립트와 호환되며, Ardule Drum Pattern Player v2.3/2.4에서 사용할 ADP v2.2 캐시 파일 생성의 기준으로 삼는다.

작업 환경: Windows PowerShell

work\
 ├─ 01_input_MID\   # 입력 MIDI 파일
 ├─ 02_MID\         # 2마디 MIDI 세그먼트들 (straight)
 ├─ 03_MID_TRIP\    # 2마디 MIDI 세그먼트들 (triplet)
 ├─ ADT\            # 변환된 ADT (백업/편집용)
 ├─ SD\
 │   ├─ PATTERNS\   # 최종 ADP만 (장치가 읽을 폴더)
 │   ├─ SONGS\      # ARR/APT (곡 구성)
 │   └─ SYSTEM\     # INDEX.TXT, SETTINGS.CFG ...
 └─ tools\          # mid2report_integrated.py, midi2adt.py, adt2adp.py, mkindex.py

02_MID와 03_MID_TRIP는 사실 별로 필요하지 않다.

8.3 포맷의 파일명을 갖춘 type 0 MIDI 파일로서 GM 드럼킷에 해당하는 note number(35~81)를 갖고 있어야 한다. mid_check.py는 옵션으로 지정한 디렉토리 내의 모든 MIDI 파일을 스캔하여 점검한다. 파일명을 8.3으로 바꾸거나 type 0으로 전환하는 기능도 갖고 있다.

> python.exe ..\..\tools\mid_check.py
name,size_bytes,format,ntrks,division,duration_sec,is_8dot3,basename_is_numeric,uses_channel_10,note_on_count,time_sigs,tempos_bpm,ch10_note_min,ch10_note_max,ch10_bad_drum_notes
12bar1.mid,1497,0,1,480,24.002,True,False,True,210,4/4,120.0,36,52,
12bar4.mid,1179,0,1,480,24.002,True,False,True,157,4/4,120.0,36,52,
12bar6.mid,1605,0,1,480,24.0,True,False,True,228,4/4,120.0,36,52,
12bar7.mid,1785,0,1,480,24.0,True,False,True,259,4/4,120.0,36,52,
2AFROCUB.MID,2694,0,1,240,70.441,True,False,True,414,4/4,102.0,36,50,
...중략...
world7.mid,3133,0,1,480,29.48,True,False,True,410,4/4,130.0,25,42,"25,29"

Summary:
{
  "files": 156,
  "bad_headers": 0,
  "formats": {
    "0": 142,
    "1": 14
  },
  "uses_ch10_count": 156,
  "total_duration_sec": 10484.821
}

GM Drum range check (channel 10, notes 35–81):
[GM-DRUM-RANGE] Latin6.mid: channel 10 notes outside 35–81 -> [82]
[GM-DRUM-RANGE] dance19.mid: channel 10 notes outside 35–81 -> [27, 102, 107]
[GM-DRUM-RANGE] dance21.mid: channel 10 notes outside 35–81 -> [94, 102, 107]
[GM-DRUM-RANGE] dance3.mid: channel 10 notes outside 35–81 -> [26, 30]
[GM-DRUM-RANGE] dance34.mid: channel 10 notes outside 35–81 -> [33]
[GM-DRUM-RANGE] dance4.mid: channel 10 notes outside 35–81 -> [22, 26, 30]
[GM-DRUM-RANGE] dance42.mid: channel 10 notes outside 35–81 -> [30, 32, 34]
[GM-DRUM-RANGE] dance8.mid: channel 10 notes outside 35–81 -> [24, 28]
[GM-DRUM-RANGE] world13.mid: channel 10 notes outside 35–81 -> [24, 26, 28, 96, 101]
[GM-DRUM-RANGE] world18.mid: channel 10 notes outside 35–81 -> [91]
[GM-DRUM-RANGE] world23.mid: channel 10 notes outside 35–81 -> [104]
[GM-DRUM-RANGE] world7.mid: channel 10 notes outside 35–81 -> [25, 29]

드럼 패턴을 그리드 형태로 표현하여 A4 용지 크기의 PDF로 출력해 보자. Break로 취급해야 할 곳을 어디인지를 파악하는데 도움이 될 것이다. 실제 연주를 들어보려면 적당한 시퀀서 또는 DAW에 로드하는 것이 정답이지만, 보다 간단하게는 온라인 도구인 html-midi-player를 써도 좋다.

> python.exe ..\tools\midi_drum_grid_multiline_pdf.py .\2BLUES.MID
[OK] Saved: 2BLUES_grid.pdf

출력된 결과 샘플: 2blues_grid.pdf

하나의 MIDI 파일을 상세하게 분석하려면 mid2report_integrade.py를 이용한다. 화면으로 길제 출력물이 나오므로 다음의 사례에서는 텍스트 파일로 리다이렉션하는 사례를 보여준다.

> python.exe ..\tools\mid2report_integrated.py .\2BLUES.MID | Out-File analysis.txt

출력된 결과 샘플: analysis.pdf

.\00_orig_MIDI_files 하위의 모든 .mid 파일에 대해 화면으로 출력되는 분석 결과 중 straight/triplet 라인만 추출하여  mid_triplet_report.csv 파일로 저장하기.
<code>
ls .\00_orig_MIDI_files\*.mid | % {
    $name = $_.Name
    $line = python .\tools\mid2report_integrated.py $_.FullName | Select-String "grid"
    if ($line -and $line.Line -match 'grid\s*:\s*(\w+)') {
        [PSCustomObject]@{
            File = $name
            Grid = $Matches[1]
        }
    }
} | Sort-Object Grid, File | Export-Csv mid_triplet_report.csv -NoTypeInformation

mid_check.py를 이용한다. 이 스크립트는 폴더 단위로 작동함에 유의하라.

다음은 .MID 파일이 위치한 폴더에서 실행하는 사례이다. 패턴의 유사도를 측정하는 일은 제법 까다롭다. 나의 경우는 곡 전체의 드럼 패턴을 연구하는 것이 아니라 재사용 목적으로 배포(?)된 드럼 패턴을 연구하는 것이라서 인접한 패턴이 유사한지를 확인하는 것에 중점을 두었다. 모든 패턴 간 pair-wise 비교는 화면 출력에 매트릭스 형태로 주어진다.

> python.exe ..\tools\split_drums_2bar_save.py .\Blues10.mid --export-grid
Saved: BLU_P001.MID
Saved: BLU_P002.MID
Saved: BLU_P003.MID
Saved: BLU_P004.MID
Saved: BLU_P005.MID
Saved: BLU_P006.MID

=== Pattern extraction report for Blues10.mid ===
Ticks per beat      : 480
Initial time sig    : 4/4
Bar ticks           : 1920
Total ticks         : 30722
Total bars (floor)  : 16
Used bars (2-bar xN): 16
Dropped full bars   : 0
Tail remainder      : 2 ticks beyond full bars
Similarity threshold: 80.0% (hybrid; global min 35.0%)

- Note: A partial tail after bar 16 was ignored.

Unique pattern groups: 6
Group -> Output file:
  1: BLU_P001.MID
  2: BLU_P002.MID
  3: BLU_P003.MID
  4: BLU_P004.MID
  5: BLU_P005.MID
  6: BLU_P006.MID

Pattern classification vs group 1 (assumed main GROOVE):
  Group 1: GROOVE
  Group 2: GROOVE
  Group 3: GROOVE
  Group 4: GROOVE
  Group 5: GROOVE
  Group 6: GROOVE

Pattern chain by 2-bar slices (group IDs, '*' = adjacent structurally similar):
  1*-2**-3**-4**-5**-6*-6-6

Slice details (index: bar_start -> group_id[mark]):
  slice 00: bar 01 -> 1*  [GROOVE]
  slice 01: bar 03 -> 2**  [GROOVE]
  slice 02: bar 05 -> 3**  [GROOVE]
  slice 03: bar 07 -> 4**  [GROOVE]
  slice 04: bar 09 -> 5**  [GROOVE]
  slice 05: bar 11 -> 6*  [GROOVE]
  slice 06: bar 13 -> 6  [GROOVE]
  slice 07: bar 15 -> 6  [GROOVE]

Neighbor similarity details (adjacent slices, hybrid):
  slices 00-01  groups 1-2  global= 99.9%  head= 99.9%  tail= 99.9%  mid_run= 50.0%
  slices 01-02  groups 2-3  global= 99.9%  head= 99.9%  tail= 99.9%  mid_run= 50.0%
  slices 02-03  groups 3-4  global= 99.7%  head= 99.9%  tail= 99.5%  mid_run= 45.8%
  slices 03-04  groups 4-5  global= 99.4%  head= 99.4%  tail= 99.4%  mid_run=  4.1%
  slices 04-05  groups 5-6  global=100.0%  head= 99.9%  tail=100.0%  mid_run=100.0%

Similarity matrix between pattern groups (global %, '*' = hybrid-similar >= threshold):
            1      2      3      4      5      6
   1  100.0   99.9* 100.0*  99.7*  99.4*  99.4*
   2   99.9* 100.0   99.9*  99.7*  99.4*  99.4*
   3  100.0*  99.9* 100.0   99.7*  99.4*  99.4*
   4   99.7*  99.7*  99.7* 100.0   99.4*  99.4*
   5   99.4*  99.4*  99.4*  99.4* 100.0  100.0*
   6   99.4*  99.4*  99.4*  99.4* 100.0* 100.0

Exporting grid PNGs for each pattern group...
Grid PNG saved: BLU_P001_grid.png
Grid PNG saved: BLU_P002_grid.png
Grid PNG saved: BLU_P003_grid.png
Grid PNG saved: BLU_P004_grid.png
Grid PNG saved: BLU_P005_grid.png
Grid PNG saved: BLU_P006_grid.png

--export-grid 옵션은 모든 패턴에 대해 다음과 같은 그리드 이미지를 만든다. 패턴을 시각적으로 비교하기에 아주 편리할 것이다. 12개의 slot은 사전에 지정되어 있지만 이 범위를 벗어나는 것은 GM drum kit에 맞춘 노트 넘버로 표현된다.

split_drums_2bar_save.py 스크립트는 원본 .MID 파일의 이름으로부터 장르를 유추한 뒤 다음과 같이 패턴명에 삽입할 수 있는 3글자 약자를 만든다.

유사한 패턴을 묶는 가장 효율적인 방법을 찾기가 매우 어렵다. 여러 .MID 파일에 대해 한꺼번에 작업을 할 때, 이미 동일한 장르의 패턴이 있는 경우 덮어쓰지 않고 번호를 새로 붙이게 만들어야 한다.

하위 디렉토리(00_orig_MIDI_files)에 있는 모든 .MID 파일에 대하여 이 스크립트를 실행하고 화면 출력을 하나의 텍스트 파일에 담는 명령어는 다음을 참고하라. 생성된 패턴 MID 파일에 대해서는 재작업을 하지 않아야 하니 명령어가 한층 더 복잡해졌다. Bash가 그립다! 이전 단계에서 동일한 장르의 패턴이 만들어진 경우 기본 동작은 덮어쓰기이므로, 이를 방지하려면 '--no-overwrite' 옵션을 주어야 한다.

$log = "all_results.txt"
Remove-Item $log -ErrorAction SilentlyContinue

Get-ChildItem ".\00_orig_MIDI_files" -Filter *.mid |
    Where-Object { $_.Name -notmatch '_P\d{3}\.mid$' } |
    ForEach-Object {
        Write-Host "Processing $($_.Name)..."
        "===== FILE: $($_.Name) =====" | Out-File -FilePath $log -Append -Encoding utf8

        python .\tools\split_drums_2bar_save.py $_.FullName --no-overwrite --export-grid --similarity 80 `
            2>&1 | Out-File -FilePath $log -Append -Encoding utf8

        "" | Out-File -FilePath $log -Append -Encoding utf8
    }
Processing 12bar1.mid...
Processing 12bar4.mid...
Processing 12bar6.mid...
Processing 12bar7.mid...
Processing 2AFROCUB.MID...
Processing 2BALLAD.MID...
Processing 2BLUES.MID...

2-bar .MID 파일로 분할한 뒤 이를 전부 다른 폴더로 옮기려면 다음과 같이 한다. 작업 디렉토리는 work라고 가정한다. work\00_orig_MIDI_files\ABC_P001.MID → work\MID로 전부 옮긴다.

Get-ChildItem "00_orig_MIDI_files" -Filter *.mid |
    Where-Object { $_.Name -match '^[A-Za-z]{3}_P[0-9]{3}\.MID$' } |
    Move-Item -Destination '.\MID'

> python.exe .\tools\mid2adt.py --in-dir .\MID --out-dir .\ADT

mid2adt.py가 분할된 2-bar 패턴의 straight/triplet 여부를 자동으로 인식한다.

> python.exe .\tools\adt2adp.py --in-dir .\ADT --out-dir .\ADP

> python .\tools\mkindex.py --patterns .\ADP\ --out .\SD\SYSTEM\INDEX.TXT

.\ADP\*.ADP 및 .\SD\SYSTEM\INDEX.TXT를 SD 카드의 \PATTERNS와 \SYSTEM으로 복사하면 된다.