khodowany
110 lines
4.3 KiB
Markdown
110 lines
4.3 KiB
Markdown
# Product Vamp
|
|
|
|
Product Vamp is a two-device sheet-music appliance.
|
|
|
|
- Raspberry Pi Zero 2 W hosts the control Wi-Fi AP, runs the display/control service in Docker, and drives a Waveshare Zero-DISP-7A 1024x600 touch display.
|
|
- Raspberry Pi Pico 2 W runs UF2 firmware for a Waveshare 2-inch capacitive touch LCD and sends menu/page commands over the Zero-hosted AP.
|
|
|
|
The Zero ensures the current SQLite schema through Noto, then imports generated score assets at startup. Runtime navigation and rendering use Ligo for the HTTP API, Luma for touch UI rendering, and Modulus for shared build/runtime utilities.
|
|
|
|
Pico controls:
|
|
|
|
- Tap: next menu item or next score page.
|
|
- Double tap: previous menu item or previous score page.
|
|
- Tap and hold: select the highlighted mode/song/part/practice row/key, or return from score view to the previous menu.
|
|
|
|
## Build
|
|
|
|
Configure and build the native development target:
|
|
|
|
```sh
|
|
python3 modulus.py configure
|
|
python3 modulus.py build
|
|
```
|
|
|
|
Release verification:
|
|
|
|
```sh
|
|
python3 modulus.py configure --target x86_64_gcc12_release
|
|
python3 modulus.py build --target x86_64_gcc12_release
|
|
```
|
|
|
|
Configure/build can read public packages anonymously from the khodo Conan registry.
|
|
|
|
Refresh clangd compile databases, including the Pico firmware database, with:
|
|
|
|
```sh
|
|
python3 modulus.py lsp
|
|
```
|
|
|
|
When running directly outside the generated Modulus Docker image, set `PICO_SDK_PATH` before refreshing the Pico database.
|
|
|
|
## Package
|
|
|
|
Product packaging targets Raspberry Pi OS/Debian trixie on ARM64 and optionally builds Pico firmware. Set `PICO_SDK_PATH` when building the firmware artifact:
|
|
|
|
```sh
|
|
PICO_SDK_PATH=/path/to/pico-sdk python3 modulus.py package --version latest --update
|
|
```
|
|
|
|
The package command creates:
|
|
|
|
```text
|
|
build/packages/product-vamp-latest-arm_64_gcc12_release.tar.gz
|
|
build/packages/product-vamp-latest-arm_64_gcc12_release.tar.gz.sha256
|
|
```
|
|
|
|
The tarball contains the Zero Docker archive, Pi install scripts, generated score assets, and Pico UF2 firmware.
|
|
|
|
Publishing the rolling generic package requires credentials only for upload:
|
|
|
|
```sh
|
|
PACKAGE_REGISTRY_USER=<user> \
|
|
PACKAGE_REGISTRY_TOKEN=<token> \
|
|
python3 package/scripts/publish_latest_generic_package.py
|
|
```
|
|
|
|
Artifacts are published to the khodo generic package registry.
|
|
|
|
## Score Assets
|
|
|
|
Source score JSON lives in `data/`. Generated score JSON is not committed. To inspect generated assets without building the full package, run:
|
|
|
|
```sh
|
|
python3 -m generator --data-dir data --output-dir /tmp/product-vamp-generated --static-assets-dir package/assets --clean --check
|
|
```
|
|
|
|
The `--check` path compares generation invariants against `data/expected/performance_summary.json`.
|
|
|
|
Authored score files use compact JSON. Metadata stays as normal JSON fields, while each measure is a readable notation string. The optional `style` field must be a supported built-in player style; compact aliases `Med.`, `Med. Swing`, and `Medium` normalize to `Medium Swing`.
|
|
|
|
```json
|
|
{
|
|
"title": "Autumn Leaves",
|
|
"key": "F",
|
|
"time": "4/4",
|
|
"clef": "treble",
|
|
"part": "Vocal",
|
|
"role": "vocal",
|
|
"measures": [
|
|
"[G-7] Bb4:1~ \"leaves\"",
|
|
"[C7] ~Bb4:4 C4:4 \"drift\" D4:4 \"by\" E4:4 \"my\"",
|
|
"{5:2 C4:4 D4:4 E4:4 F4:4 G4:4}",
|
|
"[G7] (G4 B4 F5):4 r:4"
|
|
]
|
|
}
|
|
```
|
|
|
|
Notation tokens are `PITCH:DURATION`, `r:DURATION`, and `(PITCH PITCH ...):DURATION` for written chord tones. Durations use `1`, `2`, `4`, `8`, `16`, `32`, plus `.` for dotted values. `[Chord]` applies to the next token, `[(Chord)]` marks an optional turnaround chord that is used between generated performance iterations but omitted from the final ending, quoted text applies as a lyric to the previous note, `~` starts or ends ties, and `{N:M ...}` writes tuplets such as five quarter notes in the space of two quarter notes. A measure may also be an object with `notes` plus MusicXML-style metadata fields such as `attributes`, `directions`, `harmony`, or `barlines`.
|
|
|
|
Bundled third-party font assets live in `package/assets/fonts/petaluma`. Petaluma is from Steinberg and is distributed under the SIL Open Font License; the package keeps `OFL.txt` next to the font files. If the Pico bitmap font needs to be refreshed after changing the bundled UI font, run:
|
|
|
|
```sh
|
|
python3 tools/generate_pico_font.py
|
|
python3 tools/generate_pico_font.py --check
|
|
```
|
|
|
|
## License
|
|
|
|
Product Vamp is released under the MIT License. Bundled third-party fonts keep their own licenses next to the font files.
|