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 — draft excerpt record transforms (#8986, part of #8966).
*
* A project may carry a list of `excerpts`: a director-chosen `[startSec, endSec)`
* window re-rendered at full quality through the same composed pipeline as a
* full render (see `render.js` `buildMusicVideoFfmpegArgs`'s `excerpt` option),
* plus a contact sheet sampled at the range's cut and cue boundaries and a set
* of timecoded review notes. Frame checks alone can't validate motion/audio
* sync, so the note timeline is the excerpt's OWN (0 = the excerpt's start) —
* the UI plays the excerpt alongside the sheet and lets the director drop a
* note at whatever moment they're watching.
*
* Peer sync: `excerpts` is an additive field on the whole-record LWW project
* body (same posture as `treatment`/`scene.direction`, #8980). An older peer
* stores it verbatim, carries it through its own edits (every mutator spreads
* the record), and never executes it (it has no excerpt render route to run
* against a project it receives), so no `musicVideoProjects` schema bump is
* needed.
*
* Every transform here is pure (project in, project out) so the I/O layer
* (`excerptService.js`, `excerptRender.js`) can run it under
* `mutateProjectRecord`'s write serialization without duplicating validation.
*/
import { isLipSyncScene, selectedPerformanceInstruction } from '../../lib/musicVideoShotTiming.js';
import { captureMusicVideoEvidence } from '../../lib/musicVideoDependencies.js';
import { randomUUID } from 'crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { isNonBlankStr, trimTo } from '../../lib/textUtils.js';
const MAX_NOTE_LEN = 2000;
// Matches the route's musicVideoExcerptRequestSchema bound exactly — the same
// generic "song time" ceiling every other music-video timedSec field uses —
// so a range the public schema accepts can never fail this deeper check.
const MAX_EXCERPT_SEC = 36000;
function excerptError(status, code, message, context) {
return new ServerError(message, { status, code, ...(context ? { context } : {}) });
}
/** The excerpt array on a project, tolerating a legacy record with none. */
export const projectExcerpts = (project) => (Array.isArray(project?.excerpts) ? project.excerpts : []);
/** Find one excerpt by id, or throw 404. */
function findExcerpt(project, excerptId) {
const excerpt = projectExcerpts(project).find((e) => e.id === excerptId);
if (!excerpt) throw excerptError(404, 'NOT_FOUND', 'Excerpt not found');
return excerpt;
}
/**
* Add a new `status: 'rendering'` excerpt record to the project. Its `id`
* doubles as the render job id (one render at a time per excerpt) — the
* caller kicks off the ffmpeg job under that same id. Returns the updated
* project; the render job fills in `filename`/`contactSheetFilename` (or
* `error`) once the encode finishes.
*/
export function startExcerptOnProject(project, { startSec, endSec, sections = null, performanceProject = project, partialFilename = null, renderingOn = null, aspect = null, fade = false, dependencies = null }, now = new Date().toISOString()) {
if (!(startSec >= 0) || !(endSec > startSec) || endSec > MAX_EXCERPT_SEC) {
throw excerptError(422, 'INVALID_EXCERPT_RANGE', 'endSec must be greater than startSec, and both within range');
}
const id = `mve-${randomUUID()}`;
const excerpt = {
id,
startSec,
endSec,
status: 'rendering',
dependencies: dependencies || captureMusicVideoEvidence(project, { sceneIds: sections?.map((section) => section.sceneId), startSec, endSec }),
jobId: id,
filename: null,
contactSheetFilename: null,
// #8987: the output file an in-flight encode is writing, so boot recovery
// can delete a partial file a restart left behind (cleared on every
// terminal patch).
partialFilename,
// #9010: the instance running the encode — a synced peer's boot recovery
// leaves a mark it doesn't own alone (cleared on every terminal patch).
renderingOn,
// #8987: the sections the draft cuts, in ABSOLUTE song time — what a
// flagged note maps onto when the director asks for a selective revision.
sections: Array.isArray(sections) ? sections.map((section) => {
const scene = performanceProject.scenes?.find((s) => s.sceneId === section.sceneId);
const instruction = selectedPerformanceInstruction(scene);
return { ...section, performance: isLipSyncScene(scene) && (!section.layer || section.layer === 'footage')
? { takeId: scene.videoHistoryId || null, speaker: instruction?.speaker || null, conditioning: instruction?.audio?.conditioning || null } : null };
}) : null,
// #9280: a social cut's frame (the project's own unless re-framed) and
// whether its audio edges fade; `width`/`height` land with the finished file.
aspect: aspect || null,
fade: fade === true,
error: null,
notes: [],
createdAt: now,
updatedAt: now,
};
return { project: { ...project, excerpts: [...projectExcerpts(project), excerpt] }, excerpt };
}
/** Merge a patch (status/filename/contactSheetFilename/error/jobId) onto one excerpt. */
export function applyExcerptPatch(project, excerptId, patch, now = new Date().toISOString()) {
findExcerpt(project, excerptId); // 404 if missing
return {
...project,
excerpts: projectExcerpts(project).map((e) => (e.id === excerptId ? { ...e, ...patch, updatedAt: now } : e)),
};
}
/**
* Drop one excerpt record. Throws 404 if it doesn't exist, or 409 while its
* render is still in flight (the caller cancels that job first). Returns
* `{ project, excerpt }` — the removed excerpt, so the caller can clean up its
* on-disk video/contact-sheet files.
*/
export function removeExcerptFromProject(project, excerptId) {
const excerpt = findExcerpt(project, excerptId); // 404 if missing
if (excerpt.status === 'rendering') {
throw excerptError(409, 'EXCERPT_RENDERING', 'Cancel the in-progress render before deleting this excerpt');
}
if (project.productionReview?.proof?.excerptId === excerptId) {
throw excerptError(409, 'EXCERPT_REGISTERED_PROOF', 'This excerpt is the registered production proof. Revoke its approval or register a different proof before deleting it');
}
return { project: { ...project, excerpts: projectExcerpts(project).filter((e) => e.id !== excerptId) }, excerpt };
}
const clampAtSec = (atSec, excerpt) => {
if (typeof atSec !== 'number' || !Number.isFinite(atSec) || atSec < 0) {
throw excerptError(422, 'VALIDATION_ERROR', 'atSec must be a non-negative number');
}
const span = excerpt.endSec - excerpt.startSec;
// A small tolerance past the last frame — the player's own duration and the
// encoded file's can differ by a fraction of a frame.
if (atSec > span + 0.25) {
throw excerptError(422, 'VALIDATION_ERROR', `atSec must fall within the excerpt's own ${span.toFixed(2)}s duration`);
}
return Math.min(atSec, span);
};
/** Append a timecoded review note (0 = the excerpt's own start). */
export function addExcerptNote(project, excerptId, { atSec, note, verdict = null }, now = new Date().toISOString()) {
const excerpt = findExcerpt(project, excerptId);
if (!isNonBlankStr(note)) throw excerptError(422, 'VALIDATION_ERROR', 'A review note needs text');
const record = { id: `mvn-${randomUUID()}`, atSec: clampAtSec(atSec, excerpt), note: trimTo(note, MAX_NOTE_LEN), verdict: verdict ?? null, createdAt: now, updatedAt: now };
const next = { ...excerpt, notes: [...excerpt.notes, record], updatedAt: now };
return { project: { ...project, excerpts: projectExcerpts(project).map((e) => (e.id === excerptId ? next : e)) }, note: record };
}
function findNote(excerpt, noteId) {
const note = (excerpt.notes || []).find((n) => n.id === noteId);
if (!note) throw excerptError(404, 'NOT_FOUND', 'Review note not found');
return note;
}
/** Edit a review note's text, timecode, and/or verdict. */
export function updateExcerptNote(project, excerptId, noteId, patch, now = new Date().toISOString()) {
const excerpt = findExcerpt(project, excerptId);
const existing = findNote(excerpt, noteId);
const next = { ...existing, updatedAt: now };
if (patch.atSec !== undefined) next.atSec = clampAtSec(patch.atSec, excerpt);
if (patch.note !== undefined) {
if (!isNonBlankStr(patch.note)) throw excerptError(422, 'VALIDATION_ERROR', 'A review note needs text');
next.note = trimTo(patch.note, MAX_NOTE_LEN);
}
if (patch.verdict !== undefined) next.verdict = patch.verdict;
const nextExcerpt = { ...excerpt, notes: excerpt.notes.map((n) => (n.id === noteId ? next : n)), updatedAt: now };
return { project: { ...project, excerpts: projectExcerpts(project).map((e) => (e.id === excerptId ? nextExcerpt : e)) }, note: next };
}
/** Remove a review note. */
export function removeExcerptNote(project, excerptId, noteId) {
const excerpt = findExcerpt(project, excerptId);
findNote(excerpt, noteId); // 404 if missing
const nextExcerpt = { ...excerpt, notes: excerpt.notes.filter((n) => n.id !== noteId) };
return { ...project, excerpts: projectExcerpts(project).map((e) => (e.id === excerptId ? nextExcerpt : e)) };
}