Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Hold a lyric line until its last word has been read

Claudebf5753efa4a7
diff --git a/docs/HTML_COMPOSITIONS.md b/docs/HTML_COMPOSITIONS.md
index 0f30eb227a..65f91c5391 100644
--- a/docs/HTML_COMPOSITIONS.md
+++ b/docs/HTML_COMPOSITIONS.md
@@ -487,7 +487,8 @@ its copies and the faces at the document root; a document's own copy is kept.
Lines come from `PORTOS_MV.lyrics` with their aligned word times (or
`options.lines`), and every timing is read from the song data. Each line gets
one of four roles: `line` (default sung line: words rise and fade in on their
-onsets, the line drifts up and fades 0.3s after its last word), `hook` (wide
+onsets, the line drifts up and fades 0.3s after its last word ends, but never
+before that word has shown for 0.8s), `hook` (wide
caps centred in the zone, each word slams in on its onset, one outline-only
accent word with ink beneath its light outline, cut on the next beat),
`stamp` (a three-frame stamp with a small tilt, optional strike-through) and `data` (mono HUD caption whose numbers roll;
diff --git a/server/services/musicVideo/documentTemplates/shared/lyricType.js b/server/services/musicVideo/documentTemplates/shared/lyricType.js
index a440b7c9a4..822b8c3436 100644
--- a/server/services/musicVideo/documentTemplates/shared/lyricType.js
+++ b/server/services/musicVideo/documentTemplates/shared/lyricType.js
@@ -18,7 +18,8 @@
*
* Roles:
* line default sung line: words rise and fade in on their onsets, the line
- * drifts up and fades out 0.3s after its last word.
+ * drifts up and fades out 0.3s after its last word ends, once that
+ * word has shown for 0.8s.
* hook chorus / title phrases: wide caps, centred in the zone, each word slams
* in on its onset, one outline-only accent word, cut on the next beat.
* stamp short punches, negations, spoken lines: a three-frame stamp with a
@@ -50,7 +51,7 @@ const SECTION_LABEL_KINDS = [
export const LYRIC_TIMING = Object.freeze({
lineRiseSec: 0.2, lineRisePx: 16, lineExitDelaySec: 0.3, lineExitFrames: 8,
hookSlamSec: 0.22, hookSlamFrom: 1.35, stampFrames: 3, stampFrom: 1.25, stampTiltDeg: 2,
- strikeSec: 0.2, dataRollSec: 0.4, minOnScreenSec: 0.8, minPx: 56,
+ strikeSec: 0.2, dataRollSec: 0.4, minOnScreenSec: 0.8, lastWordHoldSec: 0.8, minPx: 56,
});
const clamp = (v, a = 0, b = 1) => Math.max(a, Math.min(b, v));
@@ -149,8 +150,10 @@ function wordsForLine(line, songWords = []) {
/**
* When a line leaves the screen. A line never shows before its first onset and
- * stays at least LYRIC_TIMING.minOnScreenSec unless another cue takes its zone.
- * `line`/`data` fade 0.3s after the last word ends, finishing by the next cue in
+ * stays at least LYRIC_TIMING.minOnScreenSec, and its last word at least
+ * LYRIC_TIMING.lastWordHoldSec, so a short final word is read before the line
+ * leaves; only another cue taking its zone cuts it sooner.
+ * `line`/`data` fade 0.3s after the last word ends (or once it has held), finishing by the next cue in
* their zone (or cutting at its onset when a full fade cannot fit). A `stamp`
* cuts after its hold; a `hook` cuts on the next beat (or at the next cue if that comes first), with no fade.
*/
@@ -159,7 +162,7 @@ function lineWindow(words, role, { beats = [], nextOnset = null, fps = 24, endSe
const onset = words[0].startSec;
const last = words[words.length - 1];
const lastEnd = Math.max(...words.map((w) => (finite(w.endSec) ? w.endSec : w.startSec)), finite(endSec) ? endSec : -Infinity);
- const minExit = onset + T.minOnScreenSec;
+ const minExit = Math.max(onset + T.minOnScreenSec, last.startSec + T.lastWordHoldSec);
if (role === 'hook') {
const sorted = beats.filter(finite);
const from = Math.max(lastEnd, last.startSec, minExit);
diff --git a/server/services/musicVideo/documentTemplates/shared/lyricType.test.js b/server/services/musicVideo/documentTemplates/shared/lyricType.test.js
index b5bd078f92..f0472b020b 100644
--- a/server/services/musicVideo/documentTemplates/shared/lyricType.test.js
+++ b/server/services/musicVideo/documentTemplates/shared/lyricType.test.js
@@ -62,13 +62,14 @@ describe('lyricType timing', () => {
expect(type.wordStates(verse, 1.6)[0]).toMatchObject({ alpha: 1, dy: 0 });
});
- it('exits a sung line 0.3s after its last word and cuts a hook on the next beat', () => {
- expect(verse.exitSec).toBeCloseTo(1.9 + 0.25 + 0.3, 6);
+ it('exits a sung line once its last word has held 0.8s and cuts a hook on the next beat', () => {
+ // "static" starts at 1.9: 0.3s past its end (2.45) would fade it before it is read.
+ expect(verse.exitSec).toBeCloseTo(1.9 + 0.8, 6);
expect(verse.endSec - verse.exitSec).toBeCloseTo(8 / 24, 6);
expect(type.linesAt(verse.endSec)).toEqual([]);
- // Last hook word ends at 5.15 (cue end 5.2): the next beat is 5.5, no fade.
- expect(hook.exitSec).toBe(5.5);
- expect(hook.endSec).toBe(5.5);
+ // Last hook word starts at 5.0, so it holds to 5.8: the next beat is 6, no fade.
+ expect(hook.exitSec).toBe(6);
+ expect(hook.endSec).toBe(6);
expect(hook.accent).toBe(3); // the longest word ("signal") is the outline-only accent
});
@@ -77,10 +78,24 @@ describe('lyricType timing', () => {
expect(quick.lines[0].exitSec).toBeCloseTo(2.8, 6);
});
+ // Uniquely catches a short final word fading out before it can be read (sung and released fast).
+ it('holds a short final word on screen until it has been read', () => {
+ const type = createLyricType({ render: { fps: 24 } }, { lines: [
+ { text: 'then changed the scene', role: 'line', zone: 'lower-left', words: [
+ { text: 'then', startSec: 2, endSec: 2.2 }, { text: 'changed', startSec: 2.2, endSec: 2.5 },
+ { text: 'the', startSec: 2.5, endSec: 2.6 }, { text: 'scene', startSec: 2.6, endSec: 2.7 },
+ ] },
+ ] });
+ const [line] = type.lines;
+ expect(line.exitSec).toBeCloseTo(3.4, 6);
+ expect(type.linesAt(3.39)).toEqual([line]);
+ expect(type.wordStates(line, 3.39)[3]).toMatchObject({ shown: true, alpha: 1 });
+ });
+
it.each([
{ role: 'line', nextRole: 'line', gap: 0.1, cut: true },
{ role: 'line', nextRole: 'data', gap: 1, cut: true },
- { role: 'data', nextRole: 'line', gap: 1.2, cut: false },
+ { role: 'data', nextRole: 'line', gap: 1.6, cut: false },
])('never overlaps a $role cue with the next $nextRole cue in its zone (gap $gap)', ({ role, nextRole, gap, cut }) => {
const onset = 2;
const nextOnset = onset + gap;
@@ -91,10 +106,7 @@ describe('lyricType timing', () => {
const [first, next] = type.lines;
expect(first.endSec).toBeLessThanOrEqual(nextOnset);
if (cut) expect(first.exitSec).toBe(nextOnset);
- else {
- expect(first.endSec).toBe(nextOnset);
- expect(first.endSec - first.exitSec).toBeCloseTo(8 / 24, 6);
- }
+ else expect(first.endSec - first.exitSec).toBeCloseTo(8 / 24, 6);
for (let frame = onset * 24; frame <= (nextOnset + 1) * 24; frame++) {
expect(type.linesAt(frame / 24).length).toBeLessThanOrEqual(1);
}
@@ -107,7 +119,7 @@ describe('lyricType timing', () => {
{ text: 'Example next', role: 'line', zone: 'lower-left', words: words('Example next', 2.1, 0.02) },
] });
expect(type.linesAt(2.3)).toEqual(type.lines);
- expect(type.lines[0].exitSec).toBeCloseTo(2.8, 6);
+ expect(type.lines[0].exitSec).toBeCloseTo(2.02 + 0.8, 6);
expect(type.lines[0].endSec - type.lines[0].exitSec).toBeCloseTo(8 / 24, 6);
});
@@ -128,7 +140,7 @@ describe('lyricType timing', () => {
{ text: 'Example stamp next', role: 'stamp', words: words('Example stamp next', 5.1, 0.02) },
] });
expect(type.lines[0]).toMatchObject({ exitSec: 2.1, endSec: 2.1 });
- expect(type.lines[2].exitSec).toBeCloseTo(5.8, 6);
+ expect(type.lines[2].exitSec).toBeCloseTo(5.02 + 0.8, 6);
expect(type.lines[2].endSec).toBe(type.lines[2].exitSec);
});
});