khodo/product-vamp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rhythm Time Signatures

Browse Source
This commit is contained in:
khodowany
2026-09-26 01:44:04 -05:00
parent 4485eb7413
commit 4d6348d354
3099 changed files with 203023 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TECHNICAL_GUIDE.md
+10 -2
View File
@@ -39,7 +39,7 @@ At startup the Zero validates the packaged `catalog.db` application identifier a
Runtime catalogs contain immutable metadata shared by navigation, the HTTP service, and the UI. Song groups reference canonical records by index; practice is a flat, numerically ordered exercise list. SQLite retains complete bundles, while cached measure/page counts let menu queries avoid reading musical JSON. Python constructs the complete database before deployment; metadata and embedded JSON are published together. There are no custom rows, runtime imports, metadata-repair triggers, or persisted page-state tables. Selecting a score loads only that bundle asynchronously, discarding stale results after navigation; the view keeps at most two page textures.
Practice exercise IDs are the three-digit source stems, including `000` when present. Part IDs append the part name, such as `001-electric`. Duplicate titles and identical placeholder music remain independent exercises. Catalog schema 3 stores exercise identity and part metadata without practice categories, lesson groups, or key variants. Every exercise must have all three parts. Older catalogs must be rebuilt or reinstalled, not migrated.
Practice exercise IDs are the four-digit source stems, including `0000` when present. Part IDs append the part name, such as `0001-electric`. Duplicate titles and identical placeholder music remain independent exercises. The catalog stores exercise identity and part metadata without practice categories, lesson groups, or key variants. Every exercise must have all three parts. Older catalogs must be rebuilt or reinstalled, not migrated.
`--once` (also `runtime.exit_after_startup`) is a headless readiness check: it checks database integrity and validates the catalog and referenced page assets, checks runtime-directory writes and the configured server bind, and exits without opening audio/display devices or publishing a readiness heartbeat. Page checks include containment, checksums, CPU-only PNG decoding, and exact 976x484 dimensions. The configured heartbeat destination must be absent or a regular file, never a directory, symlink, or special file. Runtime writes and readiness probes use exclusive sibling temporary files; readiness leaves an existing heartbeat unchanged and removes its probes. `--health-check` instead probes the running service's read-only `/api/health` endpoint using the configured timeout. A stopped/unresponsive service or an invalid response fails the check; it does not create or repair files. `--check-config` remains configuration-only.
@@ -51,10 +51,18 @@ Zero and Pico share one gesture state machine: a second release within 220 ms of
The build runs `python3 -m generator` against `data/` and writes build-only assets under the CMake binary tree. Every song and exercise produces acoustic, electric, and vocal parts in its authored musical key. Source counts are discovered, not fixed in code. Generator-only optional chord markers are consumed before publishing.
Practice sources live directly in `data/practice/` with three-digit filenames, currently `001.xml` through `366.xml`; `000.xml` is also valid. For example, `data/practice/001.xml` generates `practice/001/{acoustic,electric,vocal}.json` and corresponding page directories. Songs stay in `data/songs/`. The filename number determines exercise identity and ordering; MusicXML titles determine labels, falling back to the number. Root-level XML, other practice filenames, and nested practice directories are rejected. Adding, renaming, or removing a source requires no registry edit. The current 366 exercises produce 1,098 practice parts, plus six performance parts.
Practice sources live directly in `data/practice/` with four-digit ASCII filenames, currently `0001.xml` through `0366.xml`; `0000.xml` is also valid. For example, `data/practice/0001.xml` generates `practice/0001/{acoustic,electric,vocal}.json` and corresponding page directories. Songs stay in `data/songs/`. The filename number determines exercise identity and ordering; MusicXML titles determine labels, falling back to the number. Root-level XML, other practice filenames, and nested practice directories are rejected. Adding, renaming, or removing a source requires no registry edit. Regeneration replaces the output tree and catalog, removing old three-digit paths and IDs without aliases or migration. The current 366 exercises produce 1,098 practice parts, plus six performance parts.
The pipeline is Soundslice/MuseScore -> uncompressed `.xml` -> musical model -> part generation -> semantic JSON, audio, and engraved pages -> packaged SQLite catalog. Export MusicXML 3.1 or 4.0, `score-partwise`, with one part and one staff. The musical model retains independent voices and per-tone durations/ties; automatic practice generation additionally requires a single monophonic melody and optional structured harmonies. Packaged music describes each generated part, not an archival copy of the XML.
### Rhythm Sources
`data/rhythms/<meter>/<series>/` is an independent source collection, excluded from application generation and packaging. Each series contains `4^N` four-digit numbered XML files for an N/4 meter: 16 in 2/4, 64 in 3/4, 256 in 4/4, and 1,024 in 5/4, totaling 2,720 files across both series. Numbering starts at `0001.xml` in every directory.
- Series `1` uses two measures. Read the file number minus one as `2*N` binary digits, most significant first: `0` is a quarter rest and `1` is a C5 quarter note.
- Series `2` uses one measure. Read the file number minus one as `N` base-4 digits, most significant first: `0` is a quarter note, `1` a quarter rest, `2` two eighth notes, and `3` an eighth rest followed by an eighth note.
- All pitched notes are C5, with a Vocal part, treble clef, C major, and tempo 120. Quarter-only measures use divisions 4; measures containing eighths use divisions 8. Consecutive pitched eighths beam together, interrupted by rests, quarter notes, and barlines. In 4/4, beams also break at the half-bar; the other meters use whole-measure groups. Isolated eighth notes have no beam.
### MusicXML Contract
| Area | Accepted notation |