[DONE] 정리 4단계 PR 18 — MIDI 로 나가는 메시지 벡터 열한 개와 /api/midi 벡터 아홉 개가 가상 패널에서 돈다

[patternflow-bot]

dev / https://claude.ai/code/session_01WnWnZzvrtVz8L7czv6JcHg

정리 4단계 계획서 표의 PR 18 이다. 패널이 MIDI 로 내보내는 것(손으로 돌린 노브의 CC 24~27, 버튼의 노트, 패턴이 바뀔 때의 Program Change)을 docs/midi-vectors/out- 벡터 열한 개로, /api/midi 와 status 의 midi 를 docs/rest-api-vectors/midi- 벡터 아홉 개로 적었다. 머지되면 CI 가 PR 마다 MIDI 보내는 쪽과 /api/midi 를 가상 패널에 돌려 보고, midi-spec.md 에서 옮긴 문장이 바뀌면 그 벡터가 빨개진다.

좋아지는 것: 없음

할 일

• 계획서 PR 18 행(k18)과 D7, D8, D9, D11, D12, docs/contract-vectors.md, _vectors.ts, PR 16([DONE] 정리 4단계 PR 16 — 가상 패널이 손으로 돌린 노브와 누른 버튼, 바뀐 패턴을 MIDI 로 보내고 /api/midi 에 답한다 #86)·PR 17([DONE] 정리 4단계 PR 17 — MIDI 받는 쪽 벡터 아홉 개가 가상 패널에서 돌고, check:midi-vectors 가 PR 마다 본다 #87) 본문의 「for another k」를 읽는다
• midi-spec.md 53~120행을 midi-out.ts 와 펌웨어(core_midi.h 의 observeFrame, setOutDivisor, setOutMultiplier, core_midi_http.h)에 맞대 본다
• docs/rest-api-vectors/midi-*.json 아홉 개
• docs/midi-vectors/out-*.json 열한 개
• 300줄 안: +286
• 스무 번 연달아 check:midi-vectors, 다섯 번 check:rest-vectors
• 일부러 깨뜨린 midi-out.ts·midi.ts 두 번, 스펙 문장 한 번, 모두 되돌림
• typecheck, lint, check:drift, 링크, 잠금, 글투, markers, doc-map
• 이 PR 의 CI: 66bd642 에서 둘 다 success
• [DONE] 직전 dev 를 다시 받아 본다: e912efa 그대로라 merge 할 것이 없다

한 일

REST 벡터는 check:rest-vectors 가 돌린다. 이 스위트는 midi Sender 를 가져오지 않으므로 아홉 개 모두 http 만 쓰고, 세션이 있어야 보이는 값은 타입으로만 본다. rest-api.md 에는 /api/midi 절이 없어서, 경로를 정하는 midi-spec.md 의 Status 와 Settings 에서 문장을 옮겼다. midi-caps 만 audio-caps, mqtt-caps 처럼 rest-api.md 의 conventions 문장이다.

벡터	says	보는 것
midi-caps	A feature's endpoints exist only when that feature is composed in … (rest-api.md 613행)	caps 가 ["patterns","params","sleep","midi"], GET /api/midi 가 200 과 JSON
midi-status	GET /api/status on a build with this feature lists "midi" in caps and carries (68행)	같은 caps, midi 의 열 키를 타입으로
midi-rx-detail	Unreleased 1.2 adds rxDetail to both … (81행)	status 의 midi.rxDetail 과 GET /api/midi 의 rxDetail, 표의 열두 키
midi-get	channel, outDiv, outMul, outMode, host, session state, counters (115행)	channel 1(31행), outDiv [1,1,1,1](119행의 기본값), outMode "abs"(116행), 나머지는 타입
midi-out-mode	knobs out as a virtual position (default) or as relative steps. (116행)	abs 에서 시작해 outMode=rel 로, 폼 본문 outMode=abs 로 돌아온다. GET 과 status 둘 다
midi-out-div	outbound sensitivity: detents per outbound step, 1..16, … (119행)	양 끝 16 과 1 을 받는다
midi-out-mul	Setting one of outMul/outDiv above 1 resets the other to 1 (117행)	outDiv=4 다음 outMul=8 이면 outDiv 가 1, 다시 outDiv=2 면 outMul 이 1
midi-knob	Apply outMul/outDiv to one knob; without it, to all four. (118행)	outDiv=4&knob=3, outMul=2&knob=2 뒤 [1,1,4,1], [1,2,1,1](72행의 예와 같다). knob 없이 outDiv=2 면 넷 다
midi-host	Empty string clears it. (120행)	host=192.168.0.23 이 GET 과 status 에 보이고, 폼 본문 host= 로 빈 글

보내는 쪽은 check:midi-vectors 가 _rtpmidi.ts 의 세션으로 돌린다. 손은 hand, 시간은 wait 와 out 의 within 이다. 손으로 돌린 것은 다음 프레임 끝에 나가므로 첫 메시지는 20 ms 안에 본다. 같은 노브의 다음 메시지를 보는 벡터는 그 사이에 100 ms 를 둔다.

벡터	says (midi-spec.md)	보는 것
out-cc-abs	the value is a virtual position 0..127 … starts at 64, … clamps at the ends (57행)	K1 +3 → CC 24 = 67, K2 −2 → CC 25 = 62. K1 +62 는 127 에서 멈추고 −1 이면 126, K2 −63 은 0 에서 멈추고 +1 이면 1
out-cc-rel	64 ± steps since the previous message (binary offset) (57행)	outMode=rel 뒤 K3 −2 → 62, 100 ms 뒤 +5 → 69, K1 +1 → 65
out-cc-div	The encoders have 24 detents a turn, so 1 is 24 steps per turn and 4 is 6. (119행)	outDiv=4&knob=1 뒤 K1 한 바퀴(24) → 70, K2 한 바퀴 → 88. K1 +3 은 100 ms 동안 아무것도 없고, +1 더하면 71
out-cc-mul	outbound sensitivity the other way: steps per detent, 1..8. (117행)	outMul=8&knob=4 뒤 K4 +2 → 80, K3 +2 → 66, K4 −1 → 72
out-pacing	at most one message per knob every 50 ms … trailing-edge so the final value always arrives (57행)	K1 +1 → 65. 20 ms 뒤 +1 과 40 ms 뒤 +1 은 50 ms 까지 나가지 않고, 다음 50 ms 안에 67 하나만
out-abs-same	in abs only a position that differs from the last one sent goes out (57행)	K2 +1 → 65, 50 ms 안에 +1 과 −1 이면 위치가 65 로 돌아와 100 ms 동안 아무것도 없다. 다음 +1 → 66
out-rel-sum	in rel the steps sum between messages and a sum leaving ±63 is sent at once (57행)	K4 +1 → 65, 50 ms 안의 +2 와 +3 이 합쳐 69 하나. +1 → 65 뒤 +40, +40 은 합 80 이라 바로 127(63), 50 ms 뒤 나머지 81(17)
out-buttons	Encoder button 1–4 pressed (58행)	K1 누름 → 노트 60 온 127, 500 ms 쥐고 있는 동안 아무것도 없고 놓으면 노트 오프. K4 는 노트 63
out-program-change	The pattern changed (by anyone: … MIDI, a show), for n ≤ 127 (60행)	/api/patterns/select?index=2 → PC 2, 호스트의 PC 5 → PC 5
out-no-echo	a CC or note the host itself sent is never reflected back (63행)	호스트의 CC 20 = 100, CC 25 = 65, 노트 62 온과 오프가 모두 패널에 닿고(paramActive, input) 아무것도 돌아오지 않는다
out-hand-only	Encoder 1–4 turned by a hand. (57행)	POST /api/params?p1=900 은 CC 를 내지 않는다. 100 ms 뒤 손 K1 +1 → 65

증거

로컬, web/:

$ git diff --stat origin/dev...HEAD
 docs/midi-vectors/out-abs-same.json       | 12 ++++++++++++
 docs/midi-vectors/out-buttons.json        | 13 +++++++++++++
 docs/midi-vectors/out-cc-abs.json         | 15 +++++++++++++++
 docs/midi-vectors/out-cc-div.json         | 13 +++++++++++++
 docs/midi-vectors/out-cc-mul.json         | 12 ++++++++++++
 docs/midi-vectors/out-cc-rel.json         | 12 ++++++++++++
 docs/midi-vectors/out-hand-only.json      | 10 ++++++++++
 docs/midi-vectors/out-no-echo.json        | 13 +++++++++++++
 docs/midi-vectors/out-pacing.json         | 11 +++++++++++
 docs/midi-vectors/out-program-change.json | 10 ++++++++++
 docs/midi-vectors/out-rel-sum.json        | 17 +++++++++++++++++
 docs/rest-api-vectors/midi-caps.json      |  9 +++++++++
 docs/rest-api-vectors/midi-get.json       | 19 +++++++++++++++++++
 docs/rest-api-vectors/midi-host.json      | 11 +++++++++++
 docs/rest-api-vectors/midi-knob.json      | 12 ++++++++++++
 docs/rest-api-vectors/midi-out-div.json   | 11 +++++++++++
 docs/rest-api-vectors/midi-out-mode.json  | 12 ++++++++++++
 docs/rest-api-vectors/midi-out-mul.json   | 13 +++++++++++++
 docs/rest-api-vectors/midi-rx-detail.json | 37 +++++++++++++++++++++++++++++++++++++
 docs/rest-api-vectors/midi-status.json    | 24 ++++++++++++++++++++++++
 20 files changed, 286 insertions(+)

$ npm run check:midi-vectors
docs/midi-vectors/in-cc-absolute.json: same
… in- 아홉 개 모두 same
docs/midi-vectors/out-abs-same.json: same
docs/midi-vectors/out-buttons.json: same
docs/midi-vectors/out-cc-abs.json: same
docs/midi-vectors/out-cc-div.json: same
docs/midi-vectors/out-cc-mul.json: same
docs/midi-vectors/out-cc-rel.json: same
docs/midi-vectors/out-hand-only.json: same
docs/midi-vectors/out-no-echo.json: same
docs/midi-vectors/out-pacing.json: same
docs/midi-vectors/out-program-change.json: same
docs/midi-vectors/out-rel-sum.json: same
passed   midi-vectors

$ npm run check:rest-vectors | grep midi-
docs/rest-api-vectors/midi-caps.json: same
docs/rest-api-vectors/midi-get.json: same
docs/rest-api-vectors/midi-host.json: same
docs/rest-api-vectors/midi-knob.json: same
docs/rest-api-vectors/midi-out-div.json: same
docs/rest-api-vectors/midi-out-mode.json: same
docs/rest-api-vectors/midi-out-mul.json: same
docs/rest-api-vectors/midi-rx-detail.json: same
docs/rest-api-vectors/midi-status.json: same
passed   rest-vectors

$ for i in $(seq 1 20); do npx tsx scripts/drift.ts midi-vectors; done
midi-vectors passed 20 failed 0
$ for i in $(seq 1 5); do npx tsx scripts/drift.ts rest-vectors; done
rest-vectors passed 5 failed 0

처음 돌렸을 때 out-rel-sum 하나가 drift 였다. 내가 +2 와 +3 을 70 으로 적었고 패널은 69(64 + 5)를 보냈다. 벡터를 69 로 고쳤다.

깨뜨린 한 번: midi-out.ts 를 일곱 군데 바꿨다. 간격 50 ms 를 20 으로 줄이고 시작 위치를 63 으로 옮겼다. 노트 온 벨로시티는 100 이고 PC 번호에는 1 을 더했다. knob= 과 빈 host= 는 무시했다. rel 은 63 에 걸음을 더했다. 백업 파일로 되돌렸다.

out-abs-same: drift        step 01 [176,25,65] ← [176,25,64]
out-buttons: drift         step 01 [144,60,127] ← [144,60,100]
out-cc-abs: drift          step 01 [176,24,67] ← [176,24,66]
out-cc-div: drift          step 03 [176,25,88] ← [176,25,69]
out-cc-mul: drift          step 03 [176,26,66] ← [176,26,79]
out-cc-rel: drift          step 02 [176,26,62] ← [176,26,61]
out-hand-only: drift       step 03 [176,24,65] ← [176,24,64]
out-pacing: drift          step 03 <absent> by 10 ms ← [176,24,66] at 10 ms · step 04 [176,24,67] ← nothing
out-program-change: drift  step 01 [192,2] ← [192,3]
out-rel-sum: drift         step 04 <absent> by 10 ms ← [176,27,68] at 10 ms · step 09 [176,27,127] ← [176,27,126]
failed   midi-vectors
midi-host: drift           step 04 host "" ← "192.168.0.23"
midi-knob: drift           step 03 outDiv[2] 4 ← 1, outMul [1,2,1,1] ← [2,2,2,2]
failed   rest-vectors

(벡터 ← 패널로 줄였다.) out-no-echo 는 이 깨뜨림에 걸리지 않아 두 번째로 깨뜨렸다. midi.ts 가 받은 메시지를 그대로 돌려보내게(MIDI Thru), midi-out.ts 가 버스가 잡은 노브의 손 클릭을 버리게(core_midi.h:403 처럼) 했다. 되돌렸다.

out-hand-only: drift   step 03 [176,24,65] by 20 ms ← nothing
out-no-echo: drift     step 04 <absent> ← [176,20,100], [176,25,65], [144,62,127] at 100 ms · step 06 <absent> ← [128,62,0]
failed   midi-vectors

스펙 문장을 바꾼 한 번: midi-spec.md 57행의 「clamps at the ends」를 「clamps at either end」로 바꾸면 out-cc-abs.json: drift, says docs/midi-spec.md ← says not in docs/midi-spec.md. git checkout 으로 되돌렸다.

$ npm run typecheck                    # exit 0
$ npm run lint -- --max-warnings=0     # exit 0
$ npm run check:drift
passed audio-vectors, bom, bom-schematic, changelog, editions, features, links-absolute, markers, midi-vectors, mqtt-vectors, osc-vectors, presets, rest-vectors, shared, virtual-panel · skipped roadmap(원래 레포를 못 읽는다, CI 는 strict)
$ python3 ../.github/scripts/check_links.py
all 734 relative links resolve
$ npm run check:human-lock
check:human-lock: no locked words changed
$ npm run check:voice
read: 0 added lines in 0 files
check:voice: nothing found              # JSON 의 says 는 스펙을 옮긴 글이라 읽지 않는다. 이 본문은 따로 `-` 로 돌렸다
$ npx tsx scripts/drift.ts markers
passed   markers
$ git fetch --tags && npm run doc-map           # CSV 는 git checkout 으로 되돌렸다
1120 links from 224 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
1366 Korean/English pairs → docs/investigations/2026-10-doc-parity.csv
7 en-short, 18 ko-short, 1 missing-ko, 1340 ok

GitHub, 이 PR: 66bd642 에서 「Drift checks / check」(116546946688)와 「Docs point at files that exist / check」(116546946548)가 success. 「Web CI」는 web/** 에서만 돌아 이 PR 에서는 돌지 않았다.

실행법

cd web && npm ci
npm run check:midi-vectors     # in- 아홉, out- 열하나
npm run check:rest-vectors     # midi- 아홉 개가 여기 있다

벡터 하나를 고쳐 보려면 JSON 을 고치고 같은 명령을 돌린다. git 에 넣기 전에도 디스크에서 읽는다.

가정

• 기준 브랜치는 dev(머리말). 표가 PR 18 에 적은 docs/midi-vectors/out-*.json 과 docs/rest-api-vectors/midi-*.json 만 더했다. 두 README, CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV, 가상 패널은 안 고쳤다. 라벨은 앞 PR 들처럼 달지 않았다.
• rest-api.md 에 /api/midi 절이 없어 midi- 여덟 개는 midi-spec.md 의 Status 와 Settings 를 contract 로 둔다. _vectors.ts 는 contract 가 가리키는 스펙에서 문장을 찾으므로 그대로 돈다. REST README 첫 문장(「one sentence of rest-api.md」)과는 어긋난다. 아래 「for another k」.
• 세션이 있어야 보이는 값(rtpPeers 1, rtpPeer, rx)은 벡터를 두지 않았다. PR 17 은 out-*.json 에 두라 했지만, MIDI README 는 out- 을 Device → host 의 한 행이라 하고 GET /api/midi 는 패널이 보내는 것이 아니다. midi-get 이 타입으로만 본다.
• 한 번에 도는 걸음은 ±63 안이다. 펌웨어와 패널은 한 프레임의 걸음을 ±63 에서 자르는데(core_midi.h 의 steps > 63), 스펙은 그것을 말하지 않는다. 그래서 out-cc-abs 는 62 와 −63 으로 양 끝을 넘긴다.
• out-rel-sum 의 합 80 은 바로 127(63), 나머지는 50 ms 뒤 81(17)로 본다. 바이너리 오프셋 한 메시지는 ±63 까지만 싣고, 57행이 마지막 값은 늘 닿는다고 한다. 펌웨어(core_midi.h 의 sum > 63)도 그렇게 한다.
• 노트 오프의 벨로시티는 <integer> 다. 59행은 노트 오프라고만 한다. 펌웨어는 0 을 보낸다. 노트 오프를 벨로시티 0 노트 온으로 보내는 패널은 실패한다(58·59행이 둘을 나눈다).
• 기다림의 창은 프레임이 손 뒤 20 ms 안에 도는 패널이면 맞도록 잡았다. out-pacing 의 「나가지 않는다」 창은 손 뒤 20~50 ms 로, 첫 메시지가 0 ms 보다 늦게 나간 패널이면 50 ms 규칙이 그 안에 다음 메시지를 막는다.
• PC 를 노브(SELECT, K4 길게 누름)로 바꾸는 것과 쇼가 바꾸는 것, 127 넘는 번호는 다시 돌리지 않는다. 가상 패널은 쇼를 돌리지 않고 Basics 는 34개다. 레인이 움직인 노브(57행의 Hand motion only)도 check:midi-vectors 에 ws Sender 가 없고 midi 만 넣은 패널에는 레인이 없어 돌리지 않는다. 버스(POST /api/params)는 out-hand-only 가 본다.
• outDiv=17, outMul=9 같은 범위 밖 값은 벡터가 없다. 스펙은 범위만 말하고, 거절인지 잘림인지는 말하지 않는다(D8).
• outMul 의 기본값은 <integer> 로 본다. 119행은 outDiv 의 기본값을 적고 117행은 outMul 의 기본값을 적지 않는다.
• 스크린샷은 없다. 화면이 바뀌는 PR 이 아니다.
• firmware/ 와 web/src/ 를 건드리지 않아 build.sh all, check:ci, check:panels 는 §2.1(1) 대상이 아니다. 계획서대로 typecheck 와 이 PR 의 check, 깨뜨린 한 번을 적었다.

Changelog

Tools

• MIDI out and /api/midi have contract vectors. Eleven files in docs/midi-vectors/ start with out-, each one sentence of the device → host table or the settings in docs/midi-spec.md, from three detents on knob 1 arriving as CC 24 at 67 to a host's own CC that never comes back. check:midi-vectors replays them over its RTP-MIDI session. Nine more in docs/rest-api-vectors/ start with midi- and read GET and POST /api/midi and the midi block in /api/status under check:rest-vectors.

for an issue

D9. 벡터는 스펙을 따르고, 펌웨어는 한 곳에서 다르다(PR 16 의 「k18, for an issue」).

• out-hand-only.json · midi-spec.md 57, "Encoder 1–4 turned by a hand." · core_midi.h:403 은 버스가 그 채널을 잡고 있는 프레임의 델타를 0 으로 둔다(paramAbsoluteActive). 손은 버스가 250 ms 안에 쓴 채널을 되찾지 못하므로(ABSOLUTE_RELEASE_GRACE_MS), POST /api/params?p1=900 100 ms 뒤에 K1 을 돌리면 기기는 CC 를 보내지 않는다. 위 두 번째 깨뜨림이 그 규칙이고, 벡터가 빨개진다.

벡터는 없고 PR 16 이 넘긴 것: core_midi_http.h:107 이 on=0|1 을 읽고, GET /api/midi 가 you, ip, port, outPos 를 싣는다(59~69행). Settings 표는 그중 아무것도 적지 않는다. 스펙이 말하지 않으니 벡터가 없고(D8), 모양은 다른 키를 지나가게 둔다.

for another k

• k23: midi-spec.md 32행은 패널이 「never echoes a host's messages back」이라 하고, 60행은 PC 가 「by anyone: … MIDI」로 바뀌어도 나간다 한다. out-program-change 는 메시지를 정하는 60행을 따라 호스트의 PC 5 에 PC 5 를 듣는다(D8). PR 16 도 적었다.
• k23: 117행에 outMul 의 기본값을 넣을지. midi-get 은 지금 네 정수로만 본다.
• docs/rest-api-vectors/README.md 첫 문장은 「one sentence of rest-api.md」다. midi- 여덟 개는 midi-spec.md 를 옮긴다. 표에 그 README 를 다시 가진 행이 없어, 고친다면 행을 하나 더해야 한다.
• k22: docs/README.md 의 midi-spec.md 줄에 midi-vectors/ 를(PR 17 이 적은 것과 같다). rest-api-vectors/ 에 midi- 가 있다는 것도.

Upstream

• What: Add docs/midi-vectors/out-.json, eleven vectors of docs/midi-spec.md's device → host table and its settings, and docs/rest-api-vectors/midi-.json, nine vectors of GET and POST /api/midi and the midi block in /api/status. check:midi-vectors and check:rest-vectors replay them against the virtual panel.
• Checks: npm run typecheck, npm run lint and npm run check:drift (midi-vectors and rest-vectors included) pass; firmware/ and web/src/ are untouched.
• Docs map: none.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WnWnZzvrtVz8L7czv6JcHg