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

Keep lyrics off the title card's corner while it shows (#11632)

[._.]/d4eb166da862
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
index 85a6c14177..266ede2308 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.jsx
@@ -1,6 +1,6 @@
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { Pause, Play } from 'lucide-react';
-import { normalizeTitleCard } from '../../../../server/lib/musicVideoTitleCard.js';
+import { normalizeTitleCard, titleCardVisible, titleCardWindows } from '../../../../server/lib/musicVideoTitleCard.js';
import useMounted from '../../hooks/useMounted.js';
import useGeneratedPreview from '../../hooks/useGeneratedPreview.js';
import ShotStepper, { shotSteps } from './ShotStepper.jsx';
@@ -9,12 +9,14 @@ import FrameStepper from './FrameStepper.jsx';
const buttonCls = 'flex items-center gap-1 bg-port-bg border border-port-border rounded px-2 py-1.5 text-sm min-h-[44px] sm:min-h-0 disabled:opacity-50';
// What the lyric playthrough page is built from: the song length, the word times,
-// the sheet's sections and the shots' timing and text zones. A change rebuilds it.
+// the sheet's sections, the shots' timing and text zones, and the title card's spot. A change rebuilds it.
export const playthroughVersion = (project) => JSON.stringify([
project.audioAnalysis?.durationSec ?? null,
(project.lyricCues || []).map((cue) => [cue.text, cue.startSec, cue.endSec, (cue.words || []).map((w) => [w.startSec, w.endSec])]),
(project.lyricMarkers || []).map((m) => [m.type, m.label, m.line]),
(project.scenes || []).map((s) => [s.startSec, s.endSec, s.textZone, s.lyricRole, s.lyricSize]),
+ // The lyrics step off the title card's corner while it shows.
+ titleCardVisible(project.titleCard) ? [project.titleCard.position, titleCardWindows(project.titleCard)] : null,
]);
/** The lyric line sung at song time `t`, from the project's timed cues. */
diff --git a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
index 62b61a1bad..d3f6bc2525 100644
--- a/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
+++ b/client/src/components/musicVideo/CompositionPreviewPlayer.test.jsx
@@ -45,7 +45,7 @@ vi.mock('../../services/socket', () => ({ default: socket }));
const uploadGalleryImage = vi.hoisted(() => vi.fn(async () => ({ filename: 'upload-1234abcd.png' })));
vi.mock('../../services/apiSystem.js', () => ({ uploadGalleryImage }));
-import CompositionPreviewPlayer from './CompositionPreviewPlayer.jsx';
+import CompositionPreviewPlayer, { playthroughVersion } from './CompositionPreviewPlayer.jsx';
const DOCUMENT = { directory: 'music-video/mv-1/composition/doc-a', entry: 'index.html' };
const project = {
@@ -71,6 +71,16 @@ beforeEach(() => {
socket.connected = true;
});
+describe('playthroughVersion', () => {
+ // Uniquely catches the lyric overlay keeping a stale layout when the title card starts or stops showing.
+ it('rebuilds the lyric page when the title card gains or loses its text', () => {
+ const card = { enabled: true, title: '', artist: '', year: '', extra: '', position: 'lower-left', startSec: 2, endSec: 8, outro: false };
+ const blank = playthroughVersion({ titleCard: card });
+ expect(playthroughVersion({ titleCard: { ...card, title: 'Example Song' } })).not.toBe(blank);
+ expect(playthroughVersion({ titleCard: null })).toBe(blank);
+ });
+});
+
describe('CompositionPreviewPlayer', () => {
it('resumes an expired preview only on request and restores its controls and playhead', async () => {
const look = { version: 1, preset: 'custom', grain: 0.4 };
diff --git a/docs/HTML_COMPOSITIONS.md b/docs/HTML_COMPOSITIONS.md
index 0536e20cce..1be2af77b4 100644
--- a/docs/HTML_COMPOSITIONS.md
+++ b/docs/HTML_COMPOSITIONS.md
@@ -395,7 +395,9 @@ same card again in its own window (`outroStartSec`–`outroEndSec`, song time);
turning it on times that window from the song's length (`titleCardOutroWindow`:
as long as the opening one, ending a second before the song does). The runtime's
fade covers both windows, and a composed cut gets one capture cue per window
-(`titleCardWindows`).
+(`titleCardWindows`). While the card shows, a lyric line in a default zone that
+would collide with the card's corner steps across the frame (a lower-left card
+sends it to the upper left); a Text zone set on the line's shot stays as set.
The card is not part of the composition document. `titleCardRuntimeSource()`
is a page script installed beside it, in the live preview's head (live edits
@@ -441,8 +443,8 @@ snapshot freezes (`server/services/musicVideo/documentRender.js`):
downbeats, sections, words }, lyrics, lyricMarkers, scenes: [{ sceneId,
label, startSec, endSec, shotMode, visualLayer, stillMove, cardText,
cardColor, textZone, lyricRole, lyricSize, lyricText, direction, media: { kind, src, inSec, outSec, fps,
- width, height } | null }], textCues, composition: { mode, style, posterSec,
- overlay } }`. Load it with `<script src="portos-mv.js">`; the sandbox
+ width, height } | null }], titleCard: { position, windows: [{ startSec, endSec }] }
+ | null, textCues, composition: { mode, style, posterSec, overlay } }`. Load it with `<script src="portos-mv.js">`; the sandbox
refuses `fetch`.
A shot's `speedFps`/`offsetFrames` are baked into the staged clip, so a render
seeks `media.inSec + (t - startSec)`. The live preview bridges the original
diff --git a/server/services/musicVideo/documentRender.js b/server/services/musicVideo/documentRender.js
index 2a59d1b5d7..ea29d25039 100644
--- a/server/services/musicVideo/documentRender.js
+++ b/server/services/musicVideo/documentRender.js
@@ -2,7 +2,7 @@ import { assertMusicVideoMediaSelections, musicVideoMediaMode } from '../../lib/
import { isEndFrameImageEffect, sceneImageEffect } from '../../lib/musicVideoImageEffects.js';
import { musicVideoGradeFilter } from '../../lib/musicVideoGrade.js';
import { filmLookRuntimeSource, isFilmLookNeutral } from '../../lib/filmLook.js';
-import { titleCardVisible } from '../../lib/musicVideoTitleCard.js';
+import { titleCardVisible, titleCardWindows } from '../../lib/musicVideoTitleCard.js';
import { titleCardRuntime } from './titleCardFonts.js';
/**
* Music Video — render a project's composition document over the song.
@@ -271,6 +271,10 @@ export function buildDocumentData(project, { media = new Map(), frame, clock, so
lyrics,
lyricMarkers: Array.isArray(project?.lyricMarkers) ? project.lyricMarkers : [],
scenes,
+ // Where and when the title card shows, so the lyric type keeps its default zones off it.
+ titleCard: titleCardVisible(project?.titleCard)
+ ? { position: project.titleCard.position || 'lower-left', windows: titleCardWindows(project.titleCard) }
+ : null,
textCues: (composition.textCues || []).filter((cue) => cue?.text && cue.startSec != null && cue.endSec != null),
composition: {
mode: composition.mode || 'concat',
diff --git a/server/services/musicVideo/documentTemplates/shared/lyricType.js b/server/services/musicVideo/documentTemplates/shared/lyricType.js
index ddc8eedac7..3b79ba22de 100644
--- a/server/services/musicVideo/documentTemplates/shared/lyricType.js
+++ b/server/services/musicVideo/documentTemplates/shared/lyricType.js
@@ -201,6 +201,19 @@ function lineWindow(words, role, { beats = [], nextOnset = null, fps = 24, endSe
return { startSec: onset, exitSec, endSec: exitSec + fade };
}
+// The lyric zones a title card in each spot (TITLE_CARD_POSITIONS) would collide with, and where a
+// line steps to instead: the same side across the frame, else the first clear corner.
+const TITLE_CARD_ZONES = Object.freeze({
+ 'lower-left': ['lower-left', 'lower'], 'lower-right': ['lower-right', 'lower'],
+ 'upper-left': ['upper-left', 'upper'], 'upper-right': ['upper-right', 'upper'],
+ 'lower-center': ['lower', 'lower-left', 'lower-right'], center: ['center'],
+});
+const ZONE_FLIP = Object.freeze({
+ 'lower-left': 'upper-left', 'lower-right': 'upper-right', lower: 'upper',
+ 'upper-left': 'lower-left', 'upper-right': 'lower-right', upper: 'lower', center: 'lower',
+});
+const ZONE_FALLBACKS = Object.freeze(['upper-right', 'upper-left', 'lower-right', 'lower-left']);
+
/** The pixel box a text zone allows on a width × height frame (null for `none`). */
function zoneRect(zone, width, height) {
const unit = Math.min(width, height) / 1080;
@@ -328,8 +341,21 @@ export function createLyricType(mv = globalThis.PORTOS_MV, options = {}) {
if (slammed.has(key)) line.role = 'line'; else slammed.add(key);
}
}
+ // While the title card shows, a line placed by default steps off the card's corner; a zone the
+ // line or its shot names stays where it was put.
+ const card = mv?.titleCard;
+ const cardWindows = (Array.isArray(card?.windows) ? card.windows : []).filter((w) => finite(w?.startSec) && finite(w?.endSec));
+ const cardZones = TITLE_CARD_ZONES[card?.position] || [];
+ const clearOfCard = (zone, line) => {
+ if (!cardZones.includes(zone)) return zone;
+ const from = line.words[0].startSec;
+ const until = Math.max(finite(line.endSec) ? line.endSec : 0, line.words[line.words.length - 1].endSec ?? from) + T.lastWordHoldSec + T.lineExitDelaySec;
+ if (!cardWindows.some((w) => from < w.endSec && until > w.startSec)) return zone;
+ return [ZONE_FLIP[zone], ...ZONE_FALLBACKS].find((other) => other && !cardZones.includes(other)) || zone;
+ };
const zoned = timed.map(({ zoneOf, explicit, ...line }) => {
- const zone = zoneOf || line.shot?.textZone || (line.role === 'hook' ? 'lower' : options.defaultZone || 'lower-left');
+ const named = zoneOf || line.shot?.textZone;
+ const zone = named || clearOfCard(line.role === 'hook' ? 'lower' : options.defaultZone || 'lower-left', line);
return { ...line, zone: TEXT_ZONES.includes(zone) ? zone : 'lower-left' };
});
diff --git a/server/services/musicVideo/documentTemplates/shared/lyricType.test.js b/server/services/musicVideo/documentTemplates/shared/lyricType.test.js
index ad415b71ac..43fc2a7a75 100644
--- a/server/services/musicVideo/documentTemplates/shared/lyricType.test.js
+++ b/server/services/musicVideo/documentTemplates/shared/lyricType.test.js
@@ -286,6 +286,22 @@ describe('lyricType text zones', () => {
expect(normal).toBe(60);
});
+ it('steps a default-zoned line off the title card\'s corner while the card shows, but keeps a zone the shot names', () => {
+ const mv = (textZone) => ({
+ titleCard: { position: 'lower-left', windows: [{ startSec: 0, endSec: 2 }, { startSec: 10, endSec: 14 }] },
+ scenes: [{ sceneId: 's', startSec: 0, endSec: 20, textZone }],
+ });
+ const lines = [
+ { text: 'under the end card', role: 'line', startSec: 11, words: words('under the end card', 11) },
+ { text: 'after the card', role: 'line', startSec: 16, words: words('after the card', 16) },
+ ];
+ expect(createLyricType(mv(null), { lines }).lines.map((l) => l.zone)).toEqual(['upper-left', 'lower-left']);
+ expect(createLyricType(mv('lower-left'), { lines }).lines.map((l) => l.zone)).toEqual(['lower-left', 'lower-left']);
+ // A hook's centred band shares the card's lower edge too.
+ const hook = createLyricType(mv(null), { lines: [{ text: 'big hook', role: 'hook', startSec: 0.5, words: words('big hook', 0.5) }] });
+ expect(hook.lines[0].zone).toBe('upper');
+ });
+
it('reframes zones for a portrait frame', () => {
const rect = zoneRect('lower-left', 1080, 1920);
expect(rect.x + rect.w).toBeCloseTo(1080 - rect.x, 6);