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
/** Explicit, fork-scoped song revision. Never advances on boot or selects audio automatically. */
import { randomUUID } from 'crypto';
import { ServerError } from '../../lib/errorHandler.js';
import { getProject, mutateProjectRecord, cloneProject } from './projects.js';
import { requireProject } from './requireProject.js';
import { applyProjectPatch, addScenes } from './projectsLogic.js';
import { parseLyricCues } from './timedText.js';
import { musicVideoEvents } from './events.js';
import { diffLyricLines, songBaseline, remapSongTimeline, remapStoryboardShots } from './songRemap.js';
const inflight = new Map();
const fail = (message, code = 'SONG_REVISION_CONFLICT') => { throw new ServerError(message, { status: 409, code }); };
const defaults = {
generate: async (...args) => (await import('./autonomousSuno.js')).generateSunoSong(...args),
getTrack: async (...args) => (await import('../tracks/index.js')).getTrack(...args),
cloneProject,
proposeShotRevisions: async (...args) => (await import('./planner.js')).proposeShotRevisions(...args),
startRetime: async (id) => (await import('./lyricAlignJob.js')).startLyricAlign(id, { retimeSong: true }),
};
// The director's choice of the new song is the request to re-time it; a start
// that fails leaves the re-time pending for the Song step's button.
async function startRetime(out) {
const started = await deps.startRetime(out.project.id).catch((err) => {
console.error(`❌ Song re-time did not start for ${out.project.id}: ${err.message}`);
return null;
});
return { ...out, retimeJobId: started?.jobId || null };
}
let deps = defaults;
export const __setSongRevisionDepsForTests = (overrides = {}) => { deps = { ...defaults, ...overrides }; };
function requireRevision(project, id) {
if (!project.parentProjectId) fail('Fork a version before revising its song');
if (!project.songRevision || project.songRevision.id !== id) fail('This song revision is no longer current');
return project.songRevision;
}
async function mutate(id, fn) {
const out = await mutateProjectRecord(id, (current) => {
const next = fn(current);
return { ...next, project: { ...next.project, updatedAt: new Date().toISOString(),
songRevision: { ...next.project.songRevision, sequence: (current.songRevision?.sequence || 0) + 1 } } };
});
musicVideoEvents.emit('song-revision', { projectId: id, project: out.project });
return out;
}
const patch = (id, revisionId, fn) => mutate(id, (project) => {
const revision = requireRevision(project, revisionId);
return { project: { ...project, songRevision: { ...revision, ...fn(revision), updatedAt: new Date().toISOString() } } };
});
export async function saveSongRevision(projectId, fields) {
return mutate(projectId, (project) => {
if (!project.parentProjectId) fail('Fork a version before revising its song');
if (inflight.has(projectId) || ['generating', 'review', 'selected'].includes(project.songRevision?.status)) fail('Select or cancel the current candidates; fork again after selecting a song');
const previous = project.songRevision;
const revision = { id: `mvsr-${randomUUID()}`, fields, status: 'draft', songIds: [], candidates: [], createdAt: new Date().toISOString() };
return { project: { ...project, songRevision: revision,
songRevisionHistory: previous ? [...(project.songRevisionHistory || []), previous] : (project.songRevisionHistory || []),
} };
});
}
async function generate(projectId, revisionId, controller) {
try {
controller.signal.throwIfAborted();
let revision = (await getProject(projectId)).songRevision;
const persist = async (update) => {
const out = await patch(projectId, revisionId, (r) => update(r));
revision = out.project.songRevision;
};
const accept = async (song) => {
controller.signal.throwIfAborted();
await persist((r) => ({ candidates: [...r.candidates.filter((c) => c.songId !== song.songId), { songId: song.songId, filename: song.filename } ] }));
};
if (!revision.songIds.length) {
// Reserve before dispatch. A crash without returned ids must NEVER repeat Create.
await persist(() => ({ submitted: true }));
const song = await deps.generate(revision.fields, {
signal: controller.signal,
onSubmitted: (songIds) => persist(() => ({ songIds })),
});
await accept(song);
}
for (const songId of revision.songIds) {
controller.signal.throwIfAborted();
if (revision.candidates.some((c) => c.songId === songId)) continue;
const song = await deps.generate(revision.fields, { songIds: [songId], signal: controller.signal });
await accept(song);
}
controller.signal.throwIfAborted();
await patch(projectId, revisionId, (r) => r.status === 'canceled' ? {} : { status: 'review', error: null });
} catch (err) {
// Background work owns its failures; cancellation leaves the source/master intact.
await patch(projectId, revisionId, (r) => r.status === 'canceled' ? {} : {
status: 'failed', error: err.code || 'SONG_GENERATION_FAILED',
}).catch((writeError) => console.error(`❌ Song revision could not store failure: ${writeError.code || 'STORE_FAILED'}`));
} finally {
inflight.delete(projectId);
}
}
export async function generateSongRevision(projectId, revisionId) {
if (inflight.has(projectId)) fail('Song generation is already in progress');
const controller = new AbortController();
// Install the reservation before any await; cancellation can always find it.
const pending = { controller, promise: null };
inflight.set(projectId, pending);
const out = await patch(projectId, revisionId, (r) => {
if (!['draft', 'failed', 'generating'].includes(r.status)) fail('Save a new draft to generate another song');
if (r.submitted && !r.songIds.length) fail('The previous submission has an unknown outcome. Check Suno before saving a new draft.', 'SONG_SUBMISSION_UNKNOWN');
return { status: 'generating', error: null };
}).catch((err) => { inflight.delete(projectId); throw err; });
pending.promise = generate(projectId, revisionId, controller);
return out;
}
export async function cancelSongRevision(projectId, revisionId) {
const out = await patch(projectId, revisionId, (r) => {
if (r.status === 'selected') fail('The selected song is already applied; fork another version to revise it');
return { status: 'canceled' };
});
inflight.get(projectId)?.controller.abort();
return out;
}
const productionActive = (project) => project.status === 'rendering' || project.autonomousRun?.status === 'running'
|| project.productionRuns?.some((r) => r.status === 'running');
/**
* Put a revised song on the project as its master: compare the new lyric
* sheet with the current lines (unchanged lines keep their cue ids), snapshot
* the old timeline so the board can follow the song once it is re-timed, and
* mark everything timed against the old audio as provisional. Returns the next
* project and the fields the revision records.
*/
function applyRevisedMaster(project, { trackId = null, uploadedAudioFilename = null, lyrics = '', instrumental = false }) {
const baseline = songBaseline(project);
// No sheet came with the new song (lyrics null): keep the current lines and re-time them on it.
const { cues, markers } = lyrics == null
? { cues: (project.lyricCues || []).map(({ text }) => ({ text })), markers: project.lyricMarkers || [] }
: parseLyricCues(instrumental ? '' : lyrics);
const diff = diffLyricLines(project.lyricCues || [], cues);
const next = applyProjectPatch(project, { trackId, uploadedAudioFilename, lyricCues: diff.cues, lyricMarkers: markers, phrases: [] });
if (next.productionReview) next.productionReview = { ...next.productionReview,
draft: { ...next.productionReview.draft, timingStatus: 'provisional' }, alignmentBasis: null,
approvals: next.productionReview.approvals?.art ? { art: next.productionReview.approvals.art } : {}, proof: null,
};
return { project: next, revision: { baseline, cueStatus: diff.cueStatus, changedFrom: diff.changedFrom,
removedLines: diff.removed, lyricDiff: diff.counts, retime: { status: 'pending' }, sceneReview: null, sceneCounts: null,
compositionStale: Boolean(project.composition?.document) } };
}
export async function selectSongRevision(projectId, revisionId, songId) {
return startRetime(await mutate(projectId, (project) => {
const revision = requireRevision(project, revisionId);
if (inflight.has(projectId) || !['review', 'failed'].includes(revision.status)) fail('Wait for candidate generation to settle before selecting audio');
if (productionActive(project)) fail('Stop active production before replacing the master audio');
const candidate = revision.candidates.find((c) => c.songId === songId);
if (!candidate) fail('Import and listen to a candidate before selecting it');
const applied = applyRevisedMaster(project, { uploadedAudioFilename: candidate.filename,
lyrics: revision.fields.lyrics, instrumental: revision.fields.instrumental });
const songStyle = String(revision.fields?.style || '').trim().slice(0, 2000);
return { project: { ...applied.project, concept: { ...applied.project.concept, songStyle }, songRevision: { ...revision, ...applied.revision,
status: 'selected', selectedSongId: songId, selectedAt: new Date().toISOString() } } };
}));
}
/**
* Revise the song from a track already in the music library (a Suno link the
* director imported). Forks a new version, so the current version keeps its
* song and video, and puts the track on the fork as its master with its lyric
* sheet, then starts re-timing it. Resolves `{ project, retimeJobId }`.
*/
export async function reviseSongFromTrack(projectId, { trackId }) {
const source = await requireProject(projectId);
if (productionActive(source)) fail('Stop active production before revising the song');
const track = await deps.getTrack(trackId);
if (!track) throw new ServerError('Track not found', { status: 404, code: 'NOT_FOUND' });
if (!track.audioFilename) fail('That track has no audio yet', 'SONG_REVISION_NO_AUDIO');
if (track.id === source.trackId) fail('That is already this version\'s song', 'SONG_REVISION_SAME_TRACK');
const lyrics = typeof track.lyrics === 'string' ? track.lyrics : '';
const fork = await deps.cloneProject(projectId, { variant: 'revision', includeGeneratedMedia: true });
return startRetime(await mutate(fork.id, (project) => {
const applied = applyRevisedMaster(project, { trackId: track.id, lyrics: lyrics.trim() ? lyrics : null });
const now = new Date().toISOString();
// The new song brings its own Suno style for the planners to design from.
const songStyle = typeof track.prompt === 'string' ? track.prompt.trim().slice(0, 2000) : '';
return { project: { ...applied.project, concept: { ...applied.project.concept, songStyle }, songRevision: { id: `mvsr-${randomUUID()}`, source: 'track', trackId: track.id,
fields: { title: String(track.title || project.name || 'Song').slice(0, 80), style: String(track.prompt || '').slice(0, 1000),
lyrics: (lyrics.trim() ? lyrics : (project.lyricCues || []).map((c) => c.text).join('\n')).slice(0, 5000), instrumental: false },
status: 'selected', songIds: [], candidates: [], createdAt: now, selectedAt: now, ...applied.revision } } };
}));
}
const reviewable = (revision) => revision?.status === 'selected' && revision.baseline;
/** Mark the re-time pass started or failed; the client shows it on the Song step. */
async function markSongRetime(projectId, retime) {
const project = await getProject(projectId);
if (!reviewable(project?.songRevision)) return null;
return patch(projectId, project.songRevision.id, (r) => ({ retime: { ...r.retime, ...retime } }));
}
/**
* Once the new song is analyzed and its lyrics aligned, move the board onto
* it: shared lines carry shots across, shots whose lines changed or were cut
* are flagged, inserted lines get new shots. Throws when the lyrics are not
* timed yet. A project with no revised song to carry across is returned untouched.
*/
async function remapSongRevisionBoard(projectId) {
const current = await getProject(projectId);
if (!reviewable(current?.songRevision)) return current;
const out = await mutate(projectId, (project) => {
const revision = project.songRevision;
if (!reviewable(revision)) fail('This song revision is no longer current');
// An instrumental song has no lines to align; its board moves through the song's length alone.
const cues = project.lyricCues || [];
if (cues.length && !cues.some((c) => typeof c.startSec === 'number')) fail('Align the new lyrics before re-timing the shots', 'SONG_REVISION_NOT_ALIGNED');
const remap = remapSongTimeline(project, revision);
const added = addScenes({ ...project, scenes: remap.scenes }, remap.newScenes);
const sceneReview = { ...remap.sceneReview };
for (const scene of added.scenes) sceneReview[scene.sceneId] = { status: 'new', previousLyricText: null };
// Board order follows the song once every shot is timed.
const timed = added.project.scenes.every((s) => typeof s.startSec === 'number');
const scenes = timed ? [...added.project.scenes].sort((a, b) => a.startSec - b.startSec || a.order - b.order).map((s, order) => ({ ...s, order })) : added.project.scenes;
const draft = project.productionReview?.draft;
const storyboard = draft?.storyboard ? remapStoryboardShots(draft.storyboard, { scenes, cues: project.lyricCues, map: remap.map }) : null;
return { project: { ...added.project, scenes,
...(storyboard ? { productionReview: { ...project.productionReview, draft: { ...draft, storyboard } } } : {}),
songRevision: { ...revision, sceneReview, sceneCounts: remap.counts, retime: { status: 'done', at: new Date().toISOString() }, updatedAt: new Date().toISOString() } } };
});
return out.project;
}
/**
* Re-time a revised song in one pass, as the lyric-alignment job's work:
* analyze the new master, separate its vocal and align the lyric text on it,
* then carry the board across. Each step is the same one the Song step runs
* on its own; the director's single tap is the consent for all of them.
*/
export async function retimeRevisedSong(projectId, { onProgress = () => {}, isCancelled = () => false, align, analyze } = {}) {
const checkCancel = () => {
if (isCancelled()) throw Object.assign(new Error('cancelled'), { canceled: true });
};
await markSongRetime(projectId, { status: 'running', error: null });
try {
onProgress({ stage: 'analyzing' });
await (analyze || (async (id) => (await import('./projectAudio.js')).analyzeProjectSong(id)))(projectId);
checkCancel();
const project = await getProject(projectId);
if ((project?.lyricCues || []).length) await align(projectId, { separateVocals: true, onProgress, isCancelled });
checkCancel();
onProgress({ stage: 'remapping' });
return await remapSongRevisionBoard(projectId);
} catch (err) {
await markSongRetime(projectId, err?.canceled ? { status: 'pending', error: null } : { status: 'failed', error: String(err?.message || err).slice(0, 300) })
.catch((writeError) => console.error(`❌ Song re-time could not store its state: ${writeError.message}`));
throw err;
}
}
const pendingScenes = (revision, statuses) => Object.entries(revision.sceneReview || {})
.filter(([, entry]) => statuses.includes(entry.status) && !entry.resolved).map(([sceneId]) => sceneId);
/** The note the shot planner reads for one shot whose lyrics the new song changed. */
function replanNote(scene, entry) {
const now = scene.lyricText ? `"${scene.lyricText}"` : 'no lyrics (instrumental)';
if (entry.status === 'new') return `New shot for lines the revised song added: ${now}. Plan it to fit the shots around it.`;
return `The song was revised. This shot's lyrics were ${entry.previousLyricText ? `"${entry.previousLyricText}"` : 'instrumental'} and are now ${now}. Re-plan it for the new lyrics; keep what still fits.`;
}
/**
* Act on the shots the song revision flagged: `replan` asks the shot planner
* (an explicit, user-triggered LLM call) for new frame/motion prompts for the
* changed and new shots; `remove` deletes the shots whose lines were all cut;
* `dismiss` keeps the named shots as they are.
*/
export async function resolveSongRevisionScenes(projectId, { revisionId, action, sceneIds = null, ...route }) {
const project = await requireProject(projectId);
const revision = requireRevision(project, revisionId);
if (!revision.sceneReview) fail('Re-time the shots to the new song first', 'SONG_REVISION_NOT_REMAPPED');
const statuses = action === 'remove' ? ['removed'] : action === 'replan' ? ['changed', 'new'] : ['changed', 'new', 'removed'];
const targets = pendingScenes(revision, statuses).filter((id) => !sceneIds || sceneIds.includes(id));
if (!targets.length) fail('There are no flagged shots left for that');
let updates = new Map();
if (action === 'replan') {
if (productionActive(project)) fail('Stop active production before re-planning shots');
const notes = targets.map((sceneId) => {
const scene = project.scenes.find((s) => s.sceneId === sceneId);
return scene ? { stage: 'storyboard', target: sceneId, decision: 'request-changes', text: replanNote(scene, revision.sceneReview[sceneId]) } : null;
}).filter(Boolean);
// The planner reads open review notes from the project, so the notes ride along in memory only.
const planning = { ...project, productionReview: { ...project.productionReview, feedback: [...(project.productionReview?.feedback || []), ...notes] } };
updates = await deps.proposeShotRevisions(planning, notes, route);
}
return mutate(projectId, (current) => {
const live = requireRevision(current, revisionId);
const now = new Date().toISOString();
const done = new Set(action === 'replan' ? targets.filter((id) => updates.has(id)) : targets);
let scenes = (current.scenes || []).map((scene) => (updates.has(scene.sceneId) ? { ...scene, ...updates.get(scene.sceneId) } : scene));
if (action === 'remove') scenes = scenes.filter((s) => !done.has(s.sceneId)).map((s, order) => ({ ...s, order }));
const draft = current.productionReview?.draft;
const storyboard = draft?.storyboard && (action === 'remove'
? draft.storyboard.filter((shot) => !done.has(shot.sceneId))
: draft.storyboard.map((shot) => {
const fields = updates.get(shot.sceneId);
return fields ? { ...shot, ...(fields.prompt ? { action: fields.prompt } : {}), ...(fields.framePrompt ? { staging: fields.framePrompt } : {}) } : shot;
}));
const sceneReview = Object.fromEntries(Object.entries(live.sceneReview || {}).map(([id, entry]) => [id,
done.has(id) ? { ...entry, resolved: action === 'dismiss' ? 'kept' : action === 'remove' ? 'removed' : 'replanned', resolvedAt: now } : entry]));
return { project: { ...current, scenes, updatedAt: now,
...(storyboard ? { productionReview: { ...current.productionReview, draft: { ...draft, storyboard } } } : {}),
songRevision: { ...live, sceneReview, updatedAt: now } } };
});
}
export const __testing = { settle: async () => {
const results = await Promise.allSettled([...inflight.values()].map((entry) => entry.promise));
const failures = results.filter(result => result.status === 'rejected').map(result => result.reason);
if (failures.length === 1) throw failures[0];
if (failures.length > 1) throw new AggregateError(failures, 'Song revision jobs failed during fixture settlement');
} };