Esa Kataja
b8d93cee47
The bundle is documented as a standalone format rather than as a note between two programs: producers and consumers are generic, the marker vocabulary is defined musically rather than by what a viewer does with it, and image properties are stated as guarantees with the reasoning where it is not obvious. Anything that reads scores can implement it without knowing this tool exists. Taking that view changed the substance in three places. Marker types now carry their musical meaning rather than a UI mapping. The rule against re-importing became a statement about identity - indices mean something only within one bundle, so two bundles of a piece are independent documents. And forward-compatibility rules were added, which a protocol needs and a handover note did not: ignore unknown fields and marker types, refuse an unknown version. Tempo is now an integer, beats per minute, exported as a JSON number and omitted when blank; the editor accepts digits only. A figure can drive a metronome or a click track where a verbal marking cannot, and readers do not agree on what Andante means. This needs the consumer's column changed from free-form text, which the format document flags. Every figure in the document comes from a real export.
64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
# noteman-slicer
|
||
|
||
Turns a score PDF into the ordered slice images [noteman](../noteman) consumes,
|
||
plus the navigation markers that sit on them.
|
||
|
||
A slice is one *system* — one full line of music across all voices, typically
|
||
4–12 bars with lyrics intact. noteman displays them as a continuous vertical
|
||
scroll, so the slicer's job is to cut a printed page into systems, clean them up
|
||
enough to read on a tablet, and tag them with the score's navigation symbols.
|
||
|
||
**Status: design only.** No code yet. The design is settled; see below.
|
||
|
||
## How it works
|
||
|
||
Open a PDF, and the tool proposes cuts between systems, a skew correction, and a
|
||
content rectangle. You correct all of it — source quality varies too much for
|
||
unattended processing, so detection is an accelerator that nothing depends on
|
||
being right. You mark the header and footer regions discarded, set black and
|
||
white points until the paper disappears and the notes go solid, place the
|
||
rehearsal letters and jump markers, fill in the title block, and export.
|
||
|
||
Out comes one zip: the slices in order, their markers, the original PDF, and the
|
||
song metadata. That bundle is the only channel to noteman — there's no API
|
||
between the two tools.
|
||
|
||
Erasing previous-owner pencil marks, chord letters and breath marks stays in
|
||
GIMP. That's the irreducible manual part, and GIMP with a stylus is already good
|
||
at it.
|
||
|
||
## Installation
|
||
|
||
Not yet installable. When it is:
|
||
|
||
```
|
||
uv tool install --editable .
|
||
```
|
||
|
||
That puts a `noteman-slicer` command on PATH which runs from any directory — no venv to
|
||
activate. Dependencies (PyMuPDF, PySide6, OpenCV, numpy) are all wheels; nothing
|
||
needs a system package.
|
||
|
||
## Documentation
|
||
|
||
| | |
|
||
|---|---|
|
||
| [CONTEXT.md](CONTEXT.md) | Glossary. What a slice, cut, discard, bundle and song scale actually mean here. Start here. |
|
||
| [docs/spec.md](docs/spec.md) | The specification: pipeline, geometry model, detection, editor, bundle format, and what noteman has to change. |
|
||
| [docs/bundle-format.md](docs/bundle-format.md) | The Score Bundle Format — a standalone specification of the export format, independent of this tool. |
|
||
|
||
Deferred work is tracked as issues and milestones on the Gitea repo, not in this
|
||
tree.
|
||
|
||
Decisions that were expensive to reach, each with the evidence behind it:
|
||
|
||
| | |
|
||
|---|---|
|
||
| [ADR 0001](docs/adr/0001-slicer-owns-image-processing-bundle-is-the-only-channel.md) | The slicer owns all image processing; the bundle is the only channel to noteman. |
|
||
| [ADR 0002](docs/adr/0002-raster-only-svg-renderer-deferred.md) | Raster only in release 1 — measured SVG slice sizes and what they showed. |
|
||
| [ADR 0003](docs/adr/0003-lossless-webp-with-levels-and-alpha-quantisation.md) | Lossless WebP beats every lossy option and every alternative format here. |
|
||
| [ADR 0004](docs/adr/0004-detection-proposes-the-human-disposes.md) | No unattended mode: detection suggests, a human confirms. |
|
||
| [ADR 0005](docs/adr/0005-pymupdf-for-all-pdf-access.md) | PyMuPDF for all PDF access, accepting AGPL. |
|
||
| [ADR 0006](docs/adr/0006-systems-are-found-by-brackets-not-row-gaps.md) | Systems are found by vertical brackets; row-darkness gaps get it wrong. |
|
||
| [ADR 0007](docs/adr/0007-a-project-is-spent-once-exported.md) | A project is spent once exported; reopening starts fresh. Reverses an earlier decision. |
|