Differences

This shows you the differences between two versions of the page.

--- nano_ardule_midi_controller:adt_v2.2 [2025/11/04 12:59] – ↷ Page moved from all_the_others:adt_v2.2 to nano_ardule_midi_controller:adt_v2.2 hyjeong
+++ nano_ardule_midi_controller:adt_v2.2 [2025/11/16 10:24] (current) – hyjeong
@@ Line 1: / Line 1: @@
-====== ADT v2.2 (공식 사양) ======
+====== Ardule Drum Pattern Text Format: ADT v2.2 ======
-마디 드럼 패턴을 텍스트로 기술하는 포맷. v2.2는 GRID/LENGTH 가변(32/24/48) 및 **트리플렛(8T/16T)**을 정식 지원합니다.
-===== 핵심 개념 =====
+  * **BUILD_ID**: ADT22-SPEC-20251116
-^ 항목 ^ 설명 ^ 기본값 ^
+  * **Status**: Stable specification (Ardule Drum Pattern Player v2.3 / v2.4 기준)
-| VERSION | 문서 첫 줄에 ; ADT v2.2 코멘트 권장 | — |
+  * **First published**: 2025-11-16
-| NAME | 패턴 이름(8–16자 권장) | — |
+  * **Scope**: ADT v2.2 텍스트 포맷 및 ADP v2.2 바이너리 캐시 생성 기준
-| TIME_SIG | 4/4, 3/4, 12/8 등 (표시/메타) | 4/4 |
-| GRID | 16(스트레이트), 8T(8분 트리플렛), 16T(16분 트리플렛) | 16 |
-| LENGTH | 총 스텝 수: 32 / 24 / 48 | 32 |
-| SLOTS | 슬롯 개수(12 고정 권장) | 12 |
-| KIT | 드럼맵 힌트(GM_STD/GS/XG 등) | GM_STD |
-| ORIENTATION | STEP 또는 SLOT (입력 허용, 로더가 STEP로 정규화) | STEP |
-| SWING | 0–60% (GRID=16에서 권장, 8T/16T는 보통 0) | 0 |
-| SLOTn | SLOT<n>=ABBR@NOTE[,NAME] (12줄 선언 권장) | — |
-===== 슬롯 맵(권장: GM 12슬롯) =====
+Ardule Drum Pattern System에서 사용하는 2-bar 드럼 패턴의 텍스트 표현 포맷이다.
-<code>
+ADT v2.2는 ADP v2.2 바이너리 캐시 포맷과 1:1 대응되며, 사람이 읽고 편집하기 쉬운 것을 목표로 한다.
-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
-</code>
-충돌 시 **NOTE(숫자)**를 진실로 간주(ABBR/NAME은 UI 표시용 메타).
+===== 1. 기본 개념 =====
-===== 본문(패턴 데이터) 규칙 =====
+  * **패턴 단위**: 2마디(2 bars)를 기본 전제로 한다.
+  * **TIME_SIG**: 표기 및 UI용 박자표 정보. 실제 재생 타이밍 계산에는 관여하지 않는다.
+  * **GRID / LENGTH**: 패턴의 해상도(그리드)와 총 스텝 수를 정의한다.
+    * 표준 조합(2-bar 기준)
+      * GRID=16,  LENGTH=32   (4/4, 1 bar = 16 steps)
+      * GRID=8T,  LENGTH=24   (12/8, 1 bar = 12 steps)
+      * GRID=16T, LENGTH=48   (4/4 triplet, 1 bar = 24 steps)
+    * 다른 조합도 표현은 가능하지만, ADP v2.2 표준 플레이어와의 호환성은 보장하지 않는다.
+  * **SLOTS**: 동시에 사용할 드럼 슬롯(보통 12).
+  * **ACC (accent level)**: 각 스텝의 타격 세기를 0~3의 4단계로 표현한다.
+    * 0: rest (무음)
+    * 1: 약박
+    * 2: 중간강
+    * 3: 강박
+  * **ORIENTATION**
+    * STEP: 한 줄이 “한 스텝에서의 모든 슬롯 상태”를 의미한다.
+    * SLOT: 한 줄이 “한 슬롯에서의 전체 스텝 패턴”을 의미한다.
+    * ADP 변환 시에는 항상 STEP 오리엔테이션으로 정규화된다.
-  * 사용 기호: -(ACC0), .(ACC1), o(ACC2), X(ACC3) — 대소문자 불문.
+===== 2. 파일 구조 개요 =====
-  * STEP-우선: 줄 수 = LENGTH, 각 줄 길이 = SLOTS (시간 축이 아래로 흐름).
-  * SLOT-우선: 줄 수 = SLOTS, 각 줄 길이 = LENGTH (악기별 가로 진행). 로더가 90° 전치하여 내부 STEP 배치로 정규화.
+ADT v2.2 파일은 다음과 같이 구성된다.
-  * 라인 끝 ; 이후는 주석.
+  * 첫 줄: 버전 코멘트(권장)
+  * 헤더: key=value 형식의 메타데이터
+  * SLOT 선언: SLOT0..SLOT11
+  * 본문 패턴: ORIENTATION에 따라 STEP 또는 SLOT 방식으로 표현된 문자 격자
+예)
-===== 예시 (32스텝, STEP) =====
 <code>
 ; ADT v2.2
 NAME=ROCK01_MAIN
 TIME_SIG=4/4
