====== APS (Ardule Pattern Studio) 사용자 매뉴얼 ======

GitHub: https://github.com/jeong0449/NanoArdule

본 문서는 APS v2.2a 기준의 사용자 매뉴얼 초안이다.  
APS는 드럼 패턴을 **편집·연결·재생·스트리밍**하기 위한 패턴 중심 스튜디오이며, 본 문서는 기능 나열보다 **이해 가능한 사용 흐름과 설계 의도**를 설명하는 데 목적이 있다.

{{:pictures:aps_main.png?300|메인 화면}}
{{:nano_ardule_midi_controller:stepedit.png?300|스텝에디트}}

----

===== 0. 설치 및 실행 요령 =====

==== 0.1 디렉토리 구성 ====

APS는 **단일 디렉토리 실행 구조**를 전제로 한다.

  * 모든 Python 스크립트는 **하나의 디렉토리**에 위치해야 한다.
  * 동일한 위치에 반드시 ''patterns/'' 디렉토리가 존재해야 한다.
  * ''patterns/'' 아래에는 ADT / ARR / ADP 등의 패턴 파일이 위치한다.

예시 구조:

<code>
APS/
├─ aps_main.py
├─ aps_stepseq.py
├─ aps_playback.py
├─ aps_ui.py
...
└─ patterns/
   ├─ *.ADT
   ├─ *.ARR
   └─ *.ADP
</code>

==== 0.2 실행 방법 ====

사용자가 직접 실행하는 스크립트는 **aps_main.py 하나**이다.

<code>
python aps_main.py
</code>

다른 스크립트들은 내부적으로 import되어 사용되며,
개별 실행은 지원하지 않는다.

==== 0.3 실행 환경 ====

  * Python 3.9 이상 권장 (가급적 파이썬 공식 웹사이트에서 받아서 설치할 것)
    * mido, python-rtmidi
  * curses 지원 터미널 (Windows Terminal 권장)
  * MIDI 출력 장치 또는 가상 MIDI 포트 (Windows에 기본 내장된 Microsoft GS Wavetable Synth로도 소리가 잘 남)

----

===== 1. APS 개요 =====

==== 1.1 APS는 무엇을 하기 위한 도구인가 ====

APS(Ardule Pattern Studio)는 **드럼 패턴 중심 워크플로우**를 위한 프로그램이다. 보다 쉽게 표현하자면, PC에서 돌아가는 파이썬 프로그램으로서 자체 정의한 2-bar 드럼 패턴 파일([[adt_v2.2|ADT]])를 열람하고, 이를 조합하여 곡 단위의 정보를 만들거나, 패턴 단위의 편집을 하는 작은 프로그램이다. 물론 재생 기능도 갖고 있다. ADT 파일은 공개된 포맷의 텍스트 파일로서 MIDI 파일로부터 드럼 패턴을 추출하여 만들거나(필요한 모든 스크립트 제공) APS 또는 텍스트 편집기로도 편집 가능하다. 샘플 패턴 파일은 [[https://github.com/jeong0449/NanoArdule/tree/main/patterns/ADT|GitHub]]에서 제공한다.

  * 개별 드럼 패턴 편집 (ADT)
  * 패턴 연결을 통한 곡 구조 작성 (ARR)
  * 실시간 재생 및 스트리밍 (ADS)

APS는 DAW가 아니다.  
APS의 기본 단위는 **패턴 파일**이며, 모든 재생은 패턴의 조합으로 이루어진다.

==== 1.2 ADT / ARR / ADS의 관계 ====

  * **ADT**: 1-bar 드럼 패턴 파일
  * **ARR**: 여러 ADT를 연결한 체인
  * **ADS**: 하드웨어 스트리밍용 결과물

----

===== 2. 화면과 모드 =====

==== 2.1 메인 화면 ====

메인 화면은 APS의 중심이다.

  * 패턴 목록
  * 선택된 패턴 강조
  * 상태 메시지 표시

==== 2.2 모드 개념 ====

APS에서 모드란 다음을 의미한다.

  * 현재 화면
  * 허용되는 키 입력 집합

같은 키라도 모드에 따라 다른 동작을 한다.

----

===== 3. 패턴(ADT) =====

==== 3.1 ADT 개념 ====

  * 1 bar 길이
  * 16-step 해상도
  * 악기별 드럼 레인

패턴은 **파일이며 데이터**이지, 재생 상태가 아니다.

==== 3.2 패턴 이름 규칙 ====

  * ''_P###'' : Main Pattern
  * ''_B###'' : Break Pattern

''C'' 키를 누르면 두 패턴이 전환된다.

<code>
_P001  <->  _B001
</code>

----

===== 4. Step Sequencer =====

==== 4.1 노트와 액센트 ====

^ 문자 ^ 의미 ^
| . | Rest |
| - | Soft |
| x | Medium |
| o | Strong |

J / K 키로 액센트를 변경한다.

----

===== 5. 체인(ARR) =====

==== 5.1 ARR 개념 ====

ARR은 여러 패턴을 연결한 곡 구조 파일이다.

==== 5.2 카운트인 ====

카운트인은 **특수 로직이 아니라 패턴**으로 다루는 것이 권장된다.

  * 1-bar CountIn 패턴
  * 체인 맨 앞에 1회 삽입

----

===== 6. 재생과 Playback =====

APS는 즉각 반응보다 **예측 가능한 타이밍**을 우선한다.

초기 재생 시 약간의 지연은 정상 동작이다.

----

===== 7. 대화상자 =====

APS의 대화상자는 **Norton Commander 스타일**을 따른다.

  * 테두리 박스
  * 타이틀 없음
  * 명확한 확인/취소

----

===== 8. 설계 노트 =====

  * 전역 상태 최소화
  * 특수 로직 제거
  * 패턴 중심 설계

카운트인은 sleep 기반이 아닌 **패턴 기반**이 권장된다.