# Open Lyric Alignment core model 0.1

## 1. Scope

This document defines the target-neutral semantic model. It does not define a
wire encoding. [JSON 0.1](json-v0.1.md) is the normative representation and
[SMF 0.1](smf-v0.1.md) is one transport and target binding.

## 2. Document header

An OLA Core 0.1 document has:

- `format` equal to `open-lyric-alignment`;
- `version` equal to `0.1`;
- a stable `documentId`;
- a non-negative signed 64-bit `revision`;
- optional `defaultLanguage`;
- collections of voices, lanes, targets, alignment sets, timeline mappings,
  and provenance; and
- a top-level namespaced `extensions` object.

`documentId` is an OLA ID, not necessarily a UUID. An SMF-embedded OLA document
has the additional UUID requirement in the SMF binding. A writer that changes
semantically meaningful content MUST increase `revision`. Re-serializing
unchanged values does not require a new revision.

## 3. IDs and references

Every ID is 1 through 128 printable, non-whitespace ASCII characters. IDs for
the document and every voice, lane, line, cue, target, alignment set, mapping,
provenance record, note link, placement, anchor, and boundary MUST be globally
unique in the document.

Every reference MUST resolve. An editor SHOULD preserve IDs for unchanged
objects. Splitting or merging a line or cue creates new IDs; one old ID MUST NOT
be silently reused for several new semantic objects.

## 4. Voices

A voice identifies a singer, character, ensemble role, or other performer
identity. It has `id` and optional `label`, `role`, `language`, and `performer`.
Role is an open token. A document may contain no voices when performer identity
is unknown or irrelevant.

## 5. Lanes, lines, and cues

A lane is one ordered lyric stream. It contains:

- `id`;
- zero or more `voiceIds` naming its normal performers;
- optional `label`, `role`, and `language`;
- `isPrimary`, a display and compatibility-projection preference; and
- one or more ordered lines.

A document MUST contain at least one lane. Common open lane roles include
`lead`, `background`, `duet`, `translation`, `transliteration`, and `phonetic`.
Multiple lanes may overlap in time.

A line contains:

- `id`;
- optional `label` and stable `sectionId`;
- `breakAfter`: `none`, `line`, or `paragraph`; and
- one or more ordered cues.

`sectionId` is a grouping label, not a score-repeat instruction.

A cue is an occurrence, not a reusable text dictionary entry. It contains:

- `id` and non-empty canonical Unicode `text`;
- optional printable-ASCII `fallbackTextAscii` supplied by the author;
- exact `separatorAfter`, which defaults to the empty string;
- optional `voiceIds` overriding the lane voices for that cue;
- optional `wordPosition`: `single`, `begin`, `middle`, or `end`;
- optional exact `elisionAfter` text;
- optional open `vocalization`, such as `spoken`, `hummed`, `laughed`, or
  `breathed`;
- optional open `kind`, such as `line`, `phrase`, `word`, or `syllable`; and
- optional provenance reference.

Concatenating each cue's `text`, `elisionAfter` when present, and
`separatorAfter` in line order reconstructs the canonical line text without
inferred spaces or normalization. Lyric text, separators, and elisions MUST NOT
contain control characters or line breaks.

Empty cues are invalid. A timed line or paragraph gap is represented by a line
boundary placement, not empty text.

## 6. Targets

A target identifies media against which lyrics are placed. It contains:

- `id`, open `kind`, and optional `label`;
- one required `timeUnit`, such as `tick`, `microsecond`, or `sample`;
- optional positive `ticksPerQuarterNote` or `sampleRate`; and
- a `binding` object.

The binding has optional hashes:

- `exactSha256` for complete stable, non-circular target bytes;
- `noteTopologySha256` for normalized anchor-relevant notes;
- `tempoMapSha256` for the normalized tempo map; and
- `lyricProjectionSha256` for the generated compatibility lyrics.

A complete-file hash is provenance only when embedding OLA would make it
circular. Target bindings may retain additive binding-specific properties.

Every target position has `unit` exactly equal to the target's `timeUnit` and a
non-negative signed 64-bit `value`.

## 7. Timeline mappings

A timeline mapping relates two targets without changing either target's own
placements. It has source and destination target IDs, at least two mapping
points, origin, optional confidence, and optional provenance.

Each mapping point contains one source position in the source target's unit and
one destination position in the destination target's unit. Adjacent points MUST
NOT be identical. Producers SHOULD order points monotonically unless the
declared mapping semantics explicitly state otherwise in an additive property.

## 8. Alignment sets

An alignment set places exactly one lane against exactly one target. It has:

- `id`, `laneId`, and `targetId`;
- optional `timelineMappingId`, which must include the alignment target;
- zero or more provenance references;
- shared `noteLinks`;
- cue `placements`; and
- explicit line `boundaries`.

