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.
146 lines
6.1 KiB
Markdown
146 lines
6.1 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. **Set black and white points.** Pull the *White point* down until the paper
|
|
goes pure white and its texture disappears; pull *Black point* up until the
|
|
notes are solid black rather than grey mush. Scans need this; clean digital
|
|
PDFs usually don't.
|
|
|
|
Page Up / Page Down move between pages. Levels carry over from the previous
|
|
page, so a consistent scan only needs setting once.
|
|
|
|
## 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. 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`.
|
|
|
|
## 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
|
|
```
|
|
|
|
Every command takes `--type raster|vector` to override source-type detection.
|