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.
174 lines
7.4 KiB
Markdown
174 lines
7.4 KiB
Markdown
# Making a bundle
|
|
|
|
Start to finish: a score PDF in, one `.zip` out that noteman can open. Fifteen
|
|
minutes for a typical four-page song, most of it spent nudging cuts.
|
|
|
|
## Install
|
|
|
|
```
|
|
uv tool install --editable .
|
|
```
|
|
|
|
That puts `noteman-slicer` on PATH; it runs from any directory. Everything it
|
|
needs is a wheel — no system packages. LilyPond is optional and only enables
|
|
re-engraving (below); without it the tool works the same minus that pane.
|
|
|
|
## The one command you need
|
|
|
|
```
|
|
noteman-slicer edit my-song.pdf
|
|
```
|
|
|
|
The editor opens on page 1 with detection's guesses already drawn: horizontal
|
|
**cuts** between the systems, a **skew** correction, and a blue **content
|
|
rectangle** marking what is music rather than page margin. All of it is a
|
|
starting point — detection is an accelerator, not an authority. Fix whatever is
|
|
wrong.
|
|
|
|
Your work is saved to `my-song.slicer.json` next to the PDF, automatically on
|
|
export and with Ctrl+S any time. Closing and reopening picks up where you left
|
|
off.
|
|
|
|
## What you do on each page
|
|
|
|
1. **Straighten it.** If the staff lines slope, turn the *Skew* dial until they
|
|
are level. The preview updates live.
|
|
2. **Fix the cuts.** One cut line per boundary between systems. Double-click to
|
|
add one, drag to move it, right-click to delete it. A cut is a polyline, not
|
|
a straight line — Ctrl-click on a cut adds a vertex, so it can bend around a
|
|
low-hanging lyric or a slur that crosses the gap. Right-click a vertex to
|
|
drop it.
|
|
3. **Discard what isn't music.** Page headers, footers, page numbers and title
|
|
blocks are slices too, and they should not reach the tablet. Click the slice,
|
|
press <kbd>D</kbd>. Discarded slices show hatched. <kbd>D</kbd> again brings
|
|
one back.
|
|
4. **Set the content rectangle.** Drag the blue edges so they hold the music and
|
|
nothing else. This is the horizontal crop for every slice on the page.
|
|
5. **Check black and white points.** These arrive proposed from the scan, like
|
|
the cuts do. If the paper still shows texture, pull *White point* down; if the
|
|
notes look grey rather than solid, pull *Black point* up. Getting this wrong
|
|
is the one mistake you cannot see until the bundle is on the tablet — grey ink
|
|
becomes half-transparent ink, and nothing downstream can rescue it.
|
|
|
|
Page Up / Page Down move between pages. Levels carry over from the previous
|
|
page, so a consistent scan only needs setting once.
|
|
|
|
## Bar numbers
|
|
|
|
Under *This slice*, **First bar** is the measure that slice starts at, as the
|
|
score numbers it. Optional, and only worth filling in where the printed score
|
|
shows a number — that is what lets noteman answer "take it from bar 33". A
|
|
re-engraved slice prints the number above its first bar, exactly as the scanned
|
|
systems around it do.
|
|
|
|
## Markers
|
|
|
|
Markers are the navigation symbols noteman uses to jump around the score:
|
|
rehearsal letters, section labels, segno, coda, fine, repeats, voltas, and the
|
|
D.S./D.C. instructions. They belong to a slice.
|
|
|
|
Select the slice, pick the type, type a label if the type takes one (rehearsal
|
|
letters, section labels and voltas do), and press **Add**.
|
|
|
|
Jump markers — *to coda*, *D.S. al coda*, *D.C. al fine* and friends — also need
|
|
a destination. After adding one, press **Set target…** and click the slice it
|
|
jumps to, on any page. That is what lets noteman follow the repeat structure
|
|
instead of just scrolling.
|
|
|
|
## The title block
|
|
|
|
Fill in the *Song* section. **Title is required** — export refuses without one.
|
|
The rest (subtitle, composer, original artist, arranger, lyricist, translator,
|
|
voices) is optional and travels with the bundle into noteman's library.
|
|
|
|
*Tempo* is beats per minute, a number, because a number can drive a metronome
|
|
and "Andante" cannot.
|
|
|
|
## Export
|
|
|
|
**Export bundle…**, choose where the `.zip` goes, done. It is named after the
|
|
song's title — *Bicycle Race* becomes `Bicycle-Race.zip`. Inside are the slice
|
|
images in order, their markers, the song metadata, and the original PDF as the
|
|
archive copy. That zip is the whole interface to noteman; hand it over and open
|
|
it there.
|
|
|
|
Two things worth knowing:
|
|
|
|
- **Shrink the original PDF…** offers to store the archived PDF as bilevel,
|
|
which is dramatically smaller for scans. It shows you a before/after crop
|
|
first — check that the staff lines survived. It never touches the slices.
|
|
- **An exported project is spent.** Reopening the same PDF starts fresh from
|
|
detection rather than resuming decisions that already shipped. If you really
|
|
want the old cuts back, `noteman-slicer edit my-song.pdf --resume`.
|
|
|
|
## Reopening a bundle
|
|
|
|
```
|
|
noteman-slicer open my-song.zip
|
|
```
|
|
|
|
Unpacks the archived PDF beside the bundle, rebuilds the project from it — the
|
|
cuts, skew, levels, discards, markers, title block and any re-engraved systems —
|
|
and opens the editor on it. Everything you changed re-renders from the PDF; the
|
|
slice images in the zip are output and are thrown away.
|
|
|
|
This works on any bundle, not just one you made: the cuts travel in `song.json`.
|
|
It refuses to overwrite a PDF or project file that is already there, since the
|
|
obvious place to unpack is exactly where someone's unfinished work lives — pass
|
|
`--pdf elsewhere.pdf` or `--force` if you mean it.
|
|
|
|
## Re-engraving a slice (optional, needs LilyPond)
|
|
|
|
When a system is beyond rescue — a bad scan, a wrong transposition, a passage
|
|
you want rewritten — shift-double-click it. A window opens where you enter the
|
|
music as LilyPond, one block per voice, render, and compare against the
|
|
original. Accept and the rendered version replaces that slice in the bundle.
|
|
|
|
The LilyPond you typed travels in the bundle alongside the image, so the passage
|
|
can be corrected and re-engraved later, or played, without the project file.
|
|
|
|
## Mouse and keyboard
|
|
|
|
| | |
|
|
|---|---|
|
|
| Double-click | add a cut |
|
|
| Drag a cut | move it |
|
|
| Ctrl-click a cut | add a vertex |
|
|
| Right-click | delete the cut or vertex under the cursor |
|
|
| Click a slice, then <kbd>D</kbd> | discard it (or bring it back) |
|
|
| Drag the blue edges | resize the content rectangle |
|
|
| Shift-double-click a slice | re-engrave it |
|
|
| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> | previous / next page |
|
|
| <kbd>Ctrl</kbd>+<kbd>S</kbd> | save the project |
|
|
|
|
## What the tool won't do
|
|
|
|
Erasing a previous owner's pencil marks, chord letters and breath marks. Do that
|
|
in GIMP before slicing — with a stylus it is quick, and no amount of thresholding
|
|
substitutes for it.
|
|
|
|
## When something looks wrong
|
|
|
|
| | |
|
|
|---|---|
|
|
| Detection found no systems, or one giant one | The score has no bracket joining the staves; add the cuts by hand. |
|
|
| "The PDF has changed since these cuts were made" | The file was edited or replaced under an existing project. The cuts probably no longer line up — re-cut. |
|
|
| Export says a title is required | Fill in *Song → Title*. |
|
|
| Slices look grey and washed out | The white point is too high. |
|
|
| Notes have holes in them | The black point is too high. |
|
|
|
|
## The command line
|
|
|
|
The editor is the tool; these exist for checking things quickly.
|
|
|
|
```
|
|
noteman-slicer info my-song.pdf # source type and page rasters
|
|
noteman-slicer detect my-song.pdf # detection results + debug overlays
|
|
noteman-slicer project my-song.pdf # what the project file currently holds
|
|
noteman-slicer export my-song.pdf # export without opening the editor
|
|
noteman-slicer open my-song.zip # unpack a bundle; --no-edit to stop there
|
|
```
|
|
|
|
Every command that takes a PDF takes `--type raster|vector` to override
|
|
source-type detection.
|