# HITL: スキャン画像の楽譜を Claude Code で読み取る手順

`pdf2mscz convert` が「五線が見つかりませんでした」と言う PDF (紙をスキャンした画像の PDF など) は、
Claude Code に画像を読ませて中間表現 (IR) JSON を作り、それを `.mscz` にします。

## 使い方 (人間がやること)

Claude Code にこう頼むだけです (ファイル名は置き換え):

```
prompts/hitl_omr.md の手順で 〇〇.pdf を mscz にして
```

---

## Claude Code への指示 (ここから下を毎回そのまま守ること)

あなたは楽譜の読み取り担当です。次の手順と出力形式を厳守してください。

### 1. 画像を作る
```
pdf2mscz images <PDF> -d work/<曲名> --split
```
`pageNN.png` (ページ全体) と `pageNN_sysMM.png` (段ごとの拡大) ができる。
読み取りは段ごとの拡大画像で行い、ページ全体は配置の確認に使う。

### 2. 最初に全体の構成を決める
1 ページ目を見て、次を確定してから音符を読む:
- パート数・各パートの名前 (段の左の文字)・ドラム譜かどうか (二本線の打楽器記号)
- 各五線の音部記号 (ト音 / ト音 8vb / ヘ音 / 打楽器)
- 調号 (♯/♭ の数)、拍子、テンポ、タイトル・作曲者
これを `docs/IR_FORMAT.md` の `meta` と `parts` に書く。

### 3. 段ごとに読み取る
段の画像 1 枚ずつ、**小節ごと・五線ごと**に IR の `measures` を追記していく。各小節で:
1. 小節線で区切って、その段に何小節あるか数える (段頭の小さな数字はその段の最初の小節番号)
2. 五線ごとに、左から順に音符・休符を `voices[0]` に書く
   - 符頭の種類 (白丸/黒丸)・旗や連桁の本数・付点から `duration` / `dots` を決める
   - 縦に重なった符頭は 1 つの `chord` の `notes` にまとめる
   - 同じ五線に符尾が上向きと下向きの別のリズムが同時にある時だけ、下向きを `voices[1]` にする
   - 3 連符などは数字の付いた範囲を `tuplet` で囲む
3. 音高は **実音** で書く:
   - ト音記号: 第 1 線 (一番下) が E4、第 5 線 (一番上) が F5
   - ヘ音記号: 第 1 線が G2、第 5 線が A3
   - ト音記号 8vb (下に小さい 8): ト音記号として読んでから 1 オクターブ下げる (第 1 線 = E3)
   - 調号の音、小節内で前に付いた臨時記号、タイでつながった前の音の臨時記号を反映する
4. 歌詞は五線の下の文字を、真上の音符の `lyrics` に入れる。「foo____」の下線は伸ばし (melisma)、「Hap - py」のハイフンは `syllabic`
5. コードネーム (五線の上の B♭、F/A など) は `harmony` に、小節内の位置 `at` と一緒に書く
6. 練習番号 (枠囲みの文字) は `rehearsal`、段の最後の小節には `"lineBreak": true`

### 4. 小節ごとに長さを確かめる
各五線の音価の合計が拍子と一致することを、書きながら確かめる (4/4 なら全音符 1 個分)。
合わない時は画像を見直す (付点・連桁の本数・連符・休符の見落としが多い)。
**推測で穴埋めしない**。どうしても読めない箇所は、その小節に
`"warnings": [{"measure": 小節番号, "staff": 五線番号, "msg": "読めなかった内容"}]` をトップレベルに追記して人に知らせる。

### 5. 出力形式
- ファイル: `work/<曲名>/score.json` (UTF-8, JSON 1 つ)
- 形式: `docs/IR_FORMAT.md` に完全に従う。キー名・duration の綴り (`16th`, `eighth` など) を変えない
- 長い曲は段ごとに `measures` を追記して保存してよい (途中で保存しておく)

### 6. 検査して直す
```
pdf2mscz validate work/<曲名>/score.json
```
エラーが出たら該当小節の画像を見直して修正し、エラーがなくなるまで繰り返す。

### 7. mscz にする
```
pdf2mscz from-ir work/<曲名>/score.json -o <出力先>.mscz
```

### 8. 報告
人間に次を短く報告する: 出力ファイルのパス、小節数・パート数、`warnings` に残した要確認箇所 (ページ・小節・五線)。