Esa Kataja
61b8ec8301
A bundle was a one-way trip. The slice images are output and the cuts that produced them lived only in the producer's own project file, so a bundle someone handed you meant cutting the score again from scratch. The manifest now carries the geometry, in a `source` block: per page the cut polylines, skew, levels and content rectangle, all in normalised coordinates so they survive any render resolution, and per slice the page and slot it came from. Discards are stated by omission — a slot no slice claims was discarded — since shipping a discarded slice's image would defeat discarding it. `noteman-slicer open song.zip` unpacks the archived PDF, rebuilds the project from that geometry, restores markers, engravings and the title block, and opens the editor. Jump destinations go back from an array index to the (page, slot) the editor works in. The images in the zip are discarded: the PDF is what the pipeline renders from. Re-exporting a reopened bundle reproduces its manifest exactly. It refuses to overwrite a PDF or project file already sitting there, because the obvious place to unpack is where someone's unfinished cuts live. Separately, every slice can now carry the measure it starts at, not just a re-engraved one — a scanned system is numbered in the score the same way, and noteman wants to answer "take it from bar 33" about either. It moves off the replacement onto the page, alongside markers and discards, and out of the bundle's engraving object onto the slice.
noteman-slicer
Turns a score PDF into the ordered slice images 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.
New here? docs/guide.md walks you through making your first bundle.
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
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. LilyPond is optional and only enables re-engraving.
Then:
noteman-slicer edit my-song.pdf
Documentation
| docs/guide.md | How to use it: install, cut a score, place markers, export a bundle. Start here if you just want to make one. |
| CONTEXT.md | Glossary. What a slice, cut, discard, bundle and song scale actually mean here. Start here. |
| docs/spec.md | The specification: pipeline, geometry model, detection, editor, bundle format, and what noteman has to change. |
| 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 | The slicer owns all image processing; the bundle is the only channel to noteman. |
| ADR 0002 | Raster only in release 1 — measured SVG slice sizes and what they showed. |
| ADR 0003 | Lossless WebP beats every lossy option and every alternative format here. |
| ADR 0004 | No unattended mode: detection suggests, a human confirms. |
| ADR 0005 | PyMuPDF for all PDF access, accepting AGPL. |
| ADR 0006 | Systems are found by vertical brackets; row-darkness gaps get it wrong. |
| ADR 0007 | A project is spent once exported; reopening starts fresh. Reverses an earlier decision. |