diff --git a/README.md b/README.md index e71b092..324a800 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,8 @@ A slice is one *system* — one full line of music across all voices, typically 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. -**Status: design only.** No code yet. The design is settled; see below. +**New here? [docs/guide.md](docs/guide.md) walks you through making your first +bundle.** ## How it works @@ -29,20 +30,25 @@ at it. ## Installation -Not yet installable. When it is: - ``` 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. +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. | diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..0a04e4c --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,145 @@ +# 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. **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 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. | +| 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.