noteman-slicer/docs/guide.md

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 D. Discarded slices show hatched. D 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. Under Page is the scan's own histogram: a hump of ink on the left, a hump of paper on the right, and two handles you drag. Put the white handle at the foot of the paper hump and the black one at the foot of the ink hump. The strip underneath shows the tone that results. 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. Arrow keys nudge the black point, Shift+arrows the white one.

The page rail across the top of the panel has one chip per page, with the number of slices on it underneath. Click to go there, or use Page Up / Page Down. A page whose count is far off its neighbours' is usually a page where detection missed a system. 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 D	discard it (or bring it back)
Drag the blue edges	resize the content rectangle
Shift-double-click a slice	re-engrave it
Page Up / Page Down	previous / next page
Ctrl+S	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 — drag it down onto the paper hump.
Notes have holes in them	The black point is too high — drag it left, off the ink hump.

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.