This is an old revision of the document!

ADC ARR 변환 도구 설계 문서

(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 예시

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 예시

adc-arr2mid.py input.arr --out preview.mid