phase 1

.gemini/difficulty-factors.md

@@ -0,0 +1,36 @@
+# TJA 난이도 산정 핵심 요소 (Technical Factors)
+
+'상수' 산출을 위해 채보에서 추출해야 하는 5개 핵심 차원과 세부 지표입니다.
+
+## 1. 물리적 밀도 (Physical Density)
+물리적인 타격 속도와 관련된 지표입니다.
+- **Global NPS**: `총 노트 수 / 총 연주 시간`. 곡의 전반적인 속도 체급.
+- **Peak NPS (Sliding Window)**: 1초~2초 단위 윈도우에서 추출한 최대 NPS. 순간 폭타의 한계치.
+- **Density Variance**: NPS의 표준 편차. 곡이 얼마나 균일한지 또는 급격한지 측정.
+
+## 2. 지구력 요구량 (Stamina Requirement)
+지치지 않고 집중력을 유지해야 하는 정도입니다.
+- **Longest Stream Count**: 쉼표(예: 8분음표 이상의 간격) 없이 이어지는 최대 노트 개수.
+- **Stream Density Ratio**: 전체 곡 시간 대비 스트림(연타) 구간이 차지하는 비중.
+- **Rest Interval Analysis**: 회복 가능한 구간의 배치와 빈도.
+
+## 3. 배치 복잡도 (Pattern Complexity)
+인지적 부하와 손 배치(Hand-switching)의 어려움입니다.
+- **Color Transition Ratio**: `색상 전환(d↔k) 횟수 / 총 노트 수`. 전환이 많을수록 인지 부하 증가.
+- **Hand-Switching Index**: 홀수(3, 5, 7) 및 짝수(2, 4) 연타의 혼합도. 기준 손이 강제로 바뀌는 빈도.
+- **Complex Pattern Detection**: 비정형 패턴(예: ddkdk, kkkdk 등)의 출현 빈도.
+
+## 4. 리듬 복잡도 (Rhythmic Complexity)
+정확도(98%) 달성을 방해하는 타이밍 요소입니다.
+- **Quantization Diversity**: 사용된 음표 단위(1/16, 1/12, 1/24, 1/48 등)의 종류와 혼합 빈도.
+- **Off-beat Ratio**: 정박(1/4, 1/8)을 벗어난 엇박 노지의 비율.
+- **Rhythmic Entropy**: 노트 간 시간 간격의 불규칙성 정도.
+
+## 5. 가독성 및 기믹 (Reading & Gimmicks)
+시각적인 반응 속도와 암기 요소를 측정합니다.
+- **Scroll Velocity (SV) Variance**: `#SCROLL` 변화의 진폭과 빈도.
+- **BPM Fluctuation**: `#BPMCHANGE`를 통한 급격한 속도 변화 및 정지(#DELAY).
+- **Visual Overlap**: 저속 구간에서의 노트 겹침이나 고속 구간의 반응 한계.
+
+## 상수 추정 가중치 (Proposed)
+`Constant ∝ (Peak_NPS * 0.4) + (Complexity * 0.3) + (Stamina * 0.2) + (Reading * 0.1)`

.gemini/dnn-plan.md

@@ -0,0 +1,16 @@
+# DNN 학습 로드맵 (.gemini/dnn-plan.md)
+
+### Phase 1: 데이터 정제
+- `measure.csv`를 기준으로 분석된 Factor 데이터셋 확보.
+- Null 값 제거 및 이상치(Outlier) 필터링.
+
+### Phase 2: 환경 구축
+- Python 기반 (TensorFlow/PyTorch) 또는 Node.js 기반 (TensorFlow.js) 선택.
+- 데이터 학습용 훈련 세트(Train)와 검증 세트(Validation) 분리.
+
+### Phase 3: 학습 및 검증
+- 모델 훈련 및 오차(MSE) 점검.
+- 실제 상수와의 상관계수 분석.
+
+### Phase 4: 통합
+- 학습된 가중치(Weight)를 `factorize.ts`에 로드하여 실제 상수 예측 수행.

.gemini/factorization-method.md

@@ -0,0 +1,32 @@
+# TJA Factorization 방법론
+
+이 문서는 Raw TJA 데이터를 5대 난이도 요소(Factor)로 변환하는 표준 공정을 정의합니다.
+
+## 1. 전처리: 절대 타임라인 생성 (Timeline Mapping)
+TJA의 상대적 마디/박자 구조를 초 단위의 절대 시간축으로 선형화합니다.
+- **상태 추적**: `#BPMCHANGE`, `#MEASURE`, `#DELAY`를 실시간 반영하여 각 노트의 발생 시간($T_n$)을 계산합니다.
+- **이벤트 객체화**: 각 노트를 위치($T_n$), 타입(Don/Ka), 현재 속도(BPM/SV)를 포함한 객체로 변환합니다.
+
+## 2. 요소별 특징 추출 (Feature Extraction)
+
+### A. 물리적 밀도 (Physical)
+- **Peak NPS**: 2초 단위의 슬라이딩 윈도우를 사용하여 가장 밀도가 높은 구간의 초당 노트 수를 측정합니다.
+- **지수화**: `Window_Note_Count / Window_Size`.
+
+### B. 지구력 (Stamina)
+- **Stream 정의**: 노트 간 간격이 1/16박자(약 150-200ms) 이하로 지속되는 구간을 하나의 스트림으로 봅니다.
+- **지표**: 가장 긴 스트림의 노트 개수($S_{max}$)와 곡 전체 대비 스트림 비중($R_{stream}$)을 결합합니다.
+
+### C. 배치 복잡도 (Technical)
+- **Color Transition**: 인접한 두 노트의 색상이 다를 때(d↔k)를 전환으로 카운트합니다.
+- **지표**: `Total_Transitions / Total_Notes`. 0.5에 가까울수록 복잡도가 높습니다.
+
+### D. 리듬 복잡도 (Accuracy)
+- **Subdivision Analysis**: 각 마디가 몇 등분 되었는지 분석하여 12, 24, 48분 음표 등 비정형 박자의 사용 빈도를 측정합니다.
+- **지표**: `Non_Standard_Notes / Total_Notes`.
+
+### E. 가독성 및 기믹 (Reading)
+- **Velocity Flux**: `#BPMCHANGE` 횟수와 `#SCROLL` 변화량의 절대값 합산으로 시각적 혼란도를 측정합니다.
+
+## 3. 정규화 및 통합 (Normalization)
+각 지표의 원시 수치를 0.0 ~ 1.0 범위로 정규화한 뒤, '상수' 가중치를 적용하여 최종 난이도를 도출합니다.

.gemini/notes.md

@@ -5,27 +5,13 @@
 - **Language**: TypeScript
 - **Library**: [tja](https://www.npmjs.com/package/tja) (TJA parser)
 
+## Key Documents
+- `.gemini/tja-spec.md`: Rigorous TJA format specification.
+- `tja-format.mediawiki`: Original source document.
+- `measure.csv`: Dataset with columns `상수`, `songno`, `diff`.
+
+## Models (model/)
+- `constant_predictor.py`: DNN 기반 상수 예측 모델.
+
 ## Library Usage (tja)
-- **Import**: `import { TJAParser } from "tja";`
-- **Parsing**: `const parsed = TJAParser.parse(content);`
-- **Structure**:
-    - `parsed.title`, `parsed.bpm`, `parsed.offset`
-    - `parsed.courses` (Array of `Course` objects)
-    - `course.difficulty` (e.g., "Oni")
-    - `course.stars` (Level/Stars)
-    - `course.activeCourse.getCommands()` returns an array of commands and note sequences.
-
-## Purpose
-Analyzing or processing TJA (Taiko Jiro) file formats.
-
-## Key References
-- `tja-format.mediawiki`: Detailed specification of the TJA format.
-
-## TJA Format Overview
-- **Encoding**: UTF-8 with BOM or Shift-JIS.
-- **Extension**: `.tja`.
-- **Comments**: Start with `//`.
-- **Metadata**: Key-value pairs (e.g., `TITLE:`, `BPM:`, `OFFSET:`).
-- **Course Metadata**: Specific to difficulties (e.g., `COURSE:`, `LEVEL:`, `BALLOON:`).
-- **Notation**: Commands prefixed with `#` (e.g., `#START`, `#END`, `#MEASURE`, `#BPMCHANGE`).
-- **Notes**: `0-9`, `A`, `B`, `F`.
+...

.gemini/pipeline-design.md

@@ -0,0 +1,13 @@
+# 파이프라인 실행 규칙
+
+모든 경로는 실행 시점에 인자로 지정하여 관리합니다.
+
+## 1. 학습 파이프라인 (`run_train.sh`)
+- **인자 1 (TJA_DIR)**: 학습용 TJA 채보가 저장된 폴더 (예: `sample/training`)
+- **인자 2 (MODEL_PATH)**: 모델이 저장될 경로 (예: `output/model/v2_constant`)
+- **인자 3 (DATASET_DIR)**: 데이터셋이 저장될 폴더 (예: `output/dataset`)
+
+## 2. 예측 파이프라인 (`run_predict.sh`)
+- **인자 1 (MODEL_PATH)**: 추론에 사용할 모델 경로
+- **인자 2 (TJA_DIR)**: 예측할 TJA 채보가 모여있는 폴더
+- **인자 3 (OUTPUT_DIR)**: 결과가 저장될 폴더

.gemini/tja-spec.md

@@ -0,0 +1,68 @@
+# TJA Format Specification (Rigorous)
+
+## 1. File Structure
+- **Extension**: `.tja`
+- **Encoding**: UTF-8 (with BOM) or Shift-JIS.
+- **Comments**: `//` (inline, until end of line).
+- **Sections**:
+    1. **Global Metadata**: Before any `#START`.
+    2. **Course Data**: Metadata specific to a difficulty (can be mixed with global).
+    3. **Song Notation**: Between `#START` and `#END`.
+
+## 2. Metadata (Key: Value)
+| Key | Type | Description |
+| :--- | :--- | :--- |
+| `TITLE` | string | Song title. |
+| `BPM` | float | Beats Per Minute. Default: 120. |
+| `WAVE` | string | Path to audio file. |
+| `OFFSET` | float | Seconds. Negative delays notes, positive advances them. |
+| `DEMOSTART`| float | Preview start time in seconds. |
+| `GENRE` | string | Category (e.g., アニメ, ゲームミュージック). |
+| `SCOREMODE`| 0, 1, 2| Scoring method. Default: 1. |
+| `COURSE` | enum | 0:Easy, 1:Normal, 2:Hard, 3:Oni, 4:Edit/Ura, 5:Tower, 6:Dan. |
+| `LEVEL` | int | 1-10 (Stars). |
+| `BALLOON` | int[] | Comma-separated hit counts for balloon/kusudama notes. |
+| `SCOREINIT`| int | Initial score per note. |
+| `SCOREDIFF`| int | Added score for combo milestones. |
+
+## 3. Song Notation: Notes
+| Code | Name | Description |
+| :--- | :--- | :--- |
+| `0` | Blank | No note. |
+| `1` | Don | Small Red. |
+| `2` | Ka | Small Blue. |
+| `3` | DON | Large Red. |
+| `4` | KA | Large Blue. |
+| `5` | Drumroll| Start of small drumroll. Ends with `8`. |
+| `6` | DRUMROLL| Start of large drumroll. Ends with `8`. |
+| `7` | Balloon | Start of balloon. Ends with `8`. |
+| `8` | End | Ends 5, 6, 7, or 9. |
+| `9` | Kusudama| Large balloon/Kusudama. Ends with `8` or `9`. |
+| `A` | DON(H) | Large Red (Hands/Multiplayer). |
+| `B` | KA(H) | Large Blue (Hands/Multiplayer). |
+
+## 4. Commands (#COMMAND [value])
+| Command | Value | Description |
+| :--- | :--- | :--- |
+| `#START` | (P1/P2) | Begin notation. |
+| `#END` | - | End notation. |
+| `#MEASURE` | n/d | Set time signature (e.g., 4/4). |
+| `#BPMCHANGE`| float | Change BPM. |
+| `#DELAY` | float | Delay in seconds (can be negative). |
+| `#SCROLL` | float | Multiplier for note scroll speed. |
+| `#GOGOSTART`| - | Start Go-Go Time (1.2x score). |
+| `#GOGOEND` | - | End Go-Go Time. |
+| `#SECTION` | - | Reset branch accuracy counters. |
+| `#BRANCHSTART`| type,v1,v2| Branching: `p` (accuracy) or `r` (drumrolls). |
+| `#N`, `#E`, `#M`| - | Branch paths: Normal, Advanced/Expert, Master. |
+| `#BRANCHEND`| - | End branching section. |
+| `#BARLINEOFF`| - | Hide measure lines. |
+| `#BARLINEON` | - | Show measure lines. |
+| `#LYRIC` | string | Display lyrics (`\n` for line break). |
+
+## 5. Logic & Formulas
+- **Measure Duration (ms)**: `60000 * (numerator / denominator) * 4 / BPM`
+- **Note Timing**: Equally spaced within a measure.
+- **Branching**:
+    - `p` (Percent): `(GOOD + OK*0.5) / TotalNotes * 100`.
+    - Calculated one measure before `#BRANCHSTART`.