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

Make YouTube thumbnails worth clicking, with an A/B set for Test & Compare (#11637)

[._.]/fe1c46e1cfb2
diff --git a/client/src/components/musicVideo/CoverLetteringPanel.jsx b/client/src/components/musicVideo/CoverLetteringPanel.jsx
index 98a98dd1f3..bb637285d2 100644
--- a/client/src/components/musicVideo/CoverLetteringPanel.jsx
+++ b/client/src/components/musicVideo/CoverLetteringPanel.jsx
@@ -40,7 +40,7 @@ function loadFace(font) {
return faceLoads.get(key);
}
// Re-renders once the uploaded faces are usable, so the preview's text widths are measured in them rather than in a fallback.
-function usePreviewFonts(fonts) {
+export function usePreviewFonts(fonts) {
const [tick, setTick] = useState(0);
useEffect(() => {
if (!fonts?.length || typeof FontFace === 'undefined' || typeof document === 'undefined' || !document.fonts) return undefined;
diff --git a/client/src/components/musicVideo/PublishKitPanel.jsx b/client/src/components/musicVideo/PublishKitPanel.jsx
index c53a2e19e7..df037a9f7a 100644
--- a/client/src/components/musicVideo/PublishKitPanel.jsx
+++ b/client/src/components/musicVideo/PublishKitPanel.jsx
@@ -1,9 +1,10 @@
import { useEffect, useRef, useState } from 'react';
-import { Package, Download, Copy, Sparkles, Image as ImageIcon, Captions, ListOrdered } from 'lucide-react';
+import { Package, Download, Copy, Sparkles, Captions, ListOrdered } from 'lucide-react';
import useProviderModels from '../../hooks/useProviderModels.js';
import ProviderModelSelector from '../ProviderModelSelector.jsx';
import { copyToClipboard } from '../../lib/clipboard.js';
import CoverArtPanel from './CoverArtPanel.jsx';
+import YoutubeThumbnailPanel from './YoutubeThumbnailPanel.jsx';
import PublishCard from './PublishCard.jsx';
import { formatCount, formatUsd } from '../../utils/formatters.js';
@@ -198,24 +199,12 @@ export default function PublishKitPanel({ project, publishKit, enabledTargets })
<pre className="bg-port-bg border border-port-border rounded p-2 whitespace-pre-wrap break-words font-mono text-[11px]">{chaptersText(kit.chapters)}</pre>
</div>
)}
- {kit.thumbnails?.length > 0 && (
- <div className="space-y-1">
- <span className="text-port-text-muted flex items-center gap-1"><ImageIcon size={12} /> Thumbnail: pick one, or add title text before uploading</span>
- <div className="grid grid-cols-2 sm:grid-cols-3 gap-2">
- {kit.thumbnails.map((name) => (
- <button key={name} type="button" onClick={() => publishKit.selectThumbnail(name)} aria-pressed={kit.thumbnail === name}
- aria-label={`Use thumbnail ${name}`}
- className={`rounded overflow-hidden border-2 ${kit.thumbnail === name ? 'border-port-accent' : 'border-transparent'}`}>
- <img src={`/data/video-thumbnails/${name}`} alt="" className="w-full aspect-video object-cover" />
- </button>
- ))}
- </div>
- </div>
- )}
</div>
)}
</PublishCard>
+ <YoutubeThumbnailPanel key={`yt-${project?.id}`} project={project} publishKit={publishKit} />
+
<CoverArtPanel key={project?.id} project={project} publishKit={publishKit} />
<PublishCard projectId={project?.id} cardId="copy" label="Release copy" icon={Sparkles}
diff --git a/client/src/components/musicVideo/PublishKitPanel.test.jsx b/client/src/components/musicVideo/PublishKitPanel.test.jsx
index 3abd769887..5e067b40fb 100644
--- a/client/src/components/musicVideo/PublishKitPanel.test.jsx
+++ b/client/src/components/musicVideo/PublishKitPanel.test.jsx
@@ -1,7 +1,7 @@
/**
* Publish stage panel (#9281): the kit builds only from a final render, the
* copy draft carries the director's notes and valid links, an edited field
- * saves on blur (tags as a list), and the thumbnail choice goes to the server.
+ * saves on blur (tags as a list), and a tapped image makes the YouTube thumbnail.
*/
import { describe, it, expect, vi } from 'vitest';
import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
@@ -18,7 +18,7 @@ const expandAll = () => { for (let b = screen.queryAllByRole('button', { expande
const hook = (over = {}) => ({
building: false, progress: 0, build: vi.fn(), drafting: false, saving: false,
- draftCopy: vi.fn(async () => null), saveCopy: vi.fn(async () => null), selectThumbnail: vi.fn(async () => null),
+ draftCopy: vi.fn(async () => null), saveCopy: vi.fn(async () => null), composingThumbnail: false, composeThumbnail: vi.fn(async () => null), clearThumbnail: vi.fn(async () => null),
composing: false, composeCover: vi.fn(async () => null), designing: false, designCover: vi.fn(async () => null), generateCover: vi.fn(async () => null), ...over,
});
const built = {
@@ -123,9 +123,9 @@ describe('PublishKitPanel (#9281)', () => {
await act(async () => {}); // let the field saves settle
});
- it('shows the built kit, saves an edited field on blur and picks a thumbnail', async () => {
+ it('shows the built kit, saves an edited field on blur and makes a thumbnail from a frame', async () => {
const k = hook();
- render(<PublishKitPanel project={{ id: 'mv-1', renderHistoryId: 'rh-1', publishKit: built }} publishKit={k} />);
+ render(<PublishKitPanel project={{ id: 'mv-1', name: 'Example Song', renderHistoryId: 'rh-1', publishKit: built }} publishKit={k} />);
expandAll();
expect(screen.getByText('X / social 1080p (12 Mbps)')).toBeTruthy();
expect(screen.getByText(/0:00 Opening line/)).toBeTruthy();
@@ -133,8 +133,8 @@ describe('PublishKitPanel (#9281)', () => {
fireEvent.change(tags, { target: { value: 'music, ai video ,claude' } });
fireEvent.blur(tags);
expect(k.saveCopy).toHaveBeenCalledWith({ youtube: { tags: ['music', 'ai video', 'claude'] } });
- fireEvent.click(screen.getByRole('button', { name: 'Use thumbnail t2.jpg' }));
- expect(k.selectThumbnail).toHaveBeenCalledWith('t2.jpg');
+ fireEvent.click(screen.getByRole('button', { name: 'Make the thumbnail from Video frame 2' }));
+ expect(k.composeThumbnail).toHaveBeenCalledWith(expect.objectContaining({ source: { kind: 'thumbnail', filename: 't2.jpg' }, lettering: true }));
await act(async () => {}); // let the field saves settle
});
diff --git a/client/src/components/musicVideo/PublishPlatformsPanel.test.jsx b/client/src/components/musicVideo/PublishPlatformsPanel.test.jsx
index 085362f2a5..3ba13d03dc 100644
--- a/client/src/components/musicVideo/PublishPlatformsPanel.test.jsx
+++ b/client/src/components/musicVideo/PublishPlatformsPanel.test.jsx
@@ -54,7 +54,7 @@ describe('PublishPlatformsPanel (#9287)', () => {
});
describe('PublishKitPanel copy per platform (#9287)', () => {
- const kitHook = { building: false, progress: 0, build: vi.fn(), drafting: false, saving: false, draftCopy: vi.fn(), saveCopy: vi.fn(), selectThumbnail: vi.fn() };
+ const kitHook = { building: false, progress: 0, build: vi.fn(), drafting: false, saving: false, draftCopy: vi.fn(), saveCopy: vi.fn(), composeThumbnail: vi.fn(), clearThumbnail: vi.fn() };
const project = { id: 'mv-1', renderHistoryId: 'rh', publishKit: { copy: { youtube: { title: 'T' }, reddit: { title: 'R' } }, copyDraftedAt: 'x' } };
it('shows copy only for enabled platforms (YouTube too when Suno is on)', () => {
diff --git a/client/src/components/musicVideo/YoutubeThumbnailPanel.jsx b/client/src/components/musicVideo/YoutubeThumbnailPanel.jsx
new file mode 100644
index 0000000000..9fa82cce04
--- /dev/null
+++ b/client/src/components/musicVideo/YoutubeThumbnailPanel.jsx
@@ -0,0 +1,241 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Brush, Download, FlaskConical, Images, MonitorPlay, RotateCcw, X } from 'lucide-react';
+import GalleryImagePicker from '../imageGen/GalleryImagePicker';
+import SentPromptPanel from '../media/SentPromptPanel';
+import { previewMusicVideoThumbnailPaint } from '../../services/apiMusicVideo.js';
+import useMusicVideoCoverLettering from '../../hooks/useMusicVideoCoverLettering.js';
+import { YOUTUBE_THUMBNAIL_SIZE, canvasCoverWidths, coverOverlaySvg, normalizeCoverDesign } from '../../lib/musicVideoCoverOverlay.js';
+import { usePreviewFonts } from './CoverLetteringPanel.jsx';
+import PublishCard from './PublishCard.jsx';
+
+const MAX_SOURCES = 24;
+// YouTube's Test & Compare runs up to three thumbnails on a published video.
+const MAX_TESTS = 3;
+const button = 'flex items-center gap-1 bg-port-accent/20 text-port-accent disabled:opacity-50 rounded px-2 py-1.5 min-h-[44px] sm:min-h-0';
+const srcFor = (kind, filename) => (kind === 'thumbnail' ? `/data/video-thumbnails/${encodeURIComponent(filename)}` : `/data/images/${encodeURIComponent(filename)}`);
+
+/**
+ * Images a thumbnail can be made from: the video's best frames (the kit keeps
+ * the sharpest frame of each shot, best first), then each shot's still (clean,
+ * full resolution, no lyrics drawn on it), then the cover's images and the
+ * Cast & Sets renders.
+ */
+export function thumbnailSources(project) {
+ const kit = project?.publishKit || {};
+ const seen = new Set();
+ const out = [];
+ const add = (kind, filename, label) => {
+ if (!filename || seen.has(`${kind}:${filename}`)) return;
+ seen.add(`${kind}:${filename}`);
+ out.push({ kind, filename, label, src: srcFor(kind, filename) });
+ };
+ // An image picked from history or uploaded is in none of the lists below.
+ const current = kit.youtubeThumbnail?.source;
+ (kit.youtubeThumbnail?.generated || []).forEach((f, i) => add('image', f, `Painted ${i + 1}`));
+ if (current?.kind === 'image') add('image', current.filename, 'Current thumbnail image');
+ (kit.thumbnails || []).forEach((f, i) => add('thumbnail', f, i === 0 ? 'Video frame 1 (best)' : `Video frame ${i + 1}`));
+ (project?.scenes || []).forEach((scene, i) => add('image', scene?.referenceImageId, `Shot ${i + 1}${scene?.sectionLabel ? ` (${scene.sectionLabel})` : ''}`));
+ if (kit.coverArt?.source?.kind === 'image') add('image', kit.coverArt.source.filename, 'Cover image');
+ for (const f of kit.coverArt?.generated || []) add('image', f, 'Cover image');
+ for (const [key, img] of Object.entries(project?.castAndSets?.images || {})) add('image', img?.imageId, `Cast & Sets: ${key}`);
+ return out.slice(0, MAX_SOURCES);
+}
+
+/**
+ * The YouTube thumbnail: any image the project has (the video's best frames,
+ * a shot's still, a cover image) or one from history, cropped 16:9 with the
+ * song title set large in the cover's lettering, clear of the corner where
+ * YouTube shows the length. The preview lays the title out with the code the
+ * server renders with (lib/musicVideoCoverOverlay.js). Tapping an image makes
+ * the thumbnail from it at once; the YouTube post uploads it. "Paint the title"
+ * has the image model redraw the picked image with the title painted in as
+ * display lettering, for livelier type than code can set; the brief PortOS
+ * adds shows as a chip with the full prompt before the send.
+ */
+export default function YoutubeThumbnailPanel({ project, publishKit }) {
+ const kit = project?.publishKit || {};
+ const thumb = kit.youtubeThumbnail || {};
+ const art = kit.coverArt || {};
+ const sources = thumbnailSources(project);
+ const idFor = (s) => `mv-ytthumb-${project?.id}-${s}`;
+ const savedTitle = thumb.title ?? art.title ?? project?.name ?? '';
+ const [title, setTitle] = useState(savedTitle);
+ const [focusX, setFocusX] = useState(Number.isFinite(thumb.focusX) ? thumb.focusX : 0.5);
+ const [focusY, setFocusY] = useState(Number.isFinite(thumb.focusY) ? thumb.focusY : 0.5);
+ const [lettering, setLettering] = useState(thumb.lettering !== false);
+ const [picked, setPicked] = useState(null);
+ // Follow each thumbnail the server makes (a painted one lands bare, with its own crop).
+ useEffect(() => {
+ if (!thumb.filename) return;
+ setLettering(thumb.lettering !== false);
+ setFocusX(Number.isFinite(thumb.focusX) ? thumb.focusX : 0.5);
+ setFocusY(Number.isFinite(thumb.focusY) ? thumb.focusY : 0.5);
+ setPicked(null);
+ }, [thumb.filename]); // eslint-disable-line react-hooks/exhaustive-deps
+ // Which way the picked image overflows 16:9, so the one crop slider moves it the way it can go.
+ const [wide, setWide] = useState(true);
+ const [pickerOpen, setPickerOpen] = useState(false);
+ const [paintNotes, setPaintNotes] = useState('');
+ const [sentNotes, setSentNotes] = useState('');
+ const [paintPreview, setPaintPreview] = useState(null);
+ const [paintOpen, setPaintOpen] = useState(false);
+ // The uploaded fonts matter only when the cover's design is set in one.
+ const letterAssets = useMusicVideoCoverLettering({ enabled: lettering && String(art.design?.typeface || '').startsWith('font:') });
+ const fonts = letterAssets.fonts || [];
+ const fontTick = usePreviewFonts(letterAssets.fonts);
+ const busy = Boolean(publishKit.composingThumbnail);
+
+ const source = picked || (thumb.source ? { ...thumb.source, src: srcFor(thumb.source.kind, thumb.source.filename) } : null);
+ const chosen = source ? `${source.kind}:${source.filename}` : null;
+ const needsTitle = lettering && !title.trim();
+ const look = () => ({ title: title.trim(), focusX, focusY, lettering });
+ const dirty = Boolean(thumb.filename) && (title.trim() !== savedTitle || focusX !== (thumb.focusX ?? 0.5) || focusY !== (thumb.focusY ?? 0.5) || lettering !== (thumb.lettering !== false));
+ const make = (s) => {
+ setPicked(s);
+ return publishKit.composeThumbnail({ source: { kind: s.kind, filename: s.filename }, ...look() });
+ };
+
+ const svg = useMemo(() => {
+ if (!lettering || !title.trim()) return '';
+ const design = normalizeCoverDesign(art.design, { fonts });
+ const widths = canvasCoverWidths(design, { title, tag: '', size: YOUTUBE_THUMBNAIL_SIZE, frame: 'thumbnail' }, fonts);
+ return coverOverlaySvg({ title, design, size: YOUTUBE_THUMBNAIL_SIZE, frame: 'thumbnail', widths, fonts });
+ }, [JSON.stringify(art.design ?? null), title, lettering, letterAssets.fonts, fontTick]); // eslint-disable-line react-hooks/exhaustive-deps
+
+ const tests = Array.isArray(kit.youtubeThumbnailTests) ? kit.youtubeThumbnailTests.filter((t) => t?.filename) : [];
+ const inTest = Boolean(thumb.filename) && tests.some((t) => t.filename === thumb.filename);
+ const crop = wide ? focusX : focusY;
+ const painting = Boolean(publishKit.paintingThumbnail || thumb.pending);
+ const paintTitle = title.trim();
+ // The exact prompt the paint would send, from the server's own builder, refreshed as the title or the committed notes change.
+ useEffect(() => {
+ if (!paintOpen || !project?.id || !paintTitle) { setPaintPreview(null); return undefined; }
+ let active = true;
+ previewMusicVideoThumbnailPaint(project.id, { title: paintTitle, ...(sentNotes ? { notes: sentNotes } : {}) }, { silent: true })
+ .then((res) => { if (active) setPaintPreview(res || null); })
+ .catch(() => { if (active) setPaintPreview(null); });
+ return () => { active = false; };
+ }, [paintOpen, project?.id, paintTitle, sentNotes]);
+ const paint = () => publishKit.paintThumbnail({ source: { kind: source.kind, filename: source.filename }, title: paintTitle, ...(paintNotes.trim() ? { notes: paintNotes.trim() } : {}) });
+ const setCrop = (v) => (wide ? setFocusX(v) : setFocusY(v));
+
+ return (
+ <PublishCard projectId={project?.id} cardId="youtube-thumbnail" label="YouTube thumbnail" icon={MonitorPlay}
+ summary={thumb.filename ? 'Made' : (kit.thumbnail ? 'Best video frame' : 'Not set yet')} defaultOpen={!thumb.filename}>
+ <p className="text-port-text-muted">Tap an image to make the thumbnail. The title is set large in the cover's lettering, away from the corner where YouTube shows the length.</p>
+ <div className="flex flex-col sm:flex-row gap-3">
+ <div className="w-full sm:w-80 shrink-0 space-y-1">
+ <div className="relative w-full aspect-video overflow-hidden rounded border border-port-border bg-port-bg">
+ {source ? (
+ <>
+ <img src={source.src} alt="" className="absolute inset-0 w-full h-full object-cover" style={{ objectPosition: `${focusX * 100}% ${focusY * 100}%` }}
+ onLoad={(e) => { const { naturalWidth: w, naturalHeight: h } = e.currentTarget; if (w && h) setWide(w / h >= 16 / 9); }} />
+ {svg && <div role="img" aria-label={`Thumbnail preview for ${title}`} className="absolute inset-0 [&>svg]:w-full [&>svg]:h-full" dangerouslySetInnerHTML={{ __html: svg }} />}
+ </>
+ ) : kit.thumbnail ? (
+ <img src={srcFor('thumbnail', kit.thumbnail)} alt="The best video frame" className="absolute inset-0 w-full h-full object-cover" />
+ ) : (
+ <div className="absolute inset-0 flex items-center justify-center text-port-text-muted p-2 text-center">Build the publishing kit for video frames, or pick an image</div>
+ )}
+ </div>
+ {thumb.filename ? (
+ <div className="flex flex-wrap items-center gap-3">
+ <a href={`/data/video-thumbnails/${encodeURIComponent(thumb.filename)}`} download className="text-port-accent flex items-center gap-1 min-h-[44px] sm:min-h-0"><Download size={12} /> Download</a>
+ <button type="button" onClick={publishKit.clearThumbnail} disabled={busy} className="text-port-text-muted flex items-center gap-1 disabled:opacity-50 min-h-[44px] sm:min-h-0">
+ <RotateCcw size={12} /> Use the best video frame instead
+ </button>
+ </div>
+ ) : kit.thumbnail && !source && <p className="text-port-text-muted">YouTube gets this frame, bare, until you make a thumbnail.</p>}
+ </div>
+ <div className="flex-1 space-y-2 min-w-0">
+ <label htmlFor={idFor('lettering')} className="flex items-center gap-1.5 min-h-[44px] sm:min-h-0">
+ <input id={idFor('lettering')} type="checkbox" checked={lettering} onChange={(e) => setLettering(e.target.checked)} />
+ Set the title on the image
+ </label>
+ {lettering && (
+ <div>
+ <label htmlFor={idFor('title')} className="block text-[11px] text-port-text-muted">Title on the thumbnail (short reads best)</label>
+ <input id={idFor('title')} value={title} maxLength={60} onChange={(e) => setTitle(e.target.value)}
+ className="w-full bg-port-bg border border-port-border rounded px-1.5 py-1 text-xs min-h-[44px] sm:min-h-0" />
+ </div>
+ )}
+ {source && (
+ <div>
+ <label htmlFor={idFor('crop')} className="block text-[11px] text-port-text-muted">{wide ? 'Crop position (left to right)' : 'Crop position (top to bottom)'}</label>
+ <input id={idFor('crop')} type="range" min={0} max={1} step={0.05} value={crop} onChange={(e) => setCrop(Number(e.target.value))}
+ className="w-full min-h-[44px] sm:min-h-0" />
+ </div>
+ )}
+ {source && (
+ <button type="button" onClick={() => make(source)} disabled={busy || needsTitle || (Boolean(thumb.filename) && !dirty)} className={button}>
+ {busy ? 'Making the thumbnail…' : thumb.filename ? 'Apply to the thumbnail' : 'Make the thumbnail'}
+ </button>
+ )}
+ {lettering && !art.design && <p className="text-port-text-muted">Set in the plain look until the cover has a design (Cover art › Lettering).</p>}
+ </div>
+ </div>
+
+ <div className="space-y-1">
+ <div className="flex flex-wrap items-center justify-between gap-2">
+ <span className="text-port-text-muted">Pick an image</span>
+ <button type="button" onClick={() => setPickerOpen(true)} disabled={busy || needsTitle}
+ className="flex items-center gap-1 text-port-accent disabled:opacity-50 min-h-[44px] sm:min-h-0">
+ <Images size={13} /> Choose from image history or upload
+ </button>
+ </div>
+ {sources.length > 0 && (
+ <div className="grid grid-cols-2 sm:grid-cols-4 gap-2">
+ {sources.map((s) => (
+ <button key={`${s.kind}:${s.filename}`} type="button" onClick={() => make(s)} disabled={busy || needsTitle}
+ aria-pressed={chosen === `${s.kind}:${s.filename}`} aria-label={`Make the thumbnail from ${s.label}`} title={s.label}
+ className={`rounded overflow-hidden border-2 disabled:opacity-60 ${chosen === `${s.kind}:${s.filename}` ? 'border-port-accent' : 'border-transparent'}`}>
+ <img src={s.src} alt="" loading="lazy" className="w-full aspect-video object-cover" />
+ </button>
+ ))}
+ </div>
+ )}
+ </div>
+ <details open={paintOpen} onToggle={(e) => setPaintOpen(e.currentTarget.open)} className="space-y-1 rounded border border-port-border p-2">
+ <summary className="cursor-pointer flex items-center gap-1 min-h-[44px] sm:min-h-0"><Brush size={13} /> Paint the title with the image model</summary>
+ <p className="text-port-text-muted">Redraws the picked image with the title painted in as bold lettering. The result becomes the thumbnail when it lands.</p>
+ <label htmlFor={idFor('paint-notes')} className="block text-[11px] text-port-text-muted">Lettering direction (optional)</label>
+ <textarea id={idFor('paint-notes')} value={paintNotes} maxLength={1500} rows={2} onChange={(e) => setPaintNotes(e.target.value)}
+ onBlur={() => setSentNotes(paintNotes.trim())} placeholder="Chrome 80s movie-poster letters with a hot pink glow"
+ className="w-full bg-port-bg border border-port-border rounded px-1.5 py-1 text-xs" />
+ {paintPreview && <SentPromptPanel prompt={sentNotes} sentPrompt={paintPreview.prompt} additions={paintPreview.promptAdditions || []} />}
+ <button type="button" onClick={paint} disabled={!source || busy || painting || !paintTitle} className={button}>
+ <Brush size={13} /> {publishKit.paintingThumbnail ? 'Queuing…' : thumb.pending ? 'Painting…' : 'Paint the title into this image'}
+ </button>
+ {!source && <p className="text-port-text-muted">Pick an image above first.</p>}
+ {thumb.pending && <p role="status" className="text-port-text-muted">Painting on {thumb.pending.mode || 'the image backend'}. The thumbnail updates when it lands.</p>}
+ {thumb.lastError && !thumb.pending && <p role="alert" className="text-port-warning">{thumb.lastError}</p>}
+ </details>
+
+ <div className="space-y-1 rounded border border-port-border p-2">
+ <div className="flex flex-wrap items-center justify-between gap-2">
+ <span className="flex items-center gap-1"><FlaskConical size={13} /> A/B test ({tests.length} of {MAX_TESTS})</span>
+ <button type="button" onClick={publishKit.addThumbnailTest} disabled={busy || !thumb.filename || dirty || inTest || tests.length >= MAX_TESTS} className={button}>
+ {inTest ? 'This one is in the test' : 'Add this one to the test'}
+ </button>
+ </div>
+ <p className="text-port-text-muted">Make a thumbnail, add it, then make the next. Upload the set in YouTube Studio under Test &amp; Compare.</p>
+ {tests.length > 0 && (
+ <div className="grid grid-cols-1 sm:grid-cols-3 gap-2">
+ {tests.map((t, i) => (
+ <div key={t.filename} className="space-y-1">
+ <img src={srcFor('thumbnail', t.filename)} alt={`Test thumbnail ${i + 1}`} className="w-full aspect-video object-cover rounded border border-port-border" />
+ <div className="flex items-center justify-between gap-2">
+ <a href={srcFor('thumbnail', t.filename)} download className="text-port-accent flex items-center gap-1 min-h-[44px] sm:min-h-0"><Download size={12} /> {String.fromCharCode(65 + i)}</a>
+ <button type="button" onClick={() => publishKit.removeThumbnailTest(t.filename)} aria-label={`Remove test thumbnail ${i + 1}`}
+ className="text-port-text-muted flex items-center gap-1 min-h-[44px] sm:min-h-0"><X size={12} /> Remove</button>
+ </div>
+ </div>
+ ))}
+ </div>
+ )}
+ </div>
+ <GalleryImagePicker open={pickerOpen} onClose={() => setPickerOpen(false)} allowUpload
+ onSelect={(item) => item?.filename && make({ kind: 'image', filename: item.filename, src: srcFor('image', item.filename) })} />
+ </PublishCard>
+ );
+}
diff --git a/client/src/components/musicVideo/YoutubeThumbnailPanel.test.jsx b/client/src/components/musicVideo/YoutubeThumbnailPanel.test.jsx
new file mode 100644
index 0000000000..7c97062296
--- /dev/null
+++ b/client/src/components/musicVideo/YoutubeThumbnailPanel.test.jsx
@@ -0,0 +1,59 @@
+/**
+ * YouTube thumbnail card: tapping an image makes the thumbnail from it with
+ * the title, a shot's still is offered after the video's best frames, and the
+ * made thumbnail can join the Test & Compare set until it holds three.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import YoutubeThumbnailPanel, { thumbnailSources } from './YoutubeThumbnailPanel.jsx';
+
+vi.mock('../../hooks/useMusicVideoCoverLettering.js', () => ({ default: () => ({ fonts: [], styles: [], uploading: false }) }));
+vi.mock('../imageGen/GalleryImagePicker', () => ({ default: () => null }));
+vi.mock('../../services/apiMusicVideo.js', () => ({
+ previewMusicVideoThumbnailPaint: vi.fn(async (_id, { title }) => ({ prompt: `Example brief "${title}"`, promptAdditions: [{ id: 'youtube-thumbnail-brief', label: 'YouTube thumbnail brief', text: `Example brief "${title}"` }] })),
+}));
+
+const hook = (over = {}) => ({ composingThumbnail: false, paintingThumbnail: false, paintThumbnail: vi.fn(), composeThumbnail: vi.fn(), clearThumbnail: vi.fn(), addThumbnailTest: vi.fn(), removeThumbnailTest: vi.fn(), ...over });
+const project = (kit = {}) => ({
+ id: 'mv-1', name: 'Example Song',
+ scenes: [{ sceneId: 's1', referenceImageId: 'still-1.png', sectionLabel: 'Verse 1' }],
+ publishKit: { thumbnails: ['best.jpg', 'next.jpg'], thumbnail: 'best.jpg', ...kit },
+});
+
+describe('YoutubeThumbnailPanel', () => {
+ it('offers the best frames first, then shot stills', () => {
+ expect(thumbnailSources(project()).map((s) => s.label)).toEqual(['Video frame 1 (best)', 'Video frame 2', 'Shot 1 (Verse 1)']);
+ });
+
+ it('makes the thumbnail from a tapped shot still, with the title', () => {
+ const k = hook();
+ render(<YoutubeThumbnailPanel project={project()} publishKit={k} />);
+ fireEvent.click(screen.getByRole('button', { name: 'Make the thumbnail from Shot 1 (Verse 1)' }));
+ expect(k.composeThumbnail).toHaveBeenCalledWith(expect.objectContaining({ source: { kind: 'image', filename: 'still-1.png' }, title: 'Example Song', lettering: true }));
+ });
+
+ it('adds the made thumbnail to the A/B test until it holds three', () => {
+ const k = hook();
+ const made = { filename: 'yt-2.jpg', source: { kind: 'thumbnail', filename: 'best.jpg' }, title: 'Example Song', focusX: 0.5, focusY: 0.5, lettering: true };
+ const { rerender } = render(<YoutubeThumbnailPanel project={project({ youtubeThumbnail: made, youtubeThumbnailTests: [{ filename: 'yt-1.jpg' }] })} publishKit={k} />);
+ fireEvent.click(screen.getByRole('button', { name: /YouTube thumbnail/ })); // a made thumbnail folds the card
+ fireEvent.click(screen.getByRole('button', { name: 'Add this one to the test' }));
+ expect(k.addThumbnailTest).toHaveBeenCalled();
+ fireEvent.click(screen.getByRole('button', { name: 'Remove test thumbnail 1' }));
+ expect(k.removeThumbnailTest).toHaveBeenCalledWith('yt-1.jpg');
+ rerender(<YoutubeThumbnailPanel project={project({ youtubeThumbnail: made, youtubeThumbnailTests: [{ filename: 'a.jpg' }, { filename: 'b.jpg' }, { filename: 'c.jpg' }] })} publishKit={k} />);
+ expect(screen.getByRole('button', { name: 'Add this one to the test' })).toBeDisabled();
+ });
+
+ it('paints the title into the picked image, showing the brief it adds before the send', async () => {
+ const k = hook();
+ const made = { filename: 'yt-1.jpg', source: { kind: 'thumbnail', filename: 'best.jpg' }, title: 'Example Song', lettering: true };
+ render(<YoutubeThumbnailPanel project={project({ youtubeThumbnail: made })} publishKit={k} />);
+ fireEvent.click(screen.getByRole('button', { name: /YouTube thumbnail/ }));
+ fireEvent.click(screen.getByText('Paint the title with the image model'));
+ await waitFor(() => expect(screen.getByRole('button', { name: '+ YouTube thumbnail brief' })).toBeTruthy());
+ fireEvent.change(screen.getByLabelText('Lettering direction (optional)'), { target: { value: 'chrome letters' } });
+ fireEvent.click(screen.getByRole('button', { name: /Paint the title into this image/ }));
+ expect(k.paintThumbnail).toHaveBeenCalledWith({ source: { kind: 'thumbnail', filename: 'best.jpg' }, title: 'Example Song', notes: 'chrome letters' });
+ });
+});
diff --git a/client/src/hooks/README.md b/client/src/hooks/README.md
index be6132178b..d55657a5ed 100644
--- a/client/src/hooks/README.md
+++ b/client/src/hooks/README.md
@@ -271,7 +271,7 @@ grep -i "what you want to do" client/src/hooks/README.md
| `useMusicVideoAutoReview` | Opt-in automatic review/retries (#8988): start a run over a draft window with explicit review (`maxAttempts`) and paid-generation (`maxGenerations`) limits plus a vision reviewer; applies the project pushed on `music-video:auto-review` and reports outcomes; the server generates a run's revised sections itself (#10014), so the board never submits them and a run completes with no tab open. Returns `{ busy, action, start(startSec, endSec, limits, reviewer), resume(runId, limits?), stop(runId), cancel(runId) }`. | The Music Video excerpt panel. |
| `useMusicVideoExcerpts` | Draft excerpt render + timecoded review notes (#8986): a `useSseJobSlot` render job over a chosen `[startSec, endSec)` window (any terminal frame reloads the project, since the persisted excerpt shape lives server-side) plus add/edit/delete review-note calls that apply the fresh whole project from each response. Returns `{ rendering, progress, deletingId, noteBusyId, startExcerpt(startSec, endSec), cancelExcerpt(excerptId), attachRender(jobId, projectId), deleteExcerpt(excerptId), addNote(excerptId, {atSec, note, verdict?}), editNote(excerptId, noteId, patch), deleteNote(excerptId, noteId) }`. | The Music Video excerpt panel. |
| `useMusicVideoCoverLettering` | Music Video cover Lettering controls (#10345): the install's uploaded typefaces and saved per-artist styles, loaded once. Loads whenever `enabled` (the section is open). Returns `{ fonts, styles, uploading, uploadFont(file), removeFont(id), saveStyle({ name, design }), removeStyle(name) }` (`fonts`/`styles` null until loaded); each mutation applies the server's answer at once. | `CoverArtPanel` (Publish stage). |
-| `useMusicVideoPublishKit` | Music Video publishing kit (#9281): a `useSseJobSlot` build job (encodes, thumbnails, captions, chapters) whose terminal frame reloads the project, plus the one-call copy draft, per-field copy edits and thumbnail choice, each applying the returned project. Returns `{ building, progress, build(), cancelBuild(), drafting, saving, draftCopy(body), saveCopy(patch), selectThumbnail(filename) }`. | The Music Video Publish stage. |
+| `useMusicVideoPublishKit` | Music Video publishing kit (#9281): a `useSseJobSlot` build job (encodes, thumbnails, captions, chapters) whose terminal frame reloads the project, plus the one-call copy draft, per-field copy edits, the YouTube thumbnail and cover art, each applying the returned project. Returns `{ building, progress, build(), cancelBuild(), drafting, saving, draftCopy(body), saveCopy(patch), composingThumbnail, composeThumbnail(body), clearThumbnail(), addThumbnailTest(), removeThumbnailTest(filename), paintingThumbnail, paintThumbnail(body), … }` plus the cover-art actions. | The Music Video Publish stage. |
| `useMusicVideoPublishing` | Music Video posting (#9282): per-platform drafts filled in the PortOS Browser. `prepare` returns the filled draft's summary and screenshot (a sign-in-required refusal is kept as the platform's error with its login URL), `submit` posts that reviewed draft and applies the returned project, `discard` closes it. Platforms are opt-in (#9287): it loads the saved `platforms` (enabled + optional account each) and per-platform `history` (posts, reception tally, recent notes across projects); `setPlatform` toggles one optimistically and `recordPost` saves a hand-made post's link or a post's reception and notes. Returns `{ drafts, busy, errors, prepare(target, options), submit(target), discard(target), platforms, history, enabledTargets, setPlatform(target, change), recordPost(target, body) }`. | The Music Video Publish stage's posting panel. |
| `useMusicVideoModelSettings` | A project's saved render pins — video backend (local/Grok/fal.ai)/model/generation-mode/audio-reactive LoRA + the image-side frame pin — with the Video Gen catalog they read from. Optimistic-local + silent PATCH, rollback + toast on failure; `saving` gates the dependent generate buttons. Returns `{ models, modelsLoading, defaultModel, falEnabled, saving, settings, effectiveModelId, activeModel, audioReactiveModels, audioReactiveLoras, detectedAudioReactiveLora, audioReactiveReady, audioReactiveSelected, videoBlockedReason, change, changeFramePin }`. `videoBlockedReason` is the single "why can't I generate" string (an unavailable audio-reactive setup, or a fal.ai pin with no configured API key) shared by the disabled buttons, their tooltips, and the blocked-call toast. | The Music Video renderer selects and anything building a scene-clip job payload from them. |
| `useMusicVideoSceneMedia` | Both per-scene generation lanes (reference frame + scene clip) over `useSceneRenderLifecycle`, the frame/shot prompt builders (concept-style + visual-spec direction suffix), visual-spec reference-image conditioning with explicit unsupported-backend feedback (#8965), the batch "generate the missing ones" actions, restores in-flight scene renders from the server queue on mount (`getMusicVideoSceneJobs`) so a reload doesn't invite duplicate submits, and folds the persisted `scene.lastFailure` (socket `music-video:scene-failure`) onto the scene (#10154). Returns `{ genScenes, genVideoScenes, conditioning, buildFramePrompt, buildShotPrompt, generateFrame, generateSceneVideo, continueSceneVideo, generateMissingFrames, generateMissingVideos, planMissingFrames, planMissingVideos, frameBatch, videoBatch, sceneProgress, videoSceneProgress }` (the batches run counted via `useSceneBatch`; the board confirms count + estimate before calling `generateMissing*`). | The Music Video scene board — don't re-wire the two lanes or re-derive the i2v/a2v/extend payloads. |
diff --git a/client/src/hooks/useMusicVideoPublishKit.js b/client/src/hooks/useMusicVideoPublishKit.js
index 541437c2f7..756ef28b67 100644
--- a/client/src/hooks/useMusicVideoPublishKit.js
+++ b/client/src/hooks/useMusicVideoPublishKit.js
@@ -8,7 +8,11 @@ import {
cancelMusicVideoPublishKit,
draftMusicVideoPublishCopy,
updateMusicVideoPublishCopy,
- selectMusicVideoPublishThumbnail,
+ composeMusicVideoYoutubeThumbnail,
+ clearMusicVideoYoutubeThumbnail,
+ addMusicVideoThumbnailTest,
+ paintMusicVideoYoutubeThumbnail,
+ removeMusicVideoThumbnailTest,
composeMusicVideoCoverArt,
generateMusicVideoCoverArt,
designMusicVideoCoverArt,
@@ -33,6 +37,8 @@ export default function useMusicVideoPublishKit({ project, replaceProject } = {}
const [designing, setDesigning] = useState(false);
const [savingLettering, setSavingLettering] = useState(false);
const [requestingImage, setRequestingImage] = useState(false);
+ const [composingThumbnail, setComposingThumbnail] = useState(false);
+ const [paintingThumbnail, setPaintingThumbnail] = useState(false);
const reload = (id) => {
if (!id) return;
@@ -95,7 +101,30 @@ export default function useMusicVideoPublishKit({ project, replaceProject } = {}
.catch(() => null)
.finally(() => setSaving(false));
};
- const selectThumbnail = (filename) => selectMusicVideoPublishThumbnail(projectId, filename).then(apply).catch(() => null);
+ const composeThumbnail = (body) => {
+ setComposingThumbnail(true);
+ return composeMusicVideoYoutubeThumbnail(projectId, body)
+ .then(apply)
+ .catch(() => null)
+ .finally(() => setComposingThumbnail(false));
+ };
+ // In flight from the click until the job is queued; after that the record's `pending` reports progress.
+ const paintThumbnail = (body) => {
+ setPaintingThumbnail(true);
+ return paintMusicVideoYoutubeThumbnail(projectId, body)
+ .then(apply)
+ .catch(() => null)
+ .finally(() => setPaintingThumbnail(false));
+ };
+ const addThumbnailTest = () => addMusicVideoThumbnailTest(projectId).then(apply).catch(() => null);
+ const removeThumbnailTest = (filename) => removeMusicVideoThumbnailTest(projectId, filename).then(apply).catch(() => null);
+ const clearThumbnail = () => {
+ setComposingThumbnail(true);
+ return clearMusicVideoYoutubeThumbnail(projectId)
+ .then(apply)
+ .catch(() => null)
+ .finally(() => setComposingThumbnail(false));
+ };
const composeCover = (body) => {
setComposing(true);
return composeMusicVideoCoverArt(projectId, body)
@@ -137,7 +166,13 @@ export default function useMusicVideoPublishKit({ project, replaceProject } = {}
saving,
draftCopy,
saveCopy,
- selectThumbnail,
+ composingThumbnail,
+ composeThumbnail,
+ clearThumbnail,
+ addThumbnailTest,
+ paintingThumbnail,
+ paintThumbnail,
+ removeThumbnailTest,
composing,
composeCover,
designing,
diff --git a/client/src/hooks/useMusicVideoPublishKit.test.jsx b/client/src/hooks/useMusicVideoPublishKit.test.jsx
index d854572d73..2268057f7c 100644
--- a/client/src/hooks/useMusicVideoPublishKit.test.jsx
+++ b/client/src/hooks/useMusicVideoPublishKit.test.jsx
@@ -11,7 +11,12 @@ vi.mock('../services/apiMusicVideo.js', () => ({
cancelMusicVideoPublishKit: vi.fn(() => Promise.resolve({ ok: true })),
draftMusicVideoPublishCopy: vi.fn(),
updateMusicVideoPublishCopy: vi.fn(),
- selectMusicVideoPublishThumbnail: vi.fn(),
+ composeMusicVideoYoutubeThumbnail: vi.fn(),
+ clearMusicVideoYoutubeThumbnail: vi.fn(),
+ addMusicVideoThumbnailTest: vi.fn(),
+ paintMusicVideoYoutubeThumbnail: vi.fn(),
+ previewMusicVideoThumbnailPaint: vi.fn(),
+ removeMusicVideoThumbnailTest: vi.fn(),
}));
vi.mock('../components/ui/Toast', () => ({ default: { error: vi.fn(), info: vi.fn(), success: vi.fn() } }));
beforeEach(() => { vi.clearAllMocks(); MockEventSource.reset(); vi.stubGlobal('EventSource', MockEventSource); });
diff --git a/client/src/lib/musicVideoCoverOverlay.js b/client/src/lib/musicVideoCoverOverlay.js
index 6d0f2b043d..2628a81844 100644
--- a/client/src/lib/musicVideoCoverOverlay.js
+++ b/client/src/lib/musicVideoCoverOverlay.js
@@ -11,6 +11,7 @@ import { coverFontSpec, tagTextFor, titleLinesFor } from '../../../server/lib/mu
export {
COVER_ART_SIZE,
COVER_DESIGN_OPTIONS,
+ YOUTUBE_THUMBNAIL_SIZE,
DEFAULT_COVER_DESIGN,
coverOverlaySvg,
coverTypefaceChoices,
@@ -25,7 +26,7 @@ const PROBE_PX = 100;
* font size, measured on a canvas in the design's font stack. Null where a
* canvas is unavailable, so the overlay falls back to the faces' average advance.
*/
-export function canvasCoverWidths(design, { title, tag, size }, fonts = []) {
+export function canvasCoverWidths(design, { title, tag, size, frame = 'cover' }, fonts = []) {
const ctx = typeof document === 'undefined' ? null : document.createElement('canvas').getContext?.('2d');
if (!ctx) return null;
const measure = (kind, texts) => {
@@ -36,7 +37,7 @@ export function canvasCoverWidths(design, { title, tag, size }, fonts = []) {
return (text) => out.get(text);
};
return {
- title: measure('title', titleLinesFor(title, design, size, fonts)),
- tag: measure('tag', [tagTextFor(tag, design)]),
+ title: measure('title', titleLinesFor(title, design, size, fonts, frame)),
+ tag: measure('tag', [tagTextFor(tag, design, frame)]),
};
}
diff --git a/client/src/pages/MusicVideo.test.jsx b/client/src/pages/MusicVideo.test.jsx
index 170cba1d69..634102ef9a 100644
--- a/client/src/pages/MusicVideo.test.jsx
+++ b/client/src/pages/MusicVideo.test.jsx
@@ -116,7 +116,12 @@ vi.mock('../services/apiMusicVideo.js', () => ({
getMusicVideoPromotionPlan: vi.fn(async () => ({ steps: [] })),
planMusicVideoPromotion: vi.fn(),
updateMusicVideoPublishCopy: vi.fn(),
- selectMusicVideoPublishThumbnail: vi.fn(),
+ composeMusicVideoYoutubeThumbnail: vi.fn(),
+ clearMusicVideoYoutubeThumbnail: vi.fn(),
+ addMusicVideoThumbnailTest: vi.fn(),
+ paintMusicVideoYoutubeThumbnail: vi.fn(),
+ previewMusicVideoThumbnailPaint: vi.fn(),
+ removeMusicVideoThumbnailTest: vi.fn(),
prepareMusicVideoPublishDraft: vi.fn(),
discardMusicVideoPublishDraft: vi.fn(),
getMusicVideoPublishPlatforms: vi.fn(async () => ({ platforms: {}, history: {} })),
diff --git a/client/src/services/apiMusicVideo.js b/client/src/services/apiMusicVideo.js
index 8963cfe624..1c62515598 100644
--- a/client/src/services/apiMusicVideo.js
+++ b/client/src/services/apiMusicVideo.js
@@ -349,8 +349,22 @@ export const planMusicVideoPromotion = (id, body, options = {}) =>
request(`/music-video/${encodeURIComponent(id)}/publish/promotion-plan`, { method: 'POST', body: JSON.stringify(body || {}), ...options });
export const updateMusicVideoPublishCopy = (id, patch, options = {}) =>
request(`/music-video/${encodeURIComponent(id)}/publish-kit/copy`, { method: 'PATCH', body: JSON.stringify(patch || {}), ...options });
-export const selectMusicVideoPublishThumbnail = (id, filename, options = {}) =>
- request(`/music-video/${encodeURIComponent(id)}/publish-kit/thumbnail`, { method: 'PUT', body: JSON.stringify({ filename }), ...options });
+// The YouTube thumbnail: a source cropped 16:9 with the title in the cover's lettering; DELETE goes back to the best video frame.
+export const composeMusicVideoYoutubeThumbnail = (id, body, options = {}) =>
+ request(`/music-video/${encodeURIComponent(id)}/publish-kit/youtube-thumbnail`, { method: 'POST', body: JSON.stringify(body || {}), ...options });
+export const clearMusicVideoYoutubeThumbnail = (id, options = {}) =>
+ request(`/music-video/${encodeURIComponent(id)}/publish-kit/youtube-thumbnail`, { method: 'DELETE', ...options });
+// "Paint the title" with the image model: the exact prompt and its additions, then the queued job
+// (the result arrives over the `music-video:cover-art` socket event).
+export const previewMusicVideoThumbnailPaint = (id, body, options = {}) =>
+ request(`/music-video/${encodeURIComponent(id)}/publish-kit/youtube-thumbnail/paint/preview`, { method: 'POST', body: JSON.stringify(body || {}), ...options });
+export const paintMusicVideoYoutubeThumbnail = (id, body, options = {}) =>
+ request(`/music-video/${encodeURIComponent(id)}/publish-kit/youtube-thumbnail/paint`, { method: 'POST', body: JSON.stringify(body || {}), ...options });
+// Variants kept for YouTube's Test & Compare (up to three).
+export const addMusicVideoThumbnailTest = (id, options = {}) =>
+ request(`/music-video/${encodeURIComponent(id)}/publish-kit/youtube-thumbnail/tests`, { method: 'POST', ...options });
+export const removeMusicVideoThumbnailTest = (id, filename, options = {}) =>
+ request(`/music-video/${encodeURIComponent(id)}/publish-kit/youtube-thumbnail/tests/${encodeURIComponent(filename)}`, { method: 'DELETE', ...options });
// Release cover art: compose from a source image, or queue a fresh source
// (the result arrives over the `music-video:cover-art` socket event).
export const composeMusicVideoCoverArt = (id, body, options = {}) =>
diff --git a/server/lib/backupAssetOwners.js b/server/lib/backupAssetOwners.js
index eb28d93105..518625a30d 100644
--- a/server/lib/backupAssetOwners.js
+++ b/server/lib/backupAssetOwners.js
@@ -150,6 +150,7 @@ export const BACKUP_ASSET_OWNERS = Object.freeze([
'services/musicVideo/render.js', 'services/musicVideo/excerptRender.js',
'services/musicVideo/publishKit.js', 'services/musicVideo/compositionDocument.js',
'services/musicVideo/sharingCopy.js', 'services/musicVideo/coverArt.js',
+ 'services/musicVideo/youtubeThumbnail.js',
],
},
{
diff --git a/server/lib/musicVideoCoverOverlay.js b/server/lib/musicVideoCoverOverlay.js
index 7c0c2e90e2..70474a791e 100644
--- a/server/lib/musicVideoCoverOverlay.js
+++ b/server/lib/musicVideoCoverOverlay.js
@@ -9,6 +9,20 @@
*/
export const COVER_ART_SIZE = 3000;
+// YouTube's recommended custom thumbnail size (16:9, under its 2 MB cap as a JPEG).
+export const YOUTUBE_THUMBNAIL_SIZE = Object.freeze({ width: 1280, height: 720 });
+
+// How the lettering sits on each frame. A thumbnail is seen small in a feed
+// beside the channel name, so its title is set larger, keeps to one side of the
+// frame (leaving the rest for the picture), stays clear of the bottom-right
+// corner where YouTube draws the duration, carries no artist name, and casts
+// a soft shadow so it reads over a busy frame.
+const FRAMES = {
+ cover: { textScale: 1, textWidth: 1, bottomClear: 0, tag: true, shadow: false },
+ thumbnail: { textScale: 1.7, textWidth: 0.46, bottomClear: 0.14, tag: false, shadow: true },
+};
+const SHADOW_FILTER = '<filter id="shadow" x="-10%" y="-20%" width="120%" height="140%"><feGaussianBlur in="SourceAlpha" stdDeviation="6"/><feOffset dx="0" dy="3" result="b"/><feComponentTransfer><feFuncA type="linear" slope="0.75"/></feComponentTransfer><feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge></filter>';
+export const COVER_FRAMES = Object.freeze(Object.keys(FRAMES));
// The vocabulary a design is written in (the drafting prompt offers exactly these).
export const COVER_DESIGN_OPTIONS = Object.freeze({
@@ -118,20 +132,39 @@ export function fontAttrs(d, kind, fontSize, fonts = []) {
// A stack's own quotes are SVG-safe inside a double-quoted attribute; only a custom family's name can carry markup.
const escapeFamilyStack = (family) => family.replace(/[<>&"]/g, (c) => escapeXml(c));
+/**
+ * The canvas the lettering is laid out on: `size` is a square's side or a
+ * `{ width, height }` box, `frame` a FRAMES key. Margins and the type scale
+ * follow the shorter side, so a square cover lays out exactly as before.
+ */
+function coverBox(size, frame = 'cover') {
+ const width = typeof size === 'object' && size ? size.width : size;
+ const height = typeof size === 'object' && size ? size.height : size;
+ const unit = Math.min(width, height);
+ return { width, height, unit, margin: unit * MARGIN, ...(FRAMES[frame] || FRAMES.cover) };
+}
+
+// The width a title may take: centered layouts span the frame, the others keep to the frame's textWidth.
+const titleRoom = (d, box) => {
+ const full = box.width - 2 * box.margin;
+ return d.layout.endsWith('center') ? full : Math.min(full, box.width * box.textWidth - box.margin);
+};
+
/** The title's lines as the design sets them (one line when it runs up the edge). */
-export function titleLinesFor(title, d, size, fonts = []) {
+export function titleLinesFor(title, d, size, fonts = [], frame = 'cover') {
const text = caseOf(String(title || '').trim(), d.letterCase);
if (d.layout === 'vertical-left') return [text];
- const room = size * (1 - 2 * MARGIN);
- return titleLines(text, Math.max(6, Math.round(room / (size * SCALES[d.scale] * faceFor(d.typeface, fonts).width * (1 + d.tracking)))));
+ const box = coverBox(size, frame);
+ const fontBase = box.unit * SCALES[d.scale] * box.textScale;
+ return titleLines(text, Math.max(6, Math.round(titleRoom(d, box) / (fontBase * faceFor(d.typeface, fonts).width * (1 + d.tracking)))));
}
-/** The artist tag as the design sets it: cased, trimmed, empty when the design has none. */
-export const tagTextFor = (tag, d) => (d.tagStyle === 'none' ? '' : caseOf(String(tag || '').trim().slice(0, 24), d.letterCase));
+/** The artist tag as the design sets it: cased, trimmed, empty when the design (or the frame) has none. */
+export const tagTextFor = (tag, d, frame = 'cover') => (d.tagStyle === 'none' || !coverBox(1, frame).tag ? '' : caseOf(String(tag || '').trim().slice(0, 24), d.letterCase));
// A stencil cuts each line with one thin gap at mid-height (never under 0.2% of the canvas, so a small title still shows it); `strips` are `[x, y, w, h]` in canvas space.
-const stencilGap = (fontSize, size) => Math.max(fontSize * 0.05, size * 0.002);
-const stencilMask = (size, strips) => `<mask id="stencil" maskUnits="userSpaceOnUse" x="0" y="0" width="${size}" height="${size}"><rect width="${size}" height="${size}" fill="#fff"/>${strips.map(([x, y, w, h]) => `<rect x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" fill="#000"/>`).join('')}</mask>`;
+const stencilGap = (fontSize, unit) => Math.max(fontSize * 0.05, unit * 0.002);
+const stencilMask = ({ width, height }, strips) => `<mask id="stencil" maskUnits="userSpaceOnUse" x="0" y="0" width="${width}" height="${height}"><rect width="${width}" height="${height}" fill="#fff"/>${strips.map(([x, y, w, h]) => `<rect x="${n(x)}" y="${n(y)}" width="${n(w)}" height="${n(h)}" fill="#000"/>`).join('')}</mask>`;
/** The fill/stroke that paints the title's glyphs for its `titleStyle`. */
const inkFor = (d, fontSize) => (d.titleStyle === 'outline'
@@ -146,13 +179,13 @@ const inkFor = (d, fontSize) => (d.titleStyle === 'outline'
* `with-title` is part of the block, so the backdrop and the margins hold it;
* `tagSpot` says where it goes.
*/
-function titleParts(title, d, size, widthOf, fonts, tagText) {
+function titleParts(title, d, box, widthOf, fonts, tagText, frame) {
const face = faceFor(d.typeface, fonts);
- const margin = size * MARGIN;
- const room = size - 2 * margin;
+ const { width: W, height: H, unit, margin } = box;
const parts = [];
const defs = [];
- const lines = titleLinesFor(title, d, size, fonts);
+ const lines = titleLinesFor(title, d, box, fonts, frame);
+ const maxSize = unit * SCALES[d.scale] * box.textScale;
const unitW = (line) => widthOf?.(line) ?? line.length * face.width * (1 + d.tracking);
const unitWidest = Math.max(0.001, ...lines.map(unitW));
const stencil = d.titleStyle === 'stencil';
@@ -164,72 +197,79 @@ function titleParts(title, d, size, widthOf, fonts, tagText) {
if (d.layout === 'vertical-left') {
// One line reading bottom to top along the left edge.
- const fontSize = Math.min(size * SCALES[d.scale], room / unitWidest);
+ const fontSize = Math.min(maxSize, (H - 2 * margin) / unitWidest);
if (d.backdrop !== 'none') {
- parts.push(`<rect x="0" y="0" width="${n(margin * 2 + fontSize)}" height="${size}" fill="${d.backdrop === 'band' ? d.accentColor : '#000'}" fill-opacity="${d.backdrop === 'band' ? 1 : 0.6}"/>`);
+ parts.push(`<rect x="0" y="0" width="${n(margin * 2 + fontSize)}" height="${H}" fill="${d.backdrop === 'band' ? d.accentColor : '#000'}" fill-opacity="${d.backdrop === 'band' ? 1 : 0.6}"/>`);
}
- const attrs = `transform="translate(${n(margin + fontSize * ASCENT)} ${n(size - margin)}) rotate(-90)" ${fontAttrs(d, 'title', fontSize, fonts)} ${inkFor(d, fontSize)} font-size="${n(fontSize)}"`;
- text(attrs, lines[0], strips, [margin + fontSize * ASCENT * 0.5, 0, stencilGap(fontSize, size), size]);
- if (stencil) { defs.push(stencilMask(size, strips)); parts.splice(parts.length - 1, 1, `<g mask="url(#stencil)">${parts[parts.length - 1]}</g>`); }
+ const attrs = `transform="translate(${n(margin + fontSize * ASCENT)} ${n(H - margin)}) rotate(-90)" ${fontAttrs(d, 'title', fontSize, fonts)} ${inkFor(d, fontSize)} font-size="${n(fontSize)}"`;
+ text(attrs, lines[0], strips, [margin + fontSize * ASCENT * 0.5, 0, stencilGap(fontSize, unit), H]);
+ if (stencil) { defs.push(stencilMask(box, strips)); parts.splice(parts.length - 1, 1, `<g mask="url(#stencil)">${parts[parts.length - 1]}</g>`); }
+ if (box.shadow) { defs.push(SHADOW_FILTER); parts.splice(parts.length - 1, 1, `<g filter="url(#shadow)">${parts[parts.length - 1]}</g>`); }
return { parts, defs, tagSpot: null };
}
const center = d.layout.endsWith('center');
const atTop = d.layout.startsWith('top');
// As large as the design's scale allows; a long title shrinks to fit.
- const fontSize = Math.min(size * SCALES[d.scale], room / unitWidest);
+ const room = titleRoom(d, box);
+ const fontSize = Math.min(maxSize, room / unitWidest);
const lineH = fontSize * 1.08;
const textH = lineH * (lines.length - 1) + fontSize * ASCENT;
// The tag sits under the title (and under its rule, when the rule is below it).
const ruleBelow = d.rule && (atTop || d.layout === 'center');
- const tagFs = size * TAG_SCALE;
+ const tagFs = unit * TAG_SCALE;
const tagGap = fontSize * (ruleBelow ? 0.6 : 0.3);
const reserve = tagText ? tagGap + tagFs * 1.45 : 0;
const blockH = textH + reserve;
const widest = Math.min(room, unitWidest * fontSize);
- const x = center ? size / 2 : margin;
- const left = center ? (size - widest) / 2 : margin;
- const top = atTop ? margin + size * 0.06 : d.layout === 'center' ? (size - blockH) / 2 : size - margin - blockH;
+ const x = center ? W / 2 : margin;
+ const left = center ? (W - widest) / 2 : margin;
+ const clear = H * box.bottomClear;
+ const top = atTop ? margin + unit * 0.06 : d.layout === 'center' ? (H - blockH) / 2 : H - margin - clear - blockH;
if (d.backdrop === 'fade' && d.layout !== 'center') {
defs.push(`<linearGradient id="fade" x1="0" y1="${atTop ? 1 : 0}" x2="0" y2="${atTop ? 0 : 1}"><stop offset="0" stop-color="#000" stop-opacity="0"/><stop offset="1" stop-color="#000" stop-opacity="0.7"/></linearGradient>`);
- const h = blockH + margin * 3;
- parts.push(`<rect x="0" y="${n(atTop ? 0 : size - h)}" width="${size}" height="${n(h)}" fill="url(#fade)"/>`);
+ const h = blockH + margin * 3 + (atTop ? 0 : clear);
+ parts.push(`<rect x="0" y="${n(atTop ? 0 : H - h)}" width="${W}" height="${n(h)}" fill="url(#fade)"/>`);
} else if (d.backdrop === 'band') {
const pad = fontSize * 0.35;
- parts.push(`<rect x="0" y="${n(top - pad)}" width="${size}" height="${n(blockH + pad * 2)}" fill="${d.accentColor}"/>`);
+ parts.push(`<rect x="0" y="${n(top - pad)}" width="${W}" height="${n(blockH + pad * 2)}" fill="${d.accentColor}"/>`);
} else if (d.backdrop === 'box' || (d.backdrop === 'fade' && d.layout === 'center')) {
const pad = fontSize * 0.4;
parts.push(`<rect x="${n(left - pad)}" y="${n(top - pad)}" width="${n(widest + pad * 2)}" height="${n(blockH + pad * 2)}" fill="#000" fill-opacity="0.65"/>`);
}
if (d.rule) {
const ry = atTop ? top + textH + fontSize * 0.35 : top - fontSize * 0.35;
- parts.push(`<rect x="${n(left)}" y="${n(ry)}" width="${n(widest)}" height="${n(size * 0.004)}" fill="${d.accentColor}"/>`);
+ parts.push(`<rect x="${n(left)}" y="${n(ry)}" width="${n(widest)}" height="${n(unit * 0.004)}" fill="${d.accentColor}"/>`);
}
const ink = `${fontAttrs(d, 'title', fontSize, fonts)} ${inkFor(d, fontSize)}`;
const titleStart = parts.length;
lines.forEach((line, i) => {
const baseline = top + fontSize * ASCENT + i * lineH;
- text(`x="${n(x)}" y="${n(baseline)}" ${ink} font-size="${n(fontSize)}" text-anchor="${center ? 'middle' : 'start'}"`, line, strips, [0, baseline - fontSize * ASCENT * 0.5, size, stencilGap(fontSize, size)]);
+ text(`x="${n(x)}" y="${n(baseline)}" ${ink} font-size="${n(fontSize)}" text-anchor="${center ? 'middle' : 'start'}"`, line, strips, [0, baseline - fontSize * ASCENT * 0.5, W, stencilGap(fontSize, unit)]);
});
if (stencil) {
- defs.push(stencilMask(size, strips));
+ defs.push(stencilMask(box, strips));
parts.splice(titleStart, parts.length - titleStart, `<g mask="url(#stencil)">${parts.slice(titleStart).join('')}</g>`);
}
+ if (box.shadow) {
+ defs.push(SHADOW_FILTER);
+ parts.splice(titleStart, parts.length - titleStart, `<g filter="url(#shadow)">${parts.slice(titleStart).join('')}</g>`);
+ }
const tagSpot = tagText ? { x, anchor: center ? 'middle' : 'start', baseline: top + textH + tagGap + tagFs * 1.05 } : null;
return { parts, defs, tagSpot };
}
/** The artist tag, small: under the title, or at the edge across from it. */
-function tagParts(tagText, d, size, widthOf, fonts, spot) {
+function tagParts(tagText, d, box, widthOf, fonts, spot) {
if (!tagText) return [];
- const margin = size * MARGIN;
- const fs = size * TAG_SCALE;
+ const { width: W, height: H, margin } = box;
+ const fs = box.unit * TAG_SCALE;
const w = (widthOf?.(tagText) ?? tagText.length * faceFor(d.typeface, fonts).width * 1.08) * fs;
const center = d.layout.endsWith('center') && d.layout !== 'center';
const anchor = spot ? spot.anchor : center ? 'middle' : 'end';
- const tx = spot ? spot.x : center ? size / 2 : size - margin;
- const baseline = spot ? spot.baseline : d.layout.startsWith('top') ? size - margin : margin + fs * ASCENT;
+ const tx = spot ? spot.x : center ? W / 2 : W - margin;
+ const baseline = spot ? spot.baseline : d.layout.startsWith('top') ? H - margin : margin + fs * ASCENT;
const font = `${fontAttrs(d, 'tag', fs, fonts)} font-size="${n(fs)}" text-anchor="${anchor}"`;
if (d.tagStyle !== 'boxed') return [`<text x="${n(tx)}" y="${n(baseline)}" ${font} fill="${d.accentColor}">${escapeXml(tagText)}</text>`];
const pad = fs * 0.5;
@@ -242,15 +282,18 @@ function tagParts(tagText, d, size, widthOf, fonts, spot) {
/**
* The overlay as SVG: the song's title and artist tag, laid out by its design.
+ * `size` is a square's side or a `{ width, height }` box and `frame` how the
+ * lettering sits on it (`cover`, or `thumbnail` for a YouTube thumbnail).
* `widths` is `{ title(text), tag(text) }`, each a text's width at a 1px font
* size, or null to lay out by the faces' average advance; `fonts` is the
* uploaded typefaces.
*/
-export function coverOverlaySvg({ title, tag = '', design, size = COVER_ART_SIZE, widths = null, fonts = [] }) {
+export function coverOverlaySvg({ title, tag = '', design, size = COVER_ART_SIZE, frame = 'cover', widths = null, fonts = [] }) {
const d = normalizeCoverDesign(design, { fonts });
- const tagText = tagTextFor(tag, d);
+ const box = coverBox(size, frame);
+ const tagText = tagTextFor(tag, d, frame);
const withTitle = d.tagLayout === 'with-title' && d.layout !== 'vertical-left';
- const { parts, defs, tagSpot } = titleParts(title, d, size, widths?.title, fonts, withTitle ? tagText : '');
- const tagSvg = tagParts(tagText, d, size, widths?.tag, fonts, withTitle ? tagSpot : null);
- return `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}">${defs.length ? `<defs>${defs.join('')}</defs>` : ''}${[...parts, ...tagSvg].join('')}</svg>`;
+ const { parts, defs, tagSpot } = titleParts(title, d, box, widths?.title, fonts, withTitle ? tagText : '', frame);
+ const tagSvg = tagParts(tagText, d, box, widths?.tag, fonts, withTitle ? tagSpot : null);
+ return `<svg xmlns="http://www.w3.org/2000/svg" width="${box.width}" height="${box.height}" viewBox="0 0 ${box.width} ${box.height}">${defs.length ? `<defs>${defs.join('')}</defs>` : ''}${[...parts, ...tagSvg].join('')}</svg>`;
}
diff --git a/server/lib/musicVideoCoverOverlay.test.js b/server/lib/musicVideoCoverOverlay.test.js
index 6fcbf6c6c0..f740628204 100644
--- a/server/lib/musicVideoCoverOverlay.test.js
+++ b/server/lib/musicVideoCoverOverlay.test.js
@@ -54,3 +54,29 @@ describe('cover lettering treatments', () => {
expect(textY(alone, 'EXAMPLE SONG')).toBe(textY(apart, 'EXAMPLE SONG'));
});
});
+
+describe('YouTube thumbnail lettering', () => {
+ const THUMB = { title: 'Example Song Title', tag: 'Example Artist', size: { width: 1280, height: 720 }, frame: 'thumbnail' };
+ const fontSizes = (svg) => [...svg.matchAll(/font-size="([\d.]+)"/g)].map((m) => Number(m[1]));
+
+ it('sets the title larger than a cover would on the same height, with no artist name', () => {
+ const svg = coverOverlaySvg({ ...THUMB, design: { layout: 'bottom-left' } });
+ expect(svg).toContain('width="1280" height="720" viewBox="0 0 1280 720"');
+ expect(svg).not.toContain('EXAMPLE ARTIST');
+ const cover = coverOverlaySvg({ title: THUMB.title, tag: THUMB.tag, size: 720, design: { layout: 'bottom-left' } });
+ expect(Math.max(...fontSizes(svg))).toBeGreaterThan(Math.max(...fontSizes(cover)) * 1.4);
+ });
+
+ it('keeps a side-anchored title to one side and every bottom layout above the duration badge', () => {
+ // An average-advance layout: the line's right edge is x + chars × advance × size.
+ const left = coverOverlaySvg({ ...THUMB, design: { layout: 'bottom-left', typeface: 'sans' } });
+ const lines = [...left.matchAll(/<text x="([\d.]+)" y="[\d.]+"[^>]*font-size="([\d.]+)"[^>]*>([^<]+)<\/text>/g)];
+ expect(lines.length).toBeGreaterThan(1);
+ for (const [, x, fs, line] of lines) expect(Number(x) + line.length * 0.6 * 1.02 * Number(fs)).toBeLessThanOrEqual(1280 * 0.46 + 1);
+ for (const layout of ['bottom-left', 'bottom-center']) {
+ const svg = coverOverlaySvg({ ...THUMB, design: { layout } });
+ const lowest = Math.max(...[...svg.matchAll(/<text[^>]* y="([\d.]+)"/g)].map((m) => Number(m[1])));
+ expect(lowest).toBeLessThan(720 * (1 - 0.14));
+ }
+ });
+});
diff --git a/server/lib/musicVideoValidation.js b/server/lib/musicVideoValidation.js
index ff4c956f75..9884613c12 100644
--- a/server/lib/musicVideoValidation.js
+++ b/server/lib/musicVideoValidation.js
@@ -877,6 +877,20 @@ export const musicVideoCoverArtComposeSchema = z.object({
// false = a finished cover from elsewhere: squared and sized, no title or tag set on it.
lettering: z.boolean().optional(),
}).strict();
+// The YouTube thumbnail: a source composed 16:9 with the title in the cover's lettering.
+export const musicVideoYoutubeThumbnailComposeSchema = z.object({
+ source: coverArtSourceSchema.optional(),
+ title: z.string().max(60).optional(),
+ focusX: z.number().min(0).max(1).optional(),
+ focusY: z.number().min(0).max(1).optional(),
+ lettering: z.boolean().optional(),
+}).strict();
+// "Paint the title": the image model restyles a frame with the title drawn in. Preview takes no source.
+export const musicVideoYoutubeThumbnailPaintPreviewSchema = z.object({
+ title: z.string().trim().min(1).max(60),
+ notes: z.string().max(1500).optional(),
+}).strict();
+export const musicVideoYoutubeThumbnailPaintSchema = musicVideoYoutubeThumbnailPaintPreviewSchema.extend({ source: coverArtSourceSchema }).strict();
export const musicVideoCoverArtDesignSchema = z.object({
direction: z.string().max(1500).optional(),
providerId: z.string().min(1).max(200).optional(),
diff --git a/server/routes/musicVideo.js b/server/routes/musicVideo.js
index 8125cda4f6..d9ab100847 100644
--- a/server/routes/musicVideo.js
+++ b/server/routes/musicVideo.js
@@ -49,6 +49,9 @@ import {
musicVideoPromotionPlanSchema,
musicVideoPublishThumbnailSchema,
musicVideoCoverArtComposeSchema,
+ musicVideoYoutubeThumbnailComposeSchema,
+ musicVideoYoutubeThumbnailPaintSchema,
+ musicVideoYoutubeThumbnailPaintPreviewSchema,
musicVideoCoverArtGenerateSchema,
musicVideoCoverDesignSaveSchema,
musicVideoArtistStyleSaveSchema,
@@ -1078,6 +1081,49 @@ router.put('/:id/publish-kit/thumbnail', asyncHandler(async (req, res) => {
res.json({ project });
}));
+// The YouTube thumbnail: a source cropped 16:9 with the title set in the
+// cover's lettering. DELETE goes back to the picked video frame.
+router.post('/:id/publish-kit/youtube-thumbnail', asyncHandler(async (req, res) => {
+ const input = validateRequest(musicVideoYoutubeThumbnailComposeSchema, req.body ?? {});
+ const { composeProjectYoutubeThumbnail } = await import('../services/musicVideo/youtubeThumbnail.js');
+ const { project } = await composeProjectYoutubeThumbnail(req.params.id, input);
+ res.json({ project });
+}));
+
+router.delete('/:id/publish-kit/youtube-thumbnail', asyncHandler(async (req, res) => {
+ const { clearProjectYoutubeThumbnail } = await import('../services/musicVideo/youtubeThumbnail.js');
+ const { project } = await clearProjectYoutubeThumbnail(req.params.id);
+ res.json({ project });
+}));
+
+// "Paint the title": what the image model would receive, then the queued job
+// (its completion hook makes the result the thumbnail).
+router.post('/:id/publish-kit/youtube-thumbnail/paint/preview', asyncHandler(async (req, res) => {
+ const input = validateRequest(musicVideoYoutubeThumbnailPaintPreviewSchema, req.body ?? {});
+ const { buildThumbnailPaintPrompt } = await import('../services/musicVideo/youtubeThumbnail.js');
+ res.json(buildThumbnailPaintPrompt(input));
+}));
+
+router.post('/:id/publish-kit/youtube-thumbnail/paint', asyncHandler(async (req, res) => {
+ const input = validateRequest(musicVideoYoutubeThumbnailPaintSchema, req.body ?? {});
+ const { paintYoutubeThumbnail } = await import('../services/musicVideo/youtubeThumbnail.js');
+ const { project } = await paintYoutubeThumbnail(req.params.id, input);
+ res.json({ project });
+}));
+
+// Variants kept for YouTube's Test & Compare (up to three): add the made thumbnail, or drop one.
+router.post('/:id/publish-kit/youtube-thumbnail/tests', asyncHandler(async (req, res) => {
+ const { addYoutubeThumbnailTest } = await import('../services/musicVideo/youtubeThumbnail.js');
+ const { project } = await addYoutubeThumbnailTest(req.params.id);
+ res.json({ project });
+}));
+
+router.delete('/:id/publish-kit/youtube-thumbnail/tests/:filename', asyncHandler(async (req, res) => {
+ const { removeYoutubeThumbnailTest } = await import('../services/musicVideo/youtubeThumbnail.js');
+ const { project } = await removeYoutubeThumbnailTest(req.params.id, req.params.filename);
+ res.json({ project });
+}));
+
// Release cover art: the song's own design (drafted, or adjusted from the
// director's direction), compose from a chosen image, or queue a fresh cover
// photo whose completion hook composes the cover.
diff --git a/server/services/musicVideo/backupAdmission.test.js b/server/services/musicVideo/backupAdmission.test.js
index 350821f457..7f26b1368f 100644
--- a/server/services/musicVideo/backupAdmission.test.js
+++ b/server/services/musicVideo/backupAdmission.test.js
@@ -44,6 +44,7 @@ const { renderMusicVideo } = await import('./render.js');
const { startExcerptRender } = await import('./excerptRender.js');
const { importDocumentTemplate } = await import('./compositionDocument.js');
const { startPublishKitBuild } = await import('./publishKit.js');
+const { thumbnailCandidates } = await import('./thumbnailFrames.js');
const { encodeDocumentComposition } = await import('./documentRender.js');
const { runFfmpegProcess } = await import('../../lib/ffmpeg.js');
const { mutateVideoHistory } = await import('../videoGen/local.js');
@@ -169,15 +170,17 @@ describe('publishing kit build', () => {
runFfmpegProcess.mockClear();
const release = await acquireBackupSnapshotCut();
try {
+ const frames = thumbnailCandidates(await projects.getProject(id), 12.5).length;
await startPublishKitBuild(id);
- // Thumbnails are the build's last ffmpeg step.
- await waitFor(async () => expect((await readdir(PATHS.videoThumbnails)).some(name => name.endsWith('-thumb-6.jpg'))).toBe(true));
+ // Thumbnail frames are the build's last ffmpeg step; unpicked ones are deleted, so watch the calls.
+ const lastFrame = `-thumb-${frames}.jpg`;
+ await waitFor(() => expect(runFfmpegProcess.mock.calls.some(([{ args }]) => args.at(-1).endsWith(lastFrame))).toBe(true));
await settleSeveral();
const encoded = runFfmpegProcess.mock.calls.length;
- expect(encoded).toBeGreaterThan(6);
+ expect(encoded).toBeGreaterThan(frames);
expect((await projects.getProject(id)).publishKit?.exports).toBeUndefined();
release();
- await waitFor(async () => expect((await projects.getProject(id)).publishKit?.exports?.length).toBe(encoded - 6));
+ await waitFor(async () => expect((await projects.getProject(id)).publishKit?.exports?.length).toBe(encoded - frames));
for (const { filename } of (await projects.getProject(id)).publishKit.exports) {
expect(existsSync(join(PATHS.videos, filename))).toBe(true);
}
diff --git a/server/services/musicVideo/coverArt.js b/server/services/musicVideo/coverArt.js
index 8645937ced..3dad7ce72c 100644
--- a/server/services/musicVideo/coverArt.js
+++ b/server/services/musicVideo/coverArt.js
@@ -63,7 +63,7 @@ export function __setCoverArtDepsForTests(overrides) { deps = { ...defaults, ...
* default, else the PortOS image default (local, Codex, Grok, …). Null when
* that backend cannot take a queued job or its cloud toggle is off.
*/
-async function defaultImageRoute(settings) {
+export async function defaultImageRoute(settings) {
const [{ resolveRenderTargetConfig }, { QUEUEABLE_IMAGE_MODES }, { RENDER_TARGET }] = await Promise.all([
import('../imageGen/cloudProviderConfig.js'), import('../../lib/generationModes.js'), import('../../lib/renderTargets.js'),
]);
@@ -95,7 +95,7 @@ const writeCoverArt = (projectId, update) => mutateProjectRecord(projectId, (cur
});
/** A source's file on disk: a thumbnail this kit cut, or a gallery image. */
-function sourcePath(project, source) {
+export function sourcePath(project, source) {
const name = basename(String(source?.filename || ''));
if (source?.kind === 'thumbnail') {
if (!(projectPublishKit(project).thumbnails || []).includes(name)) throw coverError(422, 'VALIDATION_ERROR', 'That thumbnail is not one this kit built');
@@ -178,10 +178,12 @@ export async function designCoverArt(projectId, { direction = '', providerId = n
lastError: null,
}));
console.log(`🖼️ Music Video cover art ${String(projectId).slice(3, 11)}: design ${previous ? 'adjusted' : 'drafted'} (${drafted.design.layout}, ${drafted.design.typeface})`);
+ const refreshed = await refreshYoutubeThumbnail(projectId);
// Restyling the lettering puts it back on a cover that was used bare.
if (art.source) return composeProjectCoverArt(projectId, { lettering: true });
- publish(projectId, out.project);
- return { project: out.project };
+ const latest = refreshed || out.project;
+ publish(projectId, latest);
+ return { project: latest };
}
/**
@@ -197,10 +199,23 @@ export async function saveCoverDesign(projectId, patch = {}) {
const design = normalizeCoverDesign({ ...normalizeCoverDesign(art.design, { fonts }), ...patch }, { fonts });
const out = await writeCoverArt(projectId, () => ({ design, lastError: null }));
console.log(`🖼️ Music Video cover art ${String(projectId).slice(3, 11)}: lettering set (${design.layout}, ${design.typeface}, ${design.titleStyle})`);
+ const refreshed = await refreshYoutubeThumbnail(projectId);
// Like a restyle, setting the lettering puts it back on a cover that was used bare.
if (art.source) return composeProjectCoverArt(projectId, { lettering: true });
- publish(projectId, out.project);
- return { project: out.project };
+ const latest = refreshed || out.project;
+ publish(projectId, latest);
+ return { project: latest };
+}
+
+// The YouTube thumbnail is set in the same lettering, so a new design re-sets it too.
+// A failure there leaves the old thumbnail and never fails the cover's change.
+// Returns the updated project, or null when nothing changed.
+async function refreshYoutubeThumbnail(projectId) {
+ const { recomposeYoutubeThumbnail } = await import('./youtubeThumbnail.js');
+ return recomposeYoutubeThumbnail(projectId).catch((err) => {
+ console.warn(`⚠️ Music Video thumbnail ${String(projectId).slice(3, 11)}: not re-set in the new lettering (${err.message})`);
+ return null;
+ });
}
// Where the photo should stay calm, so the title reads over it.
diff --git a/server/services/musicVideo/coverArtCompose.js b/server/services/musicVideo/coverArtCompose.js
index 68e6a3413a..e536010de4 100644
--- a/server/services/musicVideo/coverArtCompose.js
+++ b/server/services/musicVideo/coverArtCompose.js
@@ -14,11 +14,11 @@
*/
import {
- COVER_ART_SIZE, coverOverlaySvg, fontAttrs, normalizeCoverDesign, tagTextFor, titleLinesFor,
+ COVER_ART_SIZE, YOUTUBE_THUMBNAIL_SIZE, coverOverlaySvg, fontAttrs, normalizeCoverDesign, tagTextFor, titleLinesFor,
} from '../../lib/musicVideoCoverOverlay.js';
export {
- COVER_ART_SIZE, COVER_DESIGN_OPTIONS, DEFAULT_COVER_DESIGN, coverOverlaySvg, normalizeCoverDesign,
+ COVER_ART_SIZE, COVER_DESIGN_OPTIONS, DEFAULT_COVER_DESIGN, YOUTUBE_THUMBNAIL_SIZE, coverOverlaySvg, normalizeCoverDesign,
} from '../../lib/musicVideoCoverOverlay.js';
const escapeXml = (s) => String(s).replace(/[<>&"']/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' })[c]);
@@ -38,34 +38,47 @@ export async function measureWidths(sharp, texts, font) {
return (text) => out.get(text);
}
+const unitRange = (v, fallback = 0.5) => Math.min(1, Math.max(0, Number.isFinite(v) ? v : fallback));
+
/**
- * Write `out` (a JPEG): `source` cropped to its largest square at `focusX`
- * (0 = left edge, 1 = right edge), scaled to `size`, with the song's design on top.
- * `lettering: false` leaves the image bare: a finished cover designed elsewhere.
- * `fonts` are the uploaded typefaces the design may name (already registered
- * with the renderer, see coverFonts.js).
+ * Write `out` (a JPEG): `source` cropped to the largest `width`×`height` frame
+ * it holds, at `focusX` / `focusY` along whichever side has room to spare
+ * (0 = left/top, 1 = right/bottom), scaled to that size, with the song's
+ * design on top laid out for `frame` (lib/musicVideoCoverOverlay.js).
+ * `lettering: false` leaves the image bare. `fonts` are the uploaded typefaces
+ * the design may name (already registered with the renderer, see coverFonts.js).
*/
-export async function composeCoverArt({ source, out, title, tag = '', design = null, fonts = [], focusX = 0.5, size = COVER_ART_SIZE, lettering = true }, deps = {}) {
+async function composeLetteredImage({ source, out, title, tag = '', design = null, fonts = [], focusX = 0.5, focusY = 0.5, width, height, frame = 'cover', lettering = true, quality = 92 }, deps = {}) {
const sharp = deps.sharp || (await import('sharp')).default;
// Apply the EXIF orientation first, so the crop is measured on the upright image.
const { data, info } = await sharp(source).rotate().toBuffer({ resolveWithObject: true });
- const side = Math.min(info.width, info.height);
- const fx = Math.min(1, Math.max(0, Number.isFinite(focusX) ? focusX : 0.5));
- const left = Math.round((info.width - side) * fx);
- const top = Math.round((info.height - side) / 2);
+ const scale = Math.min(info.width / width, info.height / height);
+ const cropW = Math.min(info.width, Math.round(width * scale));
+ const cropH = Math.min(info.height, Math.round(height * scale));
let image = sharp(data)
- .extract({ left, top, width: side, height: side })
- .resize(size, size, { kernel: 'lanczos3' });
+ .extract({ left: Math.round((info.width - cropW) * unitRange(focusX)), top: Math.round((info.height - cropH) * unitRange(focusY)), width: cropW, height: cropH })
+ .resize(width, height, { kernel: 'lanczos3' });
if (lettering) {
const d = normalizeCoverDesign(design, { fonts });
+ const box = { width, height };
const widths = {
- title: await measureWidths(sharp, titleLinesFor(title, d, size, fonts), fontAttrs(d, 'title', PROBE_PX, fonts)),
- tag: await measureWidths(sharp, [tagTextFor(tag, d)], fontAttrs(d, 'tag', PROBE_PX, fonts)),
+ title: await measureWidths(sharp, titleLinesFor(title, d, box, fonts, frame), fontAttrs(d, 'title', PROBE_PX, fonts)),
+ tag: await measureWidths(sharp, [tagTextFor(tag, d, frame)], fontAttrs(d, 'tag', PROBE_PX, fonts)),
};
- image = image.composite([{ input: Buffer.from(coverOverlaySvg({ title, tag, design: d, size, widths, fonts })), top: 0, left: 0 }]);
+ image = image.composite([{ input: Buffer.from(coverOverlaySvg({ title, tag, design: d, size: box, frame, widths, fonts })), top: 0, left: 0 }]);
}
await image
- .jpeg({ quality: 92, chromaSubsampling: '4:4:4' })
+ .jpeg({ quality, chromaSubsampling: '4:4:4' })
.toFile(out);
- return { width: size, height: size };
+ return { width, height };
}
+
+/** The square release cover: `source` cropped square at `focusX`, scaled to `size`. */
+export const composeCoverArt = ({ size = COVER_ART_SIZE, ...rest }, deps = {}) => composeLetteredImage({ ...rest, width: size, height: size, frame: 'cover' }, deps);
+
+/**
+ * A YouTube thumbnail: `source` cropped 16:9, the title set large on one side
+ * and clear of the duration badge, no artist name. YouTube refuses one over
+ * 2 MB, which a 1280x720 JPEG at this quality stays well under.
+ */
+export const composeYoutubeThumbnail = (opts, deps = {}) => composeLetteredImage({ ...opts, ...YOUTUBE_THUMBNAIL_SIZE, frame: 'thumbnail', quality: 90 }, deps);
diff --git a/server/services/musicVideo/publish/payloads.js b/server/services/musicVideo/publish/payloads.js
index f0648c202f..d781f71a02 100644
--- a/server/services/musicVideo/publish/payloads.js
+++ b/server/services/musicVideo/publish/payloads.js
@@ -146,6 +146,12 @@ const releaseCover = (kit) => {
return kit.thumbnail ? { dir: 'videoThumbnails', name: kit.thumbnail } : null;
};
+// The thumbnail made under YouTube thumbnail when there is one, else the video frame picked (the best one, by default).
+const youtubeThumbnailFile = (kit) => {
+ if (kit.youtubeThumbnail?.filename) return { dir: 'videoThumbnails', name: kit.youtubeThumbnail.filename, made: true };
+ return kit.thumbnail ? { dir: 'videoThumbnails', name: kit.thumbnail } : null;
+};
+
/** The 1080p encode a native video post (LinkedIn, Facebook) uploads. */
function nativeVideo(project, kit, platform) {
const clip = (kit.exports || []).find((e) => e.kind === 'x-1080p')?.filename;
@@ -178,7 +184,7 @@ const BUILDERS = {
title: requireTitle('youtube', text(kit.copy?.youtube?.title)),
...youtubeDescription(kit, options),
tags: (kit.copy?.youtube?.tags || []).map(text).filter(Boolean),
- thumbnail: kit.thumbnail ? { dir: 'videoThumbnails', name: kit.thumbnail } : null,
+ thumbnail: youtubeThumbnailFile(kit),
captions: kit.captionsFilename ? { dir: 'videos', name: kit.captionsFilename } : null,
};
},
@@ -401,7 +407,7 @@ export function publishPreviewParts(platform, project, payload) {
add('Video', 'The final render');
add('Title', p.title); add('Description', p.description);
add('Tags', p.tags?.length ? p.tags.join(', ') : 'None');
- add('Thumbnail', p.thumbnail ? 'The one picked under Release assets' : 'None');
+ add('Thumbnail', p.thumbnail ? (p.thumbnail.made ? 'The one made under YouTube thumbnail' : 'The video frame picked under YouTube thumbnail') : 'None');
add('Captions', p.captions ? 'Lyric captions (SRT)' : 'None');
break;
case 'shorts':
diff --git a/server/services/musicVideo/publishKit.js b/server/services/musicVideo/publishKit.js
index 6e07f31638..5622eaf6b3 100644
--- a/server/services/musicVideo/publishKit.js
+++ b/server/services/musicVideo/publishKit.js
@@ -28,10 +28,10 @@ import { musicVideoDependencyChanges } from '../../lib/musicVideoDependencies.js
import { buildChapters, buildSrt, buildPublishCopyPrompt, parsePublishCopy, normalizeCopyOptions, PUBLISH_PLATFORMS } from './publishKitText.js';
import { canonicalizeSunoUrl, isSunoShareLink } from '../sunoShareLink.js';
import { trackedRenderMap } from '../renderActivity.js';
+import { pickThumbnailFrames, scoreThumbnailFrame, thumbnailCandidates } from './thumbnailFrames.js';
const jobs = new Map();
const projectBuilds = trackedRenderMap('music-video-publish-kit', { noun: 'publishing kit build', link: (projectId) => `/music-video/${encodeURIComponent(projectId)}` });
-const MAX_THUMBNAILS = 6;
// X caps a Premium upload's bitrate well under a 1080p master's; ~12 Mbps
// keeps the analog grain without the upload being re-crushed.
// 9:16 canvas: the full frame fitted to width over a blurred, cover-scaled copy of itself, so edge text is never cropped.
@@ -70,16 +70,6 @@ async function finalRenderFile(project) {
return { entry, path };
}
-/** Frame times worth a thumbnail: performance-shot midpoints spread across the song, else even steps. */
-function thumbnailTimes(project, durationSec, max = MAX_THUMBNAILS) {
- const perf = (project.scenes || [])
- .filter((s) => s?.shotMode === 'performance' && Number.isFinite(s.startSec) && Number.isFinite(s.endSec) && s.endSec > s.startSec && s.startSec < durationSec)
- .map((s) => (s.startSec + Math.min(s.endSec, durationSec)) / 2);
- const pool = perf.length ? perf : Array.from({ length: max }, (_, i) => ((i + 0.5) / max) * durationSec);
- if (pool.length <= max) return pool.map((t) => Math.round(t * 1000) / 1000);
- return Array.from({ length: max }, (_, i) => pool[Math.floor((i * pool.length) / max)]).map((t) => Math.round(t * 1000) / 1000);
-}
-
/** A file an older build left behind, deleted only once no project's kit still names it (a clone shares the record). */
export async function releaseKitFiles(filenames, keep = []) {
if (!filenames.length) return;
@@ -87,7 +77,11 @@ export async function releaseKitFiles(filenames, keep = []) {
const referenced = new Set(keep);
for (const p of others) {
const kit = projectPublishKit(p);
- for (const f of [...(kit.exports || []).map((e) => e.filename), ...(kit.thumbnails || []), kit.captionsFilename, kit.coverArt?.filename]) if (f) referenced.add(f);
+ // A made YouTube thumbnail (and each A/B variant) also holds the kit frame it was made from,
+ // so a rebuild leaves it there to re-set in new lettering.
+ const made = [kit.youtubeThumbnail, ...(Array.isArray(kit.youtubeThumbnailTests) ? kit.youtubeThumbnailTests : [])].filter(Boolean);
+ const madeFrom = made.map((t) => (t.source?.kind === 'thumbnail' ? t.source.filename : null));
+ for (const f of [...(kit.exports || []).map((e) => e.filename), ...(kit.thumbnails || []), kit.captionsFilename, kit.coverArt?.filename, ...made.map((t) => t.filename), ...madeFrom]) if (f) referenced.add(f);
}
for (const name of filenames) {
if (referenced.has(name)) continue;
@@ -153,8 +147,8 @@ async function beginPublishKitBuild(projectId, jobId) {
'-vf', VERTICAL_FIT_FILTER, ...X_VIDEO_ARGS,
'-af', `asetpts=PTS-STARTPTS${edgeFadeFilter(teaser.endSec - teaser.startSec)}`, ...AUDIO_ARGS] }] : []),
];
- const times = thumbnailTimes(project, durationSec);
- const total = encodes.length + times.length;
+ const candidates = thumbnailCandidates(project, durationSec);
+ const total = encodes.length + candidates.length;
const written = [];
let done = 0;
const step = () => broadcastSse(job, { type: 'progress', progress: Math.min(0.99, ++done / total) });
@@ -198,13 +192,19 @@ async function beginPublishKitBuild(projectId, jobId) {
written.push(encode.filename);
step();
}
- const thumbnails = [];
- for (const [i, t] of times.entries()) {
+ // Cut every candidate, keep the best frame of each shot, and drop the rest.
+ // A thumbnail fills the 16:9 frame: a master of another shape is cropped, never boxed in black bars.
+ const scored = [];
+ for (const [i, c] of candidates.entries()) {
const name = `${stem}-thumb-${i + 1}.jpg`;
- const result = await runFfmpegProcess({ bin: ffmpeg, signal: job.abort.signal, args: ['-hide_banner', '-loglevel', 'error', '-ss', String(t), '-i', masterPath, '-frames:v', '1', '-vf', 'scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2', '-q:v', '2', '-y', join(PATHS.videoThumbnails, name)] });
- if (result.ok) { thumbnails.push(name); written.push(name); }
+ const path = join(PATHS.videoThumbnails, name);
+ const result = await runFfmpegProcess({ bin: ffmpeg, signal: job.abort.signal, args: ['-hide_banner', '-loglevel', 'error', '-ss', String(c.t), '-i', masterPath, '-frames:v', '1', '-vf', 'scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720', '-q:v', '2', '-y', path] });
+ if (result.ok) scored.push({ ...c, name, score: await scoreThumbnailFrame(path).catch(() => NaN) });
step();
}
+ const thumbnails = pickThumbnailFrames(scored).map((c) => c.name);
+ await Promise.all(scored.filter((c) => !thumbnails.includes(c.name)).map((c) => unlink(join(PATHS.videoThumbnails, c.name)).catch(() => {})));
+ written.push(...thumbnails);
const srt = buildSrt(project);
const captionsFilename = srt ? `${stem}-captions.srt` : null;
if (srt) { await writeFile(join(PATHS.videos, captionsFilename), srt); written.push(captionsFilename); }
diff --git a/server/services/musicVideo/publishKit.test.js b/server/services/musicVideo/publishKit.test.js
index 90ee3b6131..b5c1a047c1 100644
--- a/server/services/musicVideo/publishKit.test.js
+++ b/server/services/musicVideo/publishKit.test.js
@@ -21,6 +21,7 @@ const { findFfmpeg, runFfmpegProcess } = ffmpegService;
const projects = await import('./projects.js');
const { saveHistory } = await import('../videoGen/history.js');
const kit = await import('./publishKit.js');
+const frames = await import('./thumbnailFrames.js');
const excerptRender = await import('./excerptRender.js');
const { captureMusicVideoEvidence } = await import('../../lib/musicVideoDependencies.js');
const ffmpeg = await findFfmpeg();
@@ -171,7 +172,7 @@ describe('publishing kit build (#9281)', () => {
const vertical = first.exports.find((e) => e.kind === 'vertical-9x16');
const probed = await runFfmpegProcess({ bin: ffmpeg, args: ['-hide_banner', '-i', join(PATHS.videos, vertical.filename), '-f', 'null', '-'] });
expect(probed.ok).toBe(true);
- expect(first.thumbnails).toHaveLength(2); // the two performance shots
+ expect(first.thumbnails).toHaveLength(3); // the best frame of each shot
expect(first.thumbnail).toBe(first.thumbnails[0]);
expect(await readFile(join(PATHS.videos, first.captionsFilename), 'utf8')).toContain('the chorus line');
expect(first.chapters.map((c) => c.label)).toEqual(['first verse line', 'the chorus line', 'last words']);
@@ -408,3 +409,57 @@ describe('publishing kit copy (#9281)', () => {
await expect(kit.selectPublishKitThumbnail(id, 'elsewhere.jpg')).rejects.toMatchObject({ status: 422 });
});
});
+
+describe('thumbnail frames', () => {
+ const project = {
+ scenes: [scene(0, 10, 'Verse 1'), scene(10, 20, 'Chorus 1', 'cutaway')],
+ lyricCues: [cue('a line', 1, 6), cue('another line', 10, 20)],
+ };
+
+ it('looks inside each shot, away from its cuts, and where the shot has a moment with no lyric on screen, inside it', () => {
+ const candidates = frames.thumbnailCandidates(project, 20);
+ expect(candidates).toHaveLength(4);
+ // Shot 1: lyrics cover 1–6 s of its 1.5–8.5 s middle, so both frames come from 6–8.5 s.
+ const first = candidates.filter((c) => c.shot === 'mvs-0');
+ for (const c of first) { expect(c.t).toBeGreaterThanOrEqual(6); expect(c.t).toBeLessThanOrEqual(8.5); }
+ expect(first.every((c) => !c.lyric && c.performance)).toBe(true);
+ // Shot 2 is sung throughout: its frames stay off the cuts and are marked as maybe carrying a lyric.
+ const second = candidates.filter((c) => c.shot === 'mvs-10');
+ for (const c of second) { expect(c.t).toBeGreaterThan(11.4); expect(c.t).toBeLessThan(18.6); }
+ expect(second.every((c) => c.lyric && !c.performance)).toBe(true);
+ // Too many shots: an even spread across the song, at most `max`.
+ const many = { scenes: Array.from({ length: 40 }, (_, i) => scene(i, i + 1, `Shot ${i}`)) };
+ const spread = frames.thumbnailCandidates(many, 40, 10);
+ expect(spread).toHaveLength(10);
+ expect(spread[spread.length - 1].t).toBeGreaterThan(30);
+ });
+
+ it('keeps the best frame of each shot, best first, favoring the singer and frames with no lyric', () => {
+ const picked = frames.pickThumbnailFrames([
+ { name: 'a1', shot: 'a', score: 10, performance: false, lyric: false },
+ { name: 'a2', shot: 'a', score: 12, performance: false, lyric: false },
+ { name: 'b1', shot: 'b', score: 11, performance: true, lyric: false },
+ { name: 'c1', shot: 'c', score: 14, performance: false, lyric: true },
+ { name: 'd1', shot: 'd', score: NaN, performance: true, lyric: false },
+ ], 2);
+ // b1 (11 × 1.15 = 12.65) beats a2 (12) and c1 (14 × 0.75 = 10.5); a failed score never makes the cut.
+ expect(picked.map((c) => c.name)).toEqual(['b1', 'a2']);
+ });
+
+ it('scores a crisp frame over a blurred copy of it, and either over a near-black one', async () => {
+ const sharp = (await import('sharp')).default;
+ await mkdir(PATHS.videoThumbnails, { recursive: true });
+ const crisp = join(PATHS.videoThumbnails, 'score-crisp.png');
+ const blurred = join(PATHS.videoThumbnails, 'score-blurred.png');
+ const dark = join(PATHS.videoThumbnails, 'score-dark.png');
+ // A checkerboard: hard edges everywhere, which a blur or a dissolve smears.
+ const cells = Buffer.alloc(320 * 180 * 3);
+ for (let y = 0; y < 180; y++) for (let x = 0; x < 320; x++) cells.fill(((x >> 4) + (y >> 4)) % 2 ? 210 : 40, (y * 320 + x) * 3, (y * 320 + x) * 3 + 3);
+ await sharp(cells, { raw: { width: 320, height: 180, channels: 3 } }).png().toFile(crisp);
+ await sharp(crisp).blur(6).toFile(blurred);
+ await sharp(crisp).linear(0.08, 0).toFile(dark);
+ const [c, b, d] = await Promise.all([crisp, blurred, dark].map((p) => frames.scoreThumbnailFrame(p)));
+ expect(c).toBeGreaterThan(b * 1.5);
+ expect(b).toBeGreaterThan(d);
+ });
+});
diff --git a/server/services/musicVideo/thumbnailFrames.js b/server/services/musicVideo/thumbnailFrames.js
new file mode 100644
index 0000000000..29d9ff9371
--- /dev/null
+++ b/server/services/musicVideo/thumbnailFrames.js
@@ -0,0 +1,85 @@
+/**
+ * Music Video — choosing the video frames worth a YouTube thumbnail.
+ *
+ * The publishing kit cuts candidate frames from the final render, scores each
+ * from the image alone, and keeps the best frame of each shot, best first.
+ * Pure apart from reading the frames; `sharp` is loaded lazily.
+ */
+
+const MAX_THUMBNAILS = 6;
+// Frames looked at to find those six: two per shot, spread across the song.
+const THUMBNAIL_CANDIDATES = 24;
+
+/** The longest stretch of [from, to] with no lyric on screen, or null when lyrics cover all of it. */
+function longestLyricFreeStretch(from, to, cues) {
+ let best = null;
+ let cursor = from;
+ const covering = cues.filter((c) => c.endSec > from && c.startSec < to).sort((a, b) => a.startSec - b.startSec);
+ for (const c of [...covering, { startSec: to, endSec: to }]) {
+ const gapEnd = Math.min(c.startSec, to);
+ if (gapEnd - cursor > (best ? best.to - best.from : 0)) best = { from: cursor, to: gapEnd };
+ cursor = Math.max(cursor, c.endSec);
+ }
+ return best;
+}
+
+/**
+ * Frame times worth judging for a thumbnail: two per shot, inside the shot's
+ * middle so a transition or a cut never lands on one, and where the shot has
+ * a moment with no lyric on screen, inside that moment (a render can draw the
+ * lyrics over the picture). Without shots, even steps across the song. Each
+ * candidate names its shot, so the pick can keep to one frame per shot.
+ */
+export function thumbnailCandidates(project, durationSec, max = THUMBNAIL_CANDIDATES) {
+ const cues = (project.lyricCues || []).filter((c) => Number.isFinite(c?.startSec) && Number.isFinite(c?.endSec) && c.endSec > c.startSec);
+ const shots = (project.scenes || [])
+ .filter((s) => Number.isFinite(s?.startSec) && Number.isFinite(s?.endSec) && s.endSec > s.startSec && s.startSec < durationSec)
+ .map((s, i) => ({ key: s.sceneId || `shot-${i}`, from: s.startSec, to: Math.min(s.endSec, durationSec), performance: s.shotMode === 'performance' }));
+ const steps = Math.max(1, Math.ceil(max / 2));
+ const pool = shots.length ? shots : Array.from({ length: steps }, (_, i) => ({ key: `step-${i}`, from: (i / steps) * durationSec, to: ((i + 1) / steps) * durationSec, performance: false }));
+ const round = (t) => Math.round(t * 1000) / 1000;
+ const all = pool.flatMap((shot) => {
+ const len = shot.to - shot.from;
+ const middle = { from: shot.from + len * 0.15, to: shot.to - len * 0.15 };
+ const free = longestLyricFreeStretch(middle.from, middle.to, cues);
+ const span = free && free.to - free.from >= 0.25 ? free : middle;
+ const lyric = span === middle && cues.some((c) => c.endSec > middle.from && c.startSec < middle.to);
+ return [0.35, 0.7].map((f) => ({ t: round(span.from + (span.to - span.from) * f), shot: shot.key, performance: shot.performance, lyric }));
+ });
+ if (all.length <= max) return all;
+ return Array.from({ length: max }, (_, i) => all[Math.floor((i * all.length) / max)]);
+}
+
+/**
+ * How good a frame looks as a thumbnail, from the image alone: how much crisp
+ * detail it holds (a frame mid-motion-blur or mid-dissolve holds little), how
+ * much contrast, and whether it is close to black or blown out. Relative: it
+ * only ranks one video's frames against each other.
+ */
+export async function scoreThumbnailFrame(path, deps = {}) {
+ const sharp = deps.sharp || (await import('sharp')).default;
+ const grey = sharp(path).resize(320, 180, { fit: 'fill' }).greyscale();
+ const [{ channels: [tone] }, { channels: [edges] }] = await Promise.all([
+ grey.clone().stats(),
+ grey.clone().convolve({ width: 3, height: 3, kernel: [0, 1, 0, 1, -4, 1, 0, 1, 0], offset: 128 }).stats(),
+ ]);
+ const exposure = tone.mean < 28 || tone.mean > 228 ? 0.3 : 1;
+ const contrast = Math.min(1, Math.max(0.3, tone.stdev / 45));
+ return edges.stdev * contrast * exposure;
+}
+
+/**
+ * The thumbnails to keep: the best-scoring frame of each shot, best first,
+ * at most `max`. The singer sells a thumbnail, so a performance shot's frame
+ * counts a little more; a frame a lyric may be drawn over counts less.
+ */
+export function pickThumbnailFrames(scored, max = MAX_THUMBNAILS) {
+ const weight = (c) => c.score * (c.performance ? 1.15 : 1) * (c.lyric ? 0.75 : 1);
+ const bestPerShot = new Map();
+ for (const c of scored) {
+ if (!Number.isFinite(c.score)) continue;
+ const held = bestPerShot.get(c.shot);
+ if (!held || weight(c) > weight(held)) bestPerShot.set(c.shot, c);
+ }
+ return [...bestPerShot.values()].sort((a, b) => weight(b) - weight(a)).slice(0, max);
+}
diff --git a/server/services/musicVideo/youtubeThumbnail.js b/server/services/musicVideo/youtubeThumbnail.js
new file mode 100644
index 0000000000..5d1e59ab7c
--- /dev/null
+++ b/server/services/musicVideo/youtubeThumbnail.js
@@ -0,0 +1,290 @@
+/**
+ * Music Video — the YouTube thumbnail.
+ *
+ * `project.publishKit.youtubeThumbnail` holds one composed 16:9 image: a
+ * source (a video frame the kit kept, or any gallery image: a shot's still,
+ * a cover photo, a Cast & Sets render) cropped 16:9, with the song title set
+ * over it by code in the song's cover lettering, laid out for a feed (large,
+ * to one side, clear of the duration badge; lib/musicVideoCoverOverlay.js).
+ * The YouTube post uploads it in place of a bare frame. No AI call: the
+ * lettering is the cover's design, and a new design re-sets this too.
+ *
+ * youtubeThumbnail: { filename, source: { kind, filename }, title,
+ * focusX, focusY, lettering, composedAt }
+ * generated: [galleryFilename…],
+ * pending: { requestId, jobId, mode, requestedAt } | null,
+ * lastError }
+ * youtubeThumbnailTests: [{ filename, source, title, … }] (at most 3)
+ *
+ * "Paint the title" asks the install's image generator to restyle a chosen
+ * frame with the title drawn into it as display lettering (an image model
+ * draws far livelier type than code can set). The job is tagged
+ * `musicVideo: { projectId, youtubeThumbnail: { requestId } }`; its completion
+ * hook (musicVideoCoverArtImageHook.js) makes the result the thumbnail, bare.
+ * What PortOS adds to the director's words is one labeled addition, previewed
+ * by the same builder before the send.
+ *
+ * The test set is the variants kept for YouTube's Test & Compare, which runs
+ * up to three thumbnails on a published video. Adding one keeps the made
+ * thumbnail as it is now; making the next one leaves it in place.
+ */
+import { randomUUID } from 'crypto';
+import { existsSync } from 'fs';
+import { basename } from 'path';
+import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { ensureDir, PATHS } from '../../lib/fileUtils.js';
+import { safeUnder } from '../../lib/ffmpeg.js';
+import { composeYoutubeThumbnail } from './coverArtCompose.js';
+import { listCoverFonts, registerCoverFonts } from './coverFonts.js';
+import { defaultImageRoute, projectCoverArt, sourcePath } from './coverArt.js';
+import { promptAddition } from '../../lib/modelInput.js';
+import { trimTo } from '../../lib/textUtils.js';
+import { musicVideoEvents } from './events.js';
+import { getProject, mutateProjectRecord } from './projects.js';
+import { projectPublishKit, releaseKitFiles } from './publishKit.js';
+
+export const MAX_THUMBNAIL_TESTS = 3;
+const MAX_GENERATED = 12;
+const LIVE_JOB = new Set(['queued', 'running', 'canceling']);
+// A reservation that never got its job id (the process died mid-enqueue) stops blocking after this.
+const RESERVATION_TTL_MS = 2 * 60 * 1000;
+// Asked for 16:9; the compose crops whatever size the backend returns to 1280x720.
+const PAINT_SIZE = { width: 1536, height: 864 };
+// The fields a thumbnail (or a test variant) is: what was made, from what.
+const MADE_FIELDS = ['filename', 'source', 'title', 'focusX', 'focusY', 'lettering', 'composedAt'];
+const madeOf = (thumb) => Object.fromEntries(MADE_FIELDS.filter((k) => thumb[k] !== undefined).map((k) => [k, thumb[k]]));
+
+const defaults = {
+ getSettings: async () => (await import('../settings.js')).getSettings(),
+ defaultRoute: defaultImageRoute,
+ imageParams: async (settings, route, common) => (await import('./castAndSetsService.js')).imageJobParams(settings, route, common),
+ enqueue: async (job) => (await import('../mediaJobQueue/index.js')).enqueueJob(job),
+ jobStatus: async (jobId) => (await import('../mediaJobQueue/index.js')).getJob(jobId)?.status || null,
+};
+let deps = { ...defaults };
+export function __setYoutubeThumbnailDepsForTests(overrides) { deps = { ...defaults, ...overrides }; }
+
+const thumbError = (status, code, message) => new ServerError(message, { status, code });
+
+export const projectYoutubeThumbnail = (project) => {
+ const thumb = projectPublishKit(project).youtubeThumbnail;
+ return thumb && typeof thumb === 'object' ? thumb : {};
+};
+
+// A kit frame the made thumbnail was cut from stays usable after a rebuild drops it from the
+// kit (releaseKitFiles keeps its file), so new lettering and re-crops still find it.
+function thumbnailSourcePath(project, from, thumb) {
+ const name = basename(String(from?.filename || ''));
+ const kept = from?.kind === 'thumbnail' && thumb.source?.kind === 'thumbnail' && thumb.source.filename === name
+ && !(projectPublishKit(project).thumbnails || []).includes(name) ? safeUnder(PATHS.videoThumbnails, name) : null;
+ return kept && existsSync(kept) ? kept : sourcePath(project, from);
+}
+
+const unitOr = (value, fallback) => (Number.isFinite(value) ? value : (Number.isFinite(fallback) ? fallback : 0.5));
+
+/**
+ * Compose the thumbnail from `source` and make it the one the YouTube post
+ * uploads. Unset fields keep the last thumbnail's (the title defaults to the
+ * cover's title, else the song's name). `lettering: false` uses the image bare.
+ */
+export async function composeProjectYoutubeThumbnail(projectId, { source = null, title, focusX, focusY, lettering } = {}) {
+ const project = await getProject(projectId);
+ if (!project) throw thumbError(404, 'NOT_FOUND', 'Project not found');
+ const thumb = projectYoutubeThumbnail(project);
+ const art = projectCoverArt(project);
+ const from = source || thumb.source;
+ if (!from) throw thumbError(422, 'VALIDATION_ERROR', 'Pick an image for the thumbnail first');
+ const path = thumbnailSourcePath(project, from, thumb);
+ const next = {
+ source: { kind: from.kind, filename: String(from.filename).split(/[\\/]/).pop() },
+ title: typeof title === 'string' ? title.trim() : (thumb.title ?? art.title ?? project.name ?? ''),
+ focusX: unitOr(focusX, thumb.focusX),
+ focusY: unitOr(focusY, thumb.focusY),
+ lettering: typeof lettering === 'boolean' ? lettering : thumb.lettering !== false,
+ };
+ if (next.lettering && !next.title) throw thumbError(422, 'VALIDATION_ERROR', 'Give the thumbnail a title');
+ await ensureDir(PATHS.videoThumbnails);
+ const fonts = await listCoverFonts();
+ await registerCoverFonts(fonts);
+ const filename = `youtube-thumb-${String(projectId).slice(3, 11)}-${randomUUID().slice(0, 8)}.jpg`;
+ await composeYoutubeThumbnail({ ...next, design: art.design || null, fonts, source: path, out: safeUnder(PATHS.videoThumbnails, filename) });
+ // The JPEG is written in place; the row that first names it commits under a backup lease (#9982).
+ const out = await withBackupAssetPublication(() => mutateProjectRecord(projectId, (current) => {
+ const kit = projectPublishKit(current);
+ return { project: { ...current, publishKit: { ...kit, youtubeThumbnail: { ...projectYoutubeThumbnail(current), ...next, filename, composedAt: new Date().toISOString(), lastError: null } } } };
+ }));
+ if (thumb.filename && thumb.filename !== filename) await releaseKitFiles([thumb.filename], [filename]);
+ console.log(`🖼️ Music Video YouTube thumbnail ${String(projectId).slice(3, 11)} ← ${next.source.filename}`);
+ musicVideoEvents.emit('cover-art', { projectId, project: out.project });
+ return { project: out.project };
+}
+
+/** Re-set a lettered thumbnail in the cover's current design. Null when there is none to re-set. */
+export async function recomposeYoutubeThumbnail(projectId) {
+ const project = await getProject(projectId);
+ const thumb = projectYoutubeThumbnail(project);
+ if (!thumb.source || thumb.lettering === false) return null;
+ return (await composeProjectYoutubeThumbnail(projectId, {})).project;
+}
+
+/** Stop using the made thumbnail: the YouTube post goes back to the best video frame. */
+export async function clearProjectYoutubeThumbnail(projectId) {
+ const project = await getProject(projectId);
+ if (!project) throw thumbError(404, 'NOT_FOUND', 'Project not found');
+ const old = projectYoutubeThumbnail(project).filename;
+ const out = await mutateProjectRecord(projectId, (current) => {
+ const { youtubeThumbnail, ...kit } = projectPublishKit(current);
+ // Painted images stay pickable; only the made thumbnail goes.
+ const generated = Array.isArray(youtubeThumbnail?.generated) ? youtubeThumbnail.generated : [];
+ return { project: { ...current, publishKit: generated.length ? { ...kit, youtubeThumbnail: { generated } } : kit } };
+ });
+ if (old) await releaseKitFiles([old]);
+ musicVideoEvents.emit('cover-art', { projectId, project: out.project });
+ return { project: out.project };
+}
+
+const testsOf = (project) => {
+ const list = projectPublishKit(project).youtubeThumbnailTests;
+ return Array.isArray(list) ? list.filter((t) => t?.filename) : [];
+};
+
+/** Keep the made thumbnail, as it is now, as one of the Test & Compare variants. */
+export async function addYoutubeThumbnailTest(projectId) {
+ const project = await getProject(projectId);
+ if (!project) throw thumbError(404, 'NOT_FOUND', 'Project not found');
+ const out = await mutateProjectRecord(projectId, (current) => {
+ const kit = projectPublishKit(current);
+ const thumb = projectYoutubeThumbnail(current);
+ if (!thumb.filename) throw thumbError(422, 'VALIDATION_ERROR', 'Make a thumbnail first');
+ const tests = testsOf(current);
+ if (tests.some((t) => t.filename === thumb.filename)) return { project: current };
+ if (tests.length >= MAX_THUMBNAIL_TESTS) throw thumbError(422, 'VALIDATION_ERROR', `YouTube tests up to ${MAX_THUMBNAIL_TESTS} thumbnails. Remove one first`);
+ return { project: { ...current, publishKit: { ...kit, youtubeThumbnailTests: [...tests, madeOf(thumb)] } } };
+ });
+ musicVideoEvents.emit('cover-art', { projectId, project: out.project });
+ return { project: out.project };
+}
+
+/** Drop a variant from the test set (its file goes once nothing names it). */
+export async function removeYoutubeThumbnailTest(projectId, filename) {
+ const project = await getProject(projectId);
+ if (!project) throw thumbError(404, 'NOT_FOUND', 'Project not found');
+ let held = false;
+ const out = await mutateProjectRecord(projectId, (current) => {
+ const kit = projectPublishKit(current);
+ const tests = testsOf(current);
+ held = tests.some((t) => t.filename === filename);
+ return { project: { ...current, publishKit: { ...kit, youtubeThumbnailTests: tests.filter((t) => t.filename !== filename) } } };
+ });
+ // Only a file this set held: the name comes from the request, and the folder holds other renders' images too.
+ if (held) await releaseKitFiles([filename]);
+ musicVideoEvents.emit('cover-art', { projectId, project: out.project });
+ return { project: out.project };
+}
+
+/**
+ * What "Paint the title" sends the image model: PortOS's thumbnail brief (one
+ * labeled addition), then the director's own words as written. The preview
+ * and the queued job both come from here, so the chips match the send.
+ */
+export function buildThumbnailPaintPrompt({ title, notes = '' }) {
+ const brief = [
+ 'Turn the attached frame into a YouTube thumbnail, 16:9.',
+ 'Keep its people, faces, wardrobe, set, light and film look exactly as they are.',
+ `Paint the title "${trimTo(title, 60)}" into the picture as big, bold display lettering with real character (painted, chrome, neon or film-title type that belongs to this world), readable at a glance on a phone.`,
+ 'Spell it exactly. Put it on one side, never over a face, and keep the bottom-right corner clear.',
+ 'No other text, no logos.',
+ ].join(' ');
+ const direction = trimTo(String(notes || '').trim(), 1500);
+ return {
+ prompt: [brief, direction].filter(Boolean).join('\n\n'),
+ promptAdditions: [promptAddition('youtube-thumbnail-brief', 'YouTube thumbnail brief', brief)],
+ };
+}
+
+async function pendingIsLive(pending) {
+ if (!pending) return false;
+ if (pending.jobId) return LIVE_JOB.has(await deps.jobStatus(pending.jobId).catch(() => null));
+ return Date.now() - Date.parse(pending.requestedAt || 0) < RESERVATION_TTL_MS;
+}
+
+const writeThumb = (projectId, update) => mutateProjectRecord(projectId, (current) => {
+ const kit = projectPublishKit(current);
+ const thumb = projectYoutubeThumbnail(current);
+ return { project: { ...current, publishKit: { ...kit, youtubeThumbnail: { ...thumb, ...update(thumb) } } } };
+});
+
+/**
+ * Ask the install's image generator to paint `title` into `source` (a kit
+ * frame or a gallery image). The completion hook makes the result the
+ * thumbnail when it lands.
+ */
+export async function paintYoutubeThumbnail(projectId, { source, title, notes = '' } = {}) {
+ const project = await getProject(projectId);
+ if (!project) throw thumbError(404, 'NOT_FOUND', 'Project not found');
+ const previous = projectYoutubeThumbnail(project).pending;
+ if (await pendingIsLive(previous)) throw thumbError(409, 'THUMBNAIL_IN_PROGRESS', 'A thumbnail is already being painted');
+ const name = String(title || '').trim();
+ if (!name) throw thumbError(422, 'VALIDATION_ERROR', 'Give the thumbnail a title');
+ const path = thumbnailSourcePath(project, source, projectYoutubeThumbnail(project));
+ const settings = await deps.getSettings();
+ const route = await deps.defaultRoute(settings);
+ if (!route) throw thumbError(409, 'THUMBNAIL_ROUTE_UNAVAILABLE', 'Image generation is not set up. Choose an image generator in Settings and try again');
+ const requestId = randomUUID();
+ await writeThumb(projectId, (thumb) => {
+ if ((thumb.pending?.requestId || null) !== (previous?.requestId || null)) throw thumbError(409, 'THUMBNAIL_IN_PROGRESS', 'A thumbnail is already being painted');
+ return { pending: { requestId, jobId: null, mode: route.mode, requestedAt: new Date().toISOString() }, title: name, lastError: null };
+ });
+ const common = {
+ ...buildThumbnailPaintPrompt({ title: name, notes }),
+ ...PAINT_SIZE,
+ referenceImagePaths: [path],
+ referenceImageStrengths: [1],
+ // The completion hook files the result by this tag; no `sceneId`, `castAndSets` or `coverArt`, so other hooks ignore it.
+ musicVideo: { projectId: project.id, youtubeThumbnail: { requestId } },
+ };
+ const sent = await deps.imageParams(settings, route, common)
+ .then((params) => deps.enqueue({ kind: 'image', params, owner: `music-video-youtube-thumbnail:${project.id}` }))
+ .catch(async (err) => {
+ const failed = await writeThumb(projectId, (thumb) => (thumb.pending?.requestId === requestId
+ ? { pending: null, lastError: trimTo(`The thumbnail could not be queued: ${err.message}`, 300) } : {}));
+ musicVideoEvents.emit('cover-art', { projectId, project: failed.project });
+ throw err;
+ });
+ const jobId = typeof sent?.jobId === 'string' ? sent.jobId : null;
+ const out = await writeThumb(projectId, (thumb) => (thumb.pending?.requestId === requestId && jobId ? { pending: { ...thumb.pending, jobId } } : {}));
+ console.log(`🖼️ Music Video YouTube thumbnail ${String(projectId).slice(3, 11)}: painting queued on ${route.mode}`);
+ musicVideoEvents.emit('cover-art', { projectId, project: out.project });
+ return { project: out.project };
+}
+
+/**
+ * The completion hook's entry: keep a painted image as a pickable source and,
+ * for the current request, make it the thumbnail (bare: its title is painted
+ * in). A failure records why. Returns true when the record changed.
+ */
+export async function onThumbnailImageSettled({ projectId, requestId, filename = null, status = null, error = null }) {
+ const project = await getProject(projectId);
+ if (!project) return false;
+ const current = projectYoutubeThumbnail(project).pending?.requestId === requestId;
+ if (!filename) {
+ if (!current) return false;
+ const out = await writeThumb(projectId, () => ({ pending: null, lastError: trimTo(error || `The thumbnail render was ${status || 'not finished'}`, 300) }));
+ console.warn(`⚠️ Music Video YouTube thumbnail ${String(projectId).slice(3, 11)}: painting ${status || 'failed'}`);
+ musicVideoEvents.emit('cover-art', { projectId, project: out.project });
+ return true;
+ }
+ const name = basename(filename);
+ const out = await writeThumb(projectId, (thumb) => ({
+ generated: [name, ...(thumb.generated || []).filter((f) => f !== name)].slice(0, MAX_GENERATED),
+ ...(current ? { pending: null } : {}),
+ }));
+ if (!current) { musicVideoEvents.emit('cover-art', { projectId, project: out.project }); return true; }
+ await composeProjectYoutubeThumbnail(projectId, { source: { kind: 'image', filename: name }, lettering: false, focusX: 0.5, focusY: 0.5 }).catch(async (err) => {
+ console.error(`❌ Music Video YouTube thumbnail ${String(projectId).slice(3, 11)} compose failed: ${err.message}`);
+ const failed = await writeThumb(projectId, () => ({ lastError: trimTo(`The thumbnail could not be made: ${err.message}`, 300) }));
+ musicVideoEvents.emit('cover-art', { projectId, project: failed.project });
+ });
+ return true;
+}
diff --git a/server/services/musicVideo/youtubeThumbnail.test.js b/server/services/musicVideo/youtubeThumbnail.test.js
new file mode 100644
index 0000000000..63a3835808
--- /dev/null
+++ b/server/services/musicVideo/youtubeThumbnail.test.js
@@ -0,0 +1,159 @@
+/**
+ * The YouTube thumbnail, through the real project store and real sharp: it is
+ * composed 16:9 from a kit frame in the cover's lettering, the YouTube post
+ * uploads it over the bare frame, a new cover design re-sets it, and the
+ * Test & Compare set keeps up to three variants whose files outlive the next
+ * thumbnail and go once removed. "Paint the title" queues one tagged image
+ * job whose prompt carries the brief as a labeled addition, and its landing
+ * makes the painted image the thumbnail, bare.
+ */
+import { describe, expect, it, vi, afterAll } from 'vitest';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';
+
+vi.mock('../../lib/paths.js', async (importOriginal) => makePathsProxy(await importOriginal(), {
+ dataRoot: () => lazyTempDataRoot('portos-mv-yt-thumb-'),
+}));
+
+const { PATHS } = await import('../../lib/paths.js');
+const projects = await import('./projects.js');
+const thumbs = await import('./youtubeThumbnail.js');
+const cover = await import('./coverArt.js');
+const { buildPublishPayload } = await import('./publish/payloads.js');
+const sharp = (await import('sharp')).default;
+
+afterAll(() => cleanupTempDataRoots());
+
+async function projectWithFrame() {
+ const { id } = await projects.createProject({ name: 'Example Song' });
+ await mkdir(PATHS.videoThumbnails, { recursive: true });
+ const frame = `frame-${id.slice(3, 11)}.jpg`;
+ // A square frame, so the 16:9 crop has height to spare and focusY moves it.
+ await sharp({ create: { width: 800, height: 800, channels: 3, background: '#446688' } }).jpeg().toFile(join(PATHS.videoThumbnails, frame));
+ await projects.mutateProjectRecord(id, (current) => ({ project: { ...current, publishKit: { thumbnails: [frame], thumbnail: frame } } }));
+ return { id, frame };
+}
+const kitOf = async (id) => (await projects.getProject(id)).publishKit;
+
+describe('YouTube thumbnail', () => {
+ it('composes a 1280x720 thumbnail with the title, which the YouTube post uploads over the bare frame', async () => {
+ const { id, frame } = await projectWithFrame();
+ await thumbs.composeProjectYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, focusY: 0.2 });
+ const made = (await kitOf(id)).youtubeThumbnail;
+ expect(made).toMatchObject({ source: { kind: 'thumbnail', filename: frame }, title: 'Example Song', focusY: 0.2, lettering: true });
+ const image = sharp(await readFile(join(PATHS.videoThumbnails, made.filename)));
+ expect(await image.metadata()).toMatchObject({ format: 'jpeg', width: 1280, height: 720 });
+ // The title is drawn over the flat frame.
+ expect(Math.max(...(await image.stats()).channels.map((c) => c.stdev))).toBeGreaterThan(5);
+
+ const project = await projects.getProject(id);
+ const payload = buildPublishPayload('youtube', { ...project, publishKit: { ...project.publishKit, master: { filename: 'master.mp4' }, copy: { youtube: { title: 'Example title' } } } }, {});
+ expect(payload.thumbnail).toMatchObject({ dir: 'videoThumbnails', name: made.filename, made: true });
+
+ // Going back to the frame drops the made file.
+ await thumbs.clearProjectYoutubeThumbnail(id);
+ expect((await kitOf(id)).youtubeThumbnail).toBeUndefined();
+ expect(existsSync(join(PATHS.videoThumbnails, made.filename))).toBe(false);
+ });
+
+ it('re-sets a lettered thumbnail when the cover lettering changes', async () => {
+ const { id, frame } = await projectWithFrame();
+ await thumbs.composeProjectYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, title: 'Example' });
+ const before = (await kitOf(id)).youtubeThumbnail.filename;
+ const { project } = await cover.saveCoverDesign(id, { layout: 'top-center' });
+ expect(project.publishKit.youtubeThumbnail.filename).not.toBe(before);
+ expect(project.publishKit.youtubeThumbnail.title).toBe('Example');
+ expect(existsSync(join(PATHS.videoThumbnails, before))).toBe(false);
+ });
+
+ it('still re-sets a thumbnail made from a kit frame after a rebuild drops that frame from the kit', async () => {
+ const { id, frame } = await projectWithFrame();
+ await thumbs.composeProjectYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, title: 'Example' });
+ // A rebuild: the kit names new frames and frees the old ones no project still holds.
+ const { releaseKitFiles } = await import('./publishKit.js');
+ await projects.mutateProjectRecord(id, (current) => ({ project: { ...current, publishKit: { ...current.publishKit, thumbnails: ['newer.jpg'], thumbnail: 'newer.jpg' } } }));
+ await releaseKitFiles([frame]);
+ expect(existsSync(join(PATHS.videoThumbnails, frame))).toBe(true);
+ const before = (await kitOf(id)).youtubeThumbnail.filename;
+ const { project } = await cover.saveCoverDesign(id, { layout: 'top-center' });
+ expect(project.publishKit.youtubeThumbnail.filename).not.toBe(before);
+ expect(project.publishKit.youtubeThumbnail.source).toEqual({ kind: 'thumbnail', filename: frame });
+ // Painting the title over that same kept frame still finds it.
+ const enqueue = vi.fn(async () => ({ jobId: 'job-example' }));
+ thumbs.__setYoutubeThumbnailDepsForTests({
+ getSettings: async () => ({}), defaultRoute: async () => ({ mode: 'codex', model: null }),
+ imageParams: async (_s, route, common) => ({ ...common, provider: route.mode }), enqueue, jobStatus: async () => 'queued',
+ });
+ await thumbs.paintYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, title: 'Example' });
+ expect(enqueue.mock.calls[0][0].params.referenceImagePaths).toEqual([join(PATHS.videoThumbnails, frame)]);
+ });
+
+ it('keeps up to three variants for Test & Compare, past the next thumbnail, and frees one once removed', async () => {
+ const { id, frame } = await projectWithFrame();
+ await expect(thumbs.addYoutubeThumbnailTest(id)).rejects.toMatchObject({ status: 422 });
+ const kept = [];
+ for (const title of ['One', 'Two', 'Three']) {
+ await thumbs.composeProjectYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, title });
+ await thumbs.addYoutubeThumbnailTest(id);
+ await thumbs.addYoutubeThumbnailTest(id); // adding the same one twice keeps one
+ kept.push((await kitOf(id)).youtubeThumbnail.filename);
+ }
+ expect((await kitOf(id)).youtubeThumbnailTests.map((t) => t.title)).toEqual(['One', 'Two', 'Three']);
+ // Making the next thumbnail leaves every variant's file in place.
+ await thumbs.composeProjectYoutubeThumbnail(id, { title: 'Four' });
+ for (const f of kept) expect(existsSync(join(PATHS.videoThumbnails, f))).toBe(true);
+ await expect(thumbs.addYoutubeThumbnailTest(id)).rejects.toMatchObject({ status: 422 });
+
+ await thumbs.removeYoutubeThumbnailTest(id, kept[0]);
+ expect((await kitOf(id)).youtubeThumbnailTests).toHaveLength(2);
+ expect(existsSync(join(PATHS.videoThumbnails, kept[0]))).toBe(false);
+ // A name the set never held is never deleted.
+ await thumbs.removeYoutubeThumbnailTest(id, frame);
+ expect(existsSync(join(PATHS.videoThumbnails, frame))).toBe(true);
+ });
+});
+
+describe('painting the title with the image model', () => {
+ it('queues the frame with the brief as an addition, and makes the painted image the thumbnail when it lands', async () => {
+ const { id, frame } = await projectWithFrame();
+ const enqueue = vi.fn(async () => ({ jobId: 'job-example' }));
+ thumbs.__setYoutubeThumbnailDepsForTests({
+ getSettings: async () => ({}), defaultRoute: async () => ({ mode: 'codex', model: null }),
+ imageParams: async (_s, route, common) => ({ ...common, provider: route.mode }), enqueue, jobStatus: async () => 'queued',
+ });
+ await thumbs.paintYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, title: 'Example Song', notes: 'chrome letters' });
+ const { params } = enqueue.mock.calls[0][0];
+ expect(params.prompt).toBe(thumbs.buildThumbnailPaintPrompt({ title: 'Example Song', notes: 'chrome letters' }).prompt);
+ expect(params.prompt).toContain('"Example Song"');
+ expect(params.prompt.endsWith('chrome letters')).toBe(true);
+ expect(params.promptAdditions).toEqual([expect.objectContaining({ id: 'youtube-thumbnail-brief' })]);
+ expect(params.referenceImagePaths).toEqual([join(PATHS.videoThumbnails, frame)]);
+ const requestId = params.musicVideo.youtubeThumbnail.requestId;
+ expect((await kitOf(id)).youtubeThumbnail.pending).toMatchObject({ requestId, jobId: 'job-example' });
+ await expect(thumbs.paintYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, title: 'Example Song' })).rejects.toMatchObject({ status: 409 });
+
+ // The painted image lands in the gallery; it becomes the thumbnail with nothing set over it.
+ await mkdir(PATHS.images, { recursive: true });
+ await sharp({ create: { width: 1536, height: 864, channels: 3, background: '#884422' } }).png().toFile(join(PATHS.images, 'painted-example.png'));
+ expect(await thumbs.onThumbnailImageSettled({ projectId: id, requestId, filename: 'painted-example.png' })).toBe(true);
+ const made = (await kitOf(id)).youtubeThumbnail;
+ expect(made).toMatchObject({ source: { kind: 'image', filename: 'painted-example.png' }, lettering: false, pending: null, generated: ['painted-example.png'] });
+ const stats = await sharp(await readFile(join(PATHS.videoThumbnails, made.filename))).stats();
+ expect(Math.max(...stats.channels.map((c) => c.stdev))).toBeLessThan(2);
+ });
+
+ it('records why a paint failed', async () => {
+ const { id, frame } = await projectWithFrame();
+ const enqueue = vi.fn(async () => ({ jobId: 'job-failing' }));
+ thumbs.__setYoutubeThumbnailDepsForTests({
+ getSettings: async () => ({}), defaultRoute: async () => ({ mode: 'codex', model: null }),
+ imageParams: async (_s, _r, common) => common, enqueue, jobStatus: async () => 'queued',
+ });
+ await thumbs.paintYoutubeThumbnail(id, { source: { kind: 'thumbnail', filename: frame }, title: 'Example Song' });
+ const requestId = enqueue.mock.calls[0][0].params.musicVideo.youtubeThumbnail.requestId;
+ await thumbs.onThumbnailImageSettled({ projectId: id, requestId, status: 'failed', error: 'The model refused' });
+ expect((await kitOf(id)).youtubeThumbnail).toMatchObject({ pending: null, lastError: 'The model refused' });
+ });
+});
diff --git a/server/services/musicVideoCoverArtImageHook.js b/server/services/musicVideoCoverArtImageHook.js
index 90482ffbc4..cfed85e8f5 100644
--- a/server/services/musicVideoCoverArtImageHook.js
+++ b/server/services/musicVideoCoverArtImageHook.js
@@ -1,5 +1,5 @@
/**
- * Music Video cover art image attach hook.
+ * Music Video cover art (and painted YouTube thumbnail) image attach hook.
*
* "Make a cover image" (musicVideo/coverArt.js) queues one image on the normal
* image queue with a `musicVideo: { projectId, coverArt: { requestId } }` tag.
@@ -14,24 +14,30 @@
import { createMediaJobImageHook } from './mediaJobImageHook.js';
-const settle = async (payload) => (await import('./musicVideo/coverArt.js')).onCoverArtImageSettled(payload);
+// A cover image and a painted YouTube thumbnail share this hook; the tag says which.
+const settle = async ({ kind, ...payload }) => (kind === 'youtubeThumbnail'
+ ? (await import('./musicVideo/youtubeThumbnail.js')).onThumbnailImageSettled(payload)
+ : (await import('./musicVideo/coverArt.js')).onCoverArtImageSettled(payload));
const hook = createMediaJobImageHook({
label: 'music-video cover art image',
initLog: '🖼️ Music Video cover art image hook initialized',
tagKey: 'musicVideo',
- identify: (tag) => (tag?.projectId && typeof tag.coverArt?.requestId === 'string'
- ? { projectId: tag.projectId, requestId: tag.coverArt.requestId }
- : null),
+ identify: (tag) => {
+ if (!tag?.projectId) return null;
+ if (typeof tag.coverArt?.requestId === 'string') return { projectId: tag.projectId, requestId: tag.coverArt.requestId, kind: 'coverArt' };
+ if (typeof tag.youtubeThumbnail?.requestId === 'string') return { projectId: tag.projectId, requestId: tag.youtubeThumbnail.requestId, kind: 'youtubeThumbnail' };
+ return null;
+ },
serializeKey: ({ projectId }) => projectId,
describe: ({ projectId, requestId }) => `${projectId}/${requestId}`,
- attach: ({ projectId, requestId, filename }) => settle({ projectId, requestId, filename })
+ attach: ({ projectId, requestId, kind, filename }) => settle({ projectId, requestId, kind, filename })
.then((changed) => (changed ? { filename } : null)),
onAttached: ({ projectId, filename }) => {
console.log(`🖼️ music-video cover art ${projectId.slice(0, 11)} ← ${filename}`);
},
- onTerminal: ({ projectId, requestId, job }, status) => settle({
- projectId, requestId, status, error: job?.error || `The render was ${status}`,
+ onTerminal: ({ projectId, requestId, kind, job }, status) => settle({
+ projectId, requestId, kind, status, error: job?.error || `The render was ${status}`,
}),
});