Differences

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

--- nano_ardule_midi_controller:adc_arr_conversion_tools_design [2026/01/06 20:13] – created hyjeong
+++ nano_ardule_midi_controller:adc_arr_conversion_tools_design [2026/01/06 20:15] (current) – [ADC ARR 변환 도구 설계 문서] hyjeong
@@ Line 1: / Line 1: @@
 <!DOCTYPE markdown>
+# ADC ARR 변환 도구 설계 문서
+작성일: 2026-01-06
+*(adc-arr2aps.py / adc-arr2mid.py)*
+이 문서는 NanoArdule ADC 툴체인에서 **ARR 기반 변환 도구 두 개**의 최종 설계를 정의한다.
+---
+## 1. 개요
+APS / ADC 생태계에서 각 파일 포맷의 역할은 다음과 같다.
+- **ADT**: 사람이 직접 보고 수정하는 리듬 패턴
+- **ARR**: 사람이 구조를 설계하는 어레인지먼트
+- **APS**: 인터랙티브 편집기 / 큐레이션 도구
+- **ADS**: 하드웨어 재생을 위한 최종 계약물
+PC 측 도구의 역할은 **변환과 검증**으로 한정되며,
+하드웨어 재생을 대체하는 참조 구현을 제공하지 않는다.
+이에 따라 다음 두 개의 ARR 기반 도구를 정의한다.
+- `adc-arr2aps.py`
+- `adc-arr2mid.py`
+이 두 도구가 완성되면 **PC 측 툴체인은 기능적으로 완결**된다.
+---
+## 2. adc-arr2aps.py — ARR → APS 체인 이식기
+### 2.1 목적
+- ARR 파일(v0.05.x)을 파싱
+- 구조 정보를 **APS가 직접 사용하는 체인 표현**으로 변환
+- APS에서 즉시 열고 편집할 수 있도록 준비
+이 도구는 **재생을 수행하지 않으며**,
+순수하게 *구조적 이식(structural migration)* 만을 담당한다.
+---
+### 2.2 입력
+- ARR 파일 (`.arr`)
+- 지원하는 지시자:
+  - `#SECTION`
+  - `#PLAY`
+  - 패턴 딕셔너리 (`n=XXX.ADT`)
+  - 체인 정의 (`MAIN|...`)
+  - `BPM=`
+  - `#COUNTIN`
+---
+### 2.3 출력
+- **APS 네이티브 체인 표현**
+  - 구체적인 저장 형식은 구현에 맡긴다
+  - 중간 포맷(JSON 등)을 강제하지 않는다
+- 출력물은 **APS가 소비**하며,
+  펌웨어나 ADS 컴파일러를 위한 입력물이 아니다.
+> JSON 또는 공개 교환 포맷은 필요하지 않다.
+---
+### 2.4 책임 범위
+- 딕셔너리 참조 해석
+- 다음 요소의 의미를 정확히 보존:
+  - 체인 순서
+  - 반복 횟수
+  - 섹션 라벨(메타데이터)
+  - half pattern 의미 (`_h`)
+  - bar 단위 시간 정합성
+- count-in 정보를 체인 메타데이터로 전달
+---
+### 2.5 비목표
+- UI 제공 ❌
+- 오디오/MIDI 재생 ❌
+- ADS 생성 ❌
+- 최적화 또는 재구성 ❌
+---
+### 2.6 CLI 예시
+```bash
+adc-arr2aps.py input.arr
+```
+선택 옵션:
+- `--strict` : 알 수 없는 지시자 발견 시 실패
+- `--dry-run` : 파싱 및 보고만 수행
+---
+## 3. adc-arr2mid.py — ARR → MIDI 미리듣기 생성기
+### 3.1 목적
+- ARR 구조를 **표준 Type 0 MIDI**로 투영
+- 청취를 통한 구조 검증
+- DAW 및 MIDI 도구를 이용한 타임라인 점검
+이 도구는 *플레이어가 아니라 투영기(projection)* 이다.
+---
+### 3.2 입력
+- ARR 파일 (`.arr`, v0.05.x)
+---
+### 3.3 출력
+- 표준 MIDI 파일:
+  - Type 0
+  - 단일 트랙
+  - GM 호환 (드럼 채널)
+---
+### 3.4 매핑 규칙
+- ADT 패턴을 노트 이벤트로 확장
+- 시간축은 ADS / 하드웨어 재생 의미와 동일
+- BPM은 MIDI 템포 메타 이벤트로 기록
+- count-in은 옵션에 따라 무음 또는 클릭으로 처리
+---
+### 3.5 선택적 메타데이터
+- 섹션 경계:
+  - MIDI Marker 이벤트
+- bar 번호:
+  - Marker 또는 Text 이벤트
+---
+### 3.6 비목표
+- ADS 에뮬레이터 ❌
+- 실시간 재생 엔진 ❌
+- 음원 합성 ❌
+---
+### 3.7 CLI 예시
+```bash
+adc-arr2mid.py input.arr --out preview.mid
+```
+선택 옵션:
+- `--markers`
+- `--metronome`
+- `--no-countin`
+---
+## 4. 설계 근거
+- ADS는 **하드웨어 전용 계약물**로 유지
+- Ardule Player만이 유일한 재생 참조 구현
+- PC 도구는 다음만 수행:
+  - 구조 이식 (`arr2aps`)
+  - 청취 투영 (`arr2mid`)
+이를 통해 의미 중복과 구현 분기를 방지한다.
+---
+## 5. 상태
+- 설계: **최종**
+- 범위: **동결**
+- PC 툴체인: **완성**
+이 문서를 기준으로 구현을 진행한다.