# Open Lyric Alignment overview

## Outcome

OLA defines lyric-alignment semantics that ordinary MIDI lyric events do not
carry, without replacing MIDI or putting MIDI constraints into the core model.

```text
OLA document
|-- voices
|-- lanes
|   `-- lines
|       `-- arbitrary cues
|-- targets
|-- timeline mappings
|-- per-lane, per-target alignment sets
|   |-- shared redundant note links
|   |-- cue placements and anchors
|   `-- explicit line-boundary placements
|-- provenance
`-- namespaced extensions
```

The same document can be serialized as lossless OLA JSON, embedded in an SMF,
or carried by a future MusicXML or audio-package binding. In SMF, standard lyric
events remain the compatibility projection.

## Why the hierarchy is explicit

Voices identify performers or vocal roles. A lane is one ordered lyric stream
and names its normal voices. Lines preserve display and paragraph structure.
Cues are the smallest author-selected alignment units inside a line. A cue can
be a line, phrase, word, syllable, breath, laugh, hum, or another fragment.

This permits line-level automatic alignment today and selective word- or
syllable-level refinement later without changing the document model. Repeated
chorus occurrences receive separate line and cue IDs so each occurrence can be
corrected independently.

## Why placements are separate

An alignment set places one lane against one target. Text does not contain MIDI
ticks or recording times. The same lane can therefore have independent
alignment sets for a score and recording. A timeline mapping can relate those
targets without replacing either placement set.

Each placement retains a resolved range. Note links are redundant, durable
structural locators shared by any number of cues and anchors. Advisory anchors
guide realignment. Hard anchors are manual constraints and cannot be moved
silently.

Line and paragraph boundaries are not empty lyric cues. A line declares its
boundary kind, and each target alignment may place that boundary explicitly.
This preserves a lyric-free gap without pretending the gap is sung text.

## Compatibility is additive

OLA-SMF embeds complete JSON in Sequencer-Specific events and independently
emits one primary lane in standard `FF 05` Lyric events. Software that ignores
OLA still receives useful lyrics. OLA-aware software receives Unicode text,
voices, line structure, range ends, confidence, provenance, timeline mappings,
shared note links, and hard/manual constraints.

Strict RP-017 output is used when cues carry representable syllable and word
information. Coarser phrase or line output remains available without fabricating
syllable timing.

## Failure is visible and recoverable

The SMF target binding keeps separate hashes for note topology, tempo mapping,
and the generated lyric projection. A reader can distinguish changed notes,
changed tempo, and external lyric edits. A corrupt, unsupported, or ambiguous
OLA payload never prevents playback or standard-lyric fallback.

## Typical authoring flow

1. Author voices, lanes, lines, and cues.
2. Place a lane automatically against one or more targets.
3. Review low-confidence placements and split only the cues needing finer
   control.
4. Create shared note links and hard-anchor corrected edges.
5. Re-run automatic alignment while preserving hard anchors.
6. Write OLA JSON and regenerate the target compatibility projection together.

## Explicit non-goals for 0.1

OLA 0.1 does not require or define:

- an automatic-alignment algorithm;
- syllable-level segmentation;
- a single singer, language, target, or recording;
- one global MIDI-to-audio warp;
- score-repeat interpretation;
- compression, signatures, encryption, or trust policy;
- mandatory audio fingerprints;
- MusicXML as the canonical authority;
- an editor interface; or
- an importer for an experimental Keyfire lyric manifest.

Standard `FF 05` ingestion is ordinary MIDI interoperability, not a legacy
Keyfire import path.