Esa Kataja
630541c0cd
A first user hit a wall at the door: the README still said "design only, no code yet", and nothing anywhere said how to drive the editor. docs/guide.md walks one PDF to one bundle — install, the five per-page decisions, markers and jump targets, the title block, export — with a mouse/key table and the failures that actually happen. The README's stale status and installation lines go with it.
70 lines
3.5 KiB
Markdown
70 lines
3.5 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.
|
||
|
||
**New here? [docs/guide.md](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](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](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. |
|