mirror of
https://github.com/got-feedBack/feedBack.git
synced 2026-09-12 19:58:31 +00:00
Miguel_LZPFandBret Mogilefsky
b45751164f
Addresses 12 of 13 review comments from Copilot and CodeRabbit on PR #332. One comment (no-manifests in validate-plugins.yml) is declined and answered inline; the rest are applied here. Substantive fixes: - .github/workflows/validate-plugins.yml — add --noconftest to the schema-tests step. tests/conftest.py imports structlog at module level, but the CI job only installs requirements-test.txt (pytest/httpx/jsonschema), so pytest collection would fail at conftest import. The schema tests don't use shared fixtures, so skipping conftest is safe and avoids dragging the full runtime requirements into a 2 KB validation job. (Copilot) - schema/plugin.schema.json — tighten the server_files regex on both settings.server_files and diagnostics.server_files to match the runtime _validate_relpath rules in plugins/__init__.py. The previous regex only blocked absolute paths, drive letters, backslashes, and "..". The runtime also rejects "//", "./", "/./", and leading-dotfile segments. Schema-valid manifests are now also load-time-valid. Verified the regex against 12 cases: the 3 in-tree manifests still validate. (Copilot) - .claude/skills/plugin-validate/SKILL.md — add a per-iteration plugin_ok flag so we no longer print "OK <path>" after an earlier FAIL in the same manifest. Schema-pass + id-mismatch previously produced both FAIL and OK lines for one plugin. (CodeRabbit) - docs/websocket-protocol.md — clarify song_info.tuning array length is source-dependent (typically 6 guitar, 4 bass, but extended-range GP imports can be 7/8/5/6). Recommend highway.getStringCount() for the authoritative count. Line 30 already said this; the table row on line 12 was the stale half. (CodeRabbit) Trivial fixes: - .claude/rules/plugin-author.md — "wants included" -> "wants to include" in the settings.server_files rule. (CodeRabbit) - Markdown MD040 — add `text` language tags to 7 bare-fence code blocks across AGENTS.md, docs/PLUGIN_AUTHORING.md, docs/testing-plugins.md, docs/plugin-logging.md, .claude/README.md, .claude/agents/slopsmith-reviewer.md, and .claude/skills/plugin-validate/SKILL.md (two fences). (CodeRabbit) Declined: - .github/workflows/validate-plugins.yml no-manifests -> exit 0 (CodeRabbit suggested exit 1). Plugins in this repo are in-tree, not submodules (no .gitmodules, git submodule status empty), and the workflow has a path filter on plugins/**/plugin.json so it only runs when a manifest actually changes. Exit 0 is correct. Answered inline on the PR. Verification: pytest tests/test_plugin_schema.py -v --noconftest # 8 passed python -c "import json,glob,jsonschema; s=json.load(open('schema/plugin.schema.json')); [jsonschema.validate(json.load(open(p)), s) for p in sorted(glob.glob('plugins/*/plugin.json'))]" # ok — all 3 in-tree manifests validate against tightened schema Signed-off-by: Miguel_LZPF <mgcdreamer@gmail.com>
45 lines
4.4 KiB
Markdown
45 lines
4.4 KiB
Markdown
# Highway WebSocket protocol reference
|
|
|
|
The highway WebSocket at `/ws/highway/{filename}?arrangement={index}` streams a song's chart data to the player. Plugins that drive their own highway, replace the renderer (see [plugin-visualization-contracts.md](plugin-visualization-contracts.md)), or consume the stream directly all read these frames.
|
|
|
|
## Message order
|
|
|
|
Each connection receives the following JSON frames, roughly in this order:
|
|
|
|
| Message | Shape | Description |
|
|
|---------|-------|-------------|
|
|
| `loading` | `{ type: 'loading', stage }` | Status/progress message during extraction or conversion. |
|
|
| `song_info` | `{ type, title, artist, arrangement, arrangement_index, arrangements, duration, tuning, capo, format, audio_url, audio_error, stems }` | Song metadata. `arrangements` is the full list for the switcher. `audio_url` is `null` when audio is unavailable, in which case `audio_error` is non-null; otherwise `audio_error` is `null`. `stems` is always present — an empty array for non-sloppak songs or sloppak songs with no split stems. `tuning` is an array whose length depends on the source arrangement (typically 6 for guitar, 4 for bass, but extended-range GP imports can be 7/8 for guitar or 5/6 for bass — use `highway.getStringCount()` for the authoritative count). |
|
|
| `beats` | `{ type, data: [{ time, measure }] }` | Beat timestamps with measure numbers. |
|
|
| `sections` | `{ type, data: [{ time, name }] }` | Named sections (Intro, Verse, Chorus, etc.). |
|
|
| `anchors` | `{ type, data: [{ time, fret, width }] }` | Fret zoom anchors. |
|
|
| `chord_templates` | `{ type, data: [{ name, frets: [6] }] }` | Named chord shapes. |
|
|
| `lyrics` | `{ type, data: [{ w, t, d }] }` | Syllables: `w`=word, `t`=time, `d`=duration. `-` joins to previous, `+` = line break. |
|
|
| `tone_changes` | `{ type: 'tone_changes', base, data: [{ time, name }] }` | Optional — tone change events relative to the arrangement base tone; only sent if tones were found. |
|
|
| `notes` | `{ type, data: [{ t, s, f, sus, ho, po, sl, bn, ... }] }` | Single notes. |
|
|
| `chords` | `{ type, data: [{ t, notes: [{ s, f, sus, ... }] }] }` | Chord events. |
|
|
| `phrases` | `{ type, data: [{ start_time, end_time, max_difficulty, levels: [...] }], total }` | Optional — per-phrase difficulty ladder for master-difficulty slider (slopsmith#48). Only sent when the source chart carries multi-level phrase data (PSARC / phrase-aware sloppak). Sent in chunks (`data` is a batch, `total` is the full count across messages) to avoid multi-MB single frames. Absent for GP imports and legacy sloppak; consumers must treat missing message as "single fixed difficulty — slider disabled". |
|
|
| `ready` | `{ type: 'ready' }` | All data sent — safe to finalize and start rendering. |
|
|
|
|
## Delivery guarantees
|
|
|
|
Message delivery is **incremental**. You may receive `loading` updates and `lyrics` before note/chord payloads. `tone_changes` comes after `lyrics` when present and may be omitted entirely. **Do not finalize rendering until you receive `ready`.**
|
|
|
|
## Consumer notes
|
|
|
|
- **Tuning array length follows arrangement.** 6 strings for guitar, 4 for bass, more for extended-range GP imports. Use `highway.getStringCount()` for the authoritative count rather than `tuning.length` (which can be the RS-XML padded 6-string form).
|
|
- **Chord templates are static.** Every `chord_id` referenced by `chords` is guaranteed to be present in `chord_templates`.
|
|
- **Notes carry technique fields.** `ho` = hammer-on, `po` = pull-off, `sl` = slide target, `bn` = bend amount. The full set is defined in `lib/song.py`.
|
|
- **Multiple connections are supported.** Split-screen panels, lyrics panes, and jumping-tab panes each open their own WebSocket. By design — don't try to multiplex.
|
|
|
|
## Phrase payload (slopsmith#48)
|
|
|
|
`phrases.data` is an array of phrase objects. Each phrase has `start_time`, `end_time`, `max_difficulty`, and `levels`. Each `level` has `difficulty`, `notes`, `chords`, `anchors`, `handshapes` — fully scoped to that phrase. The master-difficulty slider applies a single difficulty across all phrases by selecting the matching level.
|
|
|
|
## Related
|
|
|
|
- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) — guide index
|
|
- [plugin-visualization-contracts.md](plugin-visualization-contracts.md) — bundle shape passed to `draw()`
|
|
- [sloppak-spec.md](sloppak-spec.md) — sloppak format these messages are derived from
|
|
- `lib/song.py` — server-side `Note`, `Chord`, `Arrangement`, `Song` data models
|