khodowany
109 lines
6.9 KiB
Markdown
109 lines
6.9 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.
|
|
|
|
Editor settings live in `modulus.json` under `tooling.editor`. Modulus generates the ignored `.clangd`, `.clang-format`, and `pyrightconfig.json` files; edit the JSON settings rather than these outputs. The clangd configuration routes Zero/shared code to the native compile database and Pico code to its firmware database.
|
|
|
|
Modulus also generates `.nvim.lua` for Neovim 0.11+ with `exrc` enabled. Review and trust it when Neovim asks; it preserves the existing LSP capabilities/keybindings and runs clangd 19 in the build container for this repo. Run `python3 modulus.py lsp` once to prepare both databases and the shared read-only header cache. Other editors can use `python3 modulus.py clangd` as their language-server command. Startup never downloads or builds anything, and never falls back to host clangd.
|
|
|
|
`tooling.lsp.clangd` configures the server executable, arguments, trusted compiler paths, and additional header roots. Product Vamp adds the bare-metal ARM compiler and `/opt/pico-sdk`; standard-library and SDK definitions open from an image-keyed cache under `$XDG_CACHE_HOME/modulus/clangd` (default `~/.cache/modulus/clangd`). Set `tooling.editor.nvim.enabled` to `false` for a hand-managed editor setup. Existing unowned `.nvim.lua` files are preserved.
|
|
|
|
## 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
|
|
|
|
Uncompressed MusicXML 3.1/4.0 scores exported from MuseScore live 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`.
|
|
The pinned build-only dependencies are in `tools/requirements.txt`. Configure/build automatically refresh the project build image when this file changes; direct builds must install it in their Python environment.
|
|
|
|
The build-time pipeline is MuseScore -> `.xml` -> musical model -> automatic arranger/transposer -> schema-v3 JSON and engraved PNG pages. The Pi displays pages without interpreting notation. Performance sources produce acoustic, electric, and vocal parts; melody exercises produce twelve tonic variants, and chord exercises keep their authored key. Independent voices and exact pitch/rhythm remain in the semantic JSON.
|
|
|
|
Code style is managed by Modulus. Run `./modulus.py format` to format C++ and Python, or `./modulus.py format --check` to check formatting and prohibited aliases. The project-local Neovim integration routes Conform formatting through the same container tools, including format on save and existing LazyVim toggles. Run configure first when the image or exported tooling needs updating. Use `tooling.editor.clang_format` for C++ overrides and `tooling.format.exclude` for project-relative exclusion globs; do not edit generated `.clang-format` files.
|
|
|
|
See [Score Generation](TECHNICAL_GUIDE.md#score-generation) for supported MusicXML notation, Vamp properties, schema details, and diagnostics. There is no compact-JSON source format or legacy runtime adapter. Unsupported notation fails generation before existing assets are replaced.
|
|
|
|
Build-time engraving uses pinned MuseScore Studio 4.7.4 and the OTF Petaluma fonts in `package/assets/fonts/petaluma`. The managed Docker image and CI install the checksum-verified engraver automatically. For a direct host build, run `python3 tools/install_engraver.py build/build_common/musescore` and set `VAMP_MUSESCORE` to the printed executable path. Unsupported or unfaithfully exported notation fails the build rather than being approximated.
|
|
|
|
Petaluma is from Steinberg under the SIL Open Font License. Runtime packages include PNG score pages, `PetalumaScript.otf` for UI text, and `OFL.txt`; the music font and engraver stay build-only.
|
|
|
|
Font generation requires Pillow's Raqm layout support to preserve kerning. On Debian/Ubuntu, install `libfribidi0` alongside the pinned Python requirements. The build image and CI install both. See [Pillow's installation requirements](https://pillow.readthedocs.io/en/stable/installation/basic-installation.html).
|
|
|
|
Native and Pico builds generate their bitmap font implementation under `generated/vamp_style/font.cpp` in the build directory. The generated implementation is not checked in. The build image and CI install the pinned generator dependency automatically. For a direct build, first run:
|
|
|
|
```sh
|
|
python3 -m pip install -r tools/requirements.txt
|
|
```
|
|
|
|
To check a generated atlas, run `python3 tools/generate_pico_font.py --output build/build_x86_debug/generated/vamp_style/font.cpp --check`. Changing the source OTF or generator rebuilds the atlas automatically.
|
|
|
|
## License
|
|
|
|
Product Vamp is released under the MIT License. Bundled third-party fonts keep their own licenses next to the font files.
|