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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { musicVideoMediaMode, assertMusicVideoMediaSelections } from '../../lib/musicVideoMediaPolicy.js';
/**
* Music Video — pure record transforms (issue #1760, Phase 1).
*
* Mirrors the Creative Director store split: the file backend (projectsFile.js)
* and the PostgreSQL backend (projectsDB.js) share the SAME mutation semantics
* and differ only in load/persist, so all storage-agnostic logic lives here.
* Each function takes a plain project record and returns the next record (or
* throws a ServerError on a validation failure), leaving read/write to the
* caller.
*
* Peer-sync federation (#1770): the sanitize + LWW-merge decision helpers the CD
* store carries now live here too (`sanitizeProjectForSync`, `mergeProjectRecord`),
* shared by both backends so the merge can't drift. The soft-delete fields were
* already on the record, so federation was purely additive (no record migration).
*/
import { remapMusicVideoDependencies, retainMusicVideoDependencies } from '../../lib/musicVideoDependencies.js';
import { randomUUID } from 'node:crypto';
import { normalizeMusicVideoProductionPolicy } from '../../lib/musicVideoMediumPlan.js';
import { ServerError } from '../../lib/errorHandler.js';
import {
MUSIC_VIDEO_STATUSES,
MUSIC_VIDEO_REFERENCE_USES,
musicVideoAudioAnalysisSchema,
musicVideoMidiTranscriptionSchema,
musicVideoSceneCreateSchema,
musicVideoSceneUpdateSchema,
} from '../../lib/validation.js';
import { compareNewerWins } from '../../lib/lwwTimestamp.js';
import { stripMusicVideoLocalRenderPins } from '../../lib/syncWire.js';
import { persistedRenderPinFields } from '../../lib/renderTargets.js';
import { sanitizeProjectForSync } from '../../lib/projectStoreKit.js';
import { isPerformanceScene, planShotSplit, shotSplitLimit } from '../../lib/musicVideoShotTiming.js';
import { normalizeLyricCues, normalizePhrases, invalidateTimedText } from './timedText.js';
import { normalizeLyricMarkers } from './lyricMarkers.js';
import { ensureSceneTakes, keepCodeClipWithItsClip, TAKE_SLOT } from './takes.js';
import { normalizeComposition, invalidateCompositionTiming, withStoredCompositionDocument } from './composition.js';
import { normalizeSoundBed } from './soundBed.js';
import { normalizeFilmLook } from '../../lib/filmLook.js';
import { stillMoveForCamera } from '../../lib/cameraMovements.js';
import { normalizeTitleCard } from '../../lib/musicVideoTitleCard.js';
import { normalizeStatsOutro } from '../../lib/musicVideoStatsOutro.js';
import { remapTreatmentForClone, scenesFingerprint } from './treatment.js';
import { anchorShotsToSungLyrics, carryStoryboardApproval, dropStaleStoryboardRows } from './productionReview.js';
import { cuesSungWithin, sungLyricTextWithin } from '../../lib/musicVideoLyricAnchors.js';
import { normalizeMusicVideoAutomation } from '../../lib/musicVideoAutomation.js';
export { sanitizeProjectForSync } from '../../lib/projectStoreKit.js';
// Re-exported for the PG backend's typed mirror columns (mirrors the CD store).
export { mirrorTimestamp } from '../../lib/pgTimestamp.js';
const STATUS_COLUMN_MAX = 32;
/** Safe value for the `status` mirror column — bounded, never null. */
export function mirrorStatus(status) {
return (typeof status === 'string' && status ? status : 'draft').slice(0, STATUS_COLUMN_MAX);
}
/** Return the next record with `extra` merged and `updatedAt` freshly stamped. */
function touch(record, extra) {
return retainMusicVideoDependencies(record, { ...record, ...extra, updatedAt: new Date().toISOString() });
}
/** safeParse a scene payload, throwing a 400 ServerError with field detail on failure. */
function parseSceneOrThrow(schema, input) {
const parsed = schema.safeParse(input);
if (!parsed.success) {
throw new ServerError(
`Scene validation failed: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join(', ')}`,
{ status: 400, code: 'VALIDATION_ERROR' },
);
}
return parsed.data;
}
/**
* Normalize a validated visual specification (#8965): every reference persists
* a stable id and explicit defaults so edits stay addressable and a peer reads
* the same shape. `base` is the stored spec a partial patch merges onto — each
* sub-field present in the patch replaces its stored value; absent ones keep it.
*/
function normalizeVisualSpec(patch, base = null) {
const merged = { ...(base || {}), ...(patch || {}) };
const references = (Array.isArray(merged.references) ? merged.references : []).map((ref) => ({
id: typeof ref.id === 'string' && ref.id ? ref.id : `mvr-${randomUUID()}`,
imageId: ref.imageId,
role: ref.role || 'mood',
label: typeof ref.label === 'string' ? ref.label : '',
note: typeof ref.note === 'string' ? ref.note : '',
condition: ref.condition === true,
// #8980 — reference (default) / final-visible / motion-reference.
use: MUSIC_VIDEO_REFERENCE_USES.includes(ref.use) ? ref.use : 'reference',
}));
return {
references,
palette: Array.isArray(merged.palette) ? merged.palette.map((c) => c.toLowerCase()) : [],
typography: typeof merged.typography === 'string' ? merged.typography : '',
cameraRules: typeof merged.cameraRules === 'string' ? merged.cameraRules : '',
moodBoardId: typeof merged.moodBoardId === 'string' && merged.moodBoardId ? merged.moodBoardId : null,
};
}
/** Build a fresh project record from validated create input. */
export function buildProjectRecord(input, { id, now }) {
const productionPolicy = normalizeMusicVideoProductionPolicy(input.productionPolicy || (input.mediaMode ? { strategy: 'code-first', maxGeneratedVideoPercent: input.mediaMode === 'code-images-video' ? 100 : 0 } : null));
const {
name, mode = 'director', trackId = null,
uploadedAudioFilename = null, concept = null,
videoSettings = {},
} = input;
return {
id,
name,
version: 1,
parentProjectId: null,
rootProjectId: null,
status: 'draft',
mode,
createdAt: now,
updatedAt: now,
trackId,
uploadedAudioFilename,
...(input.performanceConditioningSource ? { performanceConditioningSource: input.performanceConditioningSource } : {}),
concept,
// #8965 — the reusable visual specification (moodboard/reference assets,
// palette, typography, camera rules). Null until the director sets one.
visualSpec: input.visualSpec ? normalizeVisualSpec(input.visualSpec) : null,
...(input.styleReferences ? { styleReferences: input.styleReferences } : {}),
videoSettings: {
...(videoSettings.renderPool ? { renderPool: videoSettings.renderPool } : {}),
backend: videoSettings.backend ?? 'local',
modelId: videoSettings.modelId ?? null,
grokDuration: videoSettings.grokDuration ?? 10,
falDuration: videoSettings.falDuration ?? null,
falModelId: videoSettings.falModelId ?? null,
falResolution: videoSettings.falResolution ?? null,
falEndFrameModelId: videoSettings.falEndFrameModelId ?? null,
falLipSyncResolution: videoSettings.falLipSyncResolution ?? null,
falMusicModelId: videoSettings.falMusicModelId ?? null,
falMusicResolution: videoSettings.falMusicResolution ?? null,
falLipSyncTranscription: videoSettings.falLipSyncTranscription ?? null,
runwayModelId: videoSettings.runwayModelId ?? null,
runwayDuration: videoSettings.runwayDuration ?? null,
runwayResolution: videoSettings.runwayResolution ?? null,
generationMode: videoSettings.generationMode ?? 'image',
audioReactiveLora: videoSettings.audioReactiveLora ?? null,
audioReactiveScale: videoSettings.audioReactiveScale ?? 1.2,
},
// #3231 Phase 4 — per-record image render pin for scene reference-frame
// renders (the shared universe/series/sprite field pair). Present only
// when set, so existing records keep their on-disk shape byte-stable.
...persistedRenderPinFields(input),
// Automation-first brief (tools, guidance, budget). Present only when set,
// so director-authored records keep their on-disk shape byte-stable.
...(input.automation ? { automation: normalizeMusicVideoAutomation(input.automation) } : {}),
audioAnalysis: null,
midiTranscription: null,
// #8964 — editable timed lyric cues + phrase annotations (timed against
// the current audio source) and the shot planner's pacing range.
lyricCues: Array.isArray(input.lyricCues) ? normalizeLyricCues(input.lyricCues) : [],
// Section headers + stage directions read off the lyric sheet, anchored to
// cue indices (lyricMarkers.js). Present only when the sheet had any, so a
// record without them keeps its shape.
...(Array.isArray(input.lyricMarkers) && input.lyricMarkers.length
? { lyricMarkers: normalizeLyricMarkers(input.lyricMarkers) }
: {}),
phrases: Array.isArray(input.phrases) ? normalizePhrases(input.phrases) : [],
pacing: input.pacing ?? null,
// #8984 — composition manifest (null = plain concatenation render).
// The document pointer is set only by the import routes, never on create.
// A code-first project authors a document; a footage project composes its shots.
composition: input.composition || input.mediaMode ? withStoredCompositionDocument(normalizeComposition(input.composition
|| { mode: productionPolicy.strategy === 'code-first' ? 'document' : 'composed' }), null) : null,
// #8988 — optional sound-design bed mixed under the song.
soundBed: input.soundBed ? normalizeSoundBed(input.soundBed) : null,
// The finishing film look every preview, render and baked still is viewed through; null = none.
filmLook: input.filmLook ? normalizeFilmLook(input.filmLook) : null,
// The opening title card (song, artist, year over the opener); null = none.
titleCard: normalizeTitleCard(input.titleCard),
// The cutting room floor outro after the song; null = off.
statsOutro: normalizeStatsOutro(input.statsOutro),
// #8980 — optional pre-production treatment (brief, arc, shot direction,
// proof checklist); null until the director starts one. See treatment.js.
treatment: null,
mediaMode: musicVideoMediaMode(input),
productionPolicy,
scenes: [],
renderHistoryId: null,
renderError: null,
// Soft-delete tombstone trio — kept so peer-sync federation (a follow-up)
// is additive rather than a record-shape migration.
deleted: false,
deletedAt: null,
};
}
function mintCloneSceneId(scene, sceneIdMap) {
const next = `mvs-${randomUUID()}`;
sceneIdMap.set(scene.sceneId, next);
return next;
}
/** Build an independently editable next version while reusing immutable media assets. */
export function cloneProjectRecord(source, {
id,
now,
name,
includeGeneratedMedia = true,
variant = 'revision',
}) {
// Record metadata is independently editable; only immutable asset bytes are shared.
source = structuredClone(source);
const videoVariant = variant === 'video-generation';
if (videoVariant) includeGeneratedMedia = false;
const nameMatch = typeof source.name === 'string' ? source.name.match(/^(.*?)(?:\s+v(\d+))?$/i) : null;
const inferredVersion = Number(nameMatch?.[2]) || 1;
const sourceVersion = Number.isInteger(source.version) && source.version > 0
? source.version
: inferredVersion;
const version = sourceVersion + 1;
const baseName = nameMatch?.[1]?.trim() || source.name || 'Music Video';
const sceneIdMap = new Map();
const scenes = (source.scenes || []).map((scene, order) => ({
...scene,
sceneId: mintCloneSceneId(scene, sceneIdMap),
order,
referenceImageId: includeGeneratedMedia ? (scene.referenceImageId ?? null) : null,
videoHistoryId: includeGeneratedMedia ? (scene.videoHistoryId ?? null) : null,
endImageId: includeGeneratedMedia ? (scene.endImageId ?? null) : null,
// Takes are immutable pointers to shared media, so a media-keeping clone
// carries the whole candidate history; a clean clone starts empty.
takes: includeGeneratedMedia ? ensureSceneTakes(scene, now) : [],
}));
for (const scene of scenes) scene.takes = scene.takes.map((take) => ({ ...take,
...(take.dependencies ? { dependencies: remapMusicVideoDependencies(take.dependencies, sceneIdMap) } : {}),
}));
const mediaReady = includeGeneratedMedia
&& scenes.length > 0
&& scenes.every((scene) => scene.referenceImageId && scene.videoHistoryId);
const clone = {
...source,
id,
name: name?.trim() || `${baseName} v${version}`,
version,
parentProjectId: source.id,
rootProjectId: source.rootProjectId || source.id,
status: source.audioAnalysis ? (mediaReady ? 'ready' : 'analyzed') : 'draft',
createdAt: now,
updatedAt: now,
scenes,
...(source.composition ? { composition: {
...source.composition,
...(source.composition.codeVideo ? { codeVideo: { ...source.composition.codeVideo,
sections: source.composition.codeVideo.sections.map((section) => ({ ...section, id: sceneIdMap.get(section.id) ?? section.id })),
} } : {}),
...(source.composition.reactiveSections ? { reactiveSections: source.composition.reactiveSections.map((section) => ({
...section, sectionId: sceneIdMap.get(section.sectionId) ?? section.sectionId,
})) } : {}),
...(source.composition.grade ? { grade: { ...source.composition.grade, sections: (source.composition.grade.sections || []).map((section) => ({
...section, sceneId: sceneIdMap.get(section.sceneId) ?? section.sceneId,
})) } } : {}),
} } : {}),
// #8980 — the treatment's shot directions and proofs follow the scenes to
// their new ids; proof evidence the clone can't back is dropped.
treatment: source.treatment ? remapTreatmentForClone(source.treatment, sceneIdMap, {
includeGeneratedMedia,
sourceRenderId: source.renderHistoryId ?? null,
sourceScenesFingerprint: scenesFingerprint(source.scenes || []),
cloneScenesFingerprint: scenesFingerprint(scenes),
}) : null,
// #8987 — a draft's section map follows the scenes to their new ids, so a
// clone can still revise from the review notes it carried over (#8986).
...(Array.isArray(source.excerpts) ? {
// A running encoder belongs only to the source project. Copying its
// partial-file ownership would let clone recovery delete that output.
excerpts: source.excerpts.filter((excerpt) => excerpt?.status !== 'rendering').map((excerpt) => (Array.isArray(excerpt?.sections)
? { ...excerpt, dependencies: remapMusicVideoDependencies(excerpt.dependencies, sceneIdMap), sections: excerpt.sections.map((s) => ({ ...s, sceneId: sceneIdMap.get(s.sceneId) ?? s.sceneId })) }
: excerpt)),
} : {}),
// A revision is in-progress work against the SOURCE's takes; the clone
// starts with none (its carried-over notes can open a fresh one).
revisions: [],
songRevision: null,
songRevisionHistory: [...(source.songRevisionHistory || []), ...(source.songRevision ? [source.songRevision] : [])],
audioTimingRevisions: [],
// #9102: an auto-review run is tied to the SOURCE's revisions/excerpts, so a
// clone starts with none (terminal runs too — their links are source-scoped).
...(Array.isArray(source.autoReviews) ? { autoReviews: [] } : {}),
// #9066: a production run executes against the SOURCE's scenes and jobs.
...(Array.isArray(source.productionRuns) ? { productionRuns: [] } : {}),
// An autonomous run executes against the SOURCE's audio, board and production.
...(source.autonomousRun ? { autonomousRun: null } : {}),
// Development artifacts ride along as-is: every version is an immutable
// file, so the clone points at the same bytes (devArtifacts.js). The Cast
// & Sets check-in keeps its direction and images, but its dispatch pin and
// production link belong to the source — a working stage reads as
// interrupted on the clone and can be resumed there.
productionReview: source.productionReview ? { feedback: source.productionReview.feedback || [], reviewedRevisions: source.productionReview.reviewedRevisions || {}, draft: { ...source.productionReview.draft, timingStatus: 'provisional',
storyboard: (source.productionReview.draft?.storyboard || []).map(shot => ({ ...shot, sceneId: sceneIdMap.get(shot.sceneId) || shot.sceneId })),
...(videoVariant ? { cast: '', environments: '', visualLanguage: '', motionLanguage: '', guideArtifactId: null } : {}),
}, approvals: {}, proof: null } : null,
...(source.castAndSets ? { castAndSets: { ...source.castAndSets, processId: null, productionRunId: null } } : {}),
renderHistoryId: null,
renderError: null,
renderDependencies: null,
// Publishing outputs and posted URLs belong to the source final render.
...(source.publishKit ? { publishKit: null } : {}),
// Finished outside PortOS describes the source's video; the new version is made here.
...(source.finishedOutside ? { finishedOutside: null } : {}),
// #9010: the source's in-flight render mark is not the clone's.
renderingOn: null,
renderPartialFilename: null,
renderResume: null,
deleted: false,
deletedAt: null,
};
if (!videoVariant) return clone;
// A footage adaptation starts with the same song and storyboard, but no
// procedural approvals, selected takes or running work. Nothing is dispatched.
const footageDirection = (direction) => ({ ...direction, route: 'generated',
medium: 'generated-footage', mediumPinned: false, mediumRationale: '' });
return {
...clone,
mediaMode: 'code-images-video',
composition: { ...clone.composition, mode: 'composed' },
productionPolicy: normalizeMusicVideoProductionPolicy({ strategy: 'legacy' }),
castAndSets: null,
visualSpec: clone.visualSpec ? { ...clone.visualSpec, references: [], moodBoardId: null } : null,
// The cast resets, so a loaded character style (which casts the protagonist) does too.
concept: clone.concept ? { ...clone.concept, subjects: [], moodBoardStyle: '', characterStyleId: null, characterStyle: '' } : null,
styleReferences: [],
...(clone.automation ? { automation: { ...clone.automation, tools: [], moodBoardId: null } } : {}),
scenes: clone.scenes.map((scene) => ({ ...scene, visualLayer: 'footage',
...(scene.direction ? { direction: footageDirection(scene.direction) } : {}),
})),
treatment: clone.treatment ? { ...clone.treatment, appliedRevision: null, basis: null,
shotDirections: clone.treatment.shotDirections.map(footageDirection),
} : null,
excerpts: [],
};
}
/** Merge a project metadata patch, validating status. Returns the next record. */
export function applyProjectPatch(project, patch) {
if (patch.status && !MUSIC_VIDEO_STATUSES.includes(patch.status)) {
throw new ServerError(`Invalid status: ${patch.status}`, { status: 400, code: 'VALIDATION_ERROR' });
}
// A `concept` patch merges into the existing concept sub-fields rather than
// replacing the whole object — mirrors applySceneUpdate's per-field scene merge
// below, so a caller sending only the sub-field it edited (e.g. { style: '…' })
// can't clobber a sibling sub-field (e.g. prompt) set concurrently by another
// sync peer (#3168). An explicit `concept: null` still clears it outright.
// Edited cue/phrase lists replace the stored list whole, normalized so every
// entry persists a stable id and a forward time range (timedText.js). A
// `visualSpec` patch merges per sub-field the same way (#8965).
const timedPatch = {
...patch,
...(patch.productionPolicy ? { productionPolicy: normalizeMusicVideoProductionPolicy(patch.productionPolicy, project.productionPolicy) } : {}),
...(patch.visualSpec ? { visualSpec: normalizeVisualSpec(patch.visualSpec, project.visualSpec) } : {}),
// Automation brief merges per sub-field; null clears it.
...('automation' in patch ? {
automation: patch.automation ? normalizeMusicVideoAutomation(patch.automation, project.automation) : null,
} : {}),
...(Array.isArray(patch.lyricCues) ? { lyricCues: normalizeLyricCues(patch.lyricCues).map((cue) => {
const previous = project.lyricCues?.find((entry) => entry.id === cue.id);
if (previous && previous.text !== cue.text) {
delete cue.matched;
delete cue.suspect;
}
return cue;
}) } : {}),
...(Array.isArray(patch.lyricMarkers) ? { lyricMarkers: normalizeLyricMarkers(patch.lyricMarkers) } : {}),
...(Array.isArray(patch.phrases) ? { phrases: normalizePhrases(patch.phrases) } : {}),
// #8984 — a manifest carrying its `mode` replaces the stored one whole
// (the editors send the full manifest, so an omitted key clears it); null
// clears it all. One without `mode` is a partial patch and merges over the
// stored manifest, so `{ style }` cannot silently reset mode and cutting.
// The composition document pointer is owned by the import routes: a PATCH
// that echoes (or omits, or forges) it keeps the stored one.
...('composition' in patch ? { composition: withStoredCompositionDocument(normalizeComposition(
patch.composition && typeof patch.composition === 'object' && !('mode' in patch.composition) && project.composition
? { ...project.composition, ...patch.composition } : patch.composition), project.composition) } : {}),
// #8988 — an explicitly chosen sound-design bed; null clears it.
...('soundBed' in patch ? { soundBed: normalizeSoundBed(patch.soundBed) } : {}),
// The film look is replaced whole (one bounded record); null clears it.
...('filmLook' in patch ? { filmLook: normalizeFilmLook(patch.filmLook) } : {}),
// The title card is replaced whole (one bounded record); null clears it.
...('titleCard' in patch ? { titleCard: normalizeTitleCard(patch.titleCard) } : {}),
// The outro after the song is replaced whole; null turns it off.
...('statsOutro' in patch ? { statsOutro: normalizeStatsOutro(patch.statsOutro) } : {}),
};
// #8988: a bed is mixed UNDER the song — the song itself can't be its bed.
const masterTrackId = 'trackId' in patch ? patch.trackId : project.trackId;
if (timedPatch.soundBed && masterTrackId && timedPatch.soundBed.trackId === masterTrackId) {
throw new ServerError('The sound-design bed must be a different track from the song', { status: 422, code: 'SOUND_BED_IS_MASTER' });
}
const conceptMergedPatch = ('concept' in timedPatch && timedPatch.concept && project.concept)
? { ...timedPatch, concept: { ...project.concept, ...timedPatch.concept } }
: timedPatch;
// Renderer settings are edited independently in the UI. Merge a partial
// change so picking a model cannot discard the provider or Grok duration.
const mergedPatch = ('videoSettings' in conceptMergedPatch && conceptMergedPatch.videoSettings)
? {
...conceptMergedPatch,
videoSettings: {
backend: 'local',
modelId: null,
grokDuration: 10,
falDuration: null,
falModelId: null,
falResolution: null,
falEndFrameModelId: null,
falLipSyncResolution: null,
falMusicModelId: null,
falMusicResolution: null,
generationMode: 'image',
audioReactiveLora: null,
audioReactiveScale: 1.2,
...project.videoSettings,
...conceptMergedPatch.videoSettings,
},
}
: conceptMergedPatch;
// Changing the audio source invalidates the cached beat/tempo analysis —
// it was computed from the OLD track. AI Plan / Auto-arrange / BeatTimeline
// gate on `audioAnalysis` truthiness, and the render's beat-snap step reads
// its `beats` array; a stale analysis would silently apply the previous
// song's beat grid to the new audio (#1945 — both the manual "Change
// track" picker and the YouTube-import attach PATCH through here). Any
// scene already marked `beatAligned` also stops being true — its saved
// startSec/endSec were snapped to the OLD song's beat positions, and
// `beatSnapClips` honors a beat-aligned scene's saved bounds outright
// (skipping re-derivation against the new, absent beat grid), so leaving
// the flag set would render the old song's cut points against new audio.
const trackChanged = ('trackId' in patch && patch.trackId !== project.trackId)
|| ('uploadedAudioFilename' in patch && patch.uploadedAudioFilename !== project.uploadedAudioFilename);
if ('mediaMode' in patch || patch.visualSpec || patch.styleReferences) assertMusicVideoMediaSelections({ ...project, ...mergedPatch });
if (!trackChanged) return touch(project, mergedPatch);
// A planned section belongs to the old audio too; clear its provenance so
// the renderer does not preserve that plan's timing on the replacement song.
const scenes = (project.scenes || []).map((s) => (s.beatAligned || s.sectionIndex != null
? { ...s, beatAligned: false, sectionIndex: null } : s));
// Clearing audioAnalysis means the project must be re-analyzed before it can be
// planned/arranged/rendered, so a status that implies analysis existed
// (`analyzed`/`ready`/`rendering`/`complete`) is now stale. Regress it to `draft` —
// the inverse of setAudioAnalysis's draft→analyzed flip — unless the caller set an
// explicit status in this same patch. `draft`/`failed` already imply no usable
// analysis, so leave those untouched.
const regressStatus = !patch.status && !['draft', 'failed'].includes(project.status);
const statusPatch = regressStatus ? { status: 'draft' } : {};
// The MIDI transcription was produced from the OLD audio too — clear it with
// the analysis so a stale .mid can't masquerade as the new track's score.
// Lyric-cue and phrase timings were aligned to the OLD audio as well: keep the
// director's text but clear the times and word timings (#8964, #9074), unless
// this same patch supplied fresh lists of its own.
return touch(project, {
...invalidateTimedText(project),
// Composition cue times and the poster frame were set against the old
// song too: keep the text, clear the timings (#8984).
...(project.composition ? { composition: invalidateCompositionTiming(project.composition) } : {}),
// A vocal stem is a bounce of the OLD song; conditioning a performance on
// it against the new master would sing the wrong words (#8977).
...(project.vocalStemFilename ? { vocalStemFilename: null } : {}),
performanceConditioningSource: 'master',
...mergedPatch,
...statusPatch,
audioAnalysis: null,
midiTranscription: null,
scenes,
});
}
/**
* Cache the offline beat/tempo/section analysis on the project. Flips a `draft`
* project to `analyzed`; leaves any later status untouched (re-analysis of a
* ready/rendering project shouldn't regress its lifecycle). The analysis shape
* is validated so a hand-edited/legacy record can't store a malformed map.
*/
export function setAudioAnalysis(project, analysis, sourceProject) {
if (sourceProject && (project.trackId !== sourceProject.trackId || project.uploadedAudioFilename !== sourceProject.uploadedAudioFilename)) {
throw new ServerError('The audio changed during analysis. Analyze the selected master again.', { status: 409, code: 'MUSIC_VIDEO_AUDIO_CHANGED' });
}
const validated = musicVideoAudioAnalysisSchema.parse(analysis);
const status = project.status === 'draft' ? 'analyzed' : project.status;
return touch(project, { audioAnalysis: validated, status });
}
/**
* Cache the MuScriptor audio → MIDI transcription pointer on the project (a
* .mid basename under /api/uploads). Validated so a hand-edited/legacy record
* can't store a malformed pointer; doesn't touch the lifecycle status — the
* MIDI is a parsing artifact, not an arrangement step.
*/
export function setMidiTranscription(project, midi) {
const validated = musicVideoMidiTranscriptionSchema.parse(midi);
return touch(project, { midiTranscription: validated });
}
/** Default runtime fields for a scene the director (or planner) didn't supply. */
function buildScene(input, { order }) {
return {
sceneId: `mvs-${randomUUID()}`,
order,
label: input.label ?? '',
sectionLabel: input.sectionLabel ?? null,
startSec: input.startSec ?? null,
endSec: input.endSec ?? null,
beatAligned: input.beatAligned ?? false,
prompt: input.prompt ?? '',
framePrompt: input.framePrompt ?? null,
// #8964: a new shot never silently repeats its clip to fill a span — looping
// is an explicit choice. (Pre-#8964 scenes carry no `loop` key and keep the
// legacy loop-to-fill render; see render.js#sceneLoops.)
loop: input.loop ?? false,
sectionIndex: input.sectionIndex ?? null,
lyricText: input.lyricText ?? null,
visualIntent: input.visualIntent ?? null,
...(input.frameReferenceIds ? { frameReferenceIds: input.frameReferenceIds } : {}),
...(input.characterVariant ? { characterVariant: input.characterVariant } : {}),
// #8985: what a composed render shows for this span (render.js#sceneLayer).
visualLayer: input.visualLayer ?? 'footage',
stillMove: input.stillMove ?? 'hold',
// #10589: the planned camera move (absent on hand-added and pre-#10589 shots).
...(input.camera ? { camera: input.camera } : {}),
cardText: input.cardText ?? null,
...(input.codeOverlay ? { codeOverlay: true } : {}),
...(input.codeClip ? { codeClip: true } : {}),
...(input.frameFit ? { frameFit: input.frameFit } : {}),
...(input.speedFps ? { speedFps: input.speedFps } : {}),
...(input.offsetFrames ? { offsetFrames: input.offsetFrames } : {}),
...(input.reverse ? { reverse: true } : {}),
...(input.holdLastFrame ? { holdLastFrame: true } : {}),
...(input.filmLook ? { filmLook: normalizeFilmLook(input.filmLook) } : {}),
...(input.transitionIn ? { transitionIn: input.transitionIn } : {}),
...(input.transitionOut ? { transitionOut: input.transitionOut } : {}),
...(input.glitches?.length ? { glitches: input.glitches } : {}),
...(input.cutEffect ? { cutEffect: input.cutEffect } : {}),
...(input.imageEffect ? { imageEffect: input.imageEffect } : {}),
...(input.imageEffectSec ? { imageEffectSec: input.imageEffectSec } : {}),
cardColor: input.cardColor ?? null,
...(input.textZone ? { textZone: input.textZone } : {}),
...(input.lyricRole ? { lyricRole: input.lyricRole } : {}),
...(input.lyricSize ? { lyricSize: input.lyricSize } : {}),
// #8977: cutaway (any image-to-video lane) unless the director asks for a
// lip-synced performance shot, which only a source-audio provider renders.
shotMode: input.shotMode ?? 'cutaway',
...(input.performanceSpeaker ? { performanceSpeaker: input.performanceSpeaker } : {}),
...(input.performanceStyle === 'music' ? { performanceStyle: 'music' } : {}),
...(input.panelId ? { panelId: input.panelId, panelRev: input.panelRev ?? null, panelArt: input.panelArt ?? null } : {}),
referenceImageId: null,
videoHistoryId: null,
// #8965 — immutable candidate takes; the two slot fields above are the
// director's selection among them (see takes.js).
takes: [],
};
}
/** Where a new scene goes: before the first timed scene that starts after it; untimed scenes go last. */
function insertByTime(scenes, scene) {
const at = scene.startSec;
const idx = typeof at === 'number' ? scenes.findIndex((s) => typeof s.startSec === 'number' && s.startSec > at) : -1;
return idx < 0 ? [...scenes, scene] : [...scenes.slice(0, idx), scene, ...scenes.slice(idx)];
}
/**
* Add a scene to the board at its time. Validates the input, assigns a sceneId and
* renumbers order. Returns `{ project, scene }`. A thin single-item wrapper
* over `addScenes` so the validate/build/order logic lives in exactly one
* place.
*/
export function addScene(project, sceneInput) {
const { project: next, scenes } = addScenes(project, [sceneInput]);
return { project: next, scene: scenes[0] };
}
/**
* Add several scenes to the board in one pass (the autonomous planner,
* #1855) — a single `touch`/persist instead of N sequential addScene calls, so
* a 10-section plan is one write (and one peer-sync emit) instead of ten.
* A timed scene goes in at its time, so the board stays in song order; an
* untimed one is appended. Returns `{ project, scenes }` (the newly-created
* scenes, in input order).
*/
export function addScenes(project, sceneInputs) {
const list = Array.isArray(sceneInputs) ? sceneInputs : [];
let scenes = project.scenes || [];
const ids = [];
for (const input of list) {
const data = parseSceneOrThrow(musicVideoSceneCreateSchema, input);
const scene = buildScene(data, { order: 0 });
ids.push(scene.sceneId);
scenes = insertByTime(scenes, scene);
}
scenes = scenes.map((s, i) => (s.order === i ? s : { ...s, order: i }));
const next = touch(project, { scenes });
return { project: next, scenes: ids.map((id) => scenes.find((s) => s.sceneId === id)) };
}
/**
* Replace the whole board with freshly planned scenes (AI Plan "Replace").
* A new shot whose time span matches an old scene (within 10 ms) inherits that
* scene's id, direction, reference frame, selected clip and takes, so the
* generated work and treatment direction keyed to the id survive the re-plan.
* Returns `{ project, scenes, replaced }` (`replaced` = the old scene count).
*/
export function replaceScenes(project, sceneInputs) {
const list = Array.isArray(sceneInputs) ? sceneInputs : [];
const existing = project.scenes || [];
const claimed = new Set();
const sameSpan = (a, b) => typeof a === 'number' && typeof b === 'number' && Math.abs(a - b) < 0.01;
const scenes = list.map((input, order) => {
const fresh = buildScene(parseSceneOrThrow(musicVideoSceneCreateSchema, input), { order });
const prior = existing.find((old) => !claimed.has(old.sceneId)
&& sameSpan(old.startSec, fresh.startSec) && sameSpan(old.endSec, fresh.endSec));
if (!prior) return fresh;
claimed.add(prior.sceneId);
return {
...fresh,
sceneId: prior.sceneId,
referenceImageId: prior.referenceImageId ?? null,
videoHistoryId: prior.videoHistoryId ?? null,
...(prior.endImageId ? { endImageId: prior.endImageId } : {}),
...(prior.endFramePrompt ? { endFramePrompt: prior.endFramePrompt } : {}),
...(prior.frameFit ? { frameFit: prior.frameFit } : {}),
...(prior.speedFps ? { speedFps: prior.speedFps } : {}),
...(prior.offsetFrames ? { offsetFrames: prior.offsetFrames } : {}),
...(prior.reverse ? { reverse: true } : {}),
...(prior.holdLastFrame ? { holdLastFrame: true } : {}),
...(prior.filmLook ? { filmLook: prior.filmLook } : {}),
...(prior.transitionIn ? { transitionIn: prior.transitionIn } : {}),
...(prior.transitionOut ? { transitionOut: prior.transitionOut } : {}),
...(prior.glitches?.length ? { glitches: prior.glitches } : {}),
...(prior.cutEffect ? { cutEffect: prior.cutEffect } : {}),
// A still playing an image effect stays one: the effect is the shot's picture.
...(prior.imageEffect && prior.visualLayer === 'still' ? { visualLayer: 'still', imageEffect: prior.imageEffect,
...(prior.imageEffectSec ? { imageEffectSec: prior.imageEffectSec } : {}) } : {}),
takes: prior.takes || [],
...(prior.direction ? { direction: prior.direction } : {}),
};
});
// Rows bound to shots the new plan dropped go with them.
return { project: dropStaleStoryboardRows(touch(project, { scenes })), scenes, replaced: existing.length };
}
// Scene fields a director edits within an approved shot (its span, wording, selected
// takes, and whether it plays as a clip or its still with an image effect) without
// adding a shot or lyric the storyboard approval did not cover.
const SCENE_SHOT_EDIT_FIELDS = ['startSec', 'endSec', 'beatAligned', 'label', 'prompt', 'framePrompt', 'visualIntent',
'referenceImageId', 'videoHistoryId', 'endImageId', 'codeClip', 'frameFit', 'speedFps', 'offsetFrames', 'reverse', 'holdLastFrame', 'filmLook', 'transitionIn', 'transitionOut', 'glitches', 'cutEffect',
'visualLayer', 'stillMove', 'imageEffect', 'imageEffectSec', 'frameReferenceIds', 'characterVariant', 'panelId', 'panelRev', 'panelArt'];
/**
* Apply a patch to a single scene. Returns `{ project, updated }`. Throws if the
* scene id is unknown.
*/
export function applySceneUpdate(project, sceneId, patch) {
const parsed = parseSceneOrThrow(musicVideoSceneUpdateSchema, patch);
// A shot's own look is stored complete; null returns it to the video's look.
const data = 'filmLook' in parsed ? { ...parsed, filmLook: parsed.filmLook ? normalizeFilmLook(parsed.filmLook) : null } : parsed;
const scenes = project.scenes || [];
const idx = scenes.findIndex((s) => s.sceneId === sceneId);
if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
const kept = 'codeClip' in data ? { ...scenes[idx], ...data } : keepCodeClipWithItsClip(scenes[idx], { ...scenes[idx], ...data });
// A shot turning into a still takes the nearest move to its planned camera (#10589) unless
// it already has one; from then on its Move picker owns how the still moves.
const becomesStill = data.visualLayer === 'still' && scenes[idx].visualLayer !== 'still' && !('stillMove' in data) && (kept.stillMove ?? 'hold') === 'hold';
const seeded = becomesStill ? stillMoveForCamera(kept.camera) : null;
const merged = seeded ? { ...kept, stillMove: seeded } : kept;
// Setting a slot directly (an older client, or a hand edit) still records the
// asset as a take so the candidate list stays a superset of the selection.
const touchesSlot = Object.values(TAKE_SLOT).some((field) => typeof data[field] === 'string');
const updated = touchesSlot ? { ...merged, takes: ensureSceneTakes(merged, undefined, 'manual') } : merged;
// The partial-patch schema can't enforce endSec >= startSec (the paired value
// may be unchanged on the record), so validate the merged range here.
if (updated.startSec != null && updated.endSec != null && updated.endSec < updated.startSec) {
throw new ServerError('endSec must be >= startSec', { status: 400, code: 'VALIDATION_ERROR' });
}
// A retimed shot shows, and anchors, the lyric lines now sung over it.
const retimed = (('startSec' in data && data.startSec !== scenes[idx].startSec) || ('endSec' in data && data.endSec !== scenes[idx].endSec))
&& (project.lyricCues || []).some((cue) => typeof cue?.startSec === 'number');
if (retimed && !('lyricText' in data)) {
updated.lyricText = sungLyricTextWithin(project.lyricCues, updated.startSec, updated.endSec);
}
assertMusicVideoMediaSelections({ ...project, scenes: [updated], visualSpec: null });
const nextScenes = scenes.slice();
nextScenes[idx] = updated;
const next = retimed ? anchorShotsToSungLyrics(touch(project, { scenes: nextScenes }), [sceneId]) : touch(project, { scenes: nextScenes });
// Retiming or rewording a shot, or picking another take, keeps the storyboard approval it was judged on.
const shotEdit = Object.keys(data).every((key) => SCENE_SHOT_EDIT_FIELDS.includes(key));
return { project: shotEdit ? carryStoryboardApproval(project, next, 'Edited a shot') : next, updated };
}
/** Remove a scene and re-sequence the remaining scenes' `order`. Returns the next record. */
export function removeScene(project, sceneId) {
const scenes = project.scenes || [];
if (!scenes.some((s) => s.sceneId === sceneId)) {
throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
}
const nextScenes = scenes
.filter((s) => s.sceneId !== sceneId)
.map((s, i) => ({ ...s, order: i }));
const extra = { scenes: nextScenes };
// The removed shot's storyboard row goes with it, so the board has no row bound to a missing scene.
const draft = project.productionReview?.draft;
if (Array.isArray(draft?.storyboard) && draft.storyboardSource !== 'document') {
extra.productionReview = { ...project.productionReview,
draft: { ...draft, storyboard: draft.storyboard.filter((shot) => shot?.sceneId !== sceneId) } };
}
// Cutting a shot adds nothing the approval did not cover, so a current storyboard approval stays.
return carryStoryboardApproval(project, touch(project, extra), 'Cut a shot');
}
// What a board position owns rather than the shot placed in it: the span of
// the song, its section, and the lyric sung there. A reorder leaves these on
// their positions and moves only the shot (prompts, frames, clips, takes,
// direction, camera), so swapping two shots keeps the song timing intact.
const SCENE_SLOT_FIELDS = ['startSec', 'endSec', 'beatAligned', 'sectionIndex', 'sectionLabel', 'lyricText', 'lyricRole', 'lyricSize'];
const DRAFT_SHOT_SLOT_FIELDS = ['startSec', 'endSec', 'lyricCueIds'];
const pickSlot = (record, fields) => Object.fromEntries(fields.filter((k) => k in record).map((k) => [k, record[k]]));
const withoutSlot = (record, fields) => Object.fromEntries(Object.entries(record).filter(([k]) => !fields.includes(k)));
/**
* Reorder the board to the given sceneId order. `orderedIds` must be exactly the
* project's current scene ids (a permutation) — a missing/extra/unknown id is a
* 400 so a stale client can't silently drop scenes. Each board position keeps
* its song slot (SCENE_SLOT_FIELDS) and the shots move between the slots; the
* lyric-timed storyboard draft's shots follow their scenes into the new slots,
* and a revised song's per-shot lyric verdicts stay with their slots.
* The storyboard and proof approvals hash scene timing and content, so they go
* stale on their own. Returns the next record.
*/
export function reorderScenes(project, orderedIds) {
const scenes = project.scenes || [];
const byId = new Map(scenes.map((s) => [s.sceneId, s]));
if (orderedIds.length !== scenes.length || !orderedIds.every((id) => byId.has(id)) || new Set(orderedIds).size !== orderedIds.length) {
throw new ServerError('Reorder must list each existing scene id exactly once', { status: 400, code: 'VALIDATION_ERROR' });
}
// The scene whose slot each moved scene now fills.
const slotOwner = new Map(orderedIds.map((id, i) => [id, scenes[i]]));
const nextScenes = orderedIds.map((id, i) => ({
...withoutSlot(byId.get(id), SCENE_SLOT_FIELDS), ...pickSlot(scenes[i], SCENE_SLOT_FIELDS), order: i,
}));
const extra = { scenes: nextScenes };
// A revised song's verdicts are about the lyric in a slot, so they stay with it.
const sceneReview = project.songRevision?.sceneReview;
if (sceneReview && typeof sceneReview === 'object') {
const holder = new Map(scenes.map((s, i) => [s.sceneId, orderedIds[i]]));
extra.songRevision = { ...project.songRevision,
sceneReview: Object.fromEntries(Object.entries(sceneReview).map(([id, verdict]) => [holder.get(id) ?? id, verdict])) };
}
const draft = project.productionReview?.draft;
if (!Array.isArray(draft?.storyboard) || draft.storyboardSource === 'document') return touch(project, extra);
const draftShots = new Map(draft.storyboard.filter((shot) => shot?.sceneId).map((shot) => [shot.sceneId, shot]));
const storyboard = draft.storyboard.map((shot) => {
const owner = shot?.sceneId && slotOwner.get(shot.sceneId);
if (!owner || owner.sceneId === shot.sceneId) return shot;
// The owner's own draft shot carries that slot's lyric anchors; without one,
// take the slot's timing and let the storyboard check ask for anchors.
const slot = draftShots.get(owner.sceneId);
return slot ? { ...shot, ...pickSlot(slot, DRAFT_SHOT_SLOT_FIELDS) }
: { ...shot, startSec: owner.startSec ?? shot.startSec, endSec: owner.endSec ?? shot.endSec, lyricCueIds: [] };
});
return touch(project, { ...extra, productionReview: { ...project.productionReview, draft: { ...draft, storyboard } } });
}
// Label suffix budget: the scene label schema caps at 120 characters.
const SCENE_LABEL_MAX = 120;
/**
* Split a shot longer than its backend can render in one take (#8977) into
* contiguous scenes on musical boundaries (lib/musicVideoShotTiming.js
* `planShotSplit`): a performance shot at its lip-sync provider's audio
* window, a Grok cutaway at the longest Grok clip. `backend` is the lane the
* director will render with ('' / null = the project's pinned backend).
*
* The original scene keeps its id and takes and becomes the first piece (a
* performance's lip-synced clip selection is cleared — see below). Each later
* piece is a new scene placed right after it, carrying the shot's direction
* and the selected reference frame (as a take, so the frame is ready to
* animate) but no clip — the old clip was generated for the whole span. Each
* piece's `lyricText` is the timed lines sung inside it. `atSec` instead cuts
* the shot in two at that song time, whatever the backend. Returns `{ project, scenes }` (all pieces, in
* order); throws 400 when the shot is untimed, already fits one take, or `atSec` falls outside it.
*/
export function splitScene(project, sceneId, { backend = null, atSec = null } = {}) {
const scenes = project.scenes || [];
const idx = scenes.findIndex((s) => s.sceneId === sceneId);
if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
const scene = scenes[idx];
const plan = atSec != null ? splitAtTime(scene, atSec) : planShotSplit({
startSec: scene.startSec,
endSec: scene.endSec,
maxSec: splitLimitOrThrow(project, scene, backend),
lyricCues: project.lyricCues,
phrases: project.phrases,
beats: project.audioAnalysis?.beats,
});
if (!plan.ok) throw new ServerError(plan.message, { status: 400, code: plan.code });
const now = new Date().toISOString();
const count = plan.pieces.length;
// Re-splitting a piece numbers it afresh rather than stacking suffixes.
const baseLabel = (scene.label || scene.sectionLabel || `Scene ${idx + 1}`).replace(/ · \d+\/\d+$/, '');
const pieceLabel = (i) => {
const suffix = ` · ${i + 1}/${count}`;
return `${baseLabel.slice(0, SCENE_LABEL_MAX - suffix.length)}${suffix}`;
};
const hasTimedCues = (project.lyricCues || []).some((cue) => typeof cue?.startSec === 'number');
const pieceLyrics = (piece) => (hasTimedCues ? sungLyricTextWithin(project.lyricCues, piece.startSec, piece.endSec) : scene.lyricText ?? null);
const pieces = plan.pieces.map((piece, i) => {
const timing = { label: pieceLabel(i), startSec: piece.startSec, endSec: piece.endSec, lyricText: pieceLyrics(piece) };
if (i === 0) {
const takes = ensureSceneTakes(scene, now);
// A lip-synced take was generated for the old interval and the render
// refuses it as re-timed, so the selection is cleared (the take stays a
// candidate) and "Generate missing" fills it. A cutaway clip still starts
// where the first piece does, so it stays selected and is trimmed.
return isPerformanceScene(scene)
? { ...scene, ...timing, takes, videoHistoryId: null }
: { ...scene, ...timing, takes };
}
const fresh = buildScene({
...parseSceneOrThrow(musicVideoSceneCreateSchema, {
sectionLabel: scene.sectionLabel ?? null,
prompt: scene.prompt ?? '',
framePrompt: scene.framePrompt ?? null,
beatAligned: scene.beatAligned ?? false,
loop: scene.loop ?? false,
sectionIndex: scene.sectionIndex ?? null,
visualIntent: scene.visualIntent ?? null,
visualLayer: scene.visualLayer ?? 'footage',
...(scene.stillMove ? { stillMove: scene.stillMove } : {}),
shotMode: scene.shotMode ?? 'cutaway',
performanceSpeaker: scene.performanceSpeaker ?? null,
performanceStyle: scene.performanceStyle ?? null,
...(scene.camera ? { camera: scene.camera } : {}),
...(scene.panelId ? { panelId: scene.panelId, panelRev: scene.panelRev ?? null, panelArt: scene.panelArt ?? null } : {}),
...timing,
}),
}, { order: 0 });
const seeded = {
...fresh,
...(scene.direction ? { direction: structuredClone(scene.direction) } : {}),
referenceImageId: scene.referenceImageId ?? null,
};
return { ...seeded, takes: ensureSceneTakes(seeded, now, 'manual') };
});
const nextScenes = [...scenes.slice(0, idx), ...pieces, ...scenes.slice(idx + 1)]
.map((s, i) => ({ ...s, order: i }));
const extra = { scenes: nextScenes };
// The shot's storyboard row follows its first piece; each later piece gets a
// copy of the row's direction, all anchored to the lines sung over them.
const draft = project.productionReview?.draft;
const row = Array.isArray(draft?.storyboard) && draft.storyboardSource !== 'document'
? draft.storyboard.find((shot) => shot?.sceneId === sceneId) : null;
if (row) {
const anchored = (piece) => cuesSungWithin(project.lyricCues, piece.startSec, piece.endSec).map((cue) => cue.id);
const span = (piece) => ('startSec' in row || 'endSec' in row ? { startSec: piece.startSec, endSec: piece.endSec } : {});
const rows = pieces.map((piece, i) => ({ ...row, ...(i ? { id: `shot-${piece.sceneId}`, sceneId: piece.sceneId } : {}),
...span(piece), lyricCueIds: anchored(piece) }));
const storyboard = draft.storyboard.flatMap((shot) => (shot === row ? rows : [shot]));
extra.productionReview = { ...project.productionReview, draft: { ...draft, storyboard } };
}
const next = carryStoryboardApproval(project, touch(project, extra), 'Split a shot');
return { project: next, scenes: nextScenes.slice(idx, idx + count) };
}
const timedSec = (v) => typeof v === 'number' && Number.isFinite(v);
function splitLimitOrThrow(project, scene, backend) {
const maxSec = shotSplitLimit(scene, backend || project.videoSettings?.backend || null, project.videoSettings);
if (maxSec == null) {
throw new ServerError('This backend renders the shot at any length — there is nothing to split.', { status: 400, code: 'MUSIC_VIDEO_SPLIT_NOT_NEEDED' });
}
return maxSec;
}
/** Shortest piece a split at a chosen time may leave. */
const MIN_SPLIT_PIECE_SEC = 0.1;
/** Two pieces cut at `atSec`, which must fall inside the timed shot. */
function splitAtTime(scene, atSec) {
const { startSec, endSec } = scene;
if (!timedSec(startSec) || !timedSec(endSec)) {
return { ok: false, code: 'MUSIC_VIDEO_SPLIT_UNTIMED', message: 'Give this shot a start and end time before splitting it.' };
}
if (atSec < startSec + MIN_SPLIT_PIECE_SEC || atSec > endSec - MIN_SPLIT_PIECE_SEC) {
return { ok: false, code: 'MUSIC_VIDEO_SPLIT_OUT_OF_RANGE', message: `Split inside the shot, between ${startSec + MIN_SPLIT_PIECE_SEC}s and ${endSec - MIN_SPLIT_PIECE_SEC}s.` };
}
return { ok: true, pieces: [{ startSec, endSec: atSec }, { startSec: atSec, endSec }] };
}
/**
* Join a scene with the one after it — the inverse of `splitScene`. The first
* scene keeps its id, takes and selections and stretches to the next scene's
* end; the lyric lines are joined; the next scene is removed and `order`
* renumbered; a board-sourced storyboard draft merges the matching shots.
* A selected clip survives (the director's cut was one continuous clip), but a
* performance's lip-synced clip was generated for the old interval, so its
* selection is cleared as in a split. When the second scene selects the same
* video asset as the first, its take for that asset is kept too. Refuses when
* the joined span exceeds the backend's longest take (`shotSplitLimit`) and for
* a document composition, whose shot order lives in the shot manifest.
* Returns `{ project, scene }`.
*/
export function mergeNextScene(project, sceneId, { backend = null } = {}) {
const scenes = project.scenes || [];
const idx = scenes.findIndex((s) => s.sceneId === sceneId);
if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
if (!scenes[idx + 1]) throw new ServerError('This is the last scene — there is no next scene to merge.', { status: 400, code: 'MUSIC_VIDEO_MERGE_NO_NEXT' });
return joinScenes(project, idx, { keep: 'first', backend });
}
/**
* Merge a scene over the one before it, the mirror of `mergeNextScene`: this
* scene keeps its id, takes and selections and starts where the previous scene
* started, and the previous scene is removed. Same refusals and clip rules.
* Returns `{ project, scene }`.
*/
export function mergePreviousScene(project, sceneId, { backend = null } = {}) {
const scenes = project.scenes || [];
const idx = scenes.findIndex((s) => s.sceneId === sceneId);
if (idx < 0) throw new ServerError('Scene not found', { status: 404, code: 'NOT_FOUND' });
if (idx === 0) throw new ServerError('This is the first scene — there is no previous scene to merge over.', { status: 400, code: 'MUSIC_VIDEO_MERGE_NO_PREVIOUS' });
return joinScenes(project, idx - 1, { keep: 'second', backend });
}
/** Join scenes `idx` and `idx + 1` into one spanning both, keeping the `first` or `second` scene's id and media. */
function joinScenes(project, idx, { keep, backend }) {
const scenes = project.scenes || [];
const [first, second] = [scenes[idx], scenes[idx + 1]];
const [kept, removed] = keep === 'first' ? [first, second] : [second, first];
if (project.composition?.mode === 'document') {
throw new ServerError("This video's shot order comes from its composition document — merge the shots in the shot manifest instead.", { status: 400, code: 'MUSIC_VIDEO_MERGE_DOCUMENT' });
}
const lane = backend || project.videoSettings?.backend || null;
const startSec = first.startSec;
const endSec = timedSec(second.endSec) ? second.endSec : first.endSec;
if (timedSec(startSec) && timedSec(endSec) && (endSec <= startSec || (timedSec(first.endSec) && endSec < first.endSec))) {
throw new ServerError('The next scene ends before this one does — put the scenes in song order before merging them.', { status: 400, code: 'MUSIC_VIDEO_MERGE_OUT_OF_ORDER' });
}
const maxSec = shotSplitLimit(kept, lane, project.videoSettings);
if (maxSec != null) {
if (!timedSec(startSec) || !timedSec(endSec)) {
throw new ServerError('Both scenes need a start and end time before they can be merged on this backend.', { status: 400, code: 'MUSIC_VIDEO_MERGE_UNTIMED' });
}
if (endSec - startSec > maxSec + 1e-6) {
throw new ServerError(`The merged shot would run ${(endSec - startSec).toFixed(2)}s, longer than this backend renders in one take (${maxSec.toFixed(2)}s).`, { status: 400, code: 'MUSIC_VIDEO_MERGE_TOO_LONG' });
}
}
const now = new Date().toISOString();
let takes = ensureSceneTakes(kept, now);
const sharedClip = kept.videoHistoryId && kept.videoHistoryId === removed.videoHistoryId;
if (sharedClip && !takes.some((t) => t.kind === 'video' && t.assetId === kept.videoHistoryId)) {
const shared = ensureSceneTakes(removed, now).find((t) => t.kind === 'video' && t.assetId === kept.videoHistoryId);
if (shared) takes = [...takes, shared];
}
const lyricText = [first.lyricText, second.lyricText].filter((t) => typeof t === 'string' && t.trim()).join(' / ').slice(0, 2000) || null;
const merged = {
...kept, startSec, endSec, lyricText, takes,
...(isPerformanceScene(kept) ? { videoHistoryId: null } : {}),
};
const nextScenes = [...scenes.slice(0, idx), merged, ...scenes.slice(idx + 2)].map((s, i) => ({ ...s, order: i }));
const extra = { scenes: nextScenes };
const sceneReview = project.songRevision?.sceneReview;
if (sceneReview && typeof sceneReview === 'object' && removed.sceneId in sceneReview) {
extra.songRevision = { ...project.songRevision,
sceneReview: Object.fromEntries(Object.entries(sceneReview).filter(([id]) => id !== removed.sceneId)) };
}
const draft = project.productionReview?.draft;
if (Array.isArray(draft?.storyboard) && draft.storyboardSource !== 'document') {
const rowOf = (scene) => draft.storyboard.find((shot) => shot?.sceneId === scene.sceneId);
const [firstRow, secondRow] = [rowOf(first), rowOf(second)];
const gone = rowOf(removed);
const storyboard = draft.storyboard
.filter((shot) => shot?.sceneId !== removed.sceneId)
.map((shot) => {
if (shot?.sceneId !== kept.sceneId) return shot;
const cueIds = [...new Set([...(firstRow?.lyricCueIds || []), ...(secondRow?.lyricCueIds || [])])];
return { ...shot,
...(keep === 'second' ? { startSec: timedSec(gone?.startSec) ? gone.startSec : startSec ?? shot.startSec } : {}),
endSec: timedSec(secondRow?.endSec) ? secondRow.endSec : endSec ?? shot.endSec, lyricCueIds: cueIds };
});
extra.productionReview = { ...project.productionReview, draft: { ...draft, storyboard } };
}
// Joining two shots keeps their prompts and lyrics, so a current storyboard approval stays.
return { project: carryStoryboardApproval(project, touch(project, extra), 'Merged two shots'), scene: nextScenes[idx] };
}
// ---- peer-sync federation (#1770) -----------------------------------------
// Mirrors the Creative Director store (creativeDirector/projectsLogic.js): a
// project is a whole-record LWW kind (no item-union, no ephemeral flag), so the
// wire form is the record with normalized soft-delete fields and the merge is a
// straight `updatedAt` newest-wins decision. Both backends call through here so
// the file and PG paths can't diverge.
/**
* Wire-safe / merge-safe projection of a peer-supplied project record. Rejects a
* non-object or one missing an id (the receiver could never apply it), and
* normalizes the timestamps + soft-delete pair so a legacy/hand-edited payload
* converges byte-for-byte with a freshly-written one. Returns null when unusable.
*/
/**
* LWW merge decision for one incoming peer record against the local copy.
* Returns `{ next, inserted, remoteWins, changed }`:
* - malformed remote → `{ next: null, ... }` (caller drops it)
* - no local copy → insert the remote
* - otherwise newest-`updatedAt`-wins; `changed` is false when the winner is
* byte-identical to local (a same-`updatedAt` re-push no-ops, no churn).
* Tombstone-aware purely via `updatedAt`: deleteProject stamps a fresh
* `updatedAt`, so a tombstone beats an older live copy and can't be resurrected.
*/
export function mergeProjectRecord(local, remoteRaw) {
let remote = sanitizeProjectForSync(remoteRaw);
if (!remote) return { next: null, inserted: false, remoteWins: false, changed: false };
// An older peer can still send the fields that newer peers strip. Project
// sync remains schema-v1 compatible, so apply the same projection inbound
// before either inserting or restoring this machine's local choices.
remote = stripMusicVideoLocalRenderPins(remote);
if (!local) return { next: remote, inserted: true, remoteWins: true, changed: true };
// Render pins are install-capability choices and therefore wire-local
// (#3245). sanitizeRecordForWire omits them from peer payloads; restore this
// machine's values before a newer remote record wholesale-replaces local.
// Key-presence checks preserve an intentional local empty/null value instead
// of confusing it with a missing field.
remote = { ...remote };
if (Object.hasOwn(local, 'imageMode')) remote.imageMode = local.imageMode;
if (Object.hasOwn(local, 'imageModelId')) remote.imageModelId = local.imageModelId;
// #9066: this install's production-run checkpoint survives a newer remote.
if (Object.hasOwn(local, 'productionRuns')) remote.productionRuns = local.productionRuns;
// Development artifacts and the Cast & Sets checkpoint are wire-local too:
// their files and jobs exist only on this install.
if (Object.hasOwn(local, 'devArtifacts')) remote.devArtifacts = local.devArtifacts;
delete remote.productionReview;
if (Object.hasOwn(local, 'productionReview')) remote.productionReview = local.productionReview;
if (Object.hasOwn(local, 'castAndSets')) remote.castAndSets = local.castAndSets;
if (Object.hasOwn(local, 'autonomousRun')) remote.autonomousRun = local.autonomousRun;
if (Object.hasOwn(local, 'renderError')) remote.renderError = local.renderError;
// Song revisions hold this install's paid-generation recovery checkpoint,
// candidate files and provenance; an unrelated peer edit must not erase them.
if (Object.hasOwn(local, 'songRevision')) remote.songRevision = local.songRevision;
if (Object.hasOwn(local, 'songRevisionHistory')) remote.songRevisionHistory = local.songRevisionHistory;
// The composition document's files live only on this install as well
// (compositionDocument.js), so its pointer survives a newer remote body.
if (local.composition?.document || local.composition?.documentDraft) {
const sharedComposition = remote.composition && typeof remote.composition === 'object' && !Array.isArray(remote.composition)
? remote.composition : {};
remote.composition = {
...sharedComposition,
...(local.composition.document ? { document: local.composition.document } : {}),
...(local.composition.documentDraft ? { documentDraft: local.composition.documentDraft } : {}),
};
}
if (local.videoSettings && typeof local.videoSettings === 'object'
&& !Array.isArray(local.videoSettings) && ['backend', 'renderPool'].some((key) => Object.hasOwn(local.videoSettings, key))) {
const remoteVideoSettings = remote.videoSettings && typeof remote.videoSettings === 'object'
&& !Array.isArray(remote.videoSettings) ? remote.videoSettings : {};
remote.videoSettings = { ...remoteVideoSettings,
...Object.fromEntries(['backend', 'renderPool'].filter((key) => Object.hasOwn(local.videoSettings, key)).map((key) => [key, local.videoSettings[key]])) };
}
const remoteWins = compareNewerWins(remote.updatedAt, local.updatedAt);
const next = remoteWins ? remote : local;
const changed = JSON.stringify(next) !== JSON.stringify(local);
return { next, inserted: false, remoteWins, changed };
}