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, musicVideoAllowsMedia } from '../../lib/musicVideoMediaPolicy.js';
import { prepareProductionReview } from './productionReviewService.js';
import { ALIGNMENT_UNVERIFIED_PROBLEM, assertProductionApproval, carryProductionApprovals, nameShots, productionAlignmentBasis, productionReadiness, productionReviewBasis } from './productionReview.js';
import { CAST_SETS_WORKING } from './castAndSets.js';
import { applyTreatmentPatch, applyTreatmentToProject } from './treatment.js';
import { codeFirstProductionAssets, normalizeMusicVideoProductionPolicy } from '../../lib/musicVideoMediumPlan.js';
import { MUSIC_VIDEO_AUTOMATION_TOOL_IDS } from '../../lib/musicVideoAutomation.js';
/**
* Fully-autonomous Music Video — the run orchestrator.
*
* One prompt drives a whole video: creative brief → lyrics → mood board & style
* → Suno song (PortOS Browser) → beat analysis → the existing production run
* (image/video tools) or a code-rendered video. The vocabulary, brief shape and
* Suno field limits live in `lib/musicVideoAutonomous.js`.
*
* The run is an install-local checkpoint on the project (`project.autonomousRun`,
* wire-local like `productionRuns`: it names this install's providers and the
* peer must never execute it). Each stage settles in one serialized project
* write, so a crash resumes at the stage that did not settle; a stage's output
* is stored before the next one reads it. `processId` pins a running run to the
* server process that started it — after a restart nothing advances until the
* operator (or the scheduled task) explicitly resumes (AI Provider Usage
* Policy: no cold-bootstrap work).
*
* Checkpoints are optional approval gates after `lyrics` / `style` / `song`:
* the run parks `awaiting-approval` and continues on approve; at the song
* checkpoint the director may instead retake the song (`retakeSong`), which
* discards it and generates a new one before parking there again. A signed-out
* Suno parks `needs-human`; any other failure parks `failed`. Both resume at the
* stage that stopped, reusing Suno songs already submitted. A brief may instead
* (or as a fallback, `localFallback`) make the song with the on-device Music
* Designer engines (`autonomousLocalSong.js`), so a run finishes with Suno
* unavailable.
*
* Production is delegated: `produce` starts the server-owned production run (or
* the code render) and finishes when that reports back over the `production`
* event. A code-first production run renders the film itself; when that render
* is still the project's current final video the run adopts it instead of
* rendering the same document again (#10563). Either way `produce` stays
* running ("Rendering final video") until the final render job settles over
* the `render` event: success completes the run, failure parks it `failed` and
* Retry re-renders only. A run interrupted while rendering re-checks
* `renderHistoryId` on resume (reattach, finish, or render again). Only
* explicit start/resume requests begin work.
*
* Production review (art → storyboard → proof) parks `produce` until approved.
* An authenticated start/resume can grant `brief.autoApprove` for planning;
* the route binds the grant to a session and each automatic decision to this run.
* Proof always requires recorded playback or machine review evidence. Older
* briefs granting proof auto-approval still wait for rendering, then park for review.
*
* An ORCHESTRATED run (`brief.orchestrator`) replaces the director at every
* review point instead: the orchestrator model judges the lyrics, the sound and
* look, the song, the art direction, the lyric timing, the storyboard and the
* final video, and either approves each or revises it and judges again
* (bounded by `limits.maxReviewAttempts`, then the last version is accepted).
* It also repairs a failed production pilot and approves the passing pilot as
* the proof from that review's machine evidence (settleBlockedProduction).
* Every decision lands in `run.orchestration.reviews`. It is approval
* authority, so like `autoApprove` it is granted only to a signed-in session.
*/
import { randomUUID } from 'crypto';
import { join } from 'path';
import { PATHS } from '../../lib/fileUtils.js';
import { probeVideoDuration } from '../../lib/ffmpeg.js';
import { ServerError } from '../../lib/errorHandler.js';
import { trimTo } from '../../lib/textUtils.js';
import { getMusicVideoCharacterStyle } from '../../lib/musicVideoCharacterStyles.js';
import { RENDER_TARGET } from '../../lib/renderTargets.js';
import { IMAGE_GEN_MODE } from '../../lib/generationModes.js';
import { assertFootageVideoModelsCapable, loadPoolEnv } from './productionPool.js';
import { PRODUCTION_RESUMABLE_STATUSES, PRODUCTION_TRANSIENT_RETRIES, acceptProductionPilot, productionTargets, transientProductionRetry } from './production.js';
import { currentPilotPass, pilotInputBasis, pilotRepair } from './productionPilot.js';
import {
AUTONOMOUS_DEFAULT_LIMITS,
AUTONOMOUS_LIMIT_BOUNDS,
AUTONOMOUS_LIVE_STATUSES,
AUTONOMOUS_STAGE_IDS,
autonomousLyricsReviewEnabled,
autonomousMedium,
autonomousPool,
isOrchestratedRun,
nextAutonomousStage,
ORCHESTRATOR_REVIEW_LOG_MAX,
normalizeAutoApprove,
normalizeAutonomousBrief,
normalizeLocalMusicOptions,
normalizeSunoOptions,
SUNO_LIMITS,
sunoSongFields,
} from '../../lib/musicVideoAutonomous.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
import { getProject, mutateProjectRecord as mutateRecord } from './projects.js';
import { requireProject } from './requireProject.js';
// `runId` lets the run's repairs land on shots its own approval locked (preserveAutomatedShotLocks).
const mutateProjectRecord = (id, transform, { runId = null } = {}) => mutateRecord(id, transform, { source: 'orchestrator', runId });
import { musicVideoEvents } from './events.js';
import { musicVideoDependencyChanges } from '../../lib/musicVideoDependencies.js';
import { isPerformanceScene, performanceCapability } from '../../lib/musicVideoShotTiming.js';
const PROCESS_ID = `proc-${randomUUID()}`;
const inflight = new Map();
const sunoControllers = new Map();
const short = (id) => String(id).slice(0, 8);
// Lazy imports keep this module's static closure small: it is reached by the
// route table and the scheduled handler, and each dependency below pulls a
// whole subtree (LLM runner, mood board store, browser driver, production).
const defaults = {
createProject: async (input) => (await import('./projects.js')).createProject(input),
updateProject: async (id, patch) => (await import('./projects.js')).updateProject(id, patch),
resolveLlm: async (pin) => (await import('./llmRoute.js')).resolveMusicVideoLlm(pin),
recordRoute: async (projectId, stage, route) => (await import('./llmRoute.js')).recordLlmRoute(projectId, stage, route),
draftCreativeBrief: async (args) => (await import('./autonomousBrief.js')).draftCreativeBrief(args),
writeLyrics: async (args) => (await import('../musicDesigner.js')).writeLyrics(args),
reviewLyrics: async (args) => (await import('../musicDesigner.js')).reviewLyrics(args),
createMoodBoard: async (spec, opts) => (await import('./autonomousBoard.js')).createAutonomousMoodBoard(spec, opts),
generateSunoSong: async (fields, opts) => (await import('./autonomousSuno.js')).generateSunoSong(fields, opts),
generateLocalSong: async (args) => (await import('./autonomousLocalSong.js')).generateLocalSong(args),
cancelLocalSong: async (jobId) => (await import('../mediaJobQueue/index.js')).cancelJob(jobId),
getTrack: async (id) => (await import('../tracks/index.js')).getTrack(id).catch(() => null),
createTrack: async (input) => (await import('../trackAlbumMembership.js')).createTrackWithAlbum(input).then((r) => r.track),
attachAudio: async (trackId, filename, take) => (await import('../trackAudioAttach.js')).attachAudioAsRender(trackId, filename, take),
probeDuration: (filename) => probeVideoDuration(join(PATHS.music, filename)).catch(() => null),
analyzeSong: async (projectId) => (await import('./projectAudio.js')).analyzeProjectSong(projectId),
designCoverArt: async (projectId, input) => (await import('./coverArt.js')).designCoverArt(projectId, input),
startProduction: async (...args) => (await import('./productionService.js')).startProduction(...args),
resumeProduction: async (...args) => (await import('./productionService.js')).resumeProduction(...args),
stopProduction: async (...args) => (await import('./productionService.js')).stopProduction(...args),
cancelProduction: async (...args) => (await import('./productionService.js')).cancelProduction(...args),
generateDocument: async (...args) => (await import('./documentGeneration.js')).generateMixedMediaDocument(...args),
acceptDocument: async (...args) => (await import('./documentGeneration.js')).acceptMixedMediaDocument(...args),
generateCode: async (...args) => (await import('./codeGeneration.js')).generateMusicVideoCode(...args),
renderVideo: async (...args) => (await import('./render.js')).renderMusicVideo(...args),
activeRenderJobId: async (projectId) => (await import('./render.js')).getActiveRenderJobId(projectId),
cancelRender: async (jobId) => (await import('./render.js')).cancelRender(jobId),
// An interrupted (previous process) Cast & Sets stage re-pins to this one; true when it did.
resumeInterruptedCastAndSets: async (project) => {
const { presentProjectCastAndSets, resumeCastAndSets } = await import('./castAndSetsService.js');
if (!presentProjectCastAndSets(project).castAndSets?.interrupted) return false;
await resumeCastAndSets(project.id);
return true;
},
// The review persistence path; session authority was checked on start/resume.
approveProductionReview: async (...args) => (await import('./productionReviewService.js')).approveProductionReview(...args),
// Orchestrated mode: the reviewer call, and the edits a reviewer makes by hand.
orchestrate: async (args) => (await import('./orchestratorReview.js')).askOrchestrator(args),
alignLyrics: async (projectId) => (await import('./lyricAlign.js')).alignProjectLyrics(projectId),
verifyAlignment: async (...args) => (await import('./productionReviewService.js')).reverifyProductionAlignment(...args),
addFeedback: async (...args) => (await import('./productionReviewService.js')).addProductionFeedback(...args),
closeFeedback: async (...args) => (await import('./productionReviewService.js')).closeProductionFeedback(...args),
reviseFromFeedback: async (...args) => (await import('./productionReviewService.js')).reviseProductionFromFeedback(...args),
guideImagePath: async (artifact) => (await import('./devArtifactStore.js')).resolveDevArtifactFile(artifact.file),
// A gallery image (a Cast & Sets plate, a production still) the orchestrator looks at.
// Can this local video model take a shot's song window (an LTX a2v model)?
localVideoTakesSongAudio: async (modelId) => {
const [{ resolveVideoModelSelection }, { supportsSourceAudioWindow }] = await Promise.all([
import('../videoGen/modelSelection.js'), import('../federatedMedia/sourceAudio.js')]);
return supportsSourceAudioWindow((await resolveVideoModelSelection(modelId || undefined)).model);
},
galleryImagePath: async (filename) => (await import('../../lib/pathSafety.js')).resolveGalleryImage(filename),
finalReviewFrames: async (jobId) => (await import('./orchestratorReview.js')).captureFinalReviewFrames(jobId),
// The overlay text pass before a final render: resolves the finished check.
checkOverlayText: async (projectId) => (await import('./overlayTextService.js')).startOverlayTextCheck(projectId).then((started) => started.done),
// The final-video revision of footage: a board-owned auto-review over the flagged window.
startAutoReview: async (...args) => (await import('./autoReviewService.js')).startAutoReview(...args),
cancelAutoReview: async (...args) => (await import('./autoReviewService.js')).cancelAutoReview(...args),
stopAutoReview: async (...args) => (await import('./autoReviewService.js')).stopAutoReview(...args),
resumeAutoReview: async (...args) => (await import('./autoReviewService.js')).resumeAutoReview(...args),
wait: (ms) => new Promise((resolve) => { setTimeout(resolve, ms); }),
};
let deps = { ...defaults };
export function __setAutonomousDepsForTests(overrides) { deps = { ...defaults, ...overrides }; }
const runError = (status, code, message, context) =>
new ServerError(message, { status, code, ...(context ? { context } : {}) });
const projectAutonomousRun = (project) => project?.autonomousRun || null;
const ownsRunningRun = (current, run) => current?.id === run.id && current.status === 'running' && current.processId === PROCESS_ID;
async function requireRun(projectId) {
const project = await requireProject(projectId);
const run = projectAutonomousRun(project);
if (!run) throw runError(404, 'NO_AUTONOMOUS_RUN', 'This project has no autonomous run');
return { project, run };
}
/** The run as the client sees it: `interrupted` when it was pinned to a previous server process. */
export const presentAutonomousRun = (run) => (run
? { ...run, interrupted: run.status === 'running' && run.processId !== PROCESS_ID }
: null);
/** `presentAutonomousRun` for a project read; reader-only — never persist the result. */
export const presentProjectAutonomousRun = (project) => (project?.autonomousRun
? { ...project, autonomousRun: presentAutonomousRun(project.autonomousRun) }
: project);
/** Test seam: this process's pin id. */
export const __autonomousProcessId = () => PROCESS_ID;
function publish(project, run) {
musicVideoEvents.emit('autonomous', { projectId: project.id, runId: run.id, run: presentAutonomousRun(run), project: { ...project, autonomousRun: presentAutonomousRun(run) } });
}
/** One serialized write of the run record; `fn` returns the patch to merge. */
async function patchRun(projectId, fn) {
const now = new Date().toISOString();
const out = await mutateProjectRecord(projectId, (current) => {
const run = projectAutonomousRun(current);
if (!run) throw runError(404, 'NO_AUTONOMOUS_RUN', 'This project has no autonomous run');
const patch = fn(run, current) || {};
const next = {
...run,
...patch,
stages: { ...run.stages, ...(patch.stages || {}) },
output: { ...run.output, ...(patch.output || {}) },
updatedAt: now,
};
return { project: { ...current, autonomousRun: next }, run: next };
});
publish(out.project, out.run);
return out;
}
const stagePatch = (run, stage, patch) => ({ stages: { [stage]: { ...run.stages[stage], ...patch } } });
// ---- production review auto-approval (brief.autoApprove) --------------------------
const RENDER_STEP = 'rendering';
const CAST_STEP = 'cast-and-sets';
const autoApproves = (run, stage) => normalizeAutoApprove(run.brief.autoApprove).includes(stage);
/**
* The brief fields for an auto-approve request: none when it lists no stage,
* else the stages plus when the operator granted them. A non-empty list the
* route did not authorize (authenticated session) is refused.
*/
function autoApproveGrant(list, authorized) {
const autoApprove = normalizeAutoApprove(list);
if (!autoApprove.length) return { autoApprove: [], autoApproveAuthorizedAt: null, autoApproveAuthorizedBy: null };
if (!authorized) throw runError(403, 'AUTH_REQUIRED', 'Sign in to grant automatic planning approvals.');
return { autoApprove, autoApproveAuthorizedAt: new Date().toISOString(),
...(typeof authorized === 'object' ? { autoApproveAuthorizedBy: structuredClone(authorized) } : {}) };
}
/**
* The orchestrator approves Production review stages and verifies lyric timing
* on the operator's behalf, so — like an auto-approve grant — only an
* authenticated session may start an orchestrated run, and the grant records who.
*/
function orchestratorGrant(authorized) {
if (!authorized) throw runError(403, 'AUTH_REQUIRED', 'Sign in to start an orchestrated run: the orchestrator approves stages for you.');
return { orchestratorAuthorizedAt: new Date().toISOString(),
orchestratorAuthorizedBy: typeof authorized === 'object' ? structuredClone(authorized) : null };
}
/** Approve `stage` for the run when the brief allows it and its readiness is clean; returns the fresh project. */
async function autoApproveStage(project, run, stage) {
if (!autoApproves(run, stage)) return project;
const readiness = productionReadiness(project);
if (readiness[stage].approved || readiness[stage].problems.length) return project;
const blocker = stageBlockers(project, run, stage)[0];
if (blocker) {
console.warn(`⚠️ Autonomous music video ${short(run.id)} left the ${stage} unapproved: ${trimTo(blocker, 200)}`);
return project;
}
await deps.approveProductionReview(project.id, { stage, basis: readiness.basis[stage], approvedBy: 'autopilot',
reviewer: { kind: 'autopilot', runId: run.id, authorizedBy: run.brief.autoApproveAuthorizedBy || null } });
console.log(`🤖 Autonomous music video ${short(run.id)} auto-approved ${stage} (brief.autoApprove)`);
return getProject(project.id);
}
// ---- orchestrated mode (brief.orchestrator) --------------------------------------
// The orchestrator stands in for the director at each review point. A review is
// one provider call; a revision is applied and judged again until it approves or
// `limits.maxReviewAttempts` revisions of that checkpoint are spent — then a
// text checkpoint accepts the last version and the log says so, while an art or
// storyboard gate with changes still asked for parks for the director with them
// named. Revisions are counted from the
// persisted log, so a retried stage cannot buy itself a fresh allowance.
const reviewLimit = (run) => run.brief.limits?.maxReviewAttempts || AUTONOMOUS_DEFAULT_LIMITS.maxReviewAttempts;
const latestRun = async (projectId) => projectAutonomousRun(await getProject(projectId));
const revisionsSpent = (run, checkpoint) => (run?.orchestration?.reviews || [])
.filter((r) => r.checkpoint === checkpoint && (r.verdict === 'revise' || r.verdict === 'retake')).length;
const reviewModule = () => import('./orchestratorReview.js');
const ideaOf = (run) => ({ prompt: run.brief.prompt, guidance: run.brief.guidance || '' });
const orchestratorIdentity = (run, route) => ({ kind: 'orchestrator', runId: run.id,
providerId: route?.providerId || run.brief.orchestrator.providerId, model: route?.model || run.brief.orchestrator.model || null,
authorizedBy: run.brief.orchestratorAuthorizedBy || null });
// Who acts on the run's own change requests: its orchestrator, else the autopilot.
const runReviewer = (run) => (isOrchestratedRun(run) ? orchestratorIdentity(run)
: { kind: 'autopilot', runId: run.id, authorizedBy: run.brief.autoApproveAuthorizedBy || null });
/**
* Append one decision to the run's review log (oldest dropped past the cap).
* `output` lands in the same write, so a revision is never logged without the
* revised value a retry resumes from.
*/
async function recordReview(projectId, entry, output) {
const at = new Date().toISOString();
const { run } = await patchRun(projectId, (r) => ({ ...(output ? { output } : {}), orchestration: { ...r.orchestration,
reviews: [...(r.orchestration?.reviews || []), { id: randomUUID(), at, ...entry }].slice(-ORCHESTRATOR_REVIEW_LOG_MAX) } }));
console.log(`🎬 Autonomous music video ${short(run.id)} orchestrator ${entry.verdict} ${entry.checkpoint}${entry.score ? ` (${entry.score}/10)` : ''}`);
return run;
}
/** One review call, parsed. `images` ride along when the orchestrator can see them. */
async function askReview(run, checkpoint, prompt, images = []) {
const { parseOrchestratorVerdict } = await reviewModule();
const reply = await deps.orchestrate({ orchestrator: run.brief.orchestrator, prompt, images, source: 'music-video-orchestrator-review' });
return { ...parseOrchestratorVerdict(reply.text, checkpoint), route: reply.route || null, visual: reply.visual === true };
}
const reviewEntry = (checkpoint, review, overrides = {}) => ({
checkpoint, verdict: review.verdict, score: review.score ?? null, notes: review.notes || '',
route: review.route || null, visual: review.visual === true, ...overrides,
});
/**
* Review a text checkpoint until it is approved: `apply(review)` returns the
* revised value, or null when the review carried nothing to apply. `persist(value)`
* names the run output that holds the value under review, written with each
* revision so a retry judges the latest one. Returns the accepted value.
*/
async function reviewUntilApproved(projectId, run, checkpoint, { value, prompt, apply, persist }) {
let current = value;
for (;;) {
const review = await askReview(run, checkpoint, prompt(current));
const revised = review.verdict === 'revise' ? apply(review, current) : null;
if (revised !== null && revisionsSpent(await latestRun(projectId), checkpoint) < reviewLimit(run)) {
await recordReview(projectId, reviewEntry(checkpoint, review, { verdict: 'revise' }), persist(revised));
current = revised;
continue;
}
const why = review.verdict !== 'revise' ? '' : revised === null ? 'No revision was supplied; accepted as is. ' : 'Revision limit reached; accepted the latest version. ';
await recordReview(projectId, reviewEntry(checkpoint, review, { verdict: 'approve', notes: `${why}${review.notes || ''}`.trim() }));
return current;
}
}
async function orchestrateLyrics(projectId, run, lyrics) {
const { buildLyricsReviewPrompt } = await reviewModule();
return reviewUntilApproved(projectId, run, 'lyrics', {
value: lyrics,
prompt: (current) => buildLyricsReviewPrompt({ ...ideaOf(run), title: run.output.title, description: run.output.musicalDescription, lyrics: current }),
apply: (review) => review.lyrics || null,
persist: (revised) => ({ lyricsForReview: revised }),
});
}
/** The sound & look, judged before the song is made and the mood board created from it. */
async function orchestrateStyle(projectId, run) {
const { buildStyleReviewPrompt } = await reviewModule();
// A retried review resumes from the last revision rather than the first draft.
const value = run.output.styleDraft || { sunoStyle: run.output.sunoStyle, concept: run.output.concept || {}, moodBoard: run.output.moodBoard || {} };
return reviewUntilApproved(projectId, run, 'style', {
value,
prompt: (current) => buildStyleReviewPrompt({ ...ideaOf(run), title: run.output.title, description: run.output.musicalDescription, ...current }),
apply: (review, current) => (review.sunoStyle || review.conceptStyle || review.lookPrompt ? {
sunoStyle: review.sunoStyle || current.sunoStyle,
concept: { ...current.concept, ...(review.conceptStyle ? { style: review.conceptStyle } : {}) },
moodBoard: { ...current.moodBoard, ...(review.lookPrompt ? { stylePrompt: review.lookPrompt } : {}) },
} : null),
persist: (revised) => ({ styleDraft: revised }),
});
}
const cueText = (cue) => (typeof cue?.text === 'string' ? cue.text.trim() : '');
const validSpan = (start, end) => Number.isFinite(start) && Number.isFinite(end) && end > start;
const MIN_WORD_SEC = 0.05;
// Below this share of recognizer-heard words the timings are mostly interpolated
// (the aligner itself discards a line below the same share).
const MIN_HEARD_WORD_SHARE = 0.5;
/**
* Give a lyric line with no usable word timings evenly spaced words inside its
* own span, else a share of the gap its neighbours leave — what a director does
* by hand after alignment skips a line. Consecutive skipped lines split that gap
* by word count rather than each taking all of it. Returns the repaired cues
* and the line count.
*/
function repairLyricWordTimings(cues, durationSec) {
const wordsOf = cues.map((cue) => cueText(cue).split(/\s+/).filter(Boolean));
const usable = (cue) => Array.isArray(cue.words) && cue.words.length > 0 && cue.words.every((w) => validSpan(w.startSec, w.endSec))
&& validSpan(cue.startSec, cue.endSec) && cue.words.every((w) => w.startSec >= cue.startSec && w.endSec <= cue.endSec);
const ownSpan = (cue) => validSpan(cue.startSec, cue.endSec) && cue.endSec <= durationSec;
const needs = cues.map((cue, i) => wordsOf[i].length > 0 && !usable(cue));
const spans = cues.map(() => null);
for (let i = 0; i < cues.length; i += 1) {
if (!needs[i]) continue;
if (ownSpan(cues[i])) { spans[i] = [cues[i].startSec, cues[i].endSec]; continue; }
let last = i;
while (last + 1 < cues.length && needs[last + 1] && !ownSpan(cues[last + 1])) last += 1;
const prevEnd = i > 0 && Number.isFinite(cues[i - 1].endSec) ? cues[i - 1].endSec : 0;
const nextStart = last < cues.length - 1 && Number.isFinite(cues[last + 1].startSec) ? cues[last + 1].startSec : durationSec;
const total = wordsOf.slice(i, last + 1).reduce((sum, words) => sum + words.length, 0);
let at = prevEnd;
for (let k = i; k <= last; k += 1) {
const end = k === last ? nextStart : at + ((nextStart - prevEnd) * wordsOf[k].length) / total;
spans[k] = [at, end];
at = end;
}
i = last;
}
let repaired = 0;
const round = (n) => Math.round(n * 1000) / 1000;
const out = cues.map((cue, i) => {
if (!spans[i]) return cue;
const words = wordsOf[i];
const [start, end] = spans[i];
if (!validSpan(start, end) || (end - start) / words.length < MIN_WORD_SEC) return cue;
const step = (end - start) / words.length;
repaired += 1;
return { ...cue, startSec: round(start), endSec: round(end),
words: words.map((w, k) => ({ w, startSec: round(start + k * step), endSec: round(k === words.length - 1 ? end : start + (k + 1) * step), conf: 'interpolated' })) };
});
return { cues: out, repaired };
}
/**
* Align the vocal to the lyric sheet and time the lines alignment skipped —
* the timings the storyboard gate needs. Returns the alignment error, if any,
* and keeps it on the run (`output.alignmentError`) so the storyboard gate
* will not verify guessed timings; the repair still runs so a failed
* alignment leaves what it can.
*/
async function alignRunLyrics(projectId, run) {
if (run.brief.instrumental || !(await getProject(projectId))?.lyricCues?.some((c) => cueText(c))) return null;
let alignError = null;
await deps.alignLyrics(projectId).catch((err) => { alignError = err.message; });
await mutateProjectRecord(projectId, (current) => {
const { cues, repaired } = repairLyricWordTimings(current.lyricCues || [], current.audioAnalysis?.durationSec);
return { project: repaired ? { ...current, lyricCues: cues } : current };
});
// Bound to the timings it left, so a later re-alignment by hand is judged on its own.
const basis = alignError ? productionAlignmentBasis(await getProject(projectId)) : null;
await patchRun(projectId, () => ({ output: { alignmentError: alignError ? { message: trimTo(alignError, 300), basis } : null } }));
return alignError;
}
/** The song as measurements: analysis plus how much of the written lyric the recognizer heard. */
function songFacts(project, run, alignError) {
const analysis = project.audioAnalysis || {};
const cues = (project.lyricCues || []).filter((c) => cueText(c));
const words = cues.flatMap((c) => c.words || []);
return {
instrumental: run.brief.instrumental === true,
songSource: run.output.songSource || run.brief.songSource,
durationSec: Number.isFinite(analysis.durationSec) ? Math.round(analysis.durationSec * 10) / 10 : null,
tempoBpm: Number.isFinite(analysis.bpm) ? Math.round(analysis.bpm) : Number.isFinite(analysis.tempo) ? Math.round(analysis.tempo) : null,
sections: (analysis.sections || []).slice(0, 24).map((s) => s.label || s.type || 'section'),
...(run.brief.instrumental ? {} : {
lyricLines: cues.length,
linesWithWordTimings: cues.filter((c) => c.words?.length).length,
lyricWords: words.length,
recognizedWordShare: words.length ? Math.round((words.filter((w) => w.conf === 'matched').length / words.length) * 100) / 100 : null,
...(alignError ? { alignmentError: trimTo(alignError, 300) } : {}),
}),
};
}
/**
* The song checkpoint, at the end of analysis: align the vocal to the lyric
* sheet (the timings the storyboard needs anyway), fill lines alignment
* skipped, then judge the song from those measurements. A retake is taken only
* for a local song (free) with revisions left; a Suno retake would spend
* credits the operator did not approve, so that song is kept and the reason logged.
*/
async function orchestrateSong(projectId, run) {
const alignError = await alignRunLyrics(projectId, run);
const { buildSongReviewPrompt } = await reviewModule();
const project = await getProject(projectId);
const facts = songFacts(project, run, alignError);
const review = await askReview(run, 'song', buildSongReviewPrompt({ ...ideaOf(run), title: run.output.title, facts }));
if (review.verdict === 'retake') {
const local = facts.songSource === 'local';
const left = revisionsSpent(await latestRun(projectId), 'song') < reviewLimit(run);
if (local && left) {
await recordReview(projectId, reviewEntry('song', review, { facts }));
return { retake: true };
}
const why = local ? 'Retake limit reached; kept this song.' : 'Kept: retaking a Suno song spends credits.';
await recordReview(projectId, reviewEntry('song', review, { verdict: 'approve', facts, notes: `${why} ${review.notes || ''}`.trim() }));
return { retake: false };
}
await recordReview(projectId, reviewEntry('song', review, { facts }));
return { retake: false };
}
/**
* Verify the lyric timing for the storyboard gate. Alignment already ran after
* analysis; this records the check of it as the verification a director gives
* by listening — by the orchestrator, or by an autopilot the operator granted
* storyboard approval. It verifies only when every line has bounded word
* timings, alignment ran without error and the recognizer heard at least
* `MIN_HEARD_WORD_SHARE` of the words; otherwise the timings are mostly
* guesses, so it returns why and leaves them for a director. An instrumental
* is marked as one.
*/
async function settleLyricTiming(projectId, run) {
const orchestrated = isOrchestratedRun(run);
const record = (verdict, notes) => (orchestrated
? recordReview(projectId, { checkpoint: 'alignment', verdict, score: null, notes, route: null, visual: false }) : null);
const project = await getProject(projectId);
const draft = project.productionReview?.draft;
if (!draft || draft.storyboardSource === 'document') return;
const status = productionReadiness(project).alignment.status;
if (status === 'verified' || status === 'instrumental') return;
const reviewer = runReviewer(run);
// A reused song's timing a director already verified on its source project, untouched since.
const reusedBasis = run.brief.songFrom?.verifiedAlignmentBasis;
if (reusedBasis && reusedBasis === productionAlignmentBasis(project)) {
const notes = 'Lyric timing carried over unchanged from the source project, where it was verified.';
await deps.verifyAlignment(projectId, { basis: reusedBasis, notes, reviewer });
await record('approve', notes);
return;
}
const cues = (project.lyricCues || []).filter((c) => cueText(c));
if (!cues.length) {
if (!run.brief.instrumental) return;
await mutateProjectRecord(projectId, (current) => ({ project: { ...current, productionReview: { ...current.productionReview,
draft: { ...current.productionReview.draft, lyricsMode: 'instrumental', timingNotes: 'Instrumental song: no lyric timing to verify.' } } } }));
await record('approve', 'Instrumental song: no lyric timing to verify.');
return;
}
const words = cues.flatMap((c) => c.words || []);
const timed = cues.filter((c) => c.words?.length && validSpan(c.startSec, c.endSec)).length;
const matched = words.filter((w) => w.conf === 'matched').length;
const notes = `Checked by the ${orchestrated ? 'orchestrator' : 'autopilot'}: ${timed} of ${cues.length} lines carry word timings; ${matched} of ${words.length} words were heard by the recognizer, the rest interpolated.`;
const failedAlignment = projectAutonomousRun(project)?.output?.alignmentError;
const alignmentError = failedAlignment?.basis === productionAlignmentBasis(project) ? failedAlignment.message : null;
const held = timed < cues.length ? 'Lines without timings need a director.'
: alignmentError ? `Lyric alignment failed (${alignmentError}), so these timings are guesses; a director needs to listen and verify them.`
: matched / words.length < MIN_HEARD_WORD_SHARE ? 'Too little of the vocal was heard to trust these timings; a director needs to listen and verify them.'
: null;
if (held) {
await record('revise', `${notes} ${held}`);
return `${notes} ${held}`;
}
await deps.verifyAlignment(projectId, { basis: productionAlignmentBasis(project), notes, reviewer });
await record('approve', notes);
}
/** Anchor every storyboard shot to the lyric lines it overlaps (the "Review lyric anchors" chore). */
async function anchorStoryboardLyrics(projectId) {
await mutateProjectRecord(projectId, (current) => {
const draft = current.productionReview?.draft;
if (!draft?.storyboard?.length || draft.storyboardSource === 'document') return { project: current };
const cues = (current.lyricCues || []).filter((c) => cueText(c));
let changed = false;
const storyboard = draft.storyboard.map((shot) => {
const scene = current.scenes?.find((s) => s.sceneId === shot.sceneId);
if (!scene) return shot;
const ids = cues.filter((c) => c.startSec < scene.endSec && c.endSec > scene.startSec).map((c) => c.id);
if (ids.length === (shot.lyricCueIds || []).length && ids.every((id) => shot.lyricCueIds.includes(id))) return shot;
changed = true;
return { ...shot, lyricCueIds: ids };
});
return { project: changed ? { ...current, productionReview: { ...current.productionReview, draft: { ...draft, storyboard } } } : current };
});
}
const STORYBOARD_FIELDS = ['action', 'staging', 'camera', 'transition'];
const blankShotFields = (shot) => STORYBOARD_FIELDS.filter((key) => !(typeof shot?.[key] === 'string' && shot[key].trim()));
// What a director types into a blank storyboard field when the orchestrator left it empty.
const STORYBOARD_FIELD_DEFAULT = Object.freeze({ staging: 'Medium shot', camera: 'Locked-off camera', transition: 'Cut' });
/** Fill blank storyboard fields from the review's `fill`, then plain defaults. */
async function fillStoryboard(projectId, fill = []) {
await mutateProjectRecord(projectId, (current) => {
const draft = current.productionReview?.draft;
if (!draft?.storyboard?.length || draft.storyboardSource === 'document') return { project: current };
let changed = false;
const storyboard = draft.storyboard.map((shot) => {
const blank = blankShotFields(shot);
if (!blank.length) return shot;
const scene = current.scenes?.find((s) => s.sceneId === shot.sceneId);
const given = fill.find((f) => f.sceneId === shot.sceneId) || {};
changed = true;
return { ...shot, ...Object.fromEntries(blank.map((key) => [key,
given[key] || (key === 'action' ? scene?.visualIntent || scene?.prompt || scene?.label || 'Hold on the subject' : STORYBOARD_FIELD_DEFAULT[key])])) };
});
return { project: changed ? { ...current, productionReview: { ...current.productionReview, draft: { ...draft, storyboard } } } : current };
});
}
const ART_REVIEW_PLATES = 6;
/** The Cast & Sets renders the art review looks at: the character sheet first, then the plates in plan order. */
async function castAndSetsImagePaths(project) {
const stage = project.castAndSets || {};
const keys = Object.keys(stage.images || {}).filter((key) => stage.images[key]?.status === 'done' && stage.images[key].imageId)
.sort((a, b) => Number(stage.plan?.[b]?.kind === 'character') - Number(stage.plan?.[a]?.kind === 'character'));
const paths = [];
for (const key of keys) {
if (paths.length >= ART_REVIEW_PLATES) break;
const path = await deps.galleryImagePath(stage.images[key].imageId).catch(() => null);
if (path) paths.push(path);
}
return paths;
}
async function reviewArt(run, project) {
const { buildArtReviewPrompt } = await reviewModule();
const draft = project.productionReview?.draft || {};
const guide = project.devArtifacts?.find((a) => a.id === draft.guideArtifactId && !a.deleted);
const image = guide?.mimeType?.startsWith('image/') ? await deps.guideImagePath(guide).catch(() => null) : null;
const images = [...(image ? [image] : []), ...await castAndSetsImagePaths(project)];
// The sheet and plates are not redrawn after a text revision, so a re-review is told they show the earlier text.
const sheetPredatesEdits = images.length > 0 && revisionsSpent(await latestRun(project.id), 'art') > 0;
return askReview(run, 'art', buildArtReviewPrompt({ ...ideaOf(run), concept: project.concept, draft, hasImage: images.length > 0, sheetPredatesEdits }), images);
}
async function reviewStoryboard(run, project) {
const { buildStoryboardReviewPrompt } = await reviewModule();
const draft = project.productionReview?.draft || {};
const cues = project.lyricCues || [];
const shots = (draft.storyboard || []).slice(0, 120).map((shot) => {
const scene = project.scenes?.find((s) => s.sceneId === shot.sceneId) || {};
return { sceneId: shot.sceneId, startSec: scene.startSec ?? null, endSec: scene.endSec ?? null,
lyrics: (shot.lyricCueIds || []).map((id) => cueText(cues.find((c) => c.id === id))).filter(Boolean).join(' / '),
...Object.fromEntries(STORYBOARD_FIELDS.map((key) => [key, trimTo(shot[key], 400)])) };
});
const incomplete = (draft.storyboard || []).filter((shot) => blankShotFields(shot).length).map((shot) => shot.sceneId);
return askReview(run, 'storyboard', buildStoryboardReviewPrompt({ ...ideaOf(run), concept: project.concept, shots, incomplete }));
}
async function fileReviseAndClose(projectId, { requests, revise, resolutionFor, reviewer }) {
const feedbackIds = [];
for (const request of requests) {
const { feedbackId } = await deps.addFeedback(projectId, request);
feedbackIds.push(feedbackId);
}
const failure = await revise().then(() => null, (err) => err);
for (const feedbackId of feedbackIds) {
try {
await deps.closeFeedback(projectId, { feedbackId, resolution: resolutionFor(failure), reviewer });
} catch (err) {
// Only tolerate a reviewer resolving this run's request while revision was in flight.
const entry = err.code === 'MUSIC_VIDEO_FEEDBACK_CLOSED'
? (await getProject(projectId)).productionReview?.feedback?.find((item) => item.id === feedbackId) : null;
if (!entry?.resolvedAt) throw err;
console.warn(`🎬 Autonomous feedback ${feedbackId} was already resolved; preserving its resolution`);
}
}
return failure;
}
/**
* Apply a revise verdict to a production stage; returns false when nothing could
* be applied. A storyboard re-plan that fails throws, so the stage fails and a
* Retry asks again rather than approving shots the orchestrator asked to change.
*/
async function applyProductionRevision(projectId, run, stage, review) {
if (stage === 'art') {
if (!review.changes.length) return false;
await mutateProjectRecord(projectId, (current) => ({ project: { ...current, productionReview: { ...current.productionReview,
draft: { ...current.productionReview?.draft, ...Object.fromEntries(review.changes.map((c) => [c.field, c.text])) } } } }));
return true;
}
const project = await getProject(projectId);
const known = new Set((project.productionReview?.draft?.storyboard || []).map((shot) => shot.sceneId));
const changes = review.changes.filter((c) => known.has(c.sceneId));
if (!changes.length || project.productionReview?.draft?.storyboardSource === 'document') return false;
const basis = productionReviewBasis(project).storyboard;
const { route, ...plan } = await llmOf(run, 'plan');
const failure = await fileReviseAndClose(projectId, {
requests: changes.map((change) => ({ stage, basis, target: change.sceneId, text: change.text, decision: 'request-changes' })),
revise: () => deps.reviseFromFeedback(projectId, { stage, ...plan }),
resolutionFor: (error) => error ? `The re-plan failed (${trimTo(error.message, 200)}); the orchestrator will ask again on Retry.` : 'Revised by the orchestrator.',
reviewer: orchestratorIdentity(run, review.route),
});
if (failure) {
throw runError(502, 'ORCHESTRATOR_REVISION_FAILED', `The storyboard re-plan failed: ${trimTo(failure.message, 200)}`);
}
return true;
}
/**
* Clear one Production review gate (art or storyboard) as the director would:
* review, revise and review again, then approve the current revision. A
* readiness problem the orchestrator cannot fix leaves the gate closed, and
* the run parks for a human with that problem named.
*/
async function orchestrateProductionStage(project, run, stage) {
for (;;) {
const ready = productionReadiness(project);
if (ready[stage].approved || (stage === 'storyboard' && !ready.art.approved)) return project;
if (stage === 'storyboard') await anchorStoryboardLyrics(project.id);
const review = stage === 'art' ? await reviewArt(run, await getProject(project.id)) : await reviewStoryboard(run, await getProject(project.id));
if (stage === 'storyboard') await fillStoryboard(project.id, review.fill);
const spent = revisionsSpent(await latestRun(project.id), stage);
if (review.verdict === 'revise' && spent < reviewLimit(run) && await applyProductionRevision(project.id, run, stage, review)) {
await recordReview(project.id, reviewEntry(stage, review, { changes: review.changes.map((c) => trimTo(`${c.field || c.sceneId}: ${c.text}`, 300)) }));
project = await getProject(project.id);
continue;
}
project = await getProject(project.id);
// Out of revisions with changes still asked for: the director decides, never a silent approval.
if (review.verdict === 'revise' && spent >= reviewLimit(run) && review.changes.length) {
const open = review.changes.map((c) => `${c.field || c.sceneId}: ${c.text}`);
await recordReview(project.id, reviewEntry(stage, review, { verdict: 'revise',
notes: `Revision limit reached; left for the director. ${review.notes || ''}`.trim(), changes: open.map((line) => trimTo(line, 300)) }));
throw runError(409, 'MUSIC_VIDEO_APPROVAL_REQUIRED', trimTo(`The orchestrator still wants changes to the ${stage} after ${spent} revision${spent === 1 ? '' : 's'}: ${open.join(' · ')} Approve the ${stage} yourself, or resume with more revisions per step.`, 500));
}
const readiness = productionReadiness(project);
const why = review.verdict === 'revise' ? 'Nothing to revise was supplied; accepted as is. ' : '';
const problem = readiness[stage].problems[0] || stageBlockers(project, run, stage)[0];
if (problem) {
await recordReview(project.id, reviewEntry(stage, review, { verdict: 'revise', notes: `Could not approve: ${trimTo(problem, 300)} ${review.notes || ''}`.trim() }));
return project;
}
await deps.approveProductionReview(project.id, { stage, basis: readiness.basis[stage], approvedBy: 'orchestrator', reviewer: orchestratorIdentity(run, review.route) });
await recordReview(project.id, reviewEntry(stage, review, { verdict: 'approve', notes: `${why}${review.notes || ''}`.trim() }));
return getProject(project.id);
}
}
/** The brief's prompt and guidance as production's planning directive. */
const briefDirective = (brief) => trimTo([brief.prompt, brief.guidance].filter(Boolean).join('\n\n'), 4000);
/** The run renders its film from code alone rather than through production. */
const rendersFromCode = (project, run) => musicVideoMediaMode(project) === 'code-only' || autonomousMedium(run.brief.tools) === 'code';
/**
* What would stop production of an approved storyboard: the code-first plan's
* medium conflicts. Approving over them only moves the failure to
* production, so a run that approves for the director leaves the gate closed.
*/
const stageBlockers = (project, run, stage) => (stage === 'storyboard' && !rendersFromCode(project, run)
? codeFirstProductionAssets(project)?.conflicts || [] : []);
/**
* A performance direction planned without footage (no video tool, or no
* generated-video allowance left) blocks production until the plan is revised.
* A run that approves the storyboard itself makes that revision as the
* conflict asks: those shots become cutaways, and the plan is applied again.
* Any other conflict is left for stageBlockers to name.
*/
async function reviseUnfilmablePerformances(project, run) {
const ready = productionReadiness(project);
if (ready.storyboard.approved || !ready.art.approved || !(isOrchestratedRun(run) || autoApproves(run, 'storyboard'))) return project;
if (!stageBlockers(project, run, 'storyboard').length) return project;
const sceneIds = (project.treatment?.shotDirections || [])
.filter((d) => d.mode === 'performance' && !['existing-footage', 'generated-footage'].includes(d.medium)).map((d) => d.sceneId);
if (!sceneIds.length) return project;
const rationale = 'No footage is planned for this shot, so it is staged as a cutaway rather than a visible performance.';
const revised = await mutateProjectRecord(project.id, (current) => {
const patched = applyTreatmentPatch(current, { baseRevision: current.treatment?.revision ?? 0,
shotDirections: sceneIds.map((sceneId) => ({ sceneId, mode: 'cutaway', rationale })) });
return applyTreatmentToProject(patched, { revision: patched.treatment.revision });
}).then(({ project: next }) => next, (err) => {
console.warn(`⚠️ Autonomous music video ${short(run.id)} could not re-plan ${sceneIds.length} performance shot(s): ${err.message}`);
return null;
});
if (!revised) return project;
const note = `Re-planned ${sceneIds.length} performance shot${sceneIds.length === 1 ? '' : 's'} as cutaways: no footage is planned for them.`;
if (isOrchestratedRun(run)) await recordReview(project.id, { checkpoint: 'storyboard', verdict: 'revise', notes: note });
console.log(`🎬 Autonomous music video ${short(run.id)}: ${note}`);
return revised;
}
/** Art and storyboard: the orchestrator when the run has one, else the operator's auto-approve grant. */
const settleProductionStage = async (project, run, stage) => {
if (stage === 'storyboard') project = await reviseUnfilmablePerformances(project, run);
return isOrchestratedRun(run) ? orchestrateProductionStage(project, run, stage) : autoApproveStage(project, run, stage);
};
/**
* Watch the finished film and send flagged sections back, as a director would:
* a `revise` verdict with timecoded issues starts one revision (startFinalRevision)
* while revisions remain; anything else is logged and the film is kept. Returns
* 'rerender' (re-authored: render the film again), 'wait' (a footage revision
* is under way) or null (keep this film).
*/
async function orchestrateFinal(projectId, run) {
const project = await getProject(projectId);
const frames = await deps.finalReviewFrames(run.output.renderJobId).catch((err) => ({ images: [], frameTimes: [], facts: { error: err.message }, cleanup: async () => {} }));
let review;
try {
const { buildFinalReviewPrompt } = await reviewModule();
review = await askReview(run, 'final', buildFinalReviewPrompt({ ...ideaOf(run), concept: project?.concept, facts: frames.facts, frameTimes: frames.frameTimes }), frames.images);
} catch (err) {
await recordReview(projectId, { checkpoint: 'final', verdict: 'noted', score: null, notes: `The final review could not run: ${trimTo(err.message, 300)}`, route: null, visual: false });
return null;
} finally {
await frames.cleanup?.().catch(() => {});
}
const issues = review.issues || [];
const blind = frames.images.length ? '' : `Judged without frames (${frames.facts?.error || 'none could be captured'}). `;
const keep = (why = '') => recordReview(projectId, reviewEntry('final', review, { verdict: review.verdict === 'approve' ? 'approve' : 'noted', issues,
notes: `${blind}${why}${review.notes || ''}`.trim() }));
if (review.verdict !== 'revise' || !issues.length) return keep(review.verdict === 'revise' ? 'No timecoded issue to revise; kept this film. ' : '').then(() => null);
if (revisionsSpent(await latestRun(projectId), 'final') >= reviewLimit(run)) return keep('Revision limit reached; kept the latest film. ').then(() => null);
let next;
try {
next = await startFinalRevision(projectId, run, issues);
} catch (err) {
await keep(`The revision did not go through (${trimTo(err.message, 200)}); kept this film. `);
return null;
}
await recordReview(projectId, reviewEntry('final', review, { issues, notes: `${blind}${review.notes || ''}`.trim() }));
return next;
}
const FINAL_REVISION_STEP = 'final-revision';
const timecode = (sec) => `${Math.floor(sec / 60)}:${String(Math.floor(sec % 60)).padStart(2, '0')}`;
/** The scenes the issues fall in, as one window (the auto-review's range). */
function issueWindow(project, issues) {
const scenes = (project.scenes || []).filter((scene) => issues.some((issue) => issue.atSec >= scene.startSec && issue.atSec < scene.endSec));
if (!scenes.length) return null;
return { startSec: Math.min(...scenes.map((s) => s.startSec)), endSec: Math.max(...scenes.map((s) => s.endSec)) };
}
/**
* Send the flagged sections back. A code or document composition is
* re-authored with the issues as change requests on the film (the authoring
* prompt carries open requests), then rendered again. Footage gets a
* board-owned auto-review over the scenes the issues fall in, judged by the
* orchestrator and limited to the generations production left unspent; the
* film is rendered again when it ends (onAutoReviewEvent). Throws when no
* revision can start.
*/
async function startFinalRevision(projectId, run, issues) {
const project = await getProject(projectId);
const code = rendersFromCode(project, run);
await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'running', step: FINAL_REVISION_STEP }));
if (code) return reauthorFinal(projectId, run, issues).then(() => 'rerender');
const window = issueWindow(project, issues);
if (!window) throw runError(409, 'NO_FLAGGED_SCENE', 'No scene covers the flagged times');
const production = (project.productionRuns || []).find((r) => r.id === run.output.productionRunId);
// A dollar cap is production's to enforce; a board revision cannot, so it is not spent past it.
if (production?.limits?.spendCapUsd != null) throw runError(409, 'FINAL_REVISION_BUDGET', 'a dollar budget is set, which a board revision cannot enforce');
const left = production ? Math.max(0, production.limits.maxGenerations - (production.usage?.generations || 0)) : 0;
if (!left) throw runError(409, 'FINAL_REVISION_BUDGET', 'production spent its generations');
const { run: review } = await deps.startAutoReview(projectId, { ...window, limits: { maxAttempts: 2, maxGenerations: Math.min(left, 100) },
reviewer: { providerId: run.brief.orchestrator.providerId, model: run.brief.orchestrator.model || null } });
await patchRun(projectId, () => ({ output: { finalAutoReviewId: review.id } }));
console.log(`🎬 Autonomous music video ${short(run.id)} sent ${timecode(window.startSec)}-${timecode(window.endSec)} back for revision`);
return 'wait';
}
async function reauthorFinal(projectId, run, issues, { target = 'final' } = {}) {
const project = await getProject(projectId);
const basis = productionReviewBasis(project).proof;
const authoring = !run.brief.llmStages?.authoring && run.brief.authoring ? run.brief.authoring : await llmOf(run, 'authoring');
const input = { providerId: authoring.providerId, model: authoring.model || undefined, ...(authoring.effort ? { effort: authoring.effort } : {}) };
const failure = await fileReviseAndClose(projectId, {
requests: issues.slice(0, 12).map((issue) => ({ stage: 'proof', basis, target: `${target}@${timecode(issue.atSec)}`, text: issue.text, decision: 'request-changes' })),
revise: async () => {
if ((await getProject(projectId)).composition?.mode === 'code') return deps.generateCode(projectId, input);
const candidate = await deps.generateDocument(projectId, input);
return deps.acceptDocument(projectId, candidate.document.directory);
},
resolutionFor: (error) => error ? `The re-authoring failed (${trimTo(error.message, 200)}); kept the film.`
: `Re-authored by the ${isOrchestratedRun(run) ? 'orchestrator' : 'autopilot'}.`,
reviewer: runReviewer(run),
});
if (failure) throw failure;
}
const TEXT_CHECK_STEP = 'text-check';
const TEXT_CHECKPOINT = 'text';
const textEntry = (verdict, notes, issues = []) => ({ checkpoint: TEXT_CHECKPOINT, verdict, score: null, notes, issues, route: null, visual: false });
/**
* The overlay text pass before the film renders (overlayTextService.js): check
* the composition document's text where it appears; when the run's own
* generated document collides, runs off frame, blends in or is too small,
* send the findings back to its author and check again, bounded by the run's
* review attempts. A hand-made document is never rewritten (its findings are
* logged for the director), and a check that cannot run never holds the
* render. Returns false when the run stopped meanwhile.
*/
async function settleOverlayText(projectId, run) {
for (;;) {
const project = await getProject(projectId);
if (project?.composition?.mode !== 'document' || !project.composition.document?.directory) return true;
await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'running', step: TEXT_CHECK_STEP }));
const check = await deps.checkOverlayText(projectId).catch((err) => ({ status: 'failed', error: err.message }));
if ((await latestRun(projectId))?.status !== 'running') return false;
if (check?.status !== 'complete') {
await recordReview(projectId, textEntry('noted', `The overlay text check could not run (${trimTo(check?.error || 'it was replaced by a newer check', 200)}); rendering anyway.`));
return true;
}
const findings = check.findings || [];
if (!findings.length) {
await recordReview(projectId, textEntry('approve', `No overlay text problems in ${check.textSamples ?? 0} frames with text.`));
return true;
}
const issues = findings.slice(0, 12).map((f) => ({ atSec: f.atSec, text: trimTo(f.message, 300) }));
const generated = project.composition.document.source?.kind === 'generated';
if (!generated || revisionsSpent(await latestRun(projectId), TEXT_CHECKPOINT) >= reviewLimit(run)) {
await recordReview(projectId, textEntry('noted', generated ? 'Revision limit reached; rendering the latest document.' : 'This document was made by hand, so it is left for the director to fix; rendering it as is.', issues));
return true;
}
try {
await reauthorFinal(projectId, run, issues, { target: 'text' });
} catch (err) {
await recordReview(projectId, textEntry('noted', `The re-authoring did not go through (${trimTo(err.message, 200)}); rendering the current document.`, issues));
return true;
}
await recordReview(projectId, textEntry('revise', `Sent ${issues.length} overlay text problem${issues.length === 1 ? '' : 's'} back to the document's author.`, issues));
}
}
// ---- stage executors -------------------------------------------------------------
// Each returns `{ output }` (merged into run.output) or `{ output, wait: true }`
// when the stage's completion arrives later (production).
/**
* The LLM for one of a run's stages, resolved each time the stage runs: the
* run's pin for that stage (`brief.llmStages[stage]`), else — for `authoring` —
* its code-authoring pin, else its direction pin (`brief.llm`), else an
* eligible TUI provider, else the active one (llmRoute.js). The resolved route
* rides along (`route`) so the stage can record it on the run; a failed
* registry read degrades to the plain pin rather than failing the stage.
*/
async function llmOf(run, stage) {
const { llm, llmStages, authoring } = run.brief;
const own = llmStages?.[stage] || (stage === 'authoring' && authoring) || llm;
const pin = { providerId: own?.providerId, model: own?.model || undefined, effort: own?.effort || undefined };
const resolved = await deps.resolveLlm({
stage,
automation: { llm: llm || null, llmStages: llmStages || null },
...(stage === 'authoring' && authoring ? { authoring } : {}),
}).catch((err) => {
console.warn(`⚠️ Autonomous music video: LLM route resolution failed: ${err.message}`);
return null;
});
const route = resolved?.route;
if (!route) return { ...pin, route: null };
return { providerId: route.providerId, model: route.model || undefined, effort: route.effort || undefined, route };
}
/** Keep the route a text stage ran on in the project's brief too (best-effort, never fails the stage). */
const recordRoute = (project, stage, route) => (route ? deps.recordRoute(project.id, stage, route).catch(() => null) : null);
/**
* The local song source: the track is created first (its id is stored at once),
* the render is queued onto it, and the stage settles once the audio has landed.
* A retry rejoins the stored render instead of queuing a second one.
*/
async function localSong({ project, run, save }) {
const title = trimTo(run.output.title, 200) || 'Untitled';
const lyrics = run.brief.instrumental ? '' : run.output.lyrics || '';
// The style line is editable at the style checkpoint, so it conditions the render alongside the description.
const prompt = [run.output.musicalDescription, run.output.sunoStyle].filter(Boolean).join('\n\n') || run.brief.prompt;
let trackId = run.output.localTrackId;
if (!trackId) {
const track = await deps.createTrack({ title, concept: run.brief.prompt, lyrics, prompt });
trackId = track.id;
await save({ output: { localTrackId: trackId } });
}
await deps.generateLocalSong({
trackId, title, prompt, lyrics, instrumental: run.brief.instrumental, jobId: run.output.localSongJobId,
localMusic: run.brief.localMusic,
onSubmitted: async (jobId) => {
await save({ output: { localSongJobId: jobId } });
// Stop/cancel cancel the job they find on the record; one that landed
// before this id was stored never saw it, so settle that race here.
const latest = projectAutonomousRun(await getProject(project.id));
if (latest?.status === 'running' && latest.processId === PROCESS_ID) return;
await deps.cancelLocalSong(jobId).catch(() => {});
throw runError(409, 'NOT_RUNNING', 'The run was stopped before its song render started');
},
});
// Linking the track seeds the project's timed lyric cues from the track lyrics.
await deps.updateProject(project.id, { trackId });
return { output: { trackId, songSource: 'local' } };
}
// Draft, then — when the brief asks for it — review & revise on the
// `lyricsReview` stage's LLM. The review is a step inside the lyrics stage (the
// stage list is wire/UI contract), reported through `stages.lyrics.step`. The
// draft is stored before the review runs, so a failed review retries only the review.
async function writeRunLyrics({ project, run, save }) {
if (run.brief.instrumental) return { output: { lyrics: '' } };
const review = autonomousLyricsReviewEnabled(run.brief);
const description = run.output.musicalDescription;
const guidance = run.brief.guidance || undefined;
// The prompt carries the lyrical intent (hook, subject, imagery); the musical description only the sound.
const request = run.brief.prompt || undefined;
const step = (name) => patchRun(project.id, (r) => stagePatch(r, 'lyrics', { step: name }));
let draft = review ? run.output.lyricsDraft : null;
let draftRoute = review ? run.output.lyricsRoute : null;
if (!draft) {
if (review) await step('draft');
const { route, ...llm } = await llmOf(run, 'lyrics');
({ lyrics: draft } = await deps.writeLyrics({ description, guidance, request, ...llm }));
draftRoute = route;
await recordRoute(project, 'lyrics', route);
if (!review) return { output: { lyrics: draft, ...(route ? { lyricsRoute: route } : {}) } };
await save({ output: { lyricsDraft: draft, ...(route ? { lyricsRoute: route } : {}) } });
}
await step('review');
const { route, ...llm } = await llmOf(run, 'lyricsReview');
const revised = await deps.reviewLyrics({ lyrics: draft, description, guidance, request, ...llm });
await recordRoute(project, 'lyricsReview', route);
return { output: {
lyricsDraft: draft,
lyrics: revised.lyrics,
lyricsReviewNotes: revised.notes || '',
...(draftRoute ? { lyricsRoute: draftRoute } : {}),
...(route ? { lyricsReviewRoute: route } : {}),
} };
}
// The board's notes render on the run's first image tool with its pinned model.
// Null keeps the board text-only: the brief names no image tool (its tool list
// is what autopilot may use), or the run has a dollar cap and the tool is not
// the free local backend — these pre-production renders are not counted
// against production's spend cap, so a capped run never spends on them.
// Only reached in a mode that allows images (code-only builds no board).
function boardRenderRoute(run) {
const tool = (run.brief.tools || []).find((id) => id.startsWith('image:'));
if (!tool) return null;
const mode = tool.slice('image:'.length);
if (run.brief.budgetUsd != null && mode !== IMAGE_GEN_MODE.LOCAL) return null;
return { target: RENDER_TARGET.MUSIC_VIDEO, mode, model: run.brief.models?.[tool] || undefined };
}
async function createRunStyle({ project, run }) {
if (musicVideoMediaMode(project) === 'code-only') {
await deps.updateProject(project.id, { concept: { prompt: run.output.concept.prompt, style: run.output.concept.style || run.output.moodBoard?.stylePrompt || '' } });
return { output: { moodBoardId: null } };
}
const board = run.output.moodBoard;
const moodBoardId = run.brief.moodBoardId || run.output.moodBoardId
|| (await deps.createMoodBoard(board, { renderRoute: boardRenderRoute(run) })).id;
// The board is also the project's linked mood board; the server derives the
// authored style snapshot from it (styleSnapshots.js).
await deps.updateProject(project.id, {
concept: { prompt: run.output.concept.prompt, ...(run.output.concept.style ? { style: run.output.concept.style } : {}) },
visualSpec: { moodBoardId },
});
return { output: { moodBoardId } };
}
// The brief is written knowing who stars in the video, so its concept and look
// fit the fixed character instead of inventing a different lead.
function briefGuidance(brief) {
const style = getMusicVideoCharacterStyle(brief.characterStyleId);
if (!style) return brief.guidance;
const lead = `The video stars ${style.character.name} (${style.label} character style), a fixed-identity performer: ${style.summary}`;
return [brief.guidance, lead].filter(Boolean).join('\n\n');
}
const STAGES = {
async brief({ project, run }) {
const { route, ...llm } = await llmOf(run, 'brief');
const reused = run.brief.songFrom;
const { brief: drafted } = await deps.draftCreativeBrief({
prompt: run.brief.prompt, guidance: briefGuidance(run.brief), instrumental: run.brief.instrumental, ...llm,
...(reused ? { song: { title: reused.title, style: reused.style, lyrics: run.output.lyrics } } : {}),
});
// A reused song keeps its own title and style; the brief only designs the video around it.
const brief = reused ? { ...drafted, title: reused.title, ...(reused.style ? { sunoStyle: trimTo(reused.style, SUNO_LIMITS.style) } : {}) } : drafted;
// A blank project name from the prompt gives way to the song title.
if (!run.brief.name) await deps.updateProject(project.id, { name: trimTo(brief.title, 200) });
await recordRoute(project, 'brief', route);
return { output: { ...brief, ...(route ? { briefRoute: route } : {}) } };
},
// The orchestrator judges the written lyrics and may rewrite them (orchestrateLyrics).
async lyrics(ctx) {
const { project, run, save } = ctx;
// A reused song's lyrics were copied with it at start.
if (run.brief.songFrom) return { output: {} };
if (run.brief.instrumental || !isOrchestratedRun(run)) return writeRunLyrics(ctx);
// The draft (or reviewed draft) is stored before the orchestrator judges it,
// so a failed review retries only the review.
let written = run.output.lyricsForReview ? { output: { lyrics: run.output.lyricsForReview } } : null;
if (!written) {
written = await writeRunLyrics(ctx);
await save({ output: { ...written.output, lyricsForReview: written.output.lyrics } });
}
const lyrics = await orchestrateLyrics(project.id, run, written.output.lyrics);
return { output: { ...written.output, lyrics, lyricsForReview: null } };
},
async style({ project, run, save }) {
// The orchestrator judges the sound & look before the mood board is made from it.
if (isOrchestratedRun(run) && !run.output.styleReviewed) {
const reviewed = await orchestrateStyle(project.id, run);
({ run } = await save({ output: { ...reviewed, styleDraft: null, styleReviewed: true } }));
}
return createRunStyle({ project, run });
},
async song({ project, run, save }) {
if (run.output.trackId) return { output: {} };
// `output.songSource` records a fallback already taken, so a resume stays local.
if ((run.output.songSource || run.brief.songSource) === 'local') return localSong({ project, run, save });
const fields = sunoSongFields({
title: run.output.title, style: run.output.sunoStyle, lyrics: run.output.lyrics, instrumental: run.brief.instrumental, suno: run.brief.suno,
});
let submitted = run.output.sunoSongIds?.length > 0;
let song;
const controller = new AbortController();
sunoControllers.set(run.id, controller);
try {
const latest = projectAutonomousRun(await getProject(project.id));
if (latest?.id !== run.id || latest.status !== 'running') controller.abort();
controller.signal.throwIfAborted();
song = await deps.generateSunoSong(fields, {
songIds: run.output.sunoSongIds,
signal: controller.signal,
// The long stage's sub-step rides the run record (and its socket event) so the page can show it.
onProgress: (step) => { patchRun(project.id, (r) => stagePatch(r, 'song', { step })).catch(() => {}); },
// Stored the moment Suno accepts the request, so a failed download retries
// the same songs instead of spending credits on another generation.
onSubmitted: (ids) => { submitted = true; return save({ output: { sunoSongIds: ids } }); },
});
} catch (err) {
// Only before Suno accepted a request: after that, credits are spent and a
// retry reuses those songs rather than paying for a second render.
if (controller.signal.aborted || !run.brief.localFallback || submitted) throw err;
console.warn(`⚠️ Autonomous music video ${short(run.id)} could not use Suno (${trimTo(err.message, 200)}) — rendering the song locally`);
await save({ output: { songSource: 'local', songFallbackReason: trimTo(err.message, 500) } });
return localSong({ project, run, save });
} finally {
sunoControllers.delete(run.id);
}
controller.signal.throwIfAborted();
const track = await deps.createTrack({
title: fields.title, concept: run.brief.prompt, lyrics: fields.lyrics, prompt: fields.style,
});
const durationSec = await deps.probeDuration(song.filename);
// The imported M4A is already durable; the track row that first names it
// commits under a backup lease (#9982).
await withBackupAssetPublication(() => deps.attachAudio(track.id, song.filename, { source: 'suno', prompt: fields.style, lyrics: fields.lyrics, durationSec }));
// Linking the track seeds the project's timed lyric cues from the track lyrics.
await deps.updateProject(project.id, { trackId: track.id });
return { output: { trackId: track.id, sunoSongIds: song.songIds } };
},
async analyze({ project, run }) {
if (run.brief.songFrom) {
// A reused song arrives analyzed and word-timed from its source project and is
// kept as is (no song review, so no retake); only what the source lacks is made.
if (!project.audioAnalysis) await deps.analyzeSong(project.id);
const untimed = (project.lyricCues || []).some((c) => cueText(c) && !c.words?.length);
if (untimed && (isOrchestratedRun(run) || autoApproves(run, 'storyboard'))) await alignRunLyrics(project.id, run);
} else {
await deps.analyzeSong(project.id);
// A storyboard grant needs the lyric timings production verifies, so the autopilot aligns too.
if (!isOrchestratedRun(run) && autoApproves(run, 'storyboard')) await alignRunLyrics(project.id, run);
if (isOrchestratedRun(run) && (await orchestrateSong(project.id, run)).retake) {
// A local fallback stays local: the retake must not send the run back to Suno.
const reset = Object.fromEntries(SONG_OUTPUT_KEYS.filter((key) => key !== 'songSource' && key !== 'songFallbackReason').map((key) => [key, null]));
return { output: reset, goto: 'song', unlinkTrack: run.output.trackId || null };
}
}
// The single's own cover design, drafted from the song just made, ready
// for the publishing kit. Best-effort: a failed draft never stops the video.
if (!project.publishKit?.coverArt?.design) {
const { providerId, model } = await llmOf(run, 'brief');
await deps.designCoverArt(project.id, { providerId: providerId || null, model: model || null })
.catch((err) => console.warn(`⚠️ Autonomous music video ${short(run.id)} cover design skipped: ${trimTo(err.message, 200)}`));
}
return { output: {} };
},
async produce({ project, run }) {
const medium = rendersFromCode(project, run) ? 'code' : autonomousMedium(run.brief.tools);
if (medium === 'code' && !['code', 'document'].includes(project.composition?.mode)) {
await deps.updateProject(project.id, { composition: { mode: 'document', authoringRenderer: 'three' } });
} else if (medium !== 'code') await ensureFootageComposition(project.id);
await prepareProductionReview(project.id);
project = await getProject(project.id);
// The guide is generated in the background; the art gate is only meaningful once it exists.
const castStage = project.castAndSets;
if (castStage?.status === 'failed') {
throw runError(500, 'CAST_SETS_FAILED', `Cast & Sets failed: ${castStage.stopReason || castStage.error || 'unknown error'}`);
}
if (CAST_SETS_WORKING.includes(castStage?.status) && productionReadiness(project).art.problems.length) {
await deps.resumeInterruptedCastAndSets(project);
return { output: {}, wait: true, step: CAST_STEP };
}
const artWasApproved = productionReadiness(project).art.approved;
project = await settleProductionStage(project, run, 'art');
if (!artWasApproved && productionReadiness(project).art.approved) {
// Preparing stops at the art gate; with art approved it drafts the storyboard.
await prepareProductionReview(project.id);
project = await getProject(project.id);
}
let timingHeld = null;
if (isOrchestratedRun(run) || autoApproves(run, 'storyboard')) {
timingHeld = await settleLyricTiming(project.id, run);
// The orchestrator anchors inside its storyboard review; the autopilot does it here.
if (!isOrchestratedRun(run)) await anchorStoryboardLyrics(project.id);
project = await getProject(project.id);
}
project = await settleProductionStage(project, run, 'storyboard');
// Name why the timing was left unverified rather than only that it is provisional,
// with the storyboard's other open problems so one resume can clear them all.
const storyboard = productionReadiness(project).storyboard;
if (timingHeld && !storyboard.approved) {
const others = storyboard.problems.filter((p) => p !== ALIGNMENT_UNVERIFIED_PROBLEM);
throw runError(409, 'MUSIC_VIDEO_APPROVAL_REQUIRED', trimTo([timingHeld, ...others].join(' '), 500));
}
// A medium conflict the run could not revise is named, so the director knows what to change.
const blockers = storyboard.approved ? [] : stageBlockers(project, run, 'storyboard');
if (blockers.length) throw runError(409, 'MUSIC_VIDEO_APPROVAL_REQUIRED', trimTo(blockers.join(' '), 500));
assertProductionApproval(project, 'storyboard');
// The authoring stage's pin, else the run's code-authoring pin taken as
// given (production checks it exactly), else the direction LLM.
const authoring = !run.brief.llmStages?.authoring && run.brief.authoring ? run.brief.authoring : await llmOf(run, 'authoring');
const input = { providerId: authoring.providerId, model: authoring.model || undefined, ...(authoring.effort ? { effort: authoring.effort } : {}) };
if (medium === 'code') {
if (project.composition?.mode === 'code') {
if (!project.composition?.codeVideo?.sections?.length) await deps.generateCode(project.id, input);
} else if (!project.composition?.document) {
const candidate = project.composition?.documentDraft ? { document: project.composition.documentDraft }
: await deps.generateDocument(project.id, input);
await deps.acceptDocument(project.id, candidate.document.directory);
}
// Stopped during the check: the advance loop sees the run is no longer running and lets it be.
if (!await settleOverlayText(project.id, run)) throw runError(409, 'RUN_STOPPED', 'The run stopped during the overlay text check');
// The animated proof is optional review evidence, so the run renders the film once the
// storyboard is approved; the director can still render and approve a proof by hand.
const render = await deps.renderVideo(project.id);
// A cancel/stop during the render's preparation left no job id to cancel; the fresh job is stopped here.
if (render?.jobId && projectAutonomousRun(await getProject(project.id))?.status !== 'running') {
await deps.cancelRender(render.jobId).catch((err) => console.warn(`⚠️ Autonomous music video ${short(run.id)} could not cancel render ${render.jobId}: ${err.message}`));
throw runError(409, 'RUN_STOPPED', 'The run stopped while the final render was preparing');
}
// The run is not finished until the MP4 exists: stay on produce and let the render's own event settle it.
return { output: { renderJobId: render?.jobId || null }, wait: true, step: RENDER_STEP };
}
const pool = briefProductionPool(run.brief, project);
if (!ownsRunningRun(projectAutonomousRun(await getProject(project.id)), run)) {
throw runError(409, 'RUN_STOPPED', 'The run stopped before production could start');
}
const started = await deps.startProduction(project.id, {
directive: briefDirective(run.brief),
pool,
...(stopsBeforeClips(project, run, pool) ? { stopBefore: 'clips' } : {}),
limits: { ...run.brief.limits, ...(run.brief.budgetUsd != null ? { spendCapUsd: run.brief.budgetUsd } : {}) },
// The orchestrator also judges production's plates and drafts when the run has one.
reviewer: isOrchestratedRun(run)
? { providerId: run.brief.orchestrator.providerId, model: run.brief.orchestrator.model || null }
: { providerId: run.brief.llm?.providerId || null, model: run.brief.llm?.model || null },
authoring: input,
});
// A stop during preparation had no child id to stop; cancel the fresh child before handing it off.
if (!ownsRunningRun(projectAutonomousRun(await getProject(project.id)), run)) {
// Persist the child before cancellation: a failed stop must leave it discoverable for recovery.
await patchRun(project.id, (current) => current.id === run.id && current.output.productionRunId === run.output.productionRunId
? { output: { productionRunId: started.run.id } } : {})
.catch((err) => console.error(`❌ Autonomous music video ${short(run.id)} could not retain late production ${started.run.id}: ${err.message}`));
await settleChildStop([], project.id, run, 'cancel production', started.run.id, () => deps.cancelProduction(project.id, started.run.id));
throw runError(409, 'RUN_STOPPED', 'The run stopped while production was preparing');
}
return { output: { productionRunId: started.run.id }, wait: true };
},
};
// ---- stills before video -----------------------------------------------------------
// A run that asked to stop before video, or whose tools make no video, has
// production make every still and stop before the first clip. The orchestrator
// then checks the stills and has the ones it flags regenerated, up to
// `limits.maxReviewAttempts` rounds; the run then waits on `stills` for the
// director, whose approval goes on to the clips.
const STILLS_BATCH = 6;
const STILL_FIXES_MAX = 1000;
/** Production stops before its clips: the plan needs clips, and the run asked to stop or has no video route. */
function stopsBeforeClips(project, run, pool) {
const needsClips = codeFirstProductionAssets(project)?.requiredRoutes.video ?? true;
return needsClips && (run.brief.stopBeforeVideo === true || !pool.some((route) => route.kind === 'video'));
}
/**
* One review round over every still. Clears the flagged stills (their fixes
* ride the next prompt) and returns those shots, which production makes again:
* none once the rounds are spent, when the reviewer could not see the images,
* or when a lock the run did not give refuses the repair. Null when a stop or
* cancel released the run during the review, which then changes nothing.
*/
async function reviewStills(projectId, run, productionRunId) {
const { buildStillsReviewPrompt } = await reviewModule();
const project = await getProject(projectId);
const shots = (project.scenes || []).filter((scene) => scene.referenceImageId);
const issues = [];
const reviews = [];
let shown = 0;
for (let i = 0; i < shots.length; i += STILLS_BATCH) {
const listed = [];
const images = [];
for (const scene of shots.slice(i, i + STILLS_BATCH)) {
const path = await deps.galleryImagePath(scene.referenceImageId).catch(() => null);
if (path) { listed.push(scene); images.push(path); }
}
if (!listed.length) continue;
const review = await askReview(run, 'stills', buildStillsReviewPrompt({ ...ideaOf(run), concept: project.concept,
cast: project.productionReview?.draft?.cast || '',
shots: listed.map((scene, n) => ({ image: n + 1, sceneId: scene.sceneId, label: scene.label || '', still: trimTo(scene.framePrompt || scene.prompt, 400) })) }), images);
reviews.push(review);
if (review.visual) shown += listed.length;
// A review that could not see the stills cannot judge them.
const known = new Set(listed.map((scene) => scene.sceneId));
if (review.visual && review.verdict === 'revise') issues.push(...review.issues.filter((issue) => known.has(issue.sceneId)));
}
const spent = revisionsSpent(await latestRun(projectId), 'stills');
const flagged = spent < reviewLimit(run) ? issues : [];
if (!await ownsStillsReview(projectId, productionRunId)) return null;
const fixes = new Map();
for (const issue of flagged) fixes.set(issue.sceneId, [fixes.get(issue.sceneId), issue.text].filter(Boolean).join(' '));
const at = new Date().toISOString();
// Clearing the still is what makes production generate it again; the fixes ride its next prompt.
const refused = fixes.size > 0 && (await mutateProjectRecord(projectId, (current) => ({ project: { ...current, scenes: (current.scenes || []).map((scene) => (fixes.has(scene.sceneId)
? { ...scene, referenceImageId: null, stillFixes: { text: trimTo(fixes.get(scene.sceneId), STILL_FIXES_MAX), at } } : scene)) } }), { runId: run.id })).rejected === true;
const regenerate = refused ? [] : flagged;
const scored = reviews.map((r) => r.score).filter((n) => n != null);
// Approval needs every still seen and nothing flagged; an inconclusive or unresolved round is not one.
const conclusive = shots.length > 0 && shown === shots.length;
const unresolved = issues.length > 0 && !regenerate.length;
const why = !reviews.length ? 'No still could be shown to the reviewer. '
: reviews.some((r) => !r.visual) ? 'The reviewer could not see every still. '
: refused ? `${nameShots(project, [...fixes.keys()])} locked by an approval this run did not give; unlock to regenerate. `
: unresolved ? 'Revision limit reached with changes still open. ' : '';
await recordReview(projectId, { checkpoint: 'stills', verdict: regenerate.length || unresolved || !conclusive ? 'revise' : 'approve',
score: scored.length ? Math.min(...scored) : null, route: reviews.at(-1)?.route || null, visual: reviews.length > 0 && reviews.every((r) => r.visual),
notes: trimTo(`${why}${regenerate.length ? `Regenerating ${regenerate.length} still${regenerate.length === 1 ? '' : 's'}. ` : ''}${reviews.map((r) => r.notes).filter(Boolean).join(' ')}`, 1500),
...(regenerate.length || unresolved ? { changes: (regenerate.length ? regenerate : issues).map((issue) => trimTo(`${issue.sceneId}: ${issue.text}`, 300)) } : {}) });
return regenerate;
}
/**
* Production made every still. An orchestrated run reviews them and sends the
* flagged ones back to production; otherwise (or once they pass) the run waits
* on `stills` for the director.
*/
const settlingStills = new Set();
async function settleStills(projectId, run, productionRunId) {
// Production announces the stop more than once; one review round answers it.
if (settlingStills.has(productionRunId)) return;
settlingStills.add(productionRunId);
try {
await reviewOrPark(projectId, run, productionRunId);
} catch (err) {
if (await ownsStillsReview(projectId, productionRunId)) await park(projectId, 'needs-human', { error: trimTo(`The stills review failed: ${err.message}`, 500), errorCode: err.code || 'STILLS_REVIEW_FAILED' });
} finally {
settlingStills.delete(productionRunId);
}
}
/** A stop or cancel while the stills review was pending releases the run; its verdict must then change nothing. */
async function ownsStillsReview(projectId, productionRunId) {
const latest = projectAutonomousRun(await getProject(projectId));
return latest?.status === 'running' && latest.processId === PROCESS_ID && latest.output?.productionRunId === productionRunId;
}
async function reviewOrPark(projectId, run, productionRunId) {
if (isOrchestratedRun(run)) {
const regenerate = await reviewStills(projectId, run, productionRunId);
// A stop or cancel can also land while the repair and its review entry are written.
if (!regenerate || !await ownsStillsReview(projectId, productionRunId)) return;
if (regenerate.length) {
await deps.resumeProduction(projectId, productionRunId, { acceptBasis: true, stopBefore: 'clips' });
return;
}
}
await park(projectId, 'awaiting-approval', { awaiting: 'stills' });
}
// ---- the advance loop ------------------------------------------------------------
const isLoginRequired = (err) => err?.code === 'PUBLISH_LOGIN_REQUIRED';
function logParkedRun(run, status, error) {
const log = status === 'failed' ? console.error : status === 'completed' ? console.log : console.warn;
log(`${status === 'completed' ? '✅' : status === 'failed' ? '❌' : '⏸️'} Autonomous music video ${short(run.id)} ${status}${error ? `: ${error}` : ''}`);
}
async function park(projectId, status, patch) {
const out = await patchRun(projectId, () => ({ status, ...patch }));
logParkedRun(out.run, status, patch.error);
return out;
}
async function advance(projectId) {
if (inflight.has(projectId)) return;
const settlement = Promise.withResolvers();
inflight.set(projectId, settlement.promise);
try {
for (;;) {
const project = await getProject(projectId);
const run = projectAutonomousRun(project);
if (!run || run.status !== 'running' || run.processId !== PROCESS_ID) return;
const stage = run.stage;
const executor = STAGES[stage];
if (!executor) {
await park(projectId, 'failed', { error: `Unknown stage "${stage}"`, errorCode: 'UNKNOWN_STAGE' });
return;
}
await patchRun(projectId, (r) => stagePatch(r, stage, { status: 'running', startedAt: new Date().toISOString(), error: null, step: null }));
let result;
try {
result = await executor({ project, run, save: (patch) => patchRun(projectId, () => patch) });
} catch (err) {
// Recheck ownership inside the failure write, so an already queued stop/cancel wins.
let failed = false;
const out = await patchRun(projectId, (r) => {
failed = ownsRunningRun(r, run);
return failed ? {
...stagePatch(r, stage, { status: 'failed', error: trimTo(err.message, 500), step: null }),
status: isLoginRequired(err) || err.code === 'MUSIC_VIDEO_APPROVAL_REQUIRED' ? 'needs-human' : 'failed',
error: trimTo(err.message, 500), errorCode: err.code || null,
} : {};
});
if (failed) logParkedRun(out.run, out.run.status, out.run.error);
return;
}
const finishedAt = new Date().toISOString();
// Preserve useful late output, but only the still-owned run may continue the pipeline.
let owned = false;
if (result.goto) {
// The orchestrator sent the run back (a song retake): both stages run again.
const pending = { status: 'pending', startedAt: null, finishedAt: null, error: null, step: null };
await patchRun(projectId, (r) => {
owned = ownsRunningRun(r, run);
return { output: result.output, ...(owned ? { stage: result.goto } : {}),
stages: { [stage]: { ...r.stages[stage], ...pending }, [result.goto]: { ...r.stages[result.goto], ...pending } } };
});
if (!owned) return;
if (result.unlinkTrack) await unlinkRunTrack(projectId, run.id, result.unlinkTrack);
console.log(`🎬 Autonomous music video ${short(run.id)} going back to ${result.goto}`);
continue;
}
if (result.wait) {
await patchRun(projectId, (r) => {
owned = ownsRunningRun(r, run);
return { output: result.output, ...stagePatch(r, stage, { status: 'running', step: result.step || null }) };
});
if (!owned) {
// Cancellation can win the serialized write after the executor's final ownership read.
const { productionRunId, renderJobId } = result.output || {};
if (productionRunId) await settleChildStop([], projectId, run, 'cancel production', productionRunId, () => deps.cancelProduction(projectId, productionRunId));
if (renderJobId) await settleChildStop([], projectId, run, 'cancel render', renderJobId, () => deps.cancelRender(renderJobId));
return;
}
console.log(`🎬 Autonomous music video ${short(run.id)} handed ${stage} to ${result.step === RENDER_STEP ? 'the final render' : result.step === CAST_STEP ? 'Cast & Sets' : 'production'}`);
// The render may have settled before its job id was stored on the run.
if (result.step === RENDER_STEP) await reconcileFinalRender(projectId);
// Cast & Sets may likewise have settled while the wait was being stored.
// It runs once this loop releases the project, so the re-entry it triggers is not dropped as "already running".
else if (result.step === CAST_STEP) {
settlement.promise.then(() => reconcileCastAndSets(projectId))
.catch((err) => console.error(`❌ Autonomous music video could not settle on Cast & Sets: ${err.message}`));
}
return;
}
const next = nextAutonomousStage(stage);
const checkpoint = run.brief.checkpoints.includes(stage);
await patchRun(projectId, (r) => {
owned = ownsRunningRun(r, run);
return {
output: result.output,
...stagePatch(r, stage, { status: 'done', finishedAt, step: null }),
...(owned && (checkpoint ? { status: 'awaiting-approval', awaiting: stage, stage: next } : next ? { stage: next } : { status: 'completed', stage })),
};
});
if (!owned) return;
console.log(`🎬 Autonomous music video ${short(run.id)} finished ${stage}${checkpoint ? ' — waiting for approval' : ''}`);
if (checkpoint || !next) return;
}
} catch (err) {
console.error(`❌ Autonomous music video advance failed for ${short(projectId)}: ${err.message}`);
} finally {
inflight.delete(projectId);
settlement.resolve();
}
}
function advanceInBackground(projectId) {
advance(projectId).catch((err) => console.error(`❌ Autonomous music video advance failed for ${short(projectId)}: ${err.message}`));
}
/**
* Drop the project's link to a retaken song. The rejected track stays in the
* music library (the director may still want it); only the link goes, and
* only while it still names that track (never one the director picked since).
* Unlinking keeps the lyric cues' text and clears their timings (applyProjectPatch
* → invalidateTimedText), and the new song's link re-seeds them from its own
* lyrics. A failed unlink is not fatal: that same link replaces the old one.
*/
async function unlinkRunTrack(projectId, runId, trackId) {
const { applyProjectPatch } = await import('./projectsLogic.js');
// The track and run ownership must be checked in the same write as the unlink.
await mutateProjectRecord(projectId, (project) => ({ project: project.trackId === trackId && ownsRunningRun(projectAutonomousRun(project), { id: runId })
? applyProjectPatch(project, { trackId: null }) : project }))
.catch((err) => console.warn(`⚠️ Autonomous music video ${short(runId)} could not unlink the retaken track: ${err.message}`));
}
// ---- director actions ------------------------------------------------------------
const emptyStages = () => Object.fromEntries(AUTONOMOUS_STAGE_IDS.map((id) => [id, { status: 'pending', startedAt: null, finishedAt: null, error: null }]));
/**
* Start a run from one prompt: creates the project (autonomous mode, no track
* yet) and begins the pipeline in the background. Returns `{ project, run }`.
*/
/** The production pool a brief allows on this project. */
/**
* The project video settings the run's own video tool implies, so the plan and
* production agree on what can render: its backend and local model, and Supplied
* song audio when that local model takes a shot's song window. With no video tool
* it is local video, whose lip-sync shots render as LTX audio-to-video.
*/
async function briefVideoSettings(tools, models) {
const route = autonomousPool(tools, models).find((entry) => entry.kind === 'video');
if (!route || route.mode !== 'local') return { backend: route?.mode || 'local', generationMode: 'image' };
const songAudio = await deps.localVideoTakesSongAudio(route.model).catch(() => false);
return { backend: 'local', modelId: route.model || null, generationMode: songAudio ? 'suppliedAudio' : 'image' };
}
const briefProductionPool = (brief, project) => autonomousPool(brief.tools, brief.models)
.filter((route) => musicVideoAllowsMedia(project, route.kind));
/** Refuse a pinned video model that cannot animate a frame (#10457) before the run records it. */
async function assertBriefVideoModelsCapable(tools, models) {
const pool = autonomousPool(tools, models);
if (pool.some((route) => route.kind === 'video' && route.model)) await assertFootageVideoModelsCapable(pool, await loadPoolEnv());
}
// The song fields a reused song brings along: the audio, its analysis and the
// timed lyrics. Never the source's look, cast, scenes, storyboard or treatment.
const REUSED_SONG_FIELDS = ['audioAnalysis', 'midiTranscription', 'lyricCues', 'lyricMarkers', 'phrases',
'vocalStemFilename', 'performanceConditioningSource', 'lyricAlignSource', 'lyricAlignSilentWords'];
/** The song an autonomous run reuses from another project, or a 4xx naming why it cannot. */
async function loadSongSource(projectId) {
const source = await getProject(projectId);
if (!source || source.deleted) throw runError(404, 'NOT_FOUND', 'The project to take the song from was not found');
if (!source.trackId && !source.uploadedAudioFilename) throw runError(409, 'NO_SONG', `"${source.name}" has no song to reuse`);
const track = source.trackId ? await deps.getTrack(source.trackId) : null;
const cueLines = (source.lyricCues || []).map(cueText).filter(Boolean);
return {
source,
title: trimTo(track?.title || source.name, SUNO_LIMITS.title) || 'Untitled',
style: trimTo(source.concept?.songStyle || track?.prompt || '', 2000),
lyrics: cueLines.length ? cueLines.join('\n') : (typeof track?.lyrics === 'string' ? track.lyrics.trim() : ''),
// Verified timing carries over only while it is still verified on the source.
verified: productionReadiness(source).alignment.status === 'verified',
};
}
export async function startAutonomousVideo(input, { autoApproveAuthorized = false } = {}) {
const brief = { ...normalizeAutonomousBrief(input), ...autoApproveGrant(input?.autoApprove, autoApproveAuthorized) };
if (!brief.prompt) throw runError(400, 'VALIDATION_ERROR', 'A prompt is required');
if (brief.orchestrator) Object.assign(brief, orchestratorGrant(autoApproveAuthorized));
await assertBriefVideoModelsCapable(brief.tools, brief.models);
const song = input?.fromProjectId ? await loadSongSource(input.fromProjectId) : null;
if (song) {
// No lyrics are written and no song is made, so those checkpoints have nothing to stop on.
Object.assign(brief, {
name: brief.name || trimTo(`${song.title} (Auto)`, 200),
// The source's effective media mode carries over unless the request names its own.
...(input.mediaMode === undefined ? { mediaMode: musicVideoMediaMode(song.source) } : {}),
instrumental: !song.lyrics,
checkpoints: brief.checkpoints.filter((id) => id !== 'lyrics' && id !== 'song'),
songFrom: { projectId: song.source.id, title: song.title, style: song.style, verifiedAlignmentBasis: null },
});
}
const now = new Date().toISOString();
const created = await deps.createProject({
name: brief.name || trimTo(brief.prompt.replace(/\s+/g, ' '), 60) || 'Autonomous music video',
mode: 'autonomous',
mediaMode: brief.mediaMode,
videoSettings: await briefVideoSettings(brief.tools, brief.models),
...(brief.mediaMode !== 'code-images-video' ? { productionPolicy: { strategy: 'code-first', maxGeneratedVideoPercent: 0 } } : {}),
// ...as does its production policy (a project with none is legacy), so a footage project stays one,
// also when the request names a mode that allows footage; a code-only or stills mode keeps no footage.
...(song && (input.mediaMode === undefined || brief.mediaMode === 'code-images-video') ? { productionPolicy: normalizeMusicVideoProductionPolicy(song.source.productionPolicy) } : {}),
...(song ? { trackId: song.source.trackId || null, uploadedAudioFilename: song.source.uploadedAudioFilename || null } : {}),
// The style id makes createProject cast its character and attach the sheet (styleSnapshots.js).
concept: { prompt: trimTo(brief.prompt, 8000), ...(brief.characterStyleId ? { characterStyleId: brief.characterStyleId } : {}),
...(song?.style ? { songStyle: song.style } : {}) },
automation: {
tools: brief.tools,
guidance: brief.guidance,
budgetUsd: brief.budgetUsd,
checkins: { castAndSets: brief.checkpoints.includes('cast') ? 'review' : 'auto' },
// The run's LLM pins also steer the stages production starts later (Cast & Sets, shot planning, authoring).
...(brief.llm ? { llm: brief.llm } : {}),
...(brief.llmStages ? { llmStages: brief.llmStages } : {}),
},
});
const run = {
id: `mvar-${randomUUID()}`,
status: 'running',
stage: AUTONOMOUS_STAGE_IDS[0],
awaiting: null,
brief,
stages: emptyStages(),
output: song ? { trackId: song.source.trackId || null, lyrics: song.lyrics, songSource: 'reused' } : {},
error: null,
errorCode: null,
processId: PROCESS_ID,
createdAt: now,
updatedAt: now,
};
const out = await mutateProjectRecord(created.id, (current) => {
if (!song) return { project: { ...current, autonomousRun: run }, run };
const copied = Object.fromEntries(REUSED_SONG_FIELDS.filter((key) => song.source[key] !== undefined)
.map((key) => [key, structuredClone(song.source[key])]));
const project = { ...current, ...copied, ...(copied.audioAnalysis ? { status: 'analyzed' } : {}) };
// Bound to the copy as written: any later change to the audio or timings unbinds it.
const reused = { ...run, brief: { ...run.brief, songFrom: { ...run.brief.songFrom,
verifiedAlignmentBasis: song.verified ? productionAlignmentBasis(project) : null } } };
return { project: { ...project, autonomousRun: reused }, run: reused };
});
console.log(`🎬 Autonomous music video ${short(run.id)} started${song ? ` on the song from ${short(song.source.id)}` : ''} (${brief.tools.length} tool(s), ${brief.orchestrator ? `orchestrated by ${brief.orchestrator.providerId}` : `${brief.checkpoints.length} checkpoint(s)`}${brief.autoApprove.length ? `, auto-approve ${brief.autoApprove.join('/')}` : ''}${brief.origin.kind === 'schedule' ? ', scheduled' : ''})`);
publish(out.project, out.run);
advanceInBackground(created.id);
return { project: out.project, run: presentAutonomousRun(out.run) };
}
export async function getAutonomousRun(projectId) {
const { run } = await requireRun(projectId);
return { run: presentAutonomousRun(run) };
}
/**
* Resume a parked, failed or interrupted run at the stage that stopped — or
* approve the checkpoint it is waiting on (optionally replacing the stage
* output the director edited). Returns `{ project, run }`.
*/
const assertResumable = (run) => {
// A run canceled while it waited on production can pick up again: resume adopts the
// director's own production run, or starts a new one from the brief.
const resumable = AUTONOMOUS_LIVE_STATUSES.includes(run.status) || run.status === 'failed'
|| (run.status === 'canceled' && run.stage === 'produce');
if (!resumable) throw runError(409, 'NOT_RESUMABLE', `A ${run.status} run cannot be resumed`);
if (run.status === 'running' && run.processId === PROCESS_ID) throw runError(409, 'ALREADY_RUNNING', 'This run is already running');
};
// A retake is only meaningful while the run sits on the song it would replace: parked for
// approval of it, or stopped / failed inside the song stage (a Suno request whose rows
// vanished leaves ids no export can find — the retake discards them and submits afresh).
const assertAtSongCheckpoint = (run) => {
const parkedOnSong = run.status === 'awaiting-approval' && run.awaiting === 'song';
const stuckInSong = run.stage === 'song' && ['stopped', 'failed', 'needs-human'].includes(run.status);
if (!parkedOnSong && !stuckInSong) {
throw runError(409, 'NOT_AT_SONG_CHECKPOINT', 'A song can only be retaken while the run is waiting for approval of its song, or is stopped or failed in the song stage');
}
};
// Every key the song stage (and `localSong`) writes; a retake nulls them all so
// the stage runs from scratch — a new Suno request (the director's explicit,
// credit-spending choice) or a new local render on a new track.
const SONG_OUTPUT_KEYS = ['trackId', 'sunoSongIds', 'songSource', 'songFallbackReason', 'localTrackId', 'localSongJobId'];
/**
* How a run continues on its produce stage, read from the checkpoint ids in its
* output. Those ids overlap on purpose — `patchRun` merges output, so each later
* checkpoint is written beside the earlier ones, never in place of them:
* `productionRunId` stays set once production completes (`finishFromProduction`
* adds `productionDone`, and maybe an adopted `renderJobId`), and `renderJobId`
* stays set while the orchestrator reviews that film and while a footage
* revision (`finalAutoReviewId`) works on it. So this is two views, not a phase:
*
* - `finalDelivery`: the film is being rendered, reviewed or revised — after
* production, or straight after code generation for a code-only brief.
* `productionDone` alone counts (production finished, the render has not
* started), and it does not mean the autonomous run is done.
* - `resume`: the one continuation Resume takes, latest checkpoint first —
* `final-revision` (its review id), else `final-render` (the render id, or
* null when none started), else `production` (its run id), else `advance`.
*
* Neither proves anything finished: callers keep their own status, step and
* identity checks, and check the render job, document and history themselves.
*/
function produceContinuation(run) {
const output = run?.stage === 'produce' ? run.output : null;
if (!output) return { finalDelivery: false, resume: { kind: 'advance', id: null } };
const finalDelivery = Boolean(output.renderJobId || output.productionDone);
const resume = output.finalAutoReviewId ? { kind: 'final-revision', id: output.finalAutoReviewId }
: finalDelivery ? { kind: 'final-render', id: output.renderJobId || null }
: output.productionRunId ? { kind: 'production', id: output.productionRunId }
: { kind: 'advance', id: null };
return { finalDelivery, resume };
}
export async function resumeAutonomousVideo(projectId, edits = {}, { autoApproveAuthorized = false } = {}) {
const { run } = await requireRun(projectId);
// Tools are only ever added (a video tool once the stills are approved, say); the pool follows.
const added = (edits.addTools || []).filter((id) => !run.brief.tools.includes(id));
const toolsPatch = added.length ? MUSIC_VIDEO_AUTOMATION_TOOL_IDS.filter((id) => run.brief.tools.includes(id) || added.includes(id)) : null;
const tools = toolsPatch || run.brief.tools;
// A model swap is validated like Start, then replaces the parked production run's pool (#10473).
const modelsPatch = briefModelsPatch({ ...run.brief, tools }, edits.models);
assertResumable(run);
if (modelsPatch || toolsPatch) await assertBriefVideoModelsCapable(tools, modelsPatch || run.brief.models || {});
// "Auto-approve the rest": replaces the brief's grant (an empty list clears it).
const grant = edits.autoApprove !== undefined ? autoApproveGrant(edits.autoApprove, autoApproveAuthorized) : null;
const retake = edits.retakeSong === true;
if (retake && run.brief.songFrom) throw runError(409, 'SONG_REUSED', 'This run reuses an existing song, so it has no song to retake');
if (retake) assertAtSongCheckpoint(run);
// A changed prompt or guidance reaches production's shot planner on this resume.
const directionPatch = Object.fromEntries(['prompt', 'guidance'].filter((key) => typeof edits[key] === 'string' && edits[key] !== (run.brief[key] ?? '')).map((key) => [key, edits[key]]));
const directionChanged = Object.keys(directionPatch).length > 0;
const modelsChanged = toolsPatch !== null || (modelsPatch !== null && JSON.stringify(modelsPatch) !== JSON.stringify(run.brief.models || {}));
// Approving the stills goes on to the clips, including in any new production run.
const stillsApproved = run.status === 'awaiting-approval' && run.awaiting === 'stills';
const limitsPatch = edits.limits ? { ...run.brief.limits, ...edits.limits } : null;
// A production run only takes raised limits; refuse a lower one before anything changes.
if (edits.limits && run.stage === 'produce' && Object.entries(edits.limits).some(([key, value]) => value != null && value < (run.brief.limits?.[key] ?? 0))) {
throw runError(400, 'VALIDATION_ERROR', 'Resuming production can only raise a limit');
}
// Stop changes the record immediately, but its stage may still be settling.
// Let that attempt release ownership before marking a new attempt running.
await inflight.get(projectId);
let retakenTrackId = null;
const out = await patchRun(projectId, (r, current) => {
// Cancel or another Resume may have won while the old attempt settled.
assertResumable(r);
if (retake) {
assertAtSongCheckpoint(r);
// Unlink only the track this run linked, never one the director picked since.
if (r.output.trackId && current.trackId === r.output.trackId) retakenTrackId = r.output.trackId;
}
// A run waiting on production resumes by resuming that run, not by redoing
// the stage — the stage re-runs only when production never started.
const stage = retake ? 'song' : r.stage;
return {
status: 'running', awaiting: null, error: null, errorCode: null, processId: PROCESS_ID,
...(edits.suno || edits.localMusic !== undefined || grant || modelsPatch || toolsPatch || limitsPatch || stillsApproved || directionChanged ? { brief: {
...r.brief,
...directionPatch,
...(toolsPatch ? { tools: toolsPatch } : {}),
...(stillsApproved ? { stopBeforeVideo: false } : {}),
...(modelsPatch ? { models: modelsPatch } : {}),
...(limitsPatch ? { limits: limitsPatch } : {}),
// A generation limit the director sets replaces the sized default.
...(edits.limits?.maxGenerations != null ? { sizedGenerations: false } : {}),
...(edits.suno ? { suno: normalizeSunoOptions({ ...r.brief.suno, ...edits.suno }) } : {}),
...(edits.localMusic !== undefined ? { localMusic: normalizeLocalMusicOptions(edits.localMusic ? { ...r.brief.localMusic, ...edits.localMusic } : null) } : {}),
...(grant || {}),
} } : {}),
output: {
...(retake ? Object.fromEntries(SONG_OUTPUT_KEYS.map((key) => [key, null])) : {}),
...(typeof edits.lyrics === 'string' ? { lyrics: edits.lyrics } : {}),
...(typeof edits.style === 'string' && edits.style.trim() ? { sunoStyle: edits.style.trim() } : {}),
},
...(retake
? { stage, ...stagePatch(r, stage, { status: 'pending', startedAt: null, finishedAt: null, error: null, step: null }) }
: stagePatch(r, stage, { error: null })),
};
});
if (retakenTrackId) await unlinkRunTrack(projectId, out.run.id, retakenTrackId);
// The project's brief tools gate what production may submit (a video tool for clips), so they follow
// too, as do its video settings. Performance shots no route can lip-sync play as cutaways.
if (toolsPatch || modelsPatch) {
const video = await briefVideoSettings(tools, modelsPatch || run.brief.models || {});
const lipSync = !!performanceCapability(video.backend);
await mutateProjectRecord(projectId, (current) => ({ project: { ...current,
...(toolsPatch ? { automation: { ...current.automation, tools: [...new Set([...(current.automation?.tools || []), ...added])] } } : {}),
videoSettings: { ...current.videoSettings, ...video },
...(lipSync ? {} : { scenes: (current.scenes || []).map((scene) => (isPerformanceScene(scene) ? { ...scene, shotMode: 'cutaway' } : scene)) }) } }));
}
const { resume } = produceContinuation(out.run);
if (resume.kind === 'final-revision') {
// The orchestrator's footage revision picks up where it stopped. One that
// already ended (or a director finished) leaves a revised film to render
// and review again; any other failure is the director's to see.
const failure = await deps.resumeAutoReview(projectId, resume.id).then(() => null, (err) => err);
if (!failure) {
const { project: next, run } = await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'running', step: FINAL_REVISION_STEP }));
return { project: presentProjectAutonomousRun(next), run: presentAutonomousRun(run) };
}
if (!['AUTO_REVIEW_CLOSED', 'NOT_FOUND'].includes(failure.code)) {
const parked = await park(projectId, 'needs-human', { error: trimTo(`The final revision could not resume: ${failure.message}`, 500), errorCode: failure.code || null });
return { project: parked.project, run: presentAutonomousRun(parked.run) };
}
// A hand-off the director has not finished yet still holds its revision open.
const { openAttemptRevisionId } = await import('./autoReview.js');
if (openAttemptRevisionId(await getProject(projectId), resume.id)) {
const parked = await park(projectId, 'needs-human', { error: 'Finish or cancel the open revision of the final video first, then Resume.', errorCode: 'FINAL_REVISION_NEEDS_HUMAN' });
return { project: parked.project, run: presentAutonomousRun(parked.run) };
}
const { run } = await patchRun(projectId, () => ({ output: { finalAutoReviewId: null } }));
await startFinalRender(projectId, run);
const latest = await getProject(projectId);
return { project: presentProjectAutonomousRun(latest), run: presentAutonomousRun(projectAutonomousRun(latest)) };
}
if (resume.kind === 'final-render') {
// Production (or the code render) already finished; only the final render and its review are left.
await reconcileFinalRender(projectId, { restart: true });
const latest = await getProject(projectId);
return { project: presentProjectAutonomousRun(latest), run: presentAutonomousRun(projectAutonomousRun(latest)) };
}
if (resume.kind === 'production') {
return resumeDelegatedProduction(projectId, out.run, { swapModels: modelsChanged, limits: edits.limits, stillsApproved, directionChanged });
}
advanceInBackground(projectId);
return { project: out.project, run: presentAutonomousRun(out.run) };
}
/**
* The brief's models with a resume's per-tool swaps applied (null clears a pin), or null
* when the resume names none. Only tools the brief already allows can be pinned.
*/
function briefModelsPatch(brief, models) {
if (!models || !Object.keys(models).length) return null;
const next = { ...(brief.models || {}) };
for (const [tool, model] of Object.entries(models)) {
if (!brief.tools.includes(tool)) throw runError(400, 'VALIDATION_ERROR', `The run does not use ${tool}`);
if (model) next[tool] = model;
else delete next[tool];
}
return next;
}
// Production runs that can still deliver the footage: live, parked or finished.
const ADOPTABLE_PRODUCTION = new Set(['running', 'completed', 'limit-reached', 'blocked', 'needs-replan', 'needs-human', 'stopped', 'awaiting-video']);
const PRODUCTION_LIVE = new Set(['running', 'limit-reached', 'blocked', 'needs-replan', 'needs-human', 'stopped', 'awaiting-video']);
/**
* Hand a resumed run back to production. It follows the newest production run started
* since the run began (the director may have replaced its own by hand) and resumes it
* with any raised limits and swapped models, or finishes straight to the final render
* when that run is already complete. No production run left to follow — or a model
* swap on one that cannot resume — starts a new one from the brief by re-entering `produce`.
*/
async function resumeDelegatedProduction(projectId, run, { swapModels = false, limits, stillsApproved = false, directionChanged = false } = {}) {
const project = await getProject(projectId);
const runs = Array.isArray(project.productionRuns) ? project.productionRuns : [];
const current = runs.find((r) => r.id === run.output.productionRunId) || null;
const newest = runs
.filter((r) => ADOPTABLE_PRODUCTION.has(r.status) && String(r.createdAt || '') >= String(run.createdAt || ''))
.sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')))[0] || null;
const adopt = swapModels && newest && !PRODUCTION_RESUMABLE_STATUSES.has(newest.status) ? null : newest;
if (!adopt) {
// Unlink first: the old run's own "canceled" event must no longer match this run.
const out = await patchRun(projectId, (r) => ({ output: { productionRunId: null }, ...stagePatch(r, 'produce', { status: 'pending', error: null, step: null }) }));
if (current && PRODUCTION_LIVE.has(current.status)) await settleChildStop([], projectId, run, 'cancel production', current.id, () => deps.cancelProduction(projectId, current.id));
console.log(`🎬 Autonomous music video ${short(run.id)} starting a new production run${swapModels ? ' with the new models' : ''}`);
advanceInBackground(projectId);
return { project: out.project, run: presentAutonomousRun(out.run) };
}
if (adopt.id !== run.output.productionRunId) {
await patchRun(projectId, () => ({ output: { productionRunId: adopt.id } }));
console.log(`🎬 Autonomous music video ${short(run.id)} adopted production run ${short(adopt.id)}`);
}
if (adopt.status === 'completed') {
await finishFromProduction(projectId, adopt.id);
} else if (adopt.status === 'awaiting-video' && !stillsApproved) {
// Only approving the stills goes on to the clips; any other resume reviews them (again).
settleStills(projectId, run, adopt.id).catch((err) => console.error(`❌ Autonomous music video ${short(run.id)} stills review: ${err.message}`));
} else {
// A footage run started before shots were composed by default renders its drafts from them.
if (!rendersFromCode(project, run)) await ensureFootageComposition(projectId);
// Resuming a "running" run is safe and re-pins one left by a previous server process.
const productionLimits = limits ? Object.fromEntries(Object.entries(limits).filter(([, v]) => v != null)) : undefined;
const failure = await deps.resumeProduction(projectId, adopt.id, {
acceptBasis: true,
...(productionLimits ? { limits: productionLimits } : {}),
...(swapModels ? { pool: briefProductionPool(run.brief, project) } : {}),
...(directionChanged ? { directive: briefDirective(run.brief) } : {}),
})
.then(() => null, (err) => err);
if (failure) {
const parked = await park(projectId, 'needs-human', { error: trimTo(`Production could not resume: ${failure.message}`, 500), errorCode: failure.code || null });
return { project: parked.project, run: presentAutonomousRun(parked.run) };
}
}
const latest = await getProject(projectId);
return { project: presentProjectAutonomousRun(latest), run: presentAutonomousRun(projectAutonomousRun(latest)) };
}
/**
* Stop one delegated child after the run is already marked stopped/canceled. A 404/409 means
* the child is gone or already terminal (benign); anything else is logged and recorded in
* `failures` so the response can say work may still be running. Never throws.
*/
async function settleChildStop(failures, projectId, run, action, childId, call) {
try {
await call();
} catch (err) {
if (err?.status === 404 || err?.status === 409) return;
const message = err?.message || String(err);
console.error(`❌ Autonomous music video ${short(run.id)} (project ${projectId}) could not ${action} ${childId}: ${message}`);
failures.push({ kind: action, id: childId, error: message });
}
}
// Read from the freshly patched record, so a job id stored a moment before the status flipped is seen.
const cancelLocalSongJob = (projectId, run, failures) => (run.stage === 'song' && run.output.localSongJobId
? settleChildStop(failures, projectId, run, 'cancel song job', run.output.localSongJobId, () => deps.cancelLocalSong(run.output.localSongJobId))
: null);
export async function stopAutonomousVideo(projectId) {
const { run } = await requireRun(projectId);
if (!['running', 'awaiting-approval', 'needs-human'].includes(run.status)) throw runError(409, 'NOT_RUNNING', `A ${run.status} run cannot be stopped`);
const out = await patchRun(projectId, () => ({ status: 'stopped' }));
const { productionRunId, finalAutoReviewId } = out.run.output;
const childStopFailures = [];
if (productionRunId) {
await settleChildStop(childStopFailures, projectId, run, 'stop production', productionRunId, () => deps.stopProduction(projectId, productionRunId));
}
if (finalAutoReviewId) await settleChildStop(childStopFailures, projectId, run, 'stop auto-review', finalAutoReviewId, () => deps.stopAutoReview(projectId, finalAutoReviewId));
sunoControllers.get(run.id)?.abort();
await cancelLocalSongJob(projectId, out.run, childStopFailures);
return { project: out.project, run: presentAutonomousRun(out.run), childStopFailures };
}
export async function cancelAutonomousVideo(projectId) {
const { run } = await requireRun(projectId);
if (!(AUTONOMOUS_LIVE_STATUSES.includes(run.status) || run.status === 'failed')) throw runError(409, 'NOT_CANCELABLE', `A ${run.status} run cannot be canceled`);
const out = await patchRun(projectId, () => ({ status: 'canceled', awaiting: null }));
// Child ids come from the patched record: one stored just before the flip is missed by the earlier read.
const { renderJobId, finalAutoReviewId, productionRunId } = out.run.output;
const childStopFailures = [];
if (renderJobId) await settleChildStop(childStopFailures, projectId, run, 'cancel render', renderJobId, () => deps.cancelRender(renderJobId));
if (finalAutoReviewId) await settleChildStop(childStopFailures, projectId, run, 'cancel auto-review', finalAutoReviewId, () => deps.cancelAutoReview(projectId, finalAutoReviewId));
if (productionRunId) {
await settleChildStop(childStopFailures, projectId, run, 'cancel production', productionRunId, () => deps.cancelProduction(projectId, productionRunId));
}
sunoControllers.get(run.id)?.abort();
await cancelLocalSongJob(projectId, out.run, childStopFailures);
return { project: out.project, run: presentAutonomousRun(out.run), childStopFailures };
}
// ---- production completion -------------------------------------------------------
const PRODUCTION_PARKED = new Set(['limit-reached', 'blocked', 'needs-replan', 'needs-human', 'stopped']);
/**
* A run whose director chose no generation limit outgrows the default: when
* production stops at its generation limit with stills or clips still to make,
* the limit becomes what is spent plus two per shot left (a retry or
* regeneration each), within the bound, and production resumes. Returns
* whether it did; a chosen limit, or one already that high, parks as before.
*/
async function raiseSizedLimit(projectId, runId, run, project, production) {
const limit = production.limits?.maxGenerations || 0;
const used = production.usage?.generations || 0;
if (!run.brief.sizedGenerations || used < limit) return false;
const targets = productionTargets(project);
const left = targets.frame.filter((scene) => !scene.referenceImageId).length
+ (production.stopBefore === 'clips' ? 0 : targets.clip.filter((scene) => !scene.videoHistoryId).length);
const raised = Math.min(used + left * 2, AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.max);
if (raised <= limit) return false;
const resumed = await deps.resumeProduction(projectId, runId, { acceptBasis: true, limits: { maxGenerations: raised } })
.then(() => true, (err) => { console.warn(`⚠️ Autonomous music video ${short(run.id)} could not raise its generation limit: ${err.message}`); return false; });
if (resumed) console.log(`🎬 Autonomous music video ${short(run.id)} raised its default generation limit to ${raised} for ${left} shot${left === 1 ? '' : 's'} left`);
return resumed;
}
// ---- a blocked production run, settled by the run itself --------------------------
// A run set to approve does not stop production for the director: a staled art or
// storyboard approval is reviewed and approved again (settleProductionStage), and
// in an orchestrated run a failed pilot is repaired and generated again, up to
// `limits.maxReviewAttempts` repairs per pilot, then its last take is accepted
// with the open findings noted; a passing pilot is then approved as the proof
// from the pilot review's own evidence. Anything else parks for the director.
const CLIP_FIXES_MAX = 1000;
const settlingProduction = new Set();
/** A pilot whose review of its current inputs and media did not pass. */
function failedPilot(project, production) {
for (const pilot of production.pilot?.scenes || []) {
if (currentPilotPass(project, pilot)) continue;
const review = (project.autoReviews || []).find((r) => r.id === pilot.reviewRunId);
const result = review?.attempts?.at(-1)?.review;
if (result && result.verdict !== 'pass' && !['running', 'stopped', 'limit-reached'].includes(review.status)
&& pilot.inputBasis === pilotInputBasis(project, pilot.sceneId)) return { pilot, result };
}
return null;
}
/** The review's own words for what failed: its reason and blocking findings. */
const pilotProblems = (result) => [...new Set([result.reason, ...(result.findings || [])
.filter((f) => f.severity === 'blocking').map((f) => f.note)].filter((t) => typeof t === 'string' && t.trim()).map((t) => t.trim()))];
/**
* Repair a failed pilot as its review asks: the fix rides the shot's next
* prompt (a failed plate makes a new still too), which changes the pilot's
* inputs so production makes it again and reviews the new take. Once the
* pilot's repairs are spent, the last take is accepted with the findings noted.
*/
async function repairPilot(projectId, run, productionRunId, { pilot, result }) {
const project = await getProject(projectId);
const scene = (project.scenes || []).find((s) => s.sceneId === pilot.sceneId);
if (!scene) return false;
const repair = pilotRepair(result, scene, project);
const problems = pilotProblems(result).join(' ') || `The pilot review returned ${result.verdict}.`;
const spent = ((await latestRun(projectId))?.orchestration?.reviews || [])
.filter((r) => r.checkpoint === 'pilot' && r.sceneId === pilot.sceneId && r.verdict === 'revise').length;
if (spent < reviewLimit(run)) {
const at = new Date().toISOString();
const slot = repair.category === 'plate' ? 'stillFixes' : 'clipFixes';
const { rejected } = await mutateProjectRecord(projectId, (current) => ({ project: { ...current, scenes: (current.scenes || []).map((s) => {
if (s.sceneId !== pilot.sceneId) return s;
// Earlier fixes stay in the prompt so a repair never undoes the last one; the newest win the length cap.
const text = [s[slot]?.text, problems].filter(Boolean).join(' ');
return { ...s, ...(slot === 'stillFixes' ? { referenceImageId: null } : {}), [slot]: { text: text.slice(-(slot === 'stillFixes' ? STILL_FIXES_MAX : CLIP_FIXES_MAX)), at } };
}) } }), { runId: run.id });
if (rejected) {
// Nothing landed, so production would make the same take again: leave it to the director.
await recordReview(projectId, { checkpoint: 'pilot', sceneId: pilot.sceneId, verdict: 'revise',
notes: trimTo(`Pilot ${scene.label || pilot.sceneId}: ${repair.category} repair not applied; ${nameShots(project, [pilot.sceneId])} is locked by an approval this run did not give. Unlock it to repair. ${problems}`, 1500),
changes: [trimTo(`${pilot.sceneId}: ${problems}`, 300)] });
return false;
}
await recordReview(projectId, { checkpoint: 'pilot', sceneId: pilot.sceneId, verdict: 'revise',
notes: trimTo(`Pilot ${scene.label || pilot.sceneId}: ${repair.category} repair (${spent + 1} of ${reviewLimit(run)}), generated again with the fix. ${problems}`, 1500),
changes: [trimTo(`${pilot.sceneId}: ${problems}`, 300)] });
return true;
}
const note = trimTo(`Revision limit reached; accepted the last take with open findings: ${problems}`, 1000);
await mutateProjectRecord(projectId, (current) => acceptProductionPilot(current, productionRunId, pilot.sceneId, { by: 'orchestrator', note }));
await recordReview(projectId, { checkpoint: 'pilot', sceneId: pilot.sceneId, verdict: 'approve', notes: note });
return true;
}
/** Approve the rendered pilot as the proof, from the machine evidence of its passing (or accepted) review. */
async function approvePilotProof(projectId, run, production) {
const project = await getProject(projectId);
const pilots = production.pilot?.scenes || [];
const readiness = productionReadiness(project);
const excerpt = (project.excerpts || []).find((e) => e.id === project.productionReview?.proof?.excerptId);
if (readiness.proof.approved || readiness.proof.problems.length || !excerpt?.filename
|| !pilots.length || !pilots.every((pilot) => currentPilotPass(project, pilot))) return false;
const verdicts = pilots.map((pilot) => {
const result = (project.autoReviews || []).find((r) => r.id === pilot.reviewRunId)?.attempts?.at(-1)?.review || {};
const checks = Object.entries(result.checks || {}).map(([check, value]) => `${check} ${value}`);
return { pilot, result, checks, accepted: result.verdict !== 'pass' };
});
const audio = ['audioSync', 'lipSync'];
const visualReview = verdicts.map(({ pilot, result, checks, accepted }) => `Pilot ${pilot.sceneId} (${pilot.operation}): ${accepted ? 'accepted at the revision limit' : 'passed'}`
+ `${checks.length ? `; checks ${checks.join(', ')}` : ''}${result.reason ? `. ${result.reason}` : ''}`).join(' ');
const audioReview = verdicts.map(({ pilot, result }) => `Pilot ${pilot.sceneId} audio: ${audio.map((check) => `${check} ${result.checks?.[check] || 'not checked'}`).join(', ')}`).join(' ');
const open = verdicts.filter((v) => v.accepted).map((v) => v.pilot.accepted?.note).filter(Boolean);
const limitations = trimTo(['Machine review of the rendered pilot by the run\'s orchestrator reviewer; no human playback.', ...open].join(' '), 4000);
await deps.approveProductionReview(projectId, { stage: 'proof', basis: readiness.basis.proof, approvedBy: 'orchestrator', reviewer: orchestratorIdentity(run),
proofReview: { method: 'machine', watchedWithAudio: false, excerptId: excerpt.id, filename: excerpt.filename,
machineEvidence: { visualReview: trimTo(`Rendered pilot review. ${visualReview}`, 8000), audioReview: trimTo(`Audio checks from the pilot review. ${audioReview}`, 8000), limitations } } });
await recordReview(projectId, { checkpoint: 'proof', verdict: 'approve', notes: trimTo(`Approved the rendered pilot from its review. ${limitations}`, 1500) });
return true;
}
/**
* Production stopped (`blocked`, or `stopped` by its draft review) on something
* the run can settle itself. Returns true when it settled it and production
* resumed; false parks the run for the director as before.
*/
async function settleBlockedProduction(projectId, run, productionRunId) {
if (settlingProduction.has(productionRunId)) return true;
settlingProduction.add(productionRunId);
try {
let project = await getProject(projectId);
const production = (project.productionRuns || []).find((r) => r.id === productionRunId);
if (!production) return false;
const orchestrated = isOrchestratedRun(run);
const readiness = productionReadiness(project);
const retry = production.status === 'blocked' && orchestrated ? transientProductionRetry(production) : null;
let settled = false;
if (production.status === 'stopped') {
// Only the draft review's own refusal, never a director's stop: a footage
// project made before it composed its shots has no document to render.
settled = /no composition document/i.test(production.stopReason || '') && await ensureFootageComposition(projectId);
} else if (retry) {
// The machine failed, not the shot: generate it again, within the slot's retries.
console.log(`🔁 Autonomous music video ${short(run.id)} retrying ${retry.map((s) => `${s.kind} ${s.sceneId}`).join(', ')} after a transient failure (up to ${PRODUCTION_TRANSIENT_RETRIES} retries)`);
settled = true;
} else if (!readiness.storyboard.approved && (orchestrated || autoApproves(run, 'storyboard'))) {
project = await settleProductionStage(project, run, 'art');
project = await settleProductionStage(project, run, 'storyboard');
settled = productionReadiness(project).storyboard.approved;
} else if (readiness.storyboard.approved && orchestrated) {
const failed = failedPilot(project, production);
settled = failed ? await repairPilot(projectId, run, productionRunId, failed) : await approvePilotProof(projectId, run, production);
}
if (!settled || !await ownsProduction(projectId, productionRunId)) return false;
await deps.resumeProduction(projectId, productionRunId, { acceptBasis: true });
return true;
} catch (err) {
console.warn(`⚠️ Autonomous music video ${short(run.id)} could not settle blocked production: ${err.message}`);
return false;
} finally {
settlingProduction.delete(productionRunId);
}
}
/** The run still waits on this production run (a stop or cancel during a settle releases it). */
async function ownsProduction(projectId, productionRunId) {
const latest = projectAutonomousRun(await getProject(projectId));
return latest?.status === 'running' && latest.processId === PROCESS_ID && latest.output?.productionRunId === productionRunId;
}
/**
* A production run this autonomous run delegated to advanced. Mirrors its
* terminal state onto the run: completed → kick off the final render and
* finish; failed → failed; any parked state → needs-human (resume continues it).
*/
async function onProductionEvent({ projectId, runId, run: production }) {
// Production emits on every step; only a terminal or parked state concerns us, and
// the project is read only once one arrives.
if (!projectId || !(['completed', 'failed', 'canceled', 'awaiting-video'].includes(production?.status) || PRODUCTION_PARKED.has(production?.status))) return;
const project = await getProject(projectId).catch(() => null);
const run = projectAutonomousRun(project);
if (!run || run.stage !== 'produce' || run.output.productionRunId !== runId) return;
if (!['running', 'needs-human'].includes(run.status)) return;
const reason = trimTo(production.stopReason || production.error || '', 500);
if (production.status === 'completed') {
// A repeated completion event must not start a second render.
if (run.output.renderJobId) return;
await finishFromProduction(projectId, runId, { status: 'running', processId: PROCESS_ID });
} else if (production.status === 'failed') {
await park(projectId, 'failed', { error: reason || 'Production failed', errorCode: 'PRODUCTION_FAILED' });
} else if (production.status === 'canceled') {
// Production canceled on its own (not by canceling this run): park, so Resume can adopt
// the director's replacement run or start a new one.
await park(projectId, 'needs-human', { error: reason || 'Production was canceled', errorCode: 'PRODUCTION_CANCELED' });
} else if (production.status === 'awaiting-video') {
if (run.status === 'running') await settleStills(projectId, run, runId);
} else if (production.status === 'limit-reached' && run.status === 'running' && await raiseSizedLimit(projectId, runId, run, project, production)) {
// The default generation limit grew to the planned shots and production goes on.
} else if (['blocked', 'stopped'].includes(production.status) && run.status === 'running' && await settleBlockedProduction(projectId, run, runId)) {
// A run set to approve settled the stop itself and production goes on.
} else if (PRODUCTION_PARKED.has(production.status) && run.status === 'running') {
await park(projectId, 'needs-human', { error: reason || `Production is ${production.status}`, errorCode: 'PRODUCTION_PARKED' });
}
}
/**
* The job id of a completed production run's own final render (code-first runs
* render the accepted document themselves), or null when there is none or it is
* no longer the project's current final video: a later render replaced it, the
* selected document changed, or the film's dependencies moved since it rendered.
*/
function currentProductionRenderJobId(project, productionRunId) {
const production = (project.productionRuns || []).find((r) => r.id === productionRunId);
const render = production?.finalRender;
if (render?.status !== 'completed' || !render.jobId || project.renderHistoryId !== render.jobId) return null;
if (production.documentCheckpoint?.directory !== project.composition?.document?.directory) return null;
return project.renderDependencies && !musicVideoDependencyChanges(project, project.renderDependencies).length ? render.jobId : null;
}
/**
* Production completed: adopt its own final render when it is still current
* (the reconcile then finishes on it, final review included), otherwise render
* the film — legacy and footage-only runs leave no render behind.
*/
async function finishFromProduction(projectId, productionRunId, patch = {}) {
const adopted = currentProductionRenderJobId(await getProject(projectId), productionRunId);
await patchRun(projectId, () => ({ ...patch, output: { productionDone: true, ...(adopted ? { renderJobId: adopted } : {}) } }));
if (adopted) console.log(`🎬 Autonomous music video adopted production's final render [${short(adopted)}]`);
await reconcileFinalRender(projectId, { restart: true });
}
// ---- Cast & Sets completion ------------------------------------------------------
/**
* Settle a run waiting on Cast & Sets from the project's own record: still
* working → keep waiting; failed → park failed with its error; otherwise
* (review/approved/skipped) re-enter `produce`, which now has a guide to review.
*/
async function reconcileCastAndSets(projectId) {
const project = await getProject(projectId).catch(() => null);
const run = projectAutonomousRun(project);
if (!run || run.stage !== 'produce' || run.status !== 'running' || run.processId !== PROCESS_ID || run.stages.produce?.step !== CAST_STEP) return;
const stage = project.castAndSets;
if (CAST_SETS_WORKING.includes(stage?.status)) return;
if (stage?.status === 'failed') {
const error = trimTo(`Cast & Sets failed: ${stage.stopReason || stage.error || 'unknown error'}`, 500);
await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'failed', error, step: null }));
await park(projectId, 'failed', { error, errorCode: 'CAST_SETS_FAILED' });
return;
}
advanceInBackground(projectId);
}
musicVideoEvents.on('cast-and-sets', ({ projectId }) => {
if (!projectId) return;
reconcileCastAndSets(projectId).catch((err) => console.error(`❌ Autonomous music video could not settle on Cast & Sets: ${err.message}`));
});
// ---- final render completion -----------------------------------------------------
/** Park the run as failed on its final render, with the stage marked failed so Retry re-renders only. */
async function failFinalRender(projectId, message, errorCode = 'FINAL_RENDER_FAILED') {
// A cancel/stop that landed while the render prepared is not a failure.
if (projectAutonomousRun(await getProject(projectId))?.status !== 'running') return;
const error = trimTo(message, 500);
await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'failed', error, step: null }));
await park(projectId, 'failed', { error, errorCode });
}
// projectId -> the final review in flight, so a render event and a reconcile
// that both see the finished render share one look instead of reviewing twice.
const finalReviews = new Map();
async function completeFinalRender(projectId, run) {
if (isOrchestratedRun(run) && run.output.finalReviewedJobId !== run.output.renderJobId) {
if (finalReviews.has(projectId)) return finalReviews.get(projectId);
const review = (async () => {
await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'running', step: 'final-review' }));
const next = await orchestrateFinal(projectId, run);
await patchRun(projectId, () => ({ output: { finalReviewedJobId: run.output.renderJobId || null } }));
return next;
})();
finalReviews.set(projectId, review);
let next;
try { next = await review; } finally { finalReviews.delete(projectId); }
// Stopped or canceled while the orchestrator watched: leave that state alone.
if ((await latestRun(projectId))?.status !== 'running') return;
// A revision: the re-rendered film comes back here for the next review.
if (next === 'rerender') return startFinalRender(projectId, run);
if (next === 'wait') return;
}
await patchRun(projectId, (r) => ({
status: 'completed',
...stagePatch(r, 'produce', { status: 'done', finishedAt: new Date().toISOString(), error: null, step: null }),
error: null, errorCode: null,
}));
console.log(`✅ Autonomous music video ${short(run.id)} finished — final video rendered`);
}
/**
* The run, when it is running with its final-delivery checkpoint set
* (produceContinuation): rendering the film — with a job id or not yet started —
* reviewing it, or revising its footage. Deliberately broader than an active
* render: the revision handler is admitted through it too, and each caller adds
* its own identity and step checks.
*/
const runInFinalDelivery = (project) => {
const run = projectAutonomousRun(project);
return run?.status === 'running' && produceContinuation(run).finalDelivery ? run : null;
};
/**
* Settle a run waiting on its final render from the project's own record — the
* race where the render ended before its job id was stored, and a resume after
* a restart (the job died with the process). Still rendering → keep waiting;
* `renderHistoryId` equal to the job id → it finished; otherwise it failed, or
* with `restart` (an explicit resume, or production just completed) render again.
*/
async function reconcileFinalRender(projectId, { restart = false } = {}) {
const project = await getProject(projectId).catch(() => null);
const run = runInFinalDelivery(project);
if (!run) return;
const jobId = run.output.renderJobId || null;
if (jobId && (project.status === 'rendering' || (await deps.activeRenderJobId(projectId)) === jobId)) {
await patchRun(projectId, (r) => stagePatch(r, 'produce', { status: 'running', step: RENDER_STEP }));
return;
}
if (jobId && project.renderHistoryId === jobId) return completeFinalRender(projectId, run);
if (!restart) return failFinalRender(projectId, project.renderError || 'The final render did not finish');
return startFinalRender(projectId, run);
}
/**
* A footage project left in document mode with no document (projects created
* with a media mode used to default to it) cannot render; it is composed from its shots.
*/
async function ensureFootageComposition(projectId) {
const project = await getProject(projectId);
const composition = project?.composition;
if (composition?.mode !== 'document' || composition.document || composition.documentDraft
|| normalizeMusicVideoProductionPolicy(project.productionPolicy).strategy === 'code-first') return false;
// The manifest is replaced whole, so its cues, cutting and grade ride along.
await deps.updateProject(projectId, { composition: { ...composition, mode: 'composed' } });
// No one reviewed this switch, so the approvals it would stale carry over.
await mutateProjectRecord(projectId, (current) => ({ project: carryProductionApprovals(project, current, 'Composed the footage of a project with no composition document') }));
console.log(`🎬 Autonomous music video set ${short(projectId)} to compose its footage (it had no composition document)`);
return true;
}
/** Render the film (again) and wait for the render's own event. */
async function startFinalRender(projectId, run) {
if (!await settleOverlayText(projectId, run)) return;
if (!rendersFromCode(await getProject(projectId), run)) await ensureFootageComposition(projectId);
const render = await deps.renderVideo(projectId).catch((err) => ({ error: err }));
if (render.error) return failFinalRender(projectId, `The final render did not start: ${render.error.message}`, render.error.code || 'FINAL_RENDER_FAILED');
let stopped = false;
await patchRun(projectId, (r) => {
stopped = r.status !== 'running';
return stopped ? {} : { output: { renderJobId: render.jobId || null }, ...stagePatch(r, 'produce', { status: 'running', error: null, step: RENDER_STEP }), error: null, errorCode: null };
});
if (stopped) {
// Canceled/stopped while the render prepared: the cancel saw no job id, so stop the fresh job here.
if (render.jobId) await deps.cancelRender(render.jobId).catch((err) => console.warn(`⚠️ Autonomous music video ${short(run.id)} could not cancel render ${render.jobId}: ${err.message}`));
return;
}
console.log(`🎬 Autonomous music video ${short(run.id)} is rendering the final video`);
// A render that settled before its id was stored.
await reconcileFinalRender(projectId);
}
/**
* The orchestrator's footage revision ended. One that handed off to a human
* (`needs-human`) or failed leaves its revision open, so the run parks with the
* reason and keeps the revision's id: Resume, once the director has finished
* it, renders and reviews the film again. Otherwise the film is rendered again
* for the next final review; a run it left resumable (stopped or
* limit-reached) is closed first so it does not hold the revision slot.
*/
async function onAutoReviewEvent({ projectId, runId, run: review }) {
if (!projectId || !runId || !review || review.status === 'running') return;
const project = await getProject(projectId).catch(() => null);
const run = runInFinalDelivery(project);
if (!run || run.output.finalAutoReviewId !== runId || run.stages.produce?.step !== FINAL_REVISION_STEP) return;
if (['needs-human', 'failed'].includes(review.status)) {
const reason = [review.stopReason, review.error].find((v) => typeof v === 'string' && v.trim()) || `the revision ${review.status === 'failed' ? 'failed' : 'needs a director'}`;
await park(projectId, 'needs-human', { error: trimTo(`The revision of the final video was left for a director: ${reason}`, 500), errorCode: 'FINAL_REVISION_NEEDS_HUMAN' });
return;
}
await patchRun(projectId, () => ({ output: { finalAutoReviewId: null } }));
if (['stopped', 'limit-reached'].includes(review.status)) {
await deps.cancelAutoReview(projectId, runId).catch((err) => console.warn(`⚠️ Autonomous music video ${short(run.id)} could not close its revision: ${trimTo(err.message, 200)}`));
}
console.log(`🎬 Autonomous music video ${short(run.id)} revision ${review.status}; rendering the film again`);
await startFinalRender(projectId, run);
}
async function onRenderEvent({ projectId, jobId, status, error }) {
if (!projectId || !jobId) return;
const project = await getProject(projectId).catch(() => null);
const run = runInFinalDelivery(project);
if (!run || run.output.renderJobId !== jobId) return;
if (status === 'completed') return completeFinalRender(projectId, run);
return failFinalRender(projectId, error || (status === 'canceled' ? 'The final render was cancelled' : 'The final render failed'));
}
musicVideoEvents.on('render', (event) => {
onRenderEvent(event).catch((err) => console.error(`❌ Autonomous music video could not settle on its final render: ${err.message}`));
});
musicVideoEvents.on('auto-review', (event) => {
onAutoReviewEvent(event).catch((err) => console.error(`❌ Autonomous music video could not settle on its final revision: ${err.message}`));
});
musicVideoEvents.on('production', (event) => {
onProductionEvent(event).catch((err) => console.error(`❌ Autonomous music video could not settle on production: ${err.message}`));
});
/**
* Resolves once no background advance loop is in flight, including one a
* resume started while the previous settled. Bounded, so a stage that never
* returns fails the caller's teardown loudly instead of hanging it.
*/
async function settleBackground(timeoutMs = 10_000) {
let timer;
const deadline = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`Autonomous advance did not settle within ${timeoutMs}ms`)), timeoutMs); });
try {
await Promise.race([(async () => { while (inflight.size) await Promise.allSettled([...inflight.values()]); })(), deadline]);
} finally {
clearTimeout(timer);
}
}
export const __testing = { onProductionEvent, onRenderEvent, onAutoReviewEvent, advance, settleBackground };