Esa Kataja
cdf37302d7
A bundle without a source block cannot be round-tripped, but its PDF can still be cut from scratch. Offer that instead of refusing: confirm, run detection, and line the markers up by position when the slice counts match exactly.
183 lines
8.0 KiB
Markdown
183 lines
8.0 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.
|
|
|
|
A bundle from a producer that does not record its cuts can still be opened, but
|
|
it is a fresh session rather than a round trip: it asks first, then cuts the PDF
|
|
from scratch with detection. The title block always comes back. Markers and
|
|
re-engraved systems land only if detection happens to find exactly as many
|
|
slices as the bundle has — the slices are in reading order on both sides, so
|
|
they can be lined up, but one system found or missed would shift every marker
|
|
onto the wrong slice, so in that case they are left off entirely and it says so.
|
|
`--detect` answers the question in advance, for scripts.
|
|
|
|
## 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.
|