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
/**
* Music Video Routes — REST surface for the director scene board (#1760, Phase 1).
*
* Project CRUD + per-scene board operations + a synchronous beat/tempo/section
* analysis endpoint that runs the offline analyzer (Phase 0) on the project's
* audio. Per-scene reference-frame + i2v generation and the beat-snapped render
* are filed follow-ups; this surface covers the director MVP up to "scenes
* arranged against the beat grid".
*/
import { existsSync } from 'fs';
import { unlink } from 'fs/promises';
import { pipeline } from 'stream/promises';
import { Router } from 'express';
import { musicVideoRenderCleanupSchema, musicVideoRenderPreviewSchema, musicVideoSongStyleSunoSchema, musicVideoProjectListQuerySchema, musicVideoFinishedOutsideSchema, musicVideoProductionDraftSchema, musicVideoProductionApprovalSchema, musicVideoShotLockSchema, musicVideoProductionProofSchema, musicVideoProductionImportSchema, musicVideoContinueShotSchema, musicVideoPoolUseSchema, musicVideoPoolMarkSchema, musicVideoPoolSearchQuerySchema, musicVideoPoolDeleteSchema, musicVideoPoolImportSchema, musicVideoLibrarySearchQuerySchema, musicVideoPoolAddSchema, musicVideoProductionFeedbackSchema, musicVideoProductionFeedbackResolutionSchema, musicVideoLyricAnchorSyncSchema, musicVideoProductionReviseSchema, musicVideoProductionRevertSchema } from '../lib/musicVideoValidation.js';
import { productionReadiness } from '../services/musicVideo/productionReview.js';
import { presentMusicVideoDependencies } from '../lib/musicVideoDependencies.js';
import { finishedOutsideBlocker } from '../lib/musicVideoFinishedOutside.js';
import { getProductionReview, saveProductionDraft, prepareProductionReview, approveProductionReview, lockProductionShots, renderProductionProof, requireProductionReviewer, importProductionPlanning, bindProductionShot, addProductionFeedback, closeProductionFeedback, syncLyricAnchors, removeStaleStoryboardRows, reviseProductionFromFeedback, revertProductionInput } from '../services/musicVideo/productionReviewService.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
import {
validateRequest,
musicVideoAudioTimingPreviewSchema,
musicVideoAudioTimingApplySchema,
musicVideoProjectCreateSchema,
musicVideoProjectCloneSchema,
musicVideoProjectUpdateSchema,
musicVideoSceneCreateSchema,
musicVideoSceneUpdateSchema,
musicVideoSceneReorderSchema,
musicVideoSceneSplitSchema,
musicVideoSceneStartSchema,
musicVideoPlanRequestSchema,
musicVideoManualAnalysisSchema,
musicVideoTranscribeMidiRequestSchema,
musicVideoLyricsImportSchema,
musicVideoLyricsImportTrackSchema,
musicVideoLyricsAlignSchema,
musicVideoTakeInputSchema,
musicVideoTakeReviewSchema,
musicVideoHandoffImportSchema,
musicVideoTreatmentUpdateSchema,
musicVideoTreatmentCompileSchema,
musicVideoTreatmentApplySchema,
musicVideoTreatmentProofReviewSchema,
musicVideoExcerptRequestSchema,
musicVideoSocialCutsQuerySchema,
musicVideoPublishCopyPatchSchema,
musicVideoPublishCopyDraftSchema,
musicVideoPromotionPlanSchema,
musicVideoPublishThumbnailSchema,
musicVideoCoverArtComposeSchema,
musicVideoYoutubeThumbnailComposeSchema,
musicVideoYoutubeThumbnailPaintSchema,
musicVideoYoutubeThumbnailPaintPreviewSchema,
musicVideoCoverArtGenerateSchema,
musicVideoCoverDesignSaveSchema,
musicVideoArtistStyleSaveSchema,
musicVideoArtistStyleDeleteSchema,
musicVideoCoverArtDesignSchema,
musicVideoPublishTargetSchema,
musicVideoPublishPrepareSchema,
musicVideoPublishPlatformsPatchSchema,
musicVideoPublishPostSchema,
musicVideoPublishCrossLinksSchema,
musicVideoCrossLinkTargetSchema,
musicVideoCrossLinkEditSchema,
musicVideoCodeGenerateSchema,
musicVideoExcerptNoteSchema,
musicVideoExcerptNoteUpdateSchema,
musicVideoDependencyRepairSchema,
musicVideoRevisionStartSchema,
musicVideoPerformanceRepairSchema,
musicVideoRevisionReleaseSchema,
musicVideoAutoReviewStartSchema,
musicVideoAutoReviewResumeSchema,
musicVideoProductionStartSchema,
musicVideoProductionResumeSchema,
musicVideoAutonomousStartSchema,
musicVideoAutonomousResumeSchema,
musicVideoDevArtifactImportSchema,
musicVideoDevArtifactNoteSchema,
musicVideoDevArtifactNoteUpdateSchema,
musicVideoDevArtifactReviewSchema,
musicVideoDevArtifactFileQuerySchema,
musicVideoCastAndSetsStartSchema,
musicVideoCastAndSetsDirectionEditSchema,
musicVideoCastAndSetsFeedbackSchema,
musicVideoCastAndSetsRegenerateSchema,
musicVideoDocumentDirectoryImportSchema,
musicVideoDocumentFileQuerySchema,
musicVideoDocumentTemplateSchema,
musicVideoDocumentDraftQuerySchema,
musicVideoDocumentCandidateSchema,
musicVideoMixedMediaRegenerateSchema,
isPaginationRequested,
parsePagination,
} from '../lib/validation.js';
import { recordRenderPinFields } from '../lib/sharedSchemas.js';
import { PATHS } from '../lib/fileUtils.js';
import { resolveGalleryImage } from '../lib/pathSafety.js';
import { uploadSingle } from '../lib/multipart.js';
import { isSupportedMusicUpload, MUSIC_UPLOAD_MAX_BYTES } from '../services/pipeline/musicLibrary.js';
import { attachVocalStem, detachVocalStem } from '../services/musicVideo/vocalStem.js';
import {
listProjects,
listProjectPage,
getProject,
createProject,
cloneProject,
updateProject,
deleteProject,
setProjectAnalysis,
addProjectScene,
updateScene,
deleteScene,
reorderProjectScenes,
splitProjectScene,
mergeProjectNextScene,
mergeProjectPreviousScene,
moveProjectSceneStart,
setProjectMidiTranscription,
appendSceneTakes,
appendTakesAcrossScenes,
selectSceneTake,
placeMediaPoolItem,
markMediaPoolAssets,
reviewSceneTake,
rejectUnusedSceneTakes,
swapProjectSceneFrames,
refreshSongStyleFromSuno,
} from '../services/musicVideo/projects.js';
import { requireProject } from '../services/musicVideo/requireProject.js';
import { buildHandoffManifest, buildHandoffBundle, matchSceneByFileTag } from '../services/musicVideo/handoff.js';
import { getHistoryItem } from '../services/videoGen/history.js';
import {
startMidiTranscription,
attachMidiTranscriptionSseClient,
getActiveMidiTranscriptionJobId,
cancelMidiTranscription,
} from '../services/audioMidiTranscription.js';
import { analyzeAudioFileManual, buildManualAnalysisFromCached } from '../services/musicVideo/audioAnalysis.js';
import { analyzeProjectSong, resolveProjectAudioPath } from '../services/musicVideo/projectAudio.js';
import { listInFlightSceneJobs } from '../services/musicVideo/sceneJobs.js';
import { getSharingCopy, prepareSharingCopy, sharingCopyDownload } from '../services/musicVideo/sharingCopy.js';
import { renderMusicVideo, attachRenderSseClient, cancelRender, getActiveRenderJobId } from '../services/musicVideo/render.js';
import { prepareCodeRender } from '../services/musicVideo/codeRender.js';
import { generateMusicVideoCode, regenerateMusicVideoCodeSection } from '../services/musicVideo/codeGeneration.js';
import { startExcerptRender, attachExcerptRenderSseClient, cancelExcerptRender } from '../services/musicVideo/excerptRender.js';
import { deleteExcerpt, addReviewNote, editReviewNote, deleteReviewNote } from '../services/musicVideo/excerptService.js';
import { suggestSocialCuts } from '../services/musicVideo/socialCuts.js';
import { getActivePublishKitBuild, startPublishKitBuild, attachPublishKitSseClient, cancelPublishKitBuild, draftPublishKitCopy, updatePublishKitCopy, selectPublishKitThumbnail } from '../services/musicVideo/publishKit.js';
import { preparePublishDraft, previewPublishPost, discardPublishDraft, listPublishDrafts, recordPublishPost, removePublishPost, prepareCrossLinkEdit, setPublishCrossLinks } from '../services/musicVideo/publish/index.js';
import { getPublishPlatforms, updatePublishPlatforms, publishHistory } from '../services/musicVideo/publish/platforms.js';
import { listArtistStyles, saveArtistStyle, removeArtistStyle } from '../services/musicVideo/publish/artistStyles.js';
import { addCoverFont, coverFontPath, listCoverFonts, MAX_COVER_FONT_BYTES, removeCoverFont } from '../services/musicVideo/coverFonts.js';
import {
getDependencyImpact,
startDependencyRepair,
startRevision, resumeRevision, cancelRevision, releaseRevisionSection,
} from '../services/musicVideo/revisionService.js';
import {
startAutoReview, resumeAutoReview, stopAutoReview, cancelAutoReview,
} from '../services/musicVideo/autoReviewService.js';
import {
startProduction, resumeProduction, stopProduction, cancelProduction, getProduction,
} from '../services/musicVideo/productionService.js';
import {
startAutonomousVideo, getAutonomousRun, presentProjectAutonomousRun, resumeAutonomousVideo, stopAutonomousVideo, cancelAutonomousVideo,
} from '../services/musicVideo/autonomousService.js';
import { planProject } from '../services/musicVideo/planner.js';
import {
DOCUMENT_ZIP_MAX_BYTES,
detachDocument,
discardGeneratedDocument,
documentMimeType,
exportDocumentZip,
importDocumentDirectory,
importDocumentTemplate,
importDocumentZip,
upgradeDocumentEngine,
readDocumentManifest,
resolveDocumentFile,
} from '../services/musicVideo/compositionDocument.js';
import { buildDocumentPreview } from '../services/musicVideo/documentPreview.js';
import { acceptMixedMediaDocument, generateMixedMediaDocument, readMixedMediaCandidate, regenerateMixedMediaSection, reviseMixedMediaEvents } from '../services/musicVideo/documentGeneration.js';
import { isZipUpload } from '../lib/zipStream.js';
import { parseLyricCues } from '../services/musicVideo/timedText.js';
import {
attachLyricAlignSseClient,
cancelLyricAlign,
getActiveLyricAlignJobId,
startLyricAlign,
} from '../services/musicVideo/lyricAlignJob.js';
import { importTrackLyrics, MAX_LYRIC_CUES } from '../services/musicVideo/trackLyrics.js';
import { offsetLyricMarkers } from '../services/musicVideo/lyricMarkers.js';
import {
updateTreatment,
compileTreatment,
previewTreatmentApply,
applyTreatment,
reviewProof,
} from '../services/musicVideo/treatmentService.js';
import {
listDevArtifacts,
getDevArtifact,
importDevArtifact,
resolveDevArtifactDownload,
addNote as addDevArtifactNote,
setNoteResolved as setDevArtifactNoteResolved,
reviewArtifact as reviewDevArtifact,
removeDevArtifact,
} from '../services/musicVideo/devArtifactService.js';
import { devArtifactTypeFor } from '../services/musicVideo/devArtifacts.js';
import {
startCastAndSets,
editCastAndSetsDirection,
applyCastAndSetsFeedback,
removeCastAndSetsFeedbackEntry,
regenerateCastAndSets,
resumeCastAndSets,
approveCastAndSets,
reconfirmCastAndSets,
skipCastAndSets,
getCastAndSets,
presentProjectCastAndSets,
} from '../services/musicVideo/castAndSetsService.js';
import {
summarizeMusicVideoProject,
compareMusicVideoProjectsNewestFirst,
} from '../lib/musicVideoSummary.js';
const router = Router();
// #3231 Phase 4 — the per-record image render pin (`imageMode`/`imageModelId`,
// the shared universe/series/sprite field pair) on Music Video projects: scene
// reference-frame renders resolve through it (imageGen/prepareParams.js).
// Extended at the route layer — the same pattern as routes/universeBuilder/ —
// so the pin stays a route-level concern and musicVideoProjectCreateSchema keeps
// the shape peers sync against. (Since #3873 the fragment lives in the leaf
// sharedSchemas.js, so musicVideoValidation.js COULD import it without the
// TDZ cycle that re-exporting through validation.js used to cause — the route
// layer is now a choice, not a workaround.)
const projectCreateSchema = musicVideoProjectCreateSchema.extend(recordRenderPinFields);
const projectUpdateSchema = musicVideoProjectUpdateSchema.extend(recordRenderPinFields);
// Backward-compatible by default: returns the full projects array. When a client
// passes `limit`/`offset`, the response becomes the bounded
// `{ items, total, limit, offset }` envelope every paginated PortOS list shares.
// `summary=1` (#10169) swaps each record for its bounded summary projection —
// newest first, with a `nextCursor` — for the project index and header picker, so
// they never load every project's scenes, runs and reviews.
// Both pins are process-local, so only the server can say which stages a restart orphaned.
// Approvals decide stage completion and only the server computes them (#10136), so the read
// response carries `productionReadiness` — stages derive from one record, never "not done" while a
// second request is in flight. GET /:id/production-review still serves the full review payload.
// A restart archives a thumbnail paint without clearing `pending`. Heal on read,
// and only when one is present, so a project list does not load the image stack.
async function presentProjectForRead(project) {
let current = project;
if (project?.publishKit?.youtubeThumbnail?.pending) {
const { reconcileInterruptedYoutubeThumbnail } = await import('../services/musicVideo/youtubeThumbnail.js');
current = await reconcileInterruptedYoutubeThumbnail(project);
}
const presented = presentProjectAutonomousRun(presentProjectCastAndSets(presentMusicVideoDependencies(current)));
return { ...presented, productionReadiness: productionReadiness(presented) };
}
router.get('/', asyncHandler(async (req, res) => {
const query = validateRequest(musicVideoProjectListQuerySchema, req.query);
const summary = query.summary === '1' || query.summary === 'true';
if (summary || isPaginationRequested(query)) {
// The cursor is the next page's offset; `cursor` wins over `offset`.
const cursor = parseInt(query.cursor, 10);
const paging = parsePagination(summary && Number.isInteger(cursor) && cursor >= 0 ? { ...query, offset: String(cursor) } : query,
{ defaultLimit: 50, maxLimit: 500 });
const page = await listProjectPage({ ...paging, ...(summary ? { compare: compareMusicVideoProjectsNewestFirst } : {}) });
const presented = await Promise.all(page.items.map((project) => presentProjectForRead(project)));
const items = summary ? presented.map(project => summarizeMusicVideoProject(project, project.productionReadiness)) : presented;
// A deletion between header selection and hydration still consumes its slot.
const next = Math.min(page.offset + page.limit, page.total);
return res.json({ ...page, items, ...(summary ? { nextCursor: next < page.total ? String(next) : null } : {}) });
}
res.json(await Promise.all((await listProjects()).map((project) => presentProjectForRead(project))));
}));
// Bounded projection for the Tracks page MIDI read-through (#10203): the newest
// MIDI transcription per linked track, without shipping every full project record.
router.get('/midi-sources', asyncHandler(async (req, res) => {
const newest = new Map();
for (const p of await listProjects()) {
const midi = p.midiTranscription;
if (!p.trackId || !midi?.filename) continue;
const prev = newest.get(p.trackId);
if (!prev || (midi.createdAt || '') > (prev.midiTranscription.createdAt || '')) {
newest.set(p.trackId, {
trackId: p.trackId,
id: p.id,
name: p.name,
midiTranscription: { filename: midi.filename, model: midi.model, createdAt: midi.createdAt },
});
}
}
res.json([...newest.values()]);
}));
router.get('/:id', asyncHandler(async (req, res) => {
const p = await requireProject(req.params.id);
// Transient (never persisted): lets a reloaded page reattach to a running publishing-kit build.
const activePublishKitBuild = getActivePublishKitBuild(p.id);
const presented = await presentProjectForRead(p);
res.json(activePublishKitBuild ? { ...presented, activePublishKitBuild } : presented);
}));
router.post('/', asyncHandler(async (req, res) => {
const data = validateRequest(projectCreateSchema, req.body);
const project = await createProject(data);
res.status(201).json(project);
}));
router.post('/:id/song-revision', asyncHandler(async (req, res) => {
const { musicVideoSongDraftSchema } = await import('../lib/musicVideoValidation.js');
const fields = validateRequest(musicVideoSongDraftSchema, req.body);
const { saveSongRevision } = await import('../services/musicVideo/songRevision.js');
res.json(await saveSongRevision(req.params.id, fields));
}));
router.post('/:id/song-revision/generate', asyncHandler(async (req, res) => {
const { musicVideoSongActionSchema } = await import('../lib/musicVideoValidation.js');
const { revisionId } = validateRequest(musicVideoSongActionSchema, req.body);
const { generateSongRevision } = await import('../services/musicVideo/songRevision.js');
res.status(202).json(await generateSongRevision(req.params.id, revisionId));
}));
router.post('/:id/song-revision/cancel', asyncHandler(async (req, res) => {
const { musicVideoSongActionSchema } = await import('../lib/musicVideoValidation.js');
const { revisionId } = validateRequest(musicVideoSongActionSchema, req.body);
const { cancelSongRevision } = await import('../services/musicVideo/songRevision.js');
res.json(await cancelSongRevision(req.params.id, revisionId));
}));
router.post('/:id/song-revision/select', asyncHandler(async (req, res) => {
const { musicVideoSongSelectSchema } = await import('../lib/musicVideoValidation.js');
const { revisionId, songId } = validateRequest(musicVideoSongSelectSchema, req.body);
const { selectSongRevision } = await import('../services/musicVideo/songRevision.js');
res.json(await selectSongRevision(req.params.id, revisionId, songId));
}));
router.post('/:id/song-revision/track', asyncHandler(async (req, res) => {
const { musicVideoSongFromTrackSchema } = await import('../lib/musicVideoValidation.js');
const { trackId } = validateRequest(musicVideoSongFromTrackSchema, req.body);
const { reviseSongFromTrack } = await import('../services/musicVideo/songRevision.js');
res.status(201).json(await reviseSongFromTrack(req.params.id, { trackId }));
}));
router.post('/:id/song-revision/scenes', asyncHandler(async (req, res) => {
const { musicVideoSongSceneActionSchema } = await import('../lib/musicVideoValidation.js');
const body = validateRequest(musicVideoSongSceneActionSchema, req.body);
const { resolveSongRevisionScenes } = await import('../services/musicVideo/songRevision.js');
res.json(await resolveSongRevisionScenes(req.params.id, body));
}));
router.post('/:id/clone', asyncHandler(async (req, res) => {
const options = validateRequest(musicVideoProjectCloneSchema, req.body || {});
res.status(201).json(await cloneProject(req.params.id, options));
}));
router.patch('/:id', asyncHandler(async (req, res) => {
const data = validateRequest(projectUpdateSchema, req.body);
const updated = await updateProject(req.params.id, data);
res.json(updated);
}));
// Finished outside PortOS: the earlier steps count as done without forging approvals.
router.put('/:id/finished-outside', asyncHandler(async (req, res) => {
const { finished, note } = validateRequest(musicVideoFinishedOutsideSchema, req.body);
if (finished) {
const blocker = finishedOutsideBlocker(await getProject(req.params.id));
if (blocker) throw new ServerError(blocker, { status: 409, code: 'MUSIC_VIDEO_NO_FINAL_RENDER' });
}
const finishedOutside = finished ? { markedAt: new Date().toISOString(), ...(note ? { note } : {}) } : null;
await updateProject(req.params.id, { finishedOutside });
res.json(await presentProjectForRead(await getProject(req.params.id)));
}));
// Preview is read-only; Apply rechecks audio and the serialized project basis.
router.post('/:id/audio-timing/preview', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoAudioTimingPreviewSchema, req.body);
const { previewAudioTiming } = await import('../services/musicVideo/audioTiming.js');
res.json(await previewAudioTiming(req.params.id, input));
}));
router.post('/:id/audio-timing/apply', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoAudioTimingApplySchema, req.body);
const { applyAudioTiming } = await import('../services/musicVideo/audioTiming.js');
res.json(await applyAudioTiming(req.params.id, input));
}));
router.delete('/:id', asyncHandler(async (req, res) => {
await deleteProject(req.params.id);
res.json({ ok: true });
}));
// Optional vocal stem (#8977): a full-length bounce of the vocal on the
// master's timebase. Performance shots are conditioned on it instead of the
// mix; the master stays the project's audio. Same audio formats and size cap
// as a track upload.
const vocalStemUpload = uploadSingle('stem', {
limits: { fileSize: MUSIC_UPLOAD_MAX_BYTES },
fileFilter: (_req, file, cb) => {
if (isSupportedMusicUpload(file)) cb(null, true);
else cb(new ServerError('Unsupported audio format — accepted: MP3, WAV, M4A, OGG, FLAC', { status: 400, code: 'VALIDATION_ERROR' }));
},
});
router.post('/:id/vocal-stem', vocalStemUpload, asyncHandler(async (req, res) => {
if (!req.file) throw new ServerError('No vocal stem file uploaded', { status: 400, code: 'VALIDATION_ERROR' });
res.json(await attachVocalStem(req.params.id, { tempPath: req.file.path, originalName: req.file.originalname }));
}));
router.delete('/:id/vocal-stem', asyncHandler(async (req, res) => {
res.json(await detachVocalStem(req.params.id));
}));
// Separate the vocal from the song with demucs and attach it as the stem.
// Kickoff returns 202 + a jobId (a running separation for the project is
// re-attached, not doubled); progress streams over SSE. The first run
// installs demucs into its own venv — only ever from this explicit request.
// Lazy import: the demucs runner pulls the spawn/venv helpers only this needs.
router.post('/:id/vocal-stem/separate', asyncHandler(async (req, res) => {
const { startVocalSeparation } = await import('../services/musicVideo/vocalSeparation.js');
res.status(202).json(await startVocalSeparation(req.params.id));
}));
router.get('/vocal-stem/separate/:jobId/events', asyncHandler(async (req, res) => {
const { attachVocalSeparationSseClient } = await import('../services/musicVideo/vocalSeparation.js');
if (!attachVocalSeparationSseClient(req.params.jobId, res)) {
throw new ServerError('Vocal separation job not found or expired', { status: 404, code: 'NOT_FOUND' });
}
}));
router.post('/vocal-stem/separate/:jobId/cancel', asyncHandler(async (req, res) => {
const { cancelVocalSeparation } = await import('../services/musicVideo/vocalSeparation.js');
res.json({ ok: cancelVocalSeparation(req.params.jobId) });
}));
// Run the offline beat/tempo/section analysis and cache it on the project.
// Synchronous: the DSP pass over a song-length track is a couple of seconds, so
// it returns the updated project directly (the SSE-streamed render lands later).
router.post('/:id/analyze', asyncHandler(async (req, res) => {
res.json(await analyzeProjectSong(req.params.id));
}));
// Manual-tempo fallback: lets a director supply a known BPM + first-downbeat
// offset by ear when the auto-detector caches `bpm: null` (see
// services/musicVideo/audioAnalysis.js `estimateTempo` for why). Reuses the
// prior analysis's cached `sections`/`durationSec` when present — the UI only
// offers this after a prior `/analyze` call has cached them, so this is pure
// arithmetic in the common case rather than a second ffmpeg decode; it only
// falls back to decoding when no usable prior analysis exists.
router.post('/:id/analyze/manual', asyncHandler(async (req, res) => {
const { bpm, offsetSec } = validateRequest(musicVideoManualAnalysisSchema, req.body);
const project = await requireProject(req.params.id);
const cached = project.audioAnalysis;
const analysis = cached && Array.isArray(cached.sections) && typeof cached.durationSec === 'number'
? buildManualAnalysisFromCached(cached, { bpm, offsetSec })
: await analyzeAudioFileManual(await resolveProjectAudioPath(project), { bpm, offsetSec });
if (!analysis) {
throw new ServerError('Could not analyze audio (decode failed or ffmpeg unavailable)', { status: 422, code: 'ANALYZE_FAILED' });
}
const updated = await setProjectAnalysis(project.id, analysis, project);
res.json(updated);
}));
// Autonomous shot planner (#1855, the secondary "autonomous mode" path):
// propose one scene per analyzed audio section (energy-aware durations fall
// out of the cached section boundaries) and seed them onto the director
// scene board. Director-first — this only seeds editable scenes, same as a
// hand-added one. `seedPrompts` (default true) additionally best-effort asks
// the active/given AI provider for a first-pass framePrompt/prompt per scene;
// a missing provider or parse failure degrades to plain scenes rather than
// failing the request (see `promptsSeeded`/`promptsSkippedReason` in the body).
router.post('/:id/plan', asyncHandler(async (req, res) => {
const { seedPrompts, providerId, model, effort, mode } = validateRequest(musicVideoPlanRequestSchema, req.body || {});
const result = await planProject(req.params.id, { seedPrompts, providerId, model, effort, mode: mode ?? 'require' });
res.json(result);
}));
// --- Pre-production treatment (#8980) ---
// A structured brief, a compiled whole-song arc, per-shot direction keyed to
// the board's scene ids and a proof checklist (services/musicVideo/treatment.js).
// Every write names the revision it was made against; a stale one is a 409.
router.patch('/:id/treatment', asyncHandler(async (req, res) => {
const patch = validateRequest(musicVideoTreatmentUpdateSchema, req.body);
res.json(await updateTreatment(req.params.id, patch));
}));
// Compile is an explicit user action. `useAi: false` drafts deterministically
// with no provider call; otherwise the chosen (or active) provider refines the
// draft, and any failure degrades to the deterministic draft with a reason.
router.post('/:id/treatment/compile', asyncHandler(async (req, res) => {
const options = validateRequest(musicVideoTreatmentCompileSchema, req.body);
res.json(await compileTreatment(req.params.id, options));
}));
// Read-only: which scenes Apply would change, which hand-edited prompts it
// keeps, and whether a stale input blocks it.
router.get('/:id/treatment/apply-preview', asyncHandler(async (req, res) => {
res.json(await previewTreatmentApply(req.params.id));
}));
router.post('/:id/treatment/apply', asyncHandler(async (req, res) => {
const options = validateRequest(musicVideoTreatmentApplySchema, req.body);
res.json(await applyTreatment(req.params.id, options));
}));
router.post('/:id/treatment/proofs/:proofId/review', asyncHandler(async (req, res) => {
const review = validateRequest(musicVideoTreatmentProofReviewSchema, req.body);
res.json(await reviewProof(req.params.id, req.params.proofId, review));
}));
// Import timed lyric cues (#8964) from pasted LRC, SRT/WebVTT, or plain lines
// (plain lines arrive untimed, ready to be timed by hand). `replace` swaps the
// project's cue list; `append` adds after it. The cues persist through the
// ordinary project PATCH path, so ids/normalization match hand edits.
// Plain lines keep their section headers and stage directions as lyric
// markers anchored to the imported lines (lyricMarkers.js).
router.post('/:id/lyrics/import', asyncHandler(async (req, res) => {
const { format = 'auto', text, mode = 'replace' } = validateRequest(musicVideoLyricsImportSchema, req.body);
const project = await requireProject(req.params.id);
const { format: detected, cues, markers } = parseLyricCues(text, format);
if (cues.length === 0) {
throw new ServerError(`No lyric lines found in the ${detected} text`, { status: 422, code: 'NO_LYRICS' });
}
const existing = project.lyricCues || [];
const append = mode === 'append';
const lyricCues = append ? [...existing, ...cues] : cues;
if (lyricCues.length > MAX_LYRIC_CUES) {
throw new ServerError(`A project holds at most ${MAX_LYRIC_CUES} lyric cues`, { status: 400, code: 'VALIDATION_ERROR' });
}
const lyricMarkers = append
? [...(project.lyricMarkers || []), ...offsetLyricMarkers(markers, existing.length)]
: markers;
const updated = await updateProject(project.id, { lyricCues, lyricMarkers });
res.json({ project: updated, imported: cues.length, format: detected });
}));
// Import the linked track's lyric sheet ("Use track lyrics", and the
// autopilot kickoff with `mode: 'if-empty'`, which never replaces lines).
router.post('/:id/lyrics/import-track', asyncHandler(async (req, res) => {
const { mode = 'replace' } = validateRequest(musicVideoLyricsImportTrackSchema, req.body || {});
res.json(await importTrackLyrics(req.params.id, { mode }));
}));
// Word-level alignment (#9074) as a job (#10155). It runs when the director
// clicks Align words or a line's Re-align, when an autopilot run starts, and
// when the song is prepared after a track or lyrics arrive (song/prepare below). Kickoff returns 202 + a jobId; stages (model download %, decoding,
// transcribing window n/m) stream over SSE with cancel, and the terminal
// `complete` frame carries the updated project. One job per project: a second
// request returns the running job (`reused: true`). The first alignment
// provisions MMS_FA only on demand. Explicit separateVocals consent creates
// a missing stem with Demucs first; older master-only callers retain Whisper.
router.post('/:id/lyrics/align', asyncHandler(async (req, res) => {
const { cueId, separateVocals, retimeSong } = validateRequest(musicVideoLyricsAlignSchema, req.body || {});
res.status(202).json(await startLyricAlign(req.params.id, { cueId, separateVocals, retimeSong }));
}));
// Re-read the song's Suno style (excluded styles included) from its song link,
// for a song imported before they were captured. Updates the linked track too.
router.post('/:id/song-style/suno', asyncHandler(async (req, res) => {
const { url } = validateRequest(musicVideoSongStyleSunoSchema, req.body ?? {});
res.json(await refreshSongStyleFromSuno(req.params.id, url));
}));
// After a track is attached or lyrics are imported (the director's own action),
// analyze the song if it has no analysis and start word alignment when the
// lines were never aligned. Returns the project and the alignment job to follow.
router.post('/:id/song/prepare', asyncHandler(async (req, res) => {
const { autoPrepareSong } = await import('../services/musicVideo/songAutoPrepare.js');
res.json(await autoPrepareSong(req.params.id));
}));
// The lyric timing playthrough: the aligned words drawn by the shipped template over a
// plain frame, laid out as scenes, for checking word timing before any picture exists.
router.get('/:id/lyrics/playthrough/preview', asyncHandler(async (req, res) => {
const { buildLyricPlaythroughPreview } = await import('../services/musicVideo/lyricPlaythrough.js');
res.json(await buildLyricPlaythroughPreview(await requireProject(req.params.id)));
}));
// The same words alone on a transparent page, laid over the storyboard animatic's frames.
router.get('/:id/lyrics/overlay/preview', asyncHandler(async (req, res) => {
const { buildLyricPlaythroughPreview } = await import('../services/musicVideo/lyricPlaythrough.js');
res.json(await buildLyricPlaythroughPreview(await requireProject(req.params.id), { overlay: true }));
}));
router.get('/lyrics/align/:jobId/events', (req, res) => {
if (!attachLyricAlignSseClient(req.params.jobId, res)) {
throw new ServerError('Alignment job not found or expired', { status: 404, code: 'NOT_FOUND' });
}
});
router.post('/lyrics/align/:jobId/cancel', (req, res) => {
res.json({ ok: cancelLyricAlign(req.params.jobId) });
});
// Read-only: the project's live alignment, vocal-separation and MIDI jobs on
// this instance (null when none), so a reloaded Setup reattaches to each
// instead of POSTing a new run.
router.get('/:id/active-jobs', asyncHandler(async (req, res) => {
const { getActiveVocalSeparationJobId } = await import('../services/musicVideo/vocalSeparation.js');
res.json({
alignment: getActiveLyricAlignJobId(req.params.id),
separation: getActiveVocalSeparationJobId(req.params.id),
midi: getActiveMidiTranscriptionJobId(req.params.id),
});
}));
// --- Audio → MIDI transcription (MuScriptor) ---
// Transcribe the project's source audio into a .mid via the local MuScriptor
// sidecar. Kickoff returns 202 + a jobId (503 with the install hint when the
// venv isn't provisioned); progress streams over SSE. Unlike the rounds path
// (where the client persists on Save), the terminal `complete` frame here
// carries the server-persisted pointer — the project record isn't an editor
// draft, so the server lands `midiTranscription` on completion and the frame
// includes it for the client to merge.
router.post('/:id/transcribe-midi', asyncHandler(async (req, res) => {
const { model } = validateRequest(musicVideoTranscribeMidiRequestSchema, req.body || {});
const project = await requireProject(req.params.id);
const audioPath = await resolveProjectAudioPath(project);
const projectId = project.id;
// Audio-source identity at kickoff — the completion callback re-checks it so
// a transcription of the OLD track can't land on a project whose audio was
// swapped mid-run (another client / peer sync). applyProjectPatch clears
// midiTranscription on the swap; without this guard the in-flight job would
// reintroduce the stale pointer right after.
const sourceTrackId = project.trackId ?? null;
const sourceUpload = project.uploadedAudioFilename ?? null;
res.status(202).json(await startMidiTranscription({
audioPath,
outputName: `${project.name || 'music-video'}-midi`,
model,
ownerKey: projectId,
// Land the .mid in the music dir (not uploads) so the peer-sync asset
// manifest federates it with the project's other audio — the manifest
// only ships known asset kinds/directories, and `music` is one.
destDir: PATHS.music,
onComplete: async ({ filename, model: usedModel }) => {
const current = await getProject(projectId);
if (!current) throw new Error('Project was deleted during transcription');
if ((current.trackId ?? null) !== sourceTrackId || (current.uploadedAudioFilename ?? null) !== sourceUpload) {
// The service deletes the orphaned .mid and reports a discarded (not
// "ready") completion to the client.
return { discarded: true, reason: `audio source of ${projectId} changed mid-transcription` };
}
const midiTranscription = { filename, model: usedModel, createdAt: new Date().toISOString() };
await setProjectMidiTranscription(projectId, midiTranscription);
return { midiTranscription };
},
}));
}));
// Two-segment paths — distinct from the one-segment GET /:id project read.
router.get('/transcribe-midi/:jobId/events', (req, res) => {
if (!attachMidiTranscriptionSseClient(req.params.jobId, res)) {
throw new ServerError('Transcription job not found or expired', { status: 404, code: 'NOT_FOUND' });
}
});
router.post('/transcribe-midi/:jobId/cancel', (req, res) => {
res.json({ ok: cancelMidiTranscription(req.params.jobId) });
});
// --- Render (#1760, Phase 2) ---
// Private local export; no publication or provider submission.
router.get('/:id/sharing-copy', asyncHandler(async (req, res) => {
res.json(await getSharingCopy(req.params.id));
}));
router.post('/:id/sharing-copy', asyncHandler(async (req, res) => {
res.status(202).json(await prepareSharingCopy(req.params.id));
}));
router.get('/:id/sharing-copy/download', asyncHandler(async (req, res) => {
const { file, copy, modifiedAt } = await sharingCopyDownload(req.params.id);
let stream;
const abort = () => { if (!res.writableFinished) stream?.destroy(); };
try {
if (req.aborted || res.destroyed) return;
const etag = `"${copy.hash}"`;
res.attachment(copy.filename).type('video/mp4');
res.set({ 'Cache-Control': 'private, no-store', 'Accept-Ranges': 'bytes', ETag: etag, 'Last-Modified': modifiedAt.toUTCString() });
const matches = value => value === '*' || value?.split(',').some(tag => tag.trim() === etag);
const unmodified = Date.parse(req.get('If-Unmodified-Since'));
if ((req.get('If-Match') && !matches(req.get('If-Match'))) || (!req.get('If-Match') && Number.isFinite(unmodified) && Math.floor(modifiedAt.getTime() / 1000) > Math.floor(unmodified / 1000))) {
res.status(412).end(); return;
}
if (req.fresh) { res.status(304).end(); return; }
let start = 0; let end = copy.bytes - 1;
const ifRange = req.get('If-Range');
const rangeCurrent = !ifRange || ifRange === etag || (!ifRange.includes('"') && Number.isFinite(Date.parse(ifRange)) && modifiedAt.getTime() <= Date.parse(ifRange) + 999);
if (req.get('Range') && rangeCurrent) {
const ranges = req.range(copy.bytes, { combine: true });
if (ranges === -1) { res.set('Content-Range', `bytes */${copy.bytes}`); res.status(416).end(); return; }
// Like res.download, malformed/non-byte/multipart ranges fall back to 200.
if (Array.isArray(ranges) && ranges.type === 'bytes' && ranges.length === 1) {
({ start, end } = ranges[0]);
res.status(206).set('Content-Range', `bytes ${start}-${end}/${copy.bytes}`);
}
}
res.set('Content-Length', String(end - start + 1));
if (req.method === 'HEAD') { res.end(); return; }
stream = file.createReadStream({ start, end, autoClose: false });
res.once('close', abort);
req.once('aborted', abort);
await pipeline(stream, res);
} finally {
res.off('close', abort);
req.off('aborted', abort);
stream?.destroy();
await file.close();
}
}));
// Assemble the scenes' i2v clips into one MP4 over the track as the master audio
// bed. Kickoff returns { jobId }; progress streams over SSE (mirrors
// videoTimeline). Per-project mutex returns 409 with the live jobId for re-attach.
// A shot-by-shot render started here picks up again after a server restart.
router.post('/:id/render', asyncHandler(async (req, res) => {
res.json(await renderMusicVideo(req.params.id, { resumable: true }));
}));
// Read-only: the live final-render job for a project (null when none runs on
// this instance), so a reloaded page re-attaches without POSTing a new render.
router.get('/:id/render', (req, res) => {
res.json({ jobId: getActiveRenderJobId(req.params.id) });
});
// The shot, look and cleanup reads plan the render, whose performance-take
// review decodes the song master with ffmpeg; only a caller with host control
// starts that decode (#13156). Others get the plan with the take unchecked.
let authGateModule;
const planOptions = async (req) => {
const { requestHasHostControl } = await (authGateModule ??= import('../services/authGate.js'));
return { decode: requestHasHostControl(req) };
};
router.get('/:id/render-cleanup', asyncHandler(async (req, res) => {
const { getRenderCleanup } = await import('../services/musicVideo/renderCleanup.js');
res.json(await getRenderCleanup(req.params.id, await planOptions(req)));
}));
router.post('/:id/render-cleanup', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoRenderCleanupSchema, req.body ?? {});
const { cleanupRenders } = await import('../services/musicVideo/renderCleanup.js');
res.json(await cleanupRenders(req.params.id, input));
}));
// Per-shot render segments (shotSegments.js): every shot's cache state, one
// shot's render started or stopped, and a rendered shot's silent segment.
router.get('/:id/shot-renders', asyncHandler(async (req, res) => {
const { getShotRenderStatus } = await import('../services/musicVideo/shotSegments.js');
res.json(await getShotRenderStatus(req.params.id, await planOptions(req)));
}));
router.post('/:id/shots/:sceneId/render', asyncHandler(async (req, res) => {
const { startShotRender } = await import('../services/musicVideo/shotSegments.js');
res.status(202).json(await startShotRender(req.params.id, req.params.sceneId));
}));
router.post('/:id/shots/:sceneId/render/cancel', asyncHandler(async (req, res) => {
const { cancelShotRender } = await import('../services/musicVideo/shotSegments.js');
res.json({ ok: cancelShotRender(req.params.id, req.params.sceneId) });
}));
// The shots rendered so far, stitched in order with the song (a seam check
// while the rest renders), and the film looks cached over the current takes.
router.post('/:id/shot-renders/preview', asyncHandler(async (req, res) => {
const { light } = validateRequest(musicVideoRenderPreviewSchema, req.body ?? {});
const { buildRenderPreview } = await import('../services/musicVideo/shotSegments.js');
res.json(await buildRenderPreview(req.params.id, { light: light === true }));
}));
router.get('/:id/film-looks', asyncHandler(async (req, res) => {
const { listFilmLooks } = await import('../services/musicVideo/shotSegments.js');
res.json(await listFilmLooks(req.params.id, await planOptions(req)));
}));
router.delete('/:id/film-looks/:lookId', asyncHandler(async (req, res) => {
const { deleteFilmLook } = await import('../services/musicVideo/shotSegments.js');
res.json(await deleteFilmLook(req.params.id, req.params.lookId));
}));
router.get('/:id/shot-renders/:name', asyncHandler(async (req, res) => {
const { shotSegmentFile } = await import('../services/musicVideo/shotSegments.js');
const path = shotSegmentFile(req.params.id, req.params.name);
if (!path) throw new ServerError('Shot render not found', { status: 404, code: 'NOT_FOUND' });
res.type('video/mp4').sendFile(path);
}));
// Read-only: this project's in-flight scene frame/clip renders (#10154), so a
// reloaded board restores its spinners instead of letting a duplicate be submitted.
router.get('/:id/scene-jobs', (req, res) => {
res.json({ jobs: listInFlightSceneJobs(req.params.id) });
});
router.post('/:id/production-review/feedback', asyncHandler(async (req, res) => {
res.json(await addProductionFeedback(req.params.id, validateRequest(musicVideoProductionFeedbackSchema, req.body)));
}));
router.post('/:id/production-review/feedback/resolve', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoProductionFeedbackResolutionSchema, req.body);
const reviewer = await requireProductionReviewer(req);
res.json(await closeProductionFeedback(req.params.id, { feedbackId: input.feedbackId, resolution: input.resolution, reviewer }));
}));
router.post('/:id/production-review/lyric-anchors', asyncHandler(async (req, res) => {
res.json(await syncLyricAnchors(req.params.id, validateRequest(musicVideoLyricAnchorSyncSchema, req.body ?? {})));
}));
router.delete('/:id/production-review/stale-rows', asyncHandler(async (req, res) => {
res.json(await removeStaleStoryboardRows(req.params.id));
}));
// An explicit click: the only provider call is the stage's own revision.
router.post('/:id/production-review/revise', asyncHandler(async (req, res) => {
res.json(await reviseProductionFromFeedback(req.params.id, validateRequest(musicVideoProductionReviseSchema, req.body ?? {})));
}));
router.post('/:id/production-review/revert', asyncHandler(async (req, res) => {
res.json(await revertProductionInput(req.params.id, validateRequest(musicVideoProductionRevertSchema, req.body)));
}));
// The overlay text quality pass: render the composition document at its text
// moments and flag collisions, cut-off, low contrast and phone-size text.
router.post('/:id/production-review/text-check', asyncHandler(async (req, res) => {
const { startOverlayTextCheck } = await import('../services/musicVideo/overlayTextService.js');
const { project, readiness } = await startOverlayTextCheck(req.params.id);
res.status(202).json({ project, readiness });
}));
router.get('/:id/production-review', asyncHandler(async (req, res) => {
res.json(await getProductionReview(req.params.id));
}));
router.post('/:id/production-review/document-shots', asyncHandler(async (req, res) => {
const { musicVideoDocumentShotsSchema } = await import('../lib/musicVideoValidation.js');
const input = validateRequest(musicVideoDocumentShotsSchema, req.body);
const { importDocumentShots } = await import('../services/musicVideo/productionReviewService.js');
res.json(await importDocumentShots(req.params.id, input));
}));
router.post('/:id/production-review/import', asyncHandler(async (req, res) => {
const { source } = validateRequest(musicVideoProductionImportSchema, req.body);
res.json(await importProductionPlanning(req.params.id, source));
}));
router.post('/:id/production-review/shots/:shotId/bind', asyncHandler(async (req, res) => {
res.json(await bindProductionShot(req.params.id, req.params.shotId));
}));
router.put('/:id/production-review', asyncHandler(async (req, res) => {
res.json(await saveProductionDraft(req.params.id, validateRequest(musicVideoProductionDraftSchema, req.body)));
}));
router.post('/:id/production-review/prepare', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCastAndSetsStartSchema, req.body || {});
res.json(await prepareProductionReview(req.params.id, input));
}));
router.post('/:id/production-review/alignment', asyncHandler(async (req, res) => {
const { musicVideoAlignmentReviewSchema } = await import('../lib/musicVideoValidation.js');
const input = validateRequest(musicVideoAlignmentReviewSchema, req.body);
const reviewer = await requireProductionReviewer(req);
const { reverifyProductionAlignment } = await import('../services/musicVideo/productionReviewService.js');
res.json(await reverifyProductionAlignment(req.params.id, { ...input, reviewer }));
}));
router.post('/:id/production-review/approve', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoProductionApprovalSchema, req.body);
const reviewer = await requireProductionReviewer(req);
res.json(await approveProductionReview(req.params.id, { stage: input.stage, basis: input.basis, proofReview: input.proofReview, reviewer }));
}));
// Lock or unlock single Board shots: a locked shot may have its clip made before the whole storyboard is approved.
router.post('/:id/production-review/shots', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoShotLockSchema, req.body);
const reviewer = await requireProductionReviewer(req);
res.json(await lockProductionShots(req.params.id, { ...input, reviewer }));
}));
router.post('/:id/production-review/proof', asyncHandler(async (req, res) => {
res.status(202).json(await renderProductionProof(req.params.id, validateRequest(musicVideoProductionProofSchema, req.body)));
}));
// SSE progress stream for a render job. Two-segment path — distinct from the
// one-segment GET /:id project read, so it can't shadow it.
router.get('/render/:jobId/events', (req, res) => {
const ok = attachRenderSseClient(req.params.jobId, res);
if (!ok) throw new ServerError('Render job not found or expired', { status: 404, code: 'NOT_FOUND' });
});
router.post('/render/:jobId/cancel', (req, res) => {
res.json({ ok: cancelRender(req.params.jobId) });
});
// Code-rendered style (#9076). Document reads build the page from stored
// section functions and never call a provider. Generate / regenerate are the
// only provider calls, and both require this click.
router.get('/:id/code/document', asyncHandler(async (req, res) => {
const project = await requireProject(req.params.id);
if (project.composition?.mode !== 'code') {
throw new ServerError('Switch the render style to Code-rendered first', { status: 409, code: 'NOT_CODE_MODE' });
}
res.json(prepareCodeRender(project));
}));
router.post('/:id/code/generate', asyncHandler(async (req, res) => {
const body = validateRequest(musicVideoCodeGenerateSchema, req.body || {});
res.json(await generateMusicVideoCode(req.params.id, body));
}));
router.post('/:id/code/sections/:sectionId/regenerate', asyncHandler(async (req, res) => {
const body = validateRequest(musicVideoCodeGenerateSchema, req.body || {});
res.json(await regenerateMusicVideoCodeSection(req.params.id, req.params.sectionId, body));
}));
// --- Composition document (render style `document`) ---
// A project-owned HTML composition document (services/musicVideo/
// compositionDocument.js): import a zip, a folder inside data/, or the shipped
// template; export it; read its manifest; preview it. Files stay on this
// install; the record keeps a pointer to the current immutable version.
// A new document gets its overlay text checked in the background, so the
// findings are waiting at the storyboard approval (local browser work, no provider).
// The check renders the document in the headless composition browser, so it
// runs only for a caller with host control (#13055); anyone else gets the
// import alone, and the gated production-review text check runs it later.
// Decide before responding: once the response ends the socket can close and
// lose the address that makes a caller local. authGate loads lazily because
// this router is reached by many suites that mock settings. Both deferred
// imports (`authGateModule`, declared with `planOptions`, and
// `overlayTextModule`) are memoized: overlapping first loads of one specifier can resolve
// past a test's module mock.
let overlayTextModule;
const checkOverlayTextAfterImport = async (req, projectId) => {
const { requestHasHostControl } = await (authGateModule ??= import('../services/authGate.js'));
if (!requestHasHostControl(req)) return;
(overlayTextModule ??= import('../services/musicVideo/overlayTextService.js'))
.then(({ checkOverlayTextInBackground }) => checkOverlayTextInBackground(projectId))
.catch((err) => console.error(`❌ Overlay text check did not start: ${err.message}`));
};
const documentZipUpload = uploadSingle('file', {
limits: { fileSize: DOCUMENT_ZIP_MAX_BYTES },
fileFilter: (_req, file, cb) => {
if (isZipUpload(file)) cb(null, true);
else cb(new ServerError('Upload a .zip of the composition document', { status: 400, code: 'VALIDATION_ERROR' }));
},
});
router.get('/:id/composition/document', asyncHandler(async (req, res) => {
res.json(await readDocumentManifest(await requireProject(req.params.id)));
}));
router.post('/:id/composition/document/zip', documentZipUpload, asyncHandler(async (req, res) => {
if (!req.file) throw new ServerError('No file uploaded (multipart field "file")', { status: 400, code: 'VALIDATION_ERROR' });
try {
const imported = await importDocumentZip(req.params.id, req.file.path, req.file.originalname);
await checkOverlayTextAfterImport(req, req.params.id);
res.status(201).json(imported);
} finally {
await unlink(req.file.path).catch(() => {});
}
}));
router.post('/:id/composition/document/directory', asyncHandler(async (req, res) => {
const { directory } = validateRequest(musicVideoDocumentDirectoryImportSchema, req.body || {});
const imported = await importDocumentDirectory(req.params.id, directory);
await checkOverlayTextAfterImport(req, req.params.id);
res.status(201).json(imported);
}));
router.post('/:id/composition/document/template', asyncHandler(async (req, res) => {
const { template } = validateRequest(musicVideoDocumentTemplateSchema, req.body || {});
res.status(201).json(await importDocumentTemplate(req.params.id, template));
}));
// An explicit engine-only revision: no provider call or authored-code rewrite.
router.post('/:id/composition/document/engine/upgrade', asyncHandler(async (req, res) => {
const { directory } = validateRequest(musicVideoDocumentCandidateSchema, req.body || {});
res.json(await upgradeDocumentEngine(req.params.id, directory));
}));
router.post('/:id/composition/document/generate', asyncHandler(async (req, res) => {
const body = validateRequest(musicVideoCodeGenerateSchema, req.body || {});
res.status(201).json(await generateMixedMediaDocument(req.params.id, body));
}));
router.get('/:id/composition/document/candidate', asyncHandler(async (req, res) => {
res.json(await readMixedMediaCandidate(req.params.id));
}));
router.post('/:id/composition/document/events/revise', asyncHandler(async (req, res) => {
const body = validateRequest(musicVideoMixedMediaRegenerateSchema, req.body || {});
res.status(201).json(await reviseMixedMediaEvents(req.params.id, body));
}));
router.post('/:id/composition/document/sections/:sectionId/regenerate', asyncHandler(async (req, res) => {
const body = validateRequest(musicVideoMixedMediaRegenerateSchema, req.body || {});
res.status(201).json(await regenerateMixedMediaSection(req.params.id, req.params.sectionId, body));
}));
router.post('/:id/composition/document/accept', asyncHandler(async (req, res) => {
const { directory } = validateRequest(musicVideoDocumentCandidateSchema, req.body || {});
const accepted = await acceptMixedMediaDocument(req.params.id, directory);
await checkOverlayTextAfterImport(req, req.params.id);
res.json(accepted);
}));
router.delete('/:id/composition/document/candidate', asyncHandler(async (req, res) => {
const { directory } = validateRequest(musicVideoDocumentCandidateSchema, req.body || {});
res.json(await discardGeneratedDocument(req.params.id, directory));
}));
// Local making-of compilation. The preview digest binds download to the exact
// reviewed metadata, content, rights declarations and explicit asset selection.
router.get('/:id/making-of/catalog', asyncHandler(async (req, res) => {
const { getMakingOfCatalog } = await import('../services/musicVideo/makingOf.js');
res.json(await getMakingOfCatalog(req.params.id));
}));
router.post('/making-of/preview', asyncHandler(async (req, res) => {
const { musicVideoMakingOfSelectionSchema } = await import('../lib/musicVideoValidation.js');
const input = validateRequest(musicVideoMakingOfSelectionSchema, req.body ?? {});
const { compileMakingOf } = await import('../services/musicVideo/makingOf.js');
res.json(await compileMakingOf(input));
}));
router.post('/making-of/export', asyncHandler(async (req, res) => {
const { musicVideoMakingOfSelectionSchema } = await import('../lib/musicVideoValidation.js');
const input = validateRequest(musicVideoMakingOfSelectionSchema, req.body ?? {});
const { compileMakingOf } = await import('../services/musicVideo/makingOf.js');
const { zip } = await compileMakingOf(input, { download: true });
res.set('Content-Type', 'application/zip');
res.set('Content-Disposition', 'attachment; filename="music-video-making-of.zip"');
res.set('Cache-Control', 'no-store');
res.send(zip);
}));
router.get('/:id/composition/document/export', asyncHandler(async (req, res) => {
const { zip, filename } = await exportDocumentZip(await requireProject(req.params.id));
res.set('Content-Type', 'application/zip');
res.set('Content-Disposition', `attachment; filename="${filename}"`);
res.send(zip);
}));
router.get('/:id/composition/document/preview', asyncHandler(async (req, res) => {
const { draft } = validateRequest(musicVideoDocumentDraftQuerySchema, req.query || {});
const project = await requireProject(req.params.id);
const pointer = draft ? project.composition?.documentDraft : project.composition?.document;
if (draft && !pointer) throw new ServerError('No composition candidate to preview', { status: 404, code: 'NOT_FOUND' });
res.json(await buildDocumentPreview(draft ? { ...project, composition: { ...project.composition, document: pointer } } : project, { draft: Boolean(draft) }));
}));
// One document file, for the preview's asset bridge (fetched by the PortOS
// page, never loaded by the sandboxed preview itself). Served inert: a
// sandbox CSP, no sniffing, same-origin only.
router.get('/:id/composition/document/file', asyncHandler(async (req, res) => {
const { path, draft } = validateRequest(musicVideoDocumentFileQuerySchema, req.query || {});
const project = await requireProject(req.params.id);
const pointer = draft ? project.composition?.documentDraft : project.composition?.document;
if (draft && !pointer) throw new ServerError('No composition candidate to preview', { status: 404, code: 'NOT_FOUND' });
const abs = await resolveDocumentFile(draft ? { ...project, composition: { ...project.composition, document: pointer } } : project, path);
res.setHeader('Content-Security-Policy', "sandbox; default-src 'none'");
res.setHeader('X-Content-Type-Options', 'nosniff');
res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
res.setHeader('Cache-Control', 'private, no-cache');
res.type(documentMimeType(path));
res.sendFile(abs, { dotfiles: 'allow' });
}));
router.delete('/:id/composition/document', asyncHandler(async (req, res) => {
await requireProject(req.params.id);
res.json(await detachDocument(req.params.id));
}));
// --- Draft excerpt render (#8986) ---
// A director-chosen [startSec, endSec) window re-rendered through the same
// composed pipeline, plus a cut/cue contact sheet and timecoded review notes.
// Kickoff returns { jobId, excerptId }; progress streams over SSE (mirrors the
// full render above) on its OWN job map, so an excerpt draft and a full render
// can run at once without contending for the same mutex.
router.post('/:id/excerpt', asyncHandler(async (req, res) => {
const { startSec, endSec, aspect, fade } = validateRequest(musicVideoExcerptRequestSchema, req.body);
res.json(await startExcerptRender(req.params.id, { startSec, endSec, aspect, fade }));
}));
// --- Publishing kit (#9281) ---
// Platform encodes, thumbnails, captions and chapters from the final render
// (an SSE job), plus per-platform copy: one user-triggered draft, then edits.
router.post('/:id/publish-kit/build', asyncHandler(async (req, res) => {
res.json(await startPublishKitBuild(req.params.id));
}));
router.get('/publish-kit/:jobId/events', (req, res) => {
const ok = attachPublishKitSseClient(req.params.jobId, res);
if (!ok) throw new ServerError('Publishing kit job not found or expired', { status: 404, code: 'NOT_FOUND' });
});
router.post('/publish-kit/:jobId/cancel', (req, res) => {
res.json({ ok: cancelPublishKitBuild(req.params.jobId) });
});
router.post('/:id/publish-kit/copy', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoPublishCopyDraftSchema, req.body || {});
const { project } = await draftPublishKitCopy(req.params.id, input);
res.json({ project });
}));
// The release's scheduled promotion steps (open ones), soonest first.
router.get('/:id/publish/promotion-plan', asyncHandler(async (req, res) => {
const { promotionPlanSteps } = await import('../services/musicVideo/promotionPlan.js');
res.json(await promotionPlanSteps(req.params.id));
}));
// Turn the release into dated steps only the artist can take, with reminders.
router.post('/:id/publish/promotion-plan', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoPromotionPlanSchema, req.body || {});
const { planMusicVideoPromotion } = await import('../services/musicVideo/promotionPlan.js');
res.status(201).json(await planMusicVideoPromotion(req.params.id, input));
}));
router.patch('/:id/publish-kit/copy', asyncHandler(async (req, res) => {
const patch = validateRequest(musicVideoPublishCopyPatchSchema, req.body || {});
const { project } = await updatePublishKitCopy(req.params.id, patch);
res.json({ project });
}));
router.put('/:id/publish-kit/thumbnail', asyncHandler(async (req, res) => {
const { filename } = validateRequest(musicVideoPublishThumbnailSchema, req.body || {});
const { project } = await selectPublishKitThumbnail(req.params.id, filename);
res.json({ project });
}));
// The YouTube thumbnail: a source cropped 16:9 with the title set in the
// cover's lettering. DELETE goes back to the picked video frame.
router.post('/:id/publish-kit/youtube-thumbnail', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoYoutubeThumbnailComposeSchema, req.body ?? {});
const { composeProjectYoutubeThumbnail } = await import('../services/musicVideo/youtubeThumbnail.js');
const { project } = await composeProjectYoutubeThumbnail(req.params.id, input);
res.json({ project });
}));
router.delete('/:id/publish-kit/youtube-thumbnail', asyncHandler(async (req, res) => {
const { clearProjectYoutubeThumbnail } = await import('../services/musicVideo/youtubeThumbnail.js');
const { project } = await clearProjectYoutubeThumbnail(req.params.id);
res.json({ project });
}));
// "Paint the title": what the image model would receive, then the queued job
// (its completion hook makes the result the thumbnail).
router.post('/:id/publish-kit/youtube-thumbnail/paint/preview', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoYoutubeThumbnailPaintPreviewSchema, req.body ?? {});
const { buildThumbnailPaintPrompt } = await import('../services/musicVideo/youtubeThumbnail.js');
res.json(buildThumbnailPaintPrompt(input));
}));
router.post('/:id/publish-kit/youtube-thumbnail/paint', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoYoutubeThumbnailPaintSchema, req.body ?? {});
const { paintYoutubeThumbnail } = await import('../services/musicVideo/youtubeThumbnail.js');
const { project } = await paintYoutubeThumbnail(req.params.id, input);
res.json({ project });
}));
// Variants kept for YouTube's Test & Compare (up to three): add the made thumbnail, or drop one.
router.post('/:id/publish-kit/youtube-thumbnail/tests', asyncHandler(async (req, res) => {
const { addYoutubeThumbnailTest } = await import('../services/musicVideo/youtubeThumbnail.js');
const { project } = await addYoutubeThumbnailTest(req.params.id);
res.json({ project });
}));
router.delete('/:id/publish-kit/youtube-thumbnail/tests/:filename', asyncHandler(async (req, res) => {
const { removeYoutubeThumbnailTest } = await import('../services/musicVideo/youtubeThumbnail.js');
const { project } = await removeYoutubeThumbnailTest(req.params.id, req.params.filename);
res.json({ project });
}));
// Release cover art: the song's own design (drafted, or adjusted from the
// director's direction), compose from a chosen image, or queue a fresh cover
// photo whose completion hook composes the cover.
router.post('/:id/publish-kit/cover-art', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCoverArtComposeSchema, req.body || {});
const { composeProjectCoverArt } = await import('../services/musicVideo/coverArt.js');
const { project } = await composeProjectCoverArt(req.params.id, input);
res.json({ project });
}));
router.post('/:id/publish-kit/cover-art/design', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCoverArtDesignSchema, req.body || {});
const { designCoverArt } = await import('../services/musicVideo/coverArt.js');
const { project } = await designCoverArt(req.params.id, input);
res.json({ project });
}));
// #10345: the Lettering controls set the design directly, with no AI call.
router.put('/:id/publish-kit/cover-art/design', asyncHandler(async (req, res) => {
const { design } = validateRequest(musicVideoCoverDesignSaveSchema, req.body ?? {});
const { saveCoverDesign } = await import('../services/musicVideo/coverArt.js');
const { project } = await saveCoverDesign(req.params.id, design);
res.json({ project });
}));
router.post('/:id/publish-kit/cover-art/generate', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCoverArtGenerateSchema, req.body || {});
const { generateCoverArtSource } = await import('../services/musicVideo/coverArt.js');
const { project } = await generateCoverArtSource(req.params.id, input);
res.json({ project });
}));
// --- Posting (#9282) ---
// Fill a platform's post in the PortOS Browser and return a screenshot; post
// only on a second, explicit request naming that live draft.
// #9287: where the director posts (opt-in, optional account per platform),
// with every platform's post history and ratings across projects.
router.get('/publish/platforms', asyncHandler(async (req, res) => {
const [platforms, history] = await Promise.all([getPublishPlatforms(), publishHistory()]);
res.json({ platforms, history });
}));
router.put('/publish/platforms', asyncHandler(async (req, res) => {
const patch = validateRequest(musicVideoPublishPlatformsPatchSchema, req.body || {});
res.json({ platforms: await updatePublishPlatforms(patch) });
}));
// #10345: one saved cover design per artist, and the typefaces the director uploaded.
router.get('/publish/artist-styles', asyncHandler(async (req, res) => {
res.json({ styles: await listArtistStyles() });
}));
router.put('/publish/artist-styles', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoArtistStyleSaveSchema, req.body ?? {});
res.json({ style: await saveArtistStyle(input) });
}));
router.delete('/publish/artist-styles', asyncHandler(async (req, res) => {
const { name } = validateRequest(musicVideoArtistStyleDeleteSchema, req.query);
await removeArtistStyle(name);
res.json({ ok: true });
}));
const COVER_FONT_MIME = { ttf: 'font/ttf', otf: 'font/otf', woff2: 'font/woff2' };
const coverFontUpload = uploadSingle('font', { limits: { fileSize: MAX_COVER_FONT_BYTES } });
router.get('/publish/cover-fonts', asyncHandler(async (req, res) => {
res.json({ fonts: await listCoverFonts() });
}));
router.post('/publish/cover-fonts', coverFontUpload, asyncHandler(async (req, res) => {
if (!req.file) throw new ServerError('No font file uploaded (multipart field "font")', { status: 400, code: 'VALIDATION_ERROR' });
const font = await addCoverFont({ tempPath: req.file.path, originalName: req.file.originalname }).finally(() => unlink(req.file.path).catch(() => {}));
res.status(201).json({ font, fonts: await listCoverFonts() });
}));
router.get('/publish/cover-fonts/:fontId/file', asyncHandler(async (req, res) => {
const found = await coverFontPath(req.params.fontId);
if (!found) throw new ServerError('Font not found', { status: 404, code: 'NOT_FOUND' });
res.type(COVER_FONT_MIME[found.font.ext]).sendFile(found.path);
}));
router.delete('/publish/cover-fonts/:fontId', asyncHandler(async (req, res) => {
await removeCoverFont(req.params.fontId);
res.json({ fonts: await listCoverFonts() });
}));
// Record a post made by hand, or rate one: its link, reception and notes.
router.put('/:id/publish/posts/:target', asyncHandler(async (req, res) => {
const target = validateRequest(musicVideoPublishTargetSchema, req.params.target);
const input = validateRequest(musicVideoPublishPostSchema, req.body || {});
res.json(await recordPublishPost(req.params.id, target, input));
}));
// Undo a platform's "done" (the post record only; nothing on the platform changes).
router.delete('/:id/publish/posts/:target', asyncHandler(async (req, res) => {
const target = validateRequest(musicVideoPublishTargetSchema, req.params.target);
res.json(await removePublishPost(req.params.id, target));
}));
// What Fill draft would post, read-only: the rows of text and files, or what is still missing.
router.post('/:id/publish/:target/preview', asyncHandler(async (req, res) => {
const target = validateRequest(musicVideoPublishTargetSchema, req.params.target);
const options = validateRequest(musicVideoPublishPrepareSchema, req.body || {});
res.json(await previewPublishPost(req.params.id, target, options));
}));
// Whether new drafts list the release's other posts (cross-links).
router.put('/:id/publish/cross-links', asyncHandler(async (req, res) => {
const { enabled } = validateRequest(musicVideoPublishCrossLinksSchema, req.body || {});
res.json(await setPublishCrossLinks(req.params.id, enabled));
}));
// Fill a posted platform's edit form (or a reply under it) with the links it lacks; the director saves it.
router.post('/:id/publish/:target/cross-links', asyncHandler(async (req, res) => {
const target = validateRequest(musicVideoCrossLinkTargetSchema, req.params.target);
await requireProductionReviewer(req);
const { password: _password, ...body } = req.body || {};
validateRequest(musicVideoCrossLinkEditSchema, body);
res.json(await prepareCrossLinkEdit(req.params.id, target));
}));
router.post('/:id/publish/:target/prepare', asyncHandler(async (req, res) => {
const target = validateRequest(musicVideoPublishTargetSchema, req.params.target);
await requireProductionReviewer(req);
const { password: _password, ...body } = req.body || {};
const options = validateRequest(musicVideoPublishPrepareSchema, body);
res.json(await preparePublishDraft(req.params.id, target, options));
}));
router.get('/:id/publish/drafts', asyncHandler(async (req, res) => {
res.json({ drafts: await listPublishDrafts(req.params.id) });
}));
router.delete('/:id/publish/drafts/:draftId', asyncHandler(async (req, res) => {
res.json({ ok: await discardPublishDraft(req.params.id, req.params.draftId) });
}));
// #9280: the song windows most likely to work as a vertical social cut.
router.get('/:id/social-cuts', asyncHandler(async (req, res) => {
const options = validateRequest(musicVideoSocialCutsQuerySchema, req.query);
res.json({ suggestions: suggestSocialCuts(await requireProject(req.params.id), options) });
}));
router.get('/excerpt/:jobId/events', (req, res) => {
const ok = attachExcerptRenderSseClient(req.params.jobId, res);
if (!ok) throw new ServerError('Excerpt render job not found or expired', { status: 404, code: 'NOT_FOUND' });
});
router.post('/excerpt/:jobId/cancel', (req, res) => {
res.json({ ok: cancelExcerptRender(req.params.jobId) });
});
router.delete('/:id/excerpt/:excerptId', asyncHandler(async (req, res) => {
res.json(await deleteExcerpt(req.params.id, req.params.excerptId));
}));
router.post('/:id/excerpt/:excerptId/notes', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoExcerptNoteSchema, req.body);
const { project, note } = await addReviewNote(req.params.id, req.params.excerptId, input);
res.status(201).json({ project, note });
}));
router.patch('/:id/excerpt/:excerptId/notes/:noteId', asyncHandler(async (req, res) => {
const patch = validateRequest(musicVideoExcerptNoteUpdateSchema, req.body);
const { project, note } = await editReviewNote(req.params.id, req.params.excerptId, req.params.noteId, patch);
res.json({ project, note });
}));
router.delete('/:id/excerpt/:excerptId/notes/:noteId', asyncHandler(async (req, res) => {
res.json(await deleteReviewNote(req.params.id, req.params.excerptId, req.params.noteId));
}));
router.post('/:id/scenes/:sceneId/performance-repair', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoPerformanceRepairSchema, req.body || {});
const { startPerformanceRepair } = await import('../services/musicVideo/performanceRepair.js');
res.status(201).json(await startPerformanceRepair(req.params.id, req.params.sceneId, input));
}));
// --- Selective section revision (#8987) ---
// Reject the flagged sections of a reviewed draft (their selected takes clear)
// while every other section keeps its selection. Resume continues from the
// persisted checkpoint: sections still without a take come back as
// `needsGeneration` for the board to generate; once all hold one, the draft
// window re-renders. A section holding a take is never asked to generate again,
// so a render retry never re-submits paid generation.
router.get('/:id/dependency-impact', asyncHandler(async (req, res) => {
res.json(await getDependencyImpact(req.params.id));
}));
router.post('/:id/dependency-repairs', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoDependencyRepairSchema, req.body || {});
res.status(201).json(await startDependencyRepair(req.params.id, input));
}));
router.post('/:id/excerpt/:excerptId/revisions', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoRevisionStartSchema, req.body || {});
res.status(201).json(await startRevision(req.params.id, req.params.excerptId, input));
}));
router.post('/:id/revisions/:revisionId/resume', asyncHandler(async (req, res) => {
res.json(await resumeRevision(req.params.id, req.params.revisionId));
}));
router.post('/:id/revisions/:revisionId/cancel', asyncHandler(async (req, res) => {
res.json(await cancelRevision(req.params.id, req.params.revisionId));
}));
// A generation kickoff that failed client-side before reaching the queue
// (network error, a refused request) leaves its section claimed for the
// full lease with nothing running — clear the claim so the very next resume
// hands the section out again immediately (#9011).
router.post('/:id/revisions/:revisionId/release', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoRevisionReleaseSchema, req.body || {});
res.json(await releaseRevisionSection(req.params.id, req.params.revisionId, input.sceneId));
}));
// --- Opt-in automatic review/retries (#8988) ---
// Start/resume write the checkpoint and return at once; the run advances in
// the background (render → review → revise → generate → re-render) and
// reports over the `music-video:auto-review` socket event. Only these
// explicit requests start or resume a run — nothing at boot does.
router.post('/:id/auto-reviews', asyncHandler(async (req, res) => {
const { providerId, model, ...input } = validateRequest(musicVideoAutoReviewStartSchema, req.body || {});
res.status(201).json(await startAutoReview(req.params.id, { ...input, reviewer: { providerId, model } }));
}));
router.post('/:id/auto-reviews/:runId/resume', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoAutoReviewResumeSchema, req.body || {});
res.json(await resumeAutoReview(req.params.id, req.params.runId, input));
}));
router.post('/:id/auto-reviews/:runId/stop', asyncHandler(async (req, res) => {
res.json(await stopAutoReview(req.params.id, req.params.runId));
}));
router.post('/:id/auto-reviews/:runId/cancel', asyncHandler(async (req, res) => {
res.json(await cancelAutoReview(req.params.id, req.params.runId));
}));
// --- Server-owned production run (#9066) ---
// Start/resume write the checkpoint and return at once; the run advances in
// the background (plan → frames → clips → reviewed draft → revisions) from
// queue completion events and reports over `music-video:production`. Only
// these explicit requests start or resume a run — nothing at boot does.
router.post('/:id/production-runs', asyncHandler(async (req, res) => {
const { providerId, model, ...input } = validateRequest(musicVideoProductionStartSchema, req.body || {});
res.status(201).json(await startProduction(req.params.id, { ...input, reviewer: { providerId, model } }));
}));
router.get('/:id/production-runs/:runId', asyncHandler(async (req, res) => {
res.json(await getProduction(req.params.id, req.params.runId));
}));
router.post('/:id/production-runs/:runId/resume', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoProductionResumeSchema, req.body || {});
res.json(await resumeProduction(req.params.id, req.params.runId, input));
}));
router.post('/:id/production-runs/:runId/stop', asyncHandler(async (req, res) => {
res.json(await stopProduction(req.params.id, req.params.runId));
}));
router.post('/:id/production-runs/:runId/cancel', asyncHandler(async (req, res) => {
res.json(await cancelProduction(req.params.id, req.params.runId));
}));
// --- Fully-autonomous run (one prompt → lyrics → Suno song → video) ---
// The alternate entry point: no track, style or board is picked up front. Start
// creates the project and returns at once; the run advances in the background
// (brief → lyrics → mood board → Suno → analysis → production) and reports over
// `music-video:autonomous`. Optional checkpoints park it for approval. Only these
// explicit requests (or the scheduled task) begin work — nothing at boot does.
// A non-empty `autoApprove` lets the run approve those Production review stages
// itself, and an `orchestrator` reviews and approves every stage for the operator.
// Bind either grant to the authenticated session; proof still needs review evidence.
const authorizeAutoApprove = async (req, autoApprove, orchestrator) => {
if (autoApprove === undefined && !orchestrator) return false;
return requireProductionReviewer(req);
};
router.post('/autonomous', asyncHandler(async (req, res) => {
const { password: _password, ...input } = validateRequest(musicVideoAutonomousStartSchema, req.body || {});
const autoApproveAuthorized = await authorizeAutoApprove(req, input.autoApprove, input.orchestrator);
res.status(202).json(await startAutonomousVideo(input, { autoApproveAuthorized }));
}));
router.get('/:id/autonomous', asyncHandler(async (req, res) => {
res.json(await getAutonomousRun(req.params.id));
}));
// Resume a parked/failed/interrupted run, or approve the checkpoint it waits on.
router.post('/:id/autonomous/resume', asyncHandler(async (req, res) => {
const { password: _password, ...edits } = validateRequest(musicVideoAutonomousResumeSchema, req.body || {});
const autoApproveAuthorized = await authorizeAutoApprove(req, edits.autoApprove);
res.json(await resumeAutonomousVideo(req.params.id, edits, { autoApproveAuthorized }));
}));
router.post('/:id/autonomous/stop', asyncHandler(async (req, res) => {
res.json(await stopAutonomousVideo(req.params.id));
}));
router.post('/:id/autonomous/cancel', asyncHandler(async (req, res) => {
res.json(await cancelAutonomousVideo(req.params.id));
}));
// --- Development artifacts ("ingredients") ---
// Reviewable development files attached to the project: list, import/upload
// (HTML, Markdown, MP4, PNG, JPG — a new artifact, or a new version of one),
// serve, notes, review and soft delete. See services/musicVideo/devArtifacts.js.
const DEV_ARTIFACT_MAX_BYTES = 512 * 1024 * 1024;
const devArtifactUpload = uploadSingle('file', {
limits: { fileSize: DEV_ARTIFACT_MAX_BYTES },
fileFilter: (_req, file, cb) => {
const ext = String(file.originalname || '').split('.').pop();
if (String(file.originalname || '').includes('.') && devArtifactTypeFor(ext)) cb(null, true);
else cb(new ServerError('Unsupported file type — accepted: HTML, Markdown, MP4, PNG, JPG', { status: 400, code: 'VALIDATION_ERROR' }));
},
});
// A served artifact never runs with the PortOS origin: HTML is sandboxed by
// its CSP even when opened directly (an opaque origin, no same-origin access),
// may run its own inline script inside that sandbox, and can load nothing
// from the network — images, media and fonts only as data:/blob: URLs.
const DEV_ARTIFACT_HTML_CSP = "sandbox allow-scripts; default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; media-src data: blob:; font-src data:";
const DEV_ARTIFACT_MEDIA_CSP = "sandbox; default-src 'none'; img-src 'self' data:; media-src 'self'; style-src 'unsafe-inline'";
router.get('/:id/dev-artifacts', asyncHandler(async (req, res) => {
res.json(await listDevArtifacts(req.params.id));
}));
router.post('/:id/dev-artifacts', devArtifactUpload, asyncHandler(async (req, res) => {
if (!req.file) throw new ServerError('No file uploaded (multipart field "file")', { status: 400, code: 'VALIDATION_ERROR' });
const input = (() => {
try {
return validateRequest(musicVideoDevArtifactImportSchema, req.body || {});
} catch (err) {
unlink(req.file.path).catch(() => {});
throw err;
}
})();
const out = await importDevArtifact(req.params.id, { ...input, tempPath: req.file.path, originalName: req.file.originalname });
res.status(201).json(out);
}));
router.get('/:id/dev-artifacts/:artifactId', asyncHandler(async (req, res) => {
res.json(await getDevArtifact(req.params.id, req.params.artifactId));
}));
router.get('/:id/dev-artifacts/:artifactId/file', asyncHandler(async (req, res) => {
const { version } = validateRequest(musicVideoDevArtifactFileQuerySchema, req.query || {});
const { path, mimeType } = await resolveDevArtifactDownload(req.params.id, req.params.artifactId, version ?? null);
if (!existsSync(path)) throw new ServerError('The artifact file is not on this machine', { status: 404, code: 'DEV_ARTIFACT_FILE_MISSING' });
const isHtml = mimeType === 'text/html';
res.setHeader('Content-Security-Policy', isHtml ? DEV_ARTIFACT_HTML_CSP : DEV_ARTIFACT_MEDIA_CSP);
res.setHeader('X-Content-Type-Options', 'nosniff');
res.setHeader('Referrer-Policy', 'no-referrer');
res.setHeader('Cross-Origin-Resource-Policy', 'same-origin');
res.setHeader('Cache-Control', 'private, no-cache');
// Markdown is shown as text (a browser would otherwise download it).
res.type(mimeType === 'text/markdown' ? 'text/plain; charset=utf-8' : (isHtml ? 'text/html; charset=utf-8' : mimeType));
res.sendFile(path, { dotfiles: 'deny' });
}));
router.post('/:id/dev-artifacts/:artifactId/notes', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoDevArtifactNoteSchema, req.body || {});
res.status(201).json(await addDevArtifactNote(req.params.id, req.params.artifactId, input));
}));
router.patch('/:id/dev-artifacts/:artifactId/notes/:noteId', asyncHandler(async (req, res) => {
const { resolved } = validateRequest(musicVideoDevArtifactNoteUpdateSchema, req.body || {});
res.json(await setDevArtifactNoteResolved(req.params.id, req.params.artifactId, req.params.noteId, resolved));
}));
router.post('/:id/dev-artifacts/:artifactId/review', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoDevArtifactReviewSchema, req.body || {});
res.json(await reviewDevArtifact(req.params.id, req.params.artifactId, input));
}));
router.delete('/:id/dev-artifacts/:artifactId', asyncHandler(async (req, res) => {
res.json(await removeDevArtifact(req.params.id, req.params.artifactId));
}));
// --- Cast & Sets check-in (runs before the shot plan) ---
// Start / regenerate / resume write the checkpoint and return at once; the
// direction call and the reference images advance in the background and
// report over `music-video:cast-and-sets`. Only these requests (or a
// production run the director started) begin work — nothing at boot does.
router.get('/:id/cast-and-sets', asyncHandler(async (req, res) => {
res.json(await getCastAndSets(req.params.id));
}));
router.post('/:id/cast-and-sets', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCastAndSetsStartSchema, req.body || {});
res.status(202).json(await startCastAndSets(req.params.id, input));
}));
router.post('/:id/cast-and-sets/regenerate', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCastAndSetsRegenerateSchema, req.body || {});
res.status(202).json(await regenerateCastAndSets(req.params.id, input));
}));
router.patch('/:id/cast-and-sets/direction', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCastAndSetsDirectionEditSchema, req.body || {});
res.status(202).json(await editCastAndSetsDirection(req.params.id, input));
}));
router.post('/:id/cast-and-sets/feedback', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCastAndSetsFeedbackSchema, req.body || {});
res.status(202).json(await applyCastAndSetsFeedback(req.params.id, input));
}));
router.delete('/:id/cast-and-sets/feedback/:feedbackId', asyncHandler(async (req, res) => {
res.json(await removeCastAndSetsFeedbackEntry(req.params.id, req.params.feedbackId));
}));
router.post('/:id/cast-and-sets/resume', asyncHandler(async (req, res) => {
const input = validateRequest(musicVideoCastAndSetsStartSchema, req.body || {});
res.status(202).json(await resumeCastAndSets(req.params.id, input));
}));
router.post('/:id/cast-and-sets/approve', asyncHandler(async (req, res) => {
res.json(await approveCastAndSets(req.params.id));
}));
// "Keep approved": an approved check-in whose concept, style, subjects or song
// changed since is re-stamped on the current inputs (#10141). No body.
router.post('/:id/cast-and-sets/reconfirm', asyncHandler(async (req, res) => {
res.json(await reconfirmCastAndSets(req.params.id));
}));
router.post('/:id/cast-and-sets/skip', asyncHandler(async (req, res) => {
res.json(await skipCastAndSets(req.params.id));
}));
// --- Director scene board ---
router.post('/:id/scenes', asyncHandler(async (req, res) => {
const data = validateRequest(musicVideoSceneCreateSchema, req.body);
const scene = await addProjectScene(req.params.id, data);
res.status(201).json(scene);
}));
router.patch('/:id/scenes/:sceneId', asyncHandler(async (req, res) => {
const data = validateRequest(musicVideoSceneUpdateSchema, req.body);
const updated = await updateScene(req.params.id, req.params.sceneId, data);
res.json(updated);
}));
router.delete('/:id/scenes/:sceneId', asyncHandler(async (req, res) => {
const updated = await deleteScene(req.params.id, req.params.sceneId);
res.json(updated);
}));
router.post('/:id/scenes/reorder', asyncHandler(async (req, res) => {
const { sceneIds } = validateRequest(musicVideoSceneReorderSchema, req.body);
const updated = await reorderProjectScenes(req.params.id, sceneIds);
res.json(updated);
}));
// Split a shot its backend cannot render in one take (#8977): a performance
// longer than the lip-sync window, a Grok cutaway longer than its longest clip.
// With `atSec`, cut it in two at that song time instead.
router.post('/:id/scenes/:sceneId/split', asyncHandler(async (req, res) => {
const { backend, atSec } = validateRequest(musicVideoSceneSplitSchema, req.body ?? {});
res.json(await splitProjectScene(req.params.id, req.params.sceneId, { backend, atSec }));
}));
// Merge a scene with the next one — the inverse of split.
router.post('/:id/scenes/:sceneId/merge-next', asyncHandler(async (req, res) => {
const { backend } = validateRequest(musicVideoSceneSplitSchema, req.body ?? {});
res.json(await mergeProjectNextScene(req.params.id, req.params.sceneId, { backend }));
}));
// Merge a scene over the previous one: it starts where the previous one did, which is removed.
router.post('/:id/scenes/:sceneId/merge-previous', asyncHandler(async (req, res) => {
const { backend } = validateRequest(musicVideoSceneSplitSchema, req.body ?? {});
res.json(await mergeProjectPreviousScene(req.params.id, req.params.sceneId, { backend }));
}));
// Move a shot's start; the shot before it ends at the same time, so the cut between them moves.
router.post('/:id/scenes/:sceneId/start', asyncHandler(async (req, res) => {
const { startSec } = validateRequest(musicVideoSceneStartSchema, req.body ?? {});
res.json(await moveProjectSceneStart(req.params.id, req.params.sceneId, { startSec }));
}));
// --- Scene takes (#8965) ---
// Every render or import for a scene slot is kept as an immutable take; the
// slot field is the director's explicit selection among them. A take's asset
// must already exist in this install's media stores — an image in the gallery,
// a clip in the video history (both reached through the existing upload
// routes) — so a take can never point at an arbitrary file.
async function takeAssetExists(kind, assetId) {
if (kind !== 'video') return Boolean(resolveGalleryImage(assetId));
return Boolean(await getHistoryItem(assetId));
}
// Add one candidate take to a scene: the synchronous image lane's inline
// render, or an asset the director imports from the gallery.
router.post('/:id/scenes/:sceneId/takes', asyncHandler(async (req, res) => {
const { kind, assetId, source = 'imported', provider, originalName, use, sourceImageId, inputAssets } = validateRequest(musicVideoTakeInputSchema, req.body);
if (!(await takeAssetExists(kind, assetId))) {
throw new ServerError(`${kind === 'video' ? 'Video' : 'Image'} not found in this install's media library`, { status: 400, code: 'TAKE_ASSET_NOT_FOUND' });
}
for (const imageId of [sourceImageId, ...(inputAssets || []).map((input) => input.assetId)].filter(Boolean)) {
if (!(await takeAssetExists('image', imageId))) throw new ServerError('Dependency image not found', { status: 400, code: 'TAKE_ASSET_NOT_FOUND' });
}
const { scene, appended } = await appendSceneTakes(req.params.id, req.params.sceneId, [{
kind, assetId, source, provider: provider ?? (source === 'generated' ? 'portos' : null), originalName, use, sourceImageId, inputAssets,
}]);
res.status(201).json({ scene, take: appended[0] });
}));
// Continuing shot: the previous shot's last on-screen frame becomes this scene's start frame.
router.post('/:id/scenes/:sceneId/continue-from-previous', asyncHandler(async (req, res) => {
const { keepStillAsEnd } = validateRequest(musicVideoContinueShotSchema, req.body ?? {});
const { continueFromPreviousShot } = await import('../services/musicVideo/continueShot.js');
res.json(await continueFromPreviousShot(req.params.id, req.params.sceneId, { keepStillAsEnd }));
}));
// Every still and clip generated for this video, each naming the shots using it now (the shot card's Swap picker).
router.get('/:id/media-pool', asyncHandler(async (req, res) => {
const project = await requireProject(req.params.id);
const { getMusicVideoMediaPool } = await import('../services/musicVideo/mediaPool.js');
res.json(await getMusicVideoMediaPool(project));
}));
// Swap's search: the pool items whose prompts (the shot's text and the prompt each file was made from) hold the words.
router.get('/:id/media-pool/search', asyncHandler(async (req, res) => {
const { q } = validateRequest(musicVideoPoolSearchQuerySchema, req.query);
const project = await requireProject(req.params.id);
const { searchMusicVideoMediaPool } = await import('../services/musicVideo/mediaPool.js');
res.json({ items: await searchMusicVideoMediaPool(project, q) });
}));
// The cutting room floor outro's tally: what was made, kept and turned down for this video.
router.get('/:id/stats-outro', asyncHandler(async (req, res) => {
const project = await requireProject(req.params.id);
const { getMusicVideoOutroStats } = await import('../services/musicVideo/statsOutro.js');
res.json({ stats: await getMusicVideoOutroStats(project) });
}));
// The asset manager: mark unused stills and clips ★ ingredient / ✕ bad, or delete them from the library.
router.patch('/:id/media-pool/marks', asyncHandler(async (req, res) => {
const { items, mark } = validateRequest(musicVideoPoolMarkSchema, req.body);
res.json(await markMediaPoolAssets(req.params.id, items.map((item) => `${item.kind}:${item.assetId}`), mark));
}));
// Bring an earlier draft's stills and clips into this video's assets (references; the draft is untouched).
router.post('/:id/media-pool/import', asyncHandler(async (req, res) => {
const { fromProjectId } = validateRequest(musicVideoPoolImportSchema, req.body);
if (fromProjectId === req.params.id) throw new ServerError('Pick another video', { status: 400, code: 'VALIDATION_ERROR' });
const [project, from] = await Promise.all([getProject(req.params.id), getProject(fromProjectId)]);
if (!project || !from) throw new ServerError('Project not found', { status: 404, code: 'NOT_FOUND' });
const { importMusicVideoPool, getMusicVideoMediaPool } = await import('../services/musicVideo/mediaPool.js');
const result = await importMusicVideoPool(project, from);
res.json({ ...result, items: (await getMusicVideoMediaPool(project)).items });
}));
// Media made for this video but never filed: search the whole library by prompt, then add picks.
router.get('/:id/media-pool/library', asyncHandler(async (req, res) => {
const { q } = validateRequest(musicVideoLibrarySearchQuerySchema, req.query);
const project = await requireProject(req.params.id);
const { searchMediaLibraryForPool } = await import('../services/musicVideo/mediaPool.js');
res.json(await searchMediaLibraryForPool(project, q));
}));
router.post('/:id/media-pool/add', asyncHandler(async (req, res) => {
const { items } = validateRequest(musicVideoPoolAddSchema, req.body);
const project = await requireProject(req.params.id);
const { addLibraryMediaToPool, getMusicVideoMediaPool } = await import('../services/musicVideo/mediaPool.js');
const result = await addLibraryMediaToPool(project, items);
res.json({ ...result, items: (await getMusicVideoMediaPool(project)).items });
}));
router.post('/:id/media-pool/delete', asyncHandler(async (req, res) => {
const { items } = validateRequest(musicVideoPoolDeleteSchema, req.body);
const project = await requireProject(req.params.id);
const { deleteMusicVideoPoolAssets } = await import('../services/musicVideo/mediaPool.js');
res.json(await deleteMusicVideoPoolAssets(project, items));
}));
router.post('/:id/scenes/:sceneId/takes/use', asyncHandler(async (req, res) => {
const { kind, assetId, withAssetId } = validateRequest(musicVideoPoolUseSchema, req.body);
const otherKind = kind === 'video' ? 'image' : 'video';
for (const [assetKind, id] of [[kind, assetId], [otherKind, withAssetId]]) {
if (id && !(await takeAssetExists(assetKind, id))) {
throw new ServerError(`${assetKind === 'video' ? 'Video' : 'Image'} not found in this install's media library`, { status: 400, code: 'TAKE_ASSET_NOT_FOUND' });
}
}
res.json({ scene: await placeMediaPoolItem(req.params.id, req.params.sceneId, { kind, assetId, withAssetId }) });
}));
router.post('/:id/scenes/:sceneId/takes/:takeId/select', asyncHandler(async (req, res) => {
res.json(await selectSceneTake(req.params.id, req.params.sceneId, req.params.takeId));
}));
// No body: marks the shot's unselected takes rejected, keeping their files.
router.post('/:id/scenes/:sceneId/takes/reject-unused', asyncHandler(async (req, res) => {
res.json(await rejectUnusedSceneTakes(req.params.id, req.params.sceneId));
}));
// No body: the shot's start frame becomes its end frame and the end frame its start, prompts included.
router.post('/:id/scenes/:sceneId/swap-frames', asyncHandler(async (req, res) => {
res.json(await swapProjectSceneFrames(req.params.id, req.params.sceneId));
}));
router.patch('/:id/scenes/:sceneId/takes/:takeId', asyncHandler(async (req, res) => {
const review = validateRequest(musicVideoTakeReviewSchema, req.body);
res.json(await reviewSceneTake(req.params.id, req.params.sceneId, req.params.takeId, review));
}));
// --- External-asset handoff (#8965) ---
// Export per-scene prompts + reference files for a tool PortOS does not drive
// (e.g. Midjourney), and import what the director generated there. Nothing
// here contacts the external service.
router.get('/:id/handoff', asyncHandler(async (req, res) => {
const project = await requireProject(req.params.id);
res.json(buildHandoffManifest(project));
}));
// Downloadable ZIP counterpart (#8978): the manifest plus every reference
// image and each scene's selected frame, so nothing has to be saved out of
// the gallery by hand before attaching it in the external tool.
router.get('/:id/handoff/bundle', asyncHandler(async (req, res) => {
const project = await requireProject(req.params.id);
const { zip } = await buildHandoffBundle(project);
res.set('Content-Type', 'application/zip');
res.set('Content-Disposition', `attachment; filename="music-video-${project.id}-handoff.zip"`);
res.send(zip);
}));
// Associate already-uploaded assets with scenes. An item names its scene
// explicitly or carries the manifest's file tag in `originalName`; an item that
// resolves to no scene, or whose asset isn't in this install's media stores, is
// reported in `skipped` rather than guessed. All matched items land in one
// record write with `imported` source + provider provenance.
router.post('/:id/handoff/import', asyncHandler(async (req, res) => {
const { provider, items } = validateRequest(musicVideoHandoffImportSchema, req.body);
const project = await requireProject(req.params.id);
const sceneIds = new Set((project.scenes || []).map((scene) => scene.sceneId));
const accepted = [];
const skipped = [];
for (const item of items) {
const sceneId = item.sceneId || matchSceneByFileTag(project.scenes, item.originalName);
const skip = (reason) => skipped.push({ assetId: item.assetId, originalName: item.originalName ?? null, reason });
if (!sceneId || !sceneIds.has(sceneId)) { skip('no-matching-scene'); continue; }
if (!musicVideoTakeInputSchema.safeParse({ kind: item.kind, assetId: item.assetId }).success
|| !(await takeAssetExists(item.kind, item.assetId))) { skip('asset-not-found'); continue; }
accepted.push({ sceneId, kind: item.kind, assetId: item.assetId, source: 'imported', provider, originalName: item.originalName, use: item.use });
}
if (accepted.length === 0) {
return res.json({ project, imported: [], skipped });
}
const { project: next, appended } = await appendTakesAcrossScenes(project.id, accepted);
res.json({
project: next,
imported: appended.map(({ sceneId, take }) => ({ sceneId, takeId: take.takeId, kind: take.kind, assetId: take.assetId, originalName: take.originalName })),
skipped,
});
}));
export default router;