Multiple alignment sets may exist for different lanes and targets. Products
that retain competing candidates SHOULD express their selection policy outside
the 0.1 core rather than silently merging them.

## 9. Shared note links

A note link is a durable, redundant structural locator local to its alignment
set. Placements and anchors reference it by ID, permitting many cues to share a
note and one cue to link to many notes.

A note link contains:

- `trackIndex`;
- optional `trackFingerprint`;
- optional exact `noteOnEventIndex`;
- structural `attackOrdinal`;
- absolute `tick`;
- MIDI `channel`, `pitch`, and same-location `occurrence`;
- optional `durationTicks`; and
- optional nearby note context as signed `deltaTick`, channel, and pitch.

Track indexes, event indexes, ordinals, ticks, occurrences, and durations are
non-negative. Channels are 0 through 15 and pitches 0 through 127. A
runtime-assigned note object ID is not a portable locator.

An SMF binding defines conservative resolution and rebinding behavior.

## 10. Cue placements

A placement contains:

- `id` and a `cueId` belonging to the alignment set's lane;
- required `resolvedRange` with start and optional end;
- zero or more shared `noteLinkIds`;
- zero or more anchors;
- `origin`: `automatic`, `manual`, or `imported`;
- `reviewState`: `unreviewed`, `accepted`, `needs-review`, or `rejected`;
- optional confidence from 0 through 1; and
- optional provenance reference.

The resolved range is always the playback and fallback position. Its start and
end use the target unit, and end MUST NOT precede start. A zero-length range is
valid for an instantaneous cue. Within one alignment set, placements for the
same cue and position unit MUST NOT have overlapping resolved ranges.

Confidence is producer evidence, not a universal probability. Consumers MUST
NOT invent a confidence value when none was supplied.

## 11. Anchors

An anchor constrains or describes a placement edge. It has:

- `id`;
- `edge`: `start` or `end`;
- `strength`: `advisory` or `hard`;
- `origin`;
- optional resolved target `position`;
- zero or more shared `noteLinkIds`; and
- optional signed `offset` with its own unit.

An anchor MUST contain a position or at least one note-link reference. An
advisory anchor may move during automatic realignment. A hard anchor is an
authorial constraint: an automatic operation MUST preserve its linked target
and offset unless the user explicitly removes, unlocks, or edits it.

If a hard note anchor cannot be resolved uniquely, the consumer retains the
placement's resolved range and presents the conflict for review. It MUST NOT
silently choose another chord member or overlapping note.

## 12. Explicit boundary placements

A boundary placement assigns target time to a line whose `breakAfter` is `line`
or `paragraph`. It contains `id`, `lineId`, position, origin, review state,
optional confidence, and optional provenance.

A line can have at most one boundary in an alignment set, and the line must
belong to that set's lane. A line with placed cues and a declared break SHOULD
have an explicit boundary. A boundary MUST NOT precede any cue-placement start
for that line in the same target unit. A missing boundary is recoverable and may
be derived by a projection profile, but validators SHOULD warn.

## 13. Provenance

A provenance record contains `id`, open `kind`, non-empty `agent`, optional
version and creation time, optional absolute source URI and SHA-256, and an open
JSON `details` object. An algorithm name belongs here rather than in OLA
conformance rules.

Producers SHOULD avoid private absolute paths, account identifiers, or media
fingerprints unless the user intentionally includes them. A checksum proves
byte equality, not ownership, permission, or authenticity.

## 14. Versions, capabilities, and additive data

The 0.1 format and version strings are exact. A 0.1 reference reader rejects a
different version as an authority. Future versions must state their own
compatibility rules; an unsupported version may still be preserved as opaque
data by a container binding.

Every core object may retain additive JSON properties from a later compatible
minor revision. Unknown additive properties MUST be ignored semantically and
SHOULD be preserved when rewriting. They cannot change the meaning of a 0.1
core field.

Deliberate optional capabilities use absolute URI keys in the top-level
`extensions` object. Unknown extensions MUST be ignored and preserved. A
capability required for safe interpretation cannot be introduced as an optional
0.1 extension; it requires a version whose processing rules advertise that
requirement.

## 15. Core semantic validation checklist

Beyond representation-schema validation, a conforming validator checks:

1. Global ID uniqueness and all references.
2. At least one lane, one line per lane, one non-empty cue per line.
3. Cue voice and provenance references.
4. Position units and non-negative range ordering against each target.
5. Timeline mapping target references and point counts.
6. Alignment-set lane ownership for cues and boundaries.
7. Local note-link references and MIDI value ranges.
8. Anchor target evidence and hard/advisory semantics.
9. Explicit boundary uniqueness and line break eligibility.
10. Confidence, hash, URI, text, resource-limit, and extension constraints.