# 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 툴체인: **완성** 이 문서를 기준으로 구현을 진행한다.