# OLA RP-017 portable profile 0.1

## 1. Purpose

This profile projects the sole primary OLA lane into Standard MIDI File Lyric
meta events (`FF 05`) using MIDI Recommended Practice RP-017 conventions. It
provides predictable interchange while the embedded OLA document retains richer
semantics.

The MIDI Association publishes RP-017 as the
[SMF Lyric Meta Event Definition](https://midi.org/smf-lyric-meta-event-definition).
That document remains authoritative for RP-017 itself.

## 2. Profile names

- **OLA-RP017-Portable-Syllabic-0.1** is a strict profile claim. Every lexical
  cue is a syllable with explicit word position and portable ASCII output.
- **OLA-FF05-Coarse-0.1** is a compatibility fallback, not an RP-017 conformance
  claim. Phrase or line cues are emitted at known starts without fabricated
  syllable timing.

Every OLA-SMF file has a primary projection, but only eligible files claim the
strict profile.

## 3. Primary lane and target

Exactly one lane has `isPrimary: true`. It has one alignment set for the SMF
target. The target uses `kind: "smf"`, `timeUnit: "tick"`, and its placements
and boundaries use `unit: "tick"`.

Other lanes remain losslessly in OLA JSON. A writer MAY emit additional
best-effort lyric tracks named for those lanes, but generic consumers are
guaranteed only the primary projection. Additional tracks are outside
`lyricProjectionSha256`.

## 4. Character repertoire and explicit fallback

Strict portable event content uses RP-017's accepted ASCII repertoire. Letters,
digits, ASCII space, and the punctuation listed by RP-017 are accepted. The
reserved characters `\\`, `[`, `]`, `{`, and `}` are excluded. CR and LF appear
only in standalone boundary events.

For each cue, the writer uses canonical `text` when it is printable ASCII;
otherwise it uses author-supplied `fallbackTextAscii`. If neither is available,
strict projection is impossible. The writer MUST NOT silently transliterate,
replace characters with `?`, or discard canonical text.

`elisionAfter` must also be printable ASCII to participate in the strict
projection. It is appended immediately after selected cue text.

## 5. Syllable and word mapping

In the syllabic profile, every cue has `kind: "syllable"` and produces exactly
one `FF 05` event at its placement's `resolvedRange.start.value` tick.

When one syllable cue has additional non-overlapping placements, its first
placement emits the selected syllable text and every later placement emits an
empty `FF 05` melisma event. An empty event is never represented as an empty OLA
cue.

`wordPosition` and `separatorAfter` agree as follows:

| Word position | Meaning | Required `separatorAfter` | Event trailing space |
|---|---|---|---|
| `begin` | First syllable of a multisyllable word | empty | no |
| `middle` | Internal syllable | empty | no |
| `end` | Last syllable | one ASCII space | yes |
| `single` | Complete one-syllable word | one ASCII space | yes |

Punctuation belongs in cue text or a representable elision. Any other
`separatorAfter` is not strict RP-017 portable data.

The coarse profile emits one event per cue at its resolved start using selected
ASCII text, representable elision, and separator. It preserves known timing but
does not claim that an event is one syllable.

## 6. Line and paragraph controls

Line structure comes from `line.breakAfter`; target timing comes from the
alignment set's explicit `boundaries` collection:

- `breakAfter: "line"` emits a standalone CR event with data byte `0D`.
- `breakAfter: "paragraph"` emits a standalone LF event with data byte `0A`.
- `breakAfter: "none"` emits no boundary event and cannot have an explicit
  boundary placement.

A paragraph LF is sufficient; no additional CR is emitted for that boundary.

When an eligible line lacks an explicit boundary, a coarse writer may derive
the boundary tick in this order:

1. the last cue placement's explicit resolved end;
2. the next line's first projected cue start, ordered before that event; or
3. End-of-Track for the final line.

Strict profile authors SHOULD provide every boundary explicitly. An explicit
boundary preserves deliberate lyric-free gaps. Empty lyric cues are invalid OLA
and are never needed as controls.

When boundary and next lyric share a tick, CR or LF precedes the next lyric in
track event order. Cues sharing a tick retain line and cue order.

## 7. Track requirements

The primary projection is in the OLA track for Type 1 and the sole track for
Type 0. The track SHOULD be named `Open Lyric Alignment`.

Writers emit `FF 05`, not generic Text events (`FF 01`). They do not emit Soft
Karaoke `@` headers or `/` and `\` line prefixes. Separate import/export profiles
may support those conventions, but they are not RP-017 portable output.

## 8. Projection generation and conflicts

The projection is regenerated from the primary lane and its SMF alignment set
whenever the OLA document is saved. Its raw event bytes are covered by target
binding `lyricProjectionSha256`.

If the current `FF 05` hash differs from the embedded hash, the file has an
external lyric edit. A writer MUST NOT overwrite that edit merely because the
embedded OLA payload is valid. It requires explicit reconciliation, after which
both representations are regenerated together.

## 9. Import behavior

An OLA implementation may ingest standard `FF 05` lyrics into a new OLA
document. It preserves event ticks and raw text evidence where possible and
labels uncertain segmentation as coarse. It MUST NOT infer syllable boundaries
merely from multiple events when the source convention is unknown.

The reference deterministic importer assigns an RFC 4122 version-5
`documentId` in namespace `6b5d9f0e-2e9b-4f31-8bca-91d8fe487c1a`. Its name is
the lowercase ASCII hexadecimal SHA-256 of the canonical `FF 05` projection
stream. Implementations using this recipe produce the same ID for the same
projection; other importers may assign a different conforming UUID.

Standard-MIDI import neither recognizes nor depends on a prior Keyfire-specific
`FF 7F` payload.

## 10. Strict conformance checklist

A file claiming OLA-RP017-Portable-Syllabic-0.1 has:

1. Exactly one primary lane and one SMF alignment set for it.
2. One placed `syllable` cue per non-control lyric event, with any later
   placements for that cue emitted as empty melisma events.
3. Printable ASCII canonical or explicit fallback text.
4. Explicit word position and matching separator semantics.
5. Standalone CR and LF controls with specified timing and order.
6. No `FF 01`, Soft Karaoke headers, or slash-based line controls in the
   primary projection.
7. A valid embedded OLA document whose target `lyricProjectionSha256` matches
   the generated event stream.