Kris AndersonandClaude Opus 4.8
a39e03559d
The 940-line format developer guide has moved to its own published repo, got-feedback/feedback-feedpak-spec (released as feedpak v1.0.0). Replace docs/sloppak-spec.md with a thin pointer at the same path so existing references keep resolving; it links to the authoritative spec, bridges the sloppak/feedpak naming, and keeps the feedback-specific "where it lives in lib/" implementation map. Also repoint the human-facing references — CLAUDE.md's developer-reference link, the constitution's format reference, and the hand-editing guide's cross-links (to the spec's renumbered §6/§8/§9.5). The hand-editing guide itself stays: its practical "edit your own pack" content is not in the spec repo. Inline code comments that cite old "sloppak-spec §X.Y" section numbers are left for a follow-up (the path still resolves; numbers are approximate). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Signed-off-by: Kris Anderson <topkoa@gmail.com>
2.9 KiB
Sloppak / feedpak Format — moved
The full format specification that used to live here has moved to its own repository and is now the authoritative, versioned reference:
📖 https://github.com/got-feedback/feedback-feedpak-spec — normative spec (
spec/feedpak-v1.md), JSON Schemas, examples, and a reference validator.
Update bookmarks to point there. This page is a thin pointer kept at the original path so existing links keep resolving.
Naming: sloppak here, feedpak in the spec
The published format is named feedpak (extension .feedpak, manifest key feedpak_version).
This codebase still uses the legacy sloppak name internally — lib/sloppak.py, the
.sloppak extension, SLOPSMITH_* env vars, etc. They describe the same on-disk format. The
rename is repo/public-facing only for now (see the top-level workspace CLAUDE.md), so when the
spec says feedpak / feedpak_version, the packs this server reads and writes today are the same
structure under the .sloppak name. The internal rename is a separate, later effort.
Hand-editing a pack
For the practical "how do I edit my own pack" walkthrough (record your own stem, fix metadata, swap cover art, replace a stem split), see the companion guide that stays in this repo: sloppak-hand-editing.md.
Where the format maps to code (this repo)
The spec is implementation-independent; this table is the feedback-specific bridge from format concepts to the code that reads and writes them. It is not part of the format.
| For… | Read |
|---|---|
| Format detection, source resolution, zip unpacking | lib/sloppak.py |
Data classes (Note, Chord, Arrangement, Song, Phrase) |
lib/song.py |
Wire-format helpers (*_to_wire / *_from_wire) |
lib/song.py |
| The reference pack writer (assembly pipeline) | lib/sloppak_convert.py |
| Drum-tab vocabulary and wire helpers | lib/drums.py |
| Notation vocabulary and wire helpers | lib/notation.py |
| Live streaming over WebSocket (consumes the same shapes) | server.py (/ws/highway/{filename}) |
| The plugin system (where new visualization consumers go) | CLAUDE.md |
| Tests | tests/test_sloppak.py, tests/test_sloppak_convert.py |
Note on older section references. Some inline code comments in this repo cite section numbers from the previous version of this document (e.g. "sloppak-spec §5.3"). The external spec renumbered its sections, so those citations are approximate — find the topic by name in the feedpak spec rather than by the old number.