@@ Line 51: / Line 52: @@
 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..........
+........................
+...
+</code>
+===== 3. 헤더 필드 =====
+모든 헤더 필드는 `KEY=VALUE` 형식이며, 대소문자를 구분하지 않는다.
+미지의 키는 무시된다.
+^ 키          ^ 필수 여부 ^ 형식 / 예시              ^ 설명                                  ^
+| NAME        | 필수      | `NAME=ROCK01_MAIN`      | 패턴 이름(ASCII/UTF-8 문자, 공백 허용). |
+| TIME_SIG    | 필수      | `TIME_SIG=4/4`          | 박자표. 재생 타이밍에는 영향 없음.      |
+| GRID        | 필수      | `GRID=16` / `8T` / `16T`| 패턴 해상도.                           |
+| LENGTH      | 필수      | `LENGTH=32`             | 전체 스텝 수(정수).                     |
+| SLOTS       | 필수      | `SLOTS=12`              | 슬롯 수. ADP v2.2 표준은 12를 가정.     |
+| KIT         | 필수      | `KIT=GM_STD`            | 드럼 킷 이름(문자열).                   |
+| ORIENTATION | 선택      | `ORIENTATION=STEP`      | STEP 또는 SLOT. 생략 시 자동 판정.      |
+  * **버전 코멘트**
+    * 첫 줄에 `; ADT v2.2`를 넣는 것을 권장한다.
+    * 이것은 코멘트일 뿐, 별도의 `VERSION=` 필드는 존재하지 않는다.
+  * **ORIENTATION 자동 판정 규칙**
+    * ORIENTATION이 누락되었을 때:
+      * 본문에서 “길이 L, 폭 S”인 줄이 L개 존재하면 STEP으로 해석.
+      * “길이 L, 폭 S”인 줄이 S개 존재하면 SLOT으로 해석.
+      * 둘 다 아니면 STEP으로 가정한다.
+===== 4. SLOT 선언 =====
+각 슬롯은 MIDI 노트 번호, 약어, 이름으로 정의한다.
+키 이름은 `SLOT0`부터 `SLOT11`까지를 표준으로 한다.
+형식:
+<code>
+SLOTn=ABBR@NOTE[,NAME]
+</code>
+  * `n`: 0~11 (정수)
+  * `ABBR`: 1~3자의 슬롯 약어 (예: KK, SN, CH)
+  * `NOTE`: 0~127 범위의 MIDI 노트 번호
+  * `NAME`: 인간이 읽기 위한 슬롯 이름(선택)
+예)
+<code>
 SLOT0=KK@36,KICK
 SLOT1=SN@38,SNARE
