GenoGlobe
Learning from Life

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<!DOCTYPE markdown>
# StepSeq Triplet Pattern Support – Implementation Note (StepSeq에서 Triplet 패턴 지원 및 구현 에 대한 기술 노트)

작성일: 2026-01-05  
대상: APS (Ardule Pattern Studio) – StepSeq (S key)  
관련 파일: `aps_main.py`, `aps_stepseq.py`

본 문서는  
**“StepSeq에서 triplet 패턴을 어떻게 구현할 수 있는가”라는 계획서**를 기반으로,  
**2026-01-05 기준 실제 구현이 어떤 방식으로 이루어졌는지**를 정리한 *구현 보고서*이다.

---

## 1. 구현 목표 요약 (재확인)

구현 목표는 다음 네 가지였다.

1. StepSeq(S)에서 **24-step(8T) / 48-step(16T)** ADT 패턴 진입 허용  
2. StepSeq UI에서 **bar당 step 수(12 / 24 / 16)** 가 반영된 그리드 표시  
3. 기존 **32-step 패턴과의 완전한 호환성 유지**  
4. 변경 범위를 최소화하고, 단계적으로 구현  

결론부터 말하면, **네 가지 모두 충족되었다.**

---

## 2. 핵심 설계 판단

### 2.1 “Triplet = 다른 패턴”이 아니라 “다른 grid 해상도”

Triplet 패턴은 새로운 타입의 패턴이 아니라,  
동일한 2-bar 패턴을 서로 다른 grid 해상도로 나눈 것으로 정의하였다.

| 패턴 종류 | steps / bar | total steps (2 bar) |
|---------|-------------|---------------------|
| Straight 16th | 16 | 32 |
| Triplet (8T) | 12 | 24 |
| Triplet (16T) | 24 | 48 |

따라서 다음 전제를 유지하였다.

- bar 수는 항상 **2**
- StepSeq는 항상 **2-bar 전체를 편집**
- 달라지는 것은 `total steps`, `steps_per_bar` 뿐

---

## 3. Phase 1 구현: StepSeq 진입 허용 (aps_main.py)

### 3.1 기존 제약

기존 구현에서는 다음 조건으로 인해 triplet 패턴이 즉시 차단되었다.

```python
if pat.length != 32:
    return
```

또한 내부 타이밍 계산에서도 step 수가 하드코딩되어 있었다.

```python
steps = 32
step_ticks = loop_len_ticks // steps
```

---

### 3.2 실제 구현

#### (1) 허용 길이 확장

```python
if pat.length not in (24, 32, 48):
    return
```

#### (2) step 수 일반화

```python
steps = pat.length
step_ticks = loop_len_ticks // steps
```

- loop length는 기존과 동일하게 **2 bar = 3840 ticks**
- step duration은 grid 해상도에 따라 자동 결정

#### (3) StepSeq로 전달되는 메타 정보

```python
meta.steps = steps
meta.steps_per_bar = steps // 2
```

이 단계만으로도 24-step / 48-step ADT에서 StepSeq 진입이 가능해졌다.

---

## 4. Phase 2 구현: StepSeq UI 일반화 (aps_stepseq.py)

### 4.1 PatternMeta 확장

```python
steps: int = 32
steps_per_bar: int = 16
```

기본값을 유지하여 기존 32-step 패턴과의 호환성을 보장한다.

---

### 4.2 “페이지 = bar” 개념 도입

```python
page_size = meta.steps_per_bar
start_step = page * page_size
end_step   = start_step + page_size
```

| 패턴 | page size | UI 표시 |
|----|-----------|---------|
| 32-step | 16 | 기존과 동일 |
| 24-step | 12 | 12칸 |
| 48-step | 24 | 24칸 |

---

### 4.3 bar 단위 세로 구분선 & 비트 마커

- 한 화면 = 한 bar
- `[ ]` 키는 bar 이동
- `C` 키는 bar1 → bar2 복사

비트 마커는 quarter-note 기준으로 표시된다.

| steps / bar | beat 간격 |
|-------------|-----------|
| 16 | 4 |
| 12 | 3 |
| 24 | 6 |

---

## 5. Half Pattern(_H)과 StepSeq

- `_H`는 **재생(playback) 의미**
- StepSeq는 **편집기(editor)**

따라서 `_H` 패턴이라도 StepSeq에서는 항상 2번째 bar 편집이 가능하다.

---

## 6. 구현 결과 요약

### 가능해진 것

- 24-step / 48-step StepSeq 편집
- bar 단위 UI 인식
- triplet에 맞는 비트 가이드
- 기존 32-step UX 완전 유지

### 의도적으로 제외한 것

- ADT 헤더에 grid 메타데이터 추가
- 1-bar 패턴 허용
- 변박 지원

---

## 7. 결론

Triplet StepSeq 지원은 새로운 기능 추가라기보다,  
기존 StepSeq를 **16step/bar라는 가정에서 일반화한 작업**이다.

이 구현은 이후 ADS 스트리밍, Nano Ardule 펌웨어 확장의 안정적인 기반이 된다.