noteman-slicer/CONTEXT.md

# noteman-slicer — Context

A local, single-user tool that turns a score PDF into the ordered slice images
noteman consumes, plus the navigation markers that sit on them. It automates the
mechanical part of noteman's ingestion boundary; it does not replace GIMP for
erasing previous-owner annotations.

## Language

**Score source**:
The original PDF as distributed to the choir. Either **vector** (engraved by a
notation program) or **raster** (a flatbed scan of a printed page).
_Avoid_: original, input file

**Source type**:
Whether a score source is vector or raster. Determined once per PDF, not per
page; the slicer detects it and asks the user to confirm before routing.
_Avoid_: mode, format

**Slice**:
The atomic visual unit of a song — one *system*, one full line of music across
all voices, typically 4–12 bars with lyrics intact. Same definition as noteman's.
Structurally, a horizontal region of a page: a page begins as a single slice and
each cut splits one slice into two, so slices always tile the page with no gaps
and no overlap.
_Avoid_: segment, strip, row, band

**Discard**:
A flag on a slice meaning it produces no output. How headers, footers and blank
regions leave the song — they are slices that are simply not exported. Detection
pre-sets it on a page's top and bottom slice when they contain no system.
_Avoid_: delete, skip, exclude

**Slice image**:
The rendered artifact of a slice. From a raster source: lossless WebP, RGB pure
black, `alpha = 255 − luminance`, width capped at 1920px — paper is transparency,
ink is alpha. From a vector source: SVG with text converted to paths. Both are
display-ready as produced; nothing downstream reprocesses them.
_Avoid_: PNG, page image, tile

**Marker**:
A semantic tag placed on a slice for navigation. Vocabulary is noteman's enum
verbatim (`rehearsal_letter`, `section_label`, `segno`, `coda`, `fine`,
`repeat_start`, `repeat_end`, `volta`, `to_coda`, `ds_al_coda`, `ds_al_fine`,
`dc_al_coda`, `dc_al_fine`, `generic_jump`) and is shared coupling between the
two repos.

**Project**:
The persistent state of slicing one song: the source PDF it points at, its cuts,
discards, content rectangle, levels, staff-height overrides, markers and
metadata. Autosaved beside the PDF; the bundle is generated from it, so any
export can be regenerated without repeating human work. One PDF, one song, one
project, one bundle — never a many-to-one in any direction.
_Avoid_: session, document, edit list

**Bundle**:
The single compressed file that is the *only* channel between the slicer and
noteman. There is no API call, no direct upload. Carries the slice images in
order, their markers, the original PDF and the song-level text metadata.
Rehearsal MIDI and MP3s are deliberately out of the first bundle and stay
noteman's upload chore until a later phase.
_Avoid_: export, package, upload

**Marker label**:
The free text some markers carry — `rehearsal_letter` ("C"), `section_label`
("CHORUS"), `volta` ("1."). All other types are bare tags.

**Jump source**:
A marker that sends the reader elsewhere — `to_coda`, `ds_al_coda`,
`ds_al_fine`, `dc_al_coda`, `dc_al_fine`, `generic_jump`. Every jump source
stores its **target slice explicitly**; none is resolved by type at read time.
Authoring the target costs one click on a slice already on screen, and in
exchange the bundle is self-describing — no "exactly one Coda per song" rule
living unenforced in two repos, and a score with two codas simply works.
_Avoid_: link, reference, pointer

**Cut**:
A horizontal line placed on a page that splits one slice into two. Straight at
first; a later polyline form handles pages where systems slant or interleave.
Placement is forgiving — anywhere inside the whitespace gap yields the same
output, because trim crops to ink afterwards.
_Avoid_: split, divider, break

**Content rectangle**:
The region of a page that holds music. Set per PDF, adjustable per page, applied
before cutting. Everything outside it — scan-edge bands, spine shadows, margin
page numbers — is dropped. Handles margin junk structurally rather than
case-by-case, because margin junk is by definition outside the music.
_Avoid_: crop box, mask, margin

**Detection**:
Any automatic proposal the slicer makes — skew angle, cut positions, source
type, ink bounds. Detection is always a *suggestion*: the human confirms or
modifies every result before it is committed. Source quality varies too widely
for unattended processing to be trustworthy.
_Avoid_: auto-slicing, automatic mode

**Trim**:
Cropping a slice tight to its ink on all four sides, per slice. Normalises away
the left-margin drift between scanned pages, and flattens the engraved indent of
the first system — correct here, since the printed header it made room for is
stripped anyway. The viewer supplies margins with CSS padding.

**Staff height**:
The distance between a system's top and bottom staff line. The invariant a
reader perceives as "the notes are the same size", and therefore what slices are
normalised against — not their width. Falls out of the same row-darkness profile
used for cut detection. Manually overridable, since it is detected on the same
speckled scans where detection already struggles.

**Song scale**:
Two steps, both per song, never per slice. First every slice is normalised to a
common staff height, so a rescanned page or a re-engraved slice sits at the same
note size as its neighbours. Then the whole song is scaled uniformly so its
widest slice lands at 1920px — a ceiling, never a target: a song that comes out
narrower stays narrower, because upscaling a scan past its real resolution buys
softness and bytes and no detail.

**Right pad**:
The transparent space added to the right of every slice narrower than the widest,
bringing all slices in a song to the same width. Keeps the music the same size
and flush left; a short system simply ends earlier.