@@ Line 63: / Line 118: @@
 SLOT10=CL@39,CLAP
 SLOT11=PH@44,HH_PED
-X.---------- ;1
-----o------- ;2
-X.---------- ;3
-----.------- ;4
-X.----.----- ;5
-----.------- ;6
-X.---------- ;7
-----o------- ;8
-... ;(총 32줄)
 </code>
-===== 예시 (48스텝, 16T 트리플렛, STEP) =====
+  * 어떤 SLOTn이 선언되지 않은 경우, 위의 GM 12슬롯 기본값으로 채운다.
-<code>
+  * ADP v2.2 표준에서는 SLOTS=12, SLOT0~11이 모두 존재하는 것을 기본으로 한다.
-; ADT v2.2
-NAME=BLUES_SHFL
-TIME_SIG=12/8
-GRID=16T
-LENGTH=48
-SLOTS=12
-KIT=GM_STD
-ORIENTATION=STEP
-SLOT0=KK@36,KICK
+===== 5. 본문 패턴: STEP / SLOT 표현 =====
-SLOT1=SN@38,SNARE
-SLOT2=CH@42,HH_CL
-SLOT3=OH@46,HH_OP
-...
-X-----------X-----------X-----------X-----------X-----------X-----------
+헤더와 SLOT 선언 이후부터 파일 끝까지는 “본문 패턴” 영역이다.
-----o---------------o---------------o---------------o-------------------
+빈 줄 또는 세미콜론(;)으로 시작하는 줄은 코멘트로 취급하여 무시한다.
-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-X-
-... ;(총 48줄)
-</code>
-===== 멀티-ADT(한 파일에 여러 패턴) =====
+=== 5.1 사용 가능한 문자와 ACC 매핑 ===
-<code>
-; ADT v2.2 MULTI
-[PATTERN ROCK01_MAIN]
+본문에서 사용할 수 있는 문자는 다음과 같다.
-(개별 패턴의 헤더 + 본문)
-[END]
-[PATTERN ROCK01_FILL]
+^ 문자 집합          ^ ACC 값 ^ 의미                    ^
-(헤더 + 본문)
+| `-`                | 0      | rest / hit 없음         |
-[END]
+| `.`                | 1      | 약박                    |
-</code>
+| `o`, `O`           | 2      | 중간강                  |
+| `x`, `X`, `^`      | 3      | 강박                    |
-  * 단일 패턴 파일은 섹션 없이 바로 헤더/본문으로 시작.
+  * 공백, 탭, 기타 문자는 모두 무시된다(라인 정규화 과정에서 제거).
-  * 멀티 파일 확장자는 .ADX 권장, 참조 시 FILE.ADX:SECTION.
+  * 출력 시에는 `- . o X` 형태를 권장하지만, 파서는 위 문자 집합 전체를 허용한다.
-===== 파일명 권장(8.3) =====
+=== 5.2 STEP 오리엔테이션 ===
-  * {BASE6}{NN}.ADT (예: ROCK01.ADT)
+  * 한 줄이 “한 스텝에서의 모든 슬롯 상태”를 의미한다.
-  * 멀티-ADT 컨테이너는 *.ADX 권장.
+  * 각 줄의 길이(유효 문자 수)는 `SLOTS`와 같아야 한다.
+  * 줄의 개수는 `LENGTH`와 같아야 한다.
-===== 검증 체크리스트 =====
+예) GRID=16, LENGTH=32, SLOTS=12
-  * 파일 인코딩: ASCII/UTF-8 (BOM 지양)
+<code>
-  * LENGTH ∈ {24,32,48}, SLOTS=12
+X..X..X..X..X..X..X..X..
-  * GRID ∈ {16,8T,16T}
+....X.......X..........
-  * ORIENTATION 미기재 시 본문 크기로 자동 판별
+........................
-  * STEP-우선: 줄수=LENGTH, 줄길이=SLOTS
+...
-  * SLOT-우선: 줄수=SLOTS, 줄길이=LENGTH
+</code>
-  * 본문 문자 유효성: - . o X(대소문자 허용)
-  * SLOTn 12줄, NOTE 0..127
-  * 멀티-ADT: [PATTERN]…[END] 짝/중복 검사
-===== 재생 엔진(요지) =====
+  * 위 예시에서 첫 줄은 step 0에 해당하며, 왼쪽에서 오른쪽으로 SLOT0→SLOT11 순서이다.
+  * 각 문자에 대응하는 ACC 값(0~3)이 ADP에 저장된다.
-  * 내부 PPQN 권장: 96 (또는 192)
+=== 5.3 SLOT 오리엔테이션 ===
-  * SUBDIV_PER_BEAT = { GRID=16→4, 8T→3, 16T→6 }
-  * ticks_per_step = PPQN / SUBDIV_PER_BEAT
-  * SWING: GRID=16에서 홀짝 스텝 지연(%) 적용. 8T/16T에서는 보통 0(옵션으로 셔플 해석 가능).
-===== ADP v2.2 헤더(바이너리 캐시) =====
+  * 한 줄이 “한 슬롯에서의 전체 스텝 패턴”을 의미한다.
-^ 필드 ^ 설명/예시 ^
+  * 각 줄의 길이(유효 문자 수)는 `LENGTH`와 같아야 한다.
-| sig | "ADP2" |
+  * 줄의 개수는 `SLOTS`와 같아야 한다.
-| version | 22 |
+  * 줄의 순서는 SLOT0, SLOT1, …, SLOT(SLOTS-1)이다.
-| ppqn | 96 |
-| grid | 0(16), 1(8T), 2(16T) |
-| length | 24 / 32 / 48 |
-| tempo, swing | 선택 저장(참조용) |
-| kit, slots | 메타 |
-| crc16 | 선택(무결성 확인) |
-===== 호환성 규칙 =====
+예) SLOTS=12, LENGTH=32
-  * v2.1 파일은 GRID 생략 시 16, LENGTH=32로 해석 → v2.2와 완전 호환.
+<code>
-  * SLOT 선언이 없으면 KIT 프리셋(GM_STD 등)으로 기본 맵을 로드.
+X..X..X..X..X..X..X..X..   ; SLOT0
-  * 비고: 입력이 SLOT-우선일 경우 로더가 자동으로 90° 전치하여 내부 STEP-우선 데이터로 정규화한 뒤 ADP로 인코딩합니다.
+....X.......X..........   ; SLOT1
+........................   ; SLOT2
+...
+</code>
-ChatGPT의 말:
+ADT v2.2 → ADP v2.2 변환기에서는 내부적으로 항상 STEP 오리엔테이션으로 변환한 뒤, ADP를 생성한다.
-===== 리듬 모드 (Rhythm Mode) =====
+===== 6. 멀티 ADT 컨테이너(ADX) =====
-ADT v2.2에서는 한 박(beat)을 나누는 방식(GRID)과, 그 분할을 얼마나 불균등하게 흔들지(SWING)를 별도로 제어합니다.
-즉, GRID는 ''시간 분할 구조'', SWING은 ''느낌적인 흔들림''을 의미합니다.
-==== GRID (분할 단위) ====
+ADT v2.2는 여러 개의 패턴을 하나의 파일로 묶는 컨테이너 형식(ADX)을 지원한다.
-^ GRID 값 ^ 의미 ^ 1박의 분할 수 ^ 예시 LENGTH(2마디 기준) ^ 용도 ^
-| 16 | 16분음표 기준 (스트레이트) | 4 | 32 | 일반 4/4 락·팝 |
-| 8T | 8분 트리플렛 기준 | 3 | 24 | 12/8 블루스, 6/8 셋잇단 |
-| 16T | 16분 트리플렛 기준 | 6 | 48 | 재즈 트리플렛, 셔플 계열 |
-| (향후 확장) | (예: 32, 32T) | — | — | 세밀한 subdiv용 |
-  * GRID는 ''시간 해상도''를 결정합니다.
+  * 파일 확장자: `.adx` 권장.
-  * GRID가 커질수록 더 조밀한 스텝(세밀한 리듬)을 표현할 수 있습니다.
+  * 구조:
+    * `[패턴 헤더 + SLOT 선언 + 본문]` 블록이 여러 개 연속.
+    * 각 패턴은 `NAME=` 필드를 통해 고유한 이름을 가진다.
+  * 다른 파일에서 참조:
+    * `FILE.ADX:SECTION` 형태로 참조.
+    * 여기서 `SECTION`은 해당 패턴의 `NAME` 값이다.
+      * 예: `ROCKPACK.ADX:ROCK01_MAIN`
-===== SWING (흔들림 정도) =====
+===== 7. ADP v2.2와의 관계(요약) =====
-^ SWING 값 ^ 의미 ^ 리듬 비율(1박 내 두 음 길이 비율) ^ 비고 ^
-| 0% | 균등 (스트레이트) | 1:1 | 완전 균등 16분 리듬 |
-| 30~50% | 약한 스윙 | 약 1.5:1 | 부드러운 재즈 스윙 |
-| 60~80% | 강한 셔플 | 약 2:1 | 블루스·락 셔플 |
-| 100% | 완전 트리플렛 feel | 2:1 (정확히 3분할) | 셋잇단에 가까움 |
-  * SWING은 GRID가 **16(스트레이트)**일 때만 적용하는 것이 일반적입니다.
+ADT v2.2는 ADP v2.2 바이너리 캐시와 1:1 대응한다.
-  * GRID가 8T 또는 16T(트리플렛 기반)일 때는 SWING을 0으로 두는 것이 권장됩니다.
-==== 트리플렛, 스윙, 셔플의 관계 ====
+  * 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)
-  * 트리플렛 (Triplet)
+ADT v2.2 사양에서는 SWING, TEMPO를 별도의 헤더 필드로 정의하지 않는다.
-    * 박을 정확히 3등분 (1:1:1)
+이 필드는 ADP v2.2 헤더 레벨에서만 존재하며, 현재 구현에서는 모두 0으로 저장된다.
-    * GRID=8T 또는 16T, SWING=0
-    * 정확한 셋잇단 리듬 (예: 12/8)
-  * 스윙 (Swing)
-    * 트리플렛을 기반으로 하지만 첫 음이 더 길고 두 번째가 짧음
-    * GRID=16, SWING=30~60
-    * 재즈, 팝, 펑크 등에서 흔히 사용되는 “흔들림” 느낌
-  * 셔플 (Shuffle)
-    * 스윙보다 더 강하게 첫 음을 끄는 느낌
-    * GRID=16, SWING=60~80
-    * 블루스, 록, 펑크 등 “무겁고 느긋한” 리듬
-==== 예시 비교 ====
+===== 8. 검증 체크리스트 =====
-^ 유형 ^ GRID ^ SWING ^ LENGTH ^ 리듬 간격 비율 ^ 느낌/장르 ^
-| 스트레이트 락 | 16 | 0 | 32 | 1:1 | 팝, 락, EDM |
-| 재즈 스윙 | 16 | 50 | 32 | 약 1.5:1 | 재즈, 펑크 |
-| 셔플 블루스 | 16 | 70 | 32 | 약 2:1 | 블루스, 락 |
-| 트리플렛 재즈 | 16T | 0 | 48 | 1:1:1 | 재즈 트리플렛 |
-| 12/8 발라드 | 8T | 0 | 24 | 1:1:1 | 느린 셋잇단 발라드 |
-===== 구현 시 주의 =====
+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 캐시 파일 생성의 기준으로 삼는다.
-  * 시계 계산:
-<code>
-ticks_per_step = PPQN / SUBDIV_PER_BEAT
-(SUBDIV_PER_BEAT = GRID에 따른 분할 수)
-</code>
-  * 스윙 적용:
-    * GRID=16에서 홀수 스텝을 SWING%만큼 지연.
-    * GRID=8T/16T는 이미 트리플렛 기반이므로 SWING=0.
-  * UI 표시:
-    * LCD 등에 GRID=16 SW=60 형태로 동시 표시하면 사용자 이해가 용이합니다.