Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { MUSIC_VIDEO_MEDIA_MODES } from './musicVideoMediaPolicy.js';
import { MUSIC_VIDEO_GRADE_PRESETS, MUSIC_VIDEO_GRADE_MAX_GRAIN } from './musicVideoGrade.js';
import { filmLookSchema } from './filmLookValidation.js';
import { TITLE_CARD_FONTS, TITLE_CARD_LIMITS, TITLE_CARD_POSITIONS, TITLE_CARD_STYLES } from './musicVideoTitleCard.js';
import { STATS_OUTRO_LIMITS, STATS_OUTRO_LINES } from './musicVideoStatsOutro.js';
import { COVER_DESIGN_OPTIONS } from './musicVideoCoverOverlay.js';
import { DISTROKID_REMEMBERED_OPTIONS } from './distrokidGenres.js';
import { CROSS_LINK_EDIT_TARGETS } from './musicVideoCrossLinks.js';
/**
* Music Video production mode — Zod schemas + shared enums (issue #1760, Phase 1).
*
* Validates the `musicVideoProject` db-primary record's route inputs: project
* create/update, the per-scene create/update/reorder operations of the director
* scene board, and the cached audio-analysis shape (produced by
* services/musicVideo/audioAnalysis.js, Phase 0). Re-exported flat from
* validation.js and as a namespace from server/lib/index.js.
*/
import { z } from 'zod';
import { GROK_VIDEO_DURATIONS } from './grokVideoClip.js';
import { knownFilmStyleIdSchema } from './filmStyleGrammars.js';
const makingOfId = z.string().regex(/^[A-Za-z0-9_-]{1,100}$/);
export const musicVideoMakingOfSelectionSchema = z.object({
projects: z.array(z.object({
projectId: makingOfId,
snapshot: z.string().regex(/^[a-f0-9]{64}$/),
assets: z.array(z.object({
id: z.string().min(1).max(250),
rights: z.enum(['unknown', 'owned', 'licensed']).default('unknown'),
attribution: z.string().max(2000).default(''),
ownershipConfirmed: z.boolean().default(false),
}).strict()).max(300),
}).strict()).min(1).max(8),
previewDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
}).strict().superRefine((selection, ctx) => {
if (new Set(selection.projects.map(p => p.projectId)).size !== selection.projects.length
|| selection.projects.some(p => new Set(p.assets.map(a => a.id)).size !== p.assets.length)) {
ctx.addIssue({ code: 'custom', message: 'Duplicate project or asset selection' });
}
});
export const musicVideoSongDraftSchema = z.object({
title: z.string().trim().min(1).max(80), style: z.string().trim().min(1).max(1000),
lyrics: z.string().max(5000), instrumental: z.boolean().default(false),
}).strict().refine((v) => v.instrumental || v.lyrics.trim().length > 0, 'Lyrics are required for a vocal song');
export const musicVideoSongActionSchema = z.object({ revisionId: z.string().min(1) }).strict();
export const musicVideoSongSelectSchema = z.object({ revisionId: z.string().min(1), songId: z.string().min(1) }).strict();
// Revise the song from a library track (an imported Suno link): forks a new version on it.
export const musicVideoSongFromTrackSchema = z.object({ trackId: z.string().min(1).max(128) }).strict();
import { EFFORT_LEVELS } from './providerModels.js';
import { shotActionContractProblem } from './musicVideoActionContract.js';
import { NARRATIVE_EVENT_KINDS } from './musicVideoNarrativeEvents.js';
import { MUSIC_VIDEO_MEDIA } from './musicVideoMediumPlan.js';
import { CLIP_OFFSET_FRAMES_RANGE, CLIP_SPEED_FPS_RANGE, MUSIC_VIDEO_FRAME_FITS, MUSIC_VIDEO_LYRIC_ROLES, MUSIC_VIDEO_LYRIC_SIZES, MUSIC_VIDEO_STILL_MOVES, MUSIC_VIDEO_TEXT_ZONES, MUSIC_VIDEO_VISUAL_LAYERS } from './musicVideoLayers.js';
import { MUSIC_VIDEO_SHOT_GLITCH_LIMIT, MUSIC_VIDEO_TRANSITIONS } from './musicVideoTransitions.js';
import { BEAT_TOGGLE_OVERLAP, BEAT_TOGGLE_RATES, MUSIC_VIDEO_CUT_EFFECTS } from './musicVideoCutEffects.js';
import { IMAGE_EFFECT_SEC_RANGE, MUSIC_VIDEO_IMAGE_EFFECTS } from './musicVideoImageEffects.js';
import { CAMERA_FRAMINGS, CAMERA_MOVEMENT_VALUES, CAMERA_SPEEDS } from './cameraMovements.js';
import { CAST_ERAS } from './catalogMediaLibrary.js';
import { STORYBOARD_ID_PATTERN } from './storyboardVocabulary.js';
import { MUSIC_VIDEO_PERFORMANCE_STYLES, MUSIC_VIDEO_SHOT_MODES, SOURCE_AUDIO_LIPSYNC } from './musicVideoShotTiming.js';
import {
MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD,
MUSIC_VIDEO_AUTOMATION_GUIDANCE_MAX,
MUSIC_VIDEO_AUTOMATION_TOOL_IDS,
MUSIC_VIDEO_LLM_STAGES,
MUSIC_VIDEO_CHECKIN_MODES,
} from './musicVideoAutomation.js';
import {
AUTONOMOUS_AUTO_APPROVE_STAGES,
AUTONOMOUS_CHECKPOINT_IDS,
AUTONOMOUS_LIMIT_BOUNDS,
AUTONOMOUS_NAME_MAX,
AUTONOMOUS_ORIGINS,
AUTONOMOUS_PROMPT_MAX,
AUTONOMOUS_SONG_SOURCES,
LOCAL_MUSIC_CODE_LANGUAGES,
LOCAL_MUSIC_TYPES,
SUNO_LIMITS,
SUNO_MODEL_PATTERN,
SUNO_VOCAL_GENDERS,
normalizeAutoApprove,
} from './musicVideoAutonomous.js';
import { MUSCRIPTOR_MODELS } from './muscriptorModels.js';
import { MUSIC_VIDEO_CHARACTER_STYLE_IDS } from './musicVideoCharacterStyles.js';
import { IMAGE_GEN_MODES, VIDEO_GEN_MODES } from './generationModes.js';
// A project is authored hands-on (director) or seeded by the AI planner
// (autonomous); both share the same record + scene board.
export const MUSIC_VIDEO_MODES = ['director', 'autonomous'];
// Lifecycle. `draft` → has scenes/analysis → `ready` → `rendering` → `complete`
// (or `failed`). `analyzed` marks "beat map cached but not yet arranged".
export const MUSIC_VIDEO_STATUSES = ['draft', 'analyzed', 'ready', 'rendering', 'complete', 'failed'];
// Re-read a project's song style from its Suno song link.
// Explicit cleanup keeps comparison looks unless the director opts to purge them.
export const musicVideoRenderCleanupSchema = z.object({ unusedLooks: z.boolean().optional() }).strict();
// The rendered-so-far player: `light` asks for the lighter phone copy.
export const musicVideoRenderPreviewSchema = z.object({ light: z.boolean().optional() }).strict();
export const musicVideoSongStyleSunoSchema = z.object({ url: z.string().trim().min(1).max(2000) });
// Optional global visual direction for the whole video.
export const musicVideoConceptSchema = z.object({
prompt: z.string().max(8000).optional(),
// The director's visual style, appended to every frame and shot prompt.
style: z.string().max(2000).optional(),
// The song's own style (the Suno style prompt, excluded styles included),
// snapshotted from the track. Planning LLMs translate it into design; it
// never reaches an image or video prompt verbatim.
songStyle: z.string().max(2000).optional(),
universeId: z.string().max(64).nullable().optional(),
// Authored snapshots keep the production stable when source canon changes.
universeStyle: z.string().max(4000).optional(),
moodBoardStyle: z.string().max(4000).optional(),
// A built-in character style (musicVideoCharacterStyles.js); the server
// snapshots its text into `characterStyle` and casts its character.
characterStyleId: z.enum(MUSIC_VIDEO_CHARACTER_STYLE_IDS).nullable().optional(),
characterStyle: z.string().max(4000).optional(),
subjects: z.array(z.object({
id: z.string().min(1).max(64),
kind: z.enum(['character', 'place', 'object']),
name: z.string().trim().min(1).max(120),
description: z.string().max(1000).optional(),
role: z.enum(['protagonist', 'band', 'supporting']).optional(),
canonId: z.string().max(64).optional(),
// The catalog record this subject was cast from (Casting / Environments /
// Objects). The project keeps its own name and description snapshot.
ingredientId: z.string().max(128).optional(),
// Kept in this video only: never offered for saving to the catalog.
localOnly: z.boolean().optional(),
}).strict()).max(24).optional(),
}).strict();
// Renderer settings travel with the project so reopening a director board (or
// opening it on a sync peer) cannot silently change provider/model. `modelId`
// is optional because Grok does not consume it; the video-gen route performs
// the authoritative installed-model validation when a local render starts.
export const musicVideoVideoSettingsSchema = z.object({
renderPool: z.object({
mode: z.enum(['local', 'peers', 'both']),
peers: z.array(z.object({ peerId: z.string().uuid(), modelId: z.string().trim().min(1).max(256) }).strict()).max(12),
}).strict().refine((v) => v.mode === 'local' || v.peers.length > 0, { message: 'Select at least one peer model' })
.refine((v) => new Set(v.peers.map((p) => p.peerId)).size === v.peers.length, { message: 'Choose one model per peer' }).optional(),
// null clears the per-project pin so this install's configured default wins.
// 'fal' is the metered fal.ai queue REST backend (server/services/videoGen/fal.js,
// #8968) — image-to-video only here; the audio-reactive lane stays local-only
// (see generationMode below). 'runway' is Runway's developer API
// (services/videoGen/runway.js), cutaways only.
backend: z.enum(['local', 'grok', 'fal', 'runway']).nullable().optional(),
modelId: z.string().max(64).nullable().optional(),
grokDuration: z.union(GROK_VIDEO_DURATIONS.map((d) => z.literal(d))).optional(),
// fal.ai clip length in seconds. Loosely bounded (not a closed enum) for the
// same reason routes/videoGen.js's falDuration is: fal's own model catalog,
// not PortOS, owns the set of valid durations per model. null/omitted lets
// the backend's model default apply.
falDuration: z.number().min(1).max(60).nullable().optional(),
// fal.ai cutaway model (lib/falVideoModels.js) and its output resolution.
// Loosely validated like routes/videoGen.js's falModelId/falResolution: a
// peer on a newer catalog may pin a model this install does not curate yet,
// and the resolution alphabet is per model — the provider resolves both (an
// uncurated id renders on the legacy body with its cost reported unknown).
// null/omitted = the default model (Hailuo-02 image-to-video) / its default.
falModelId: z.string().min(1).max(200).nullable().optional(),
falResolution: z.string().min(1).max(16).nullable().optional(),
// Upgrade model for shots with a style-break end frame (one that takes an
// end frame, e.g. Kling v3 Pro); null/omitted = those shots use falModelId.
falEndFrameModelId: z.string().min(1).max(200).nullable().optional(),
// Output resolution of a performance (lip-sync) take — fal's own alphabet
// for the lip-sync route. null/omitted = MUSIC_VIDEO_LIPSYNC_DEFAULT_RESOLUTION.
falLipSyncResolution: z.enum(SOURCE_AUDIO_LIPSYNC.fal.resolutions).nullable().optional(),
// false = lip-sync to the audio alone, without the provider transcribing it
// first (sung words it mishears turn into the wrong mouth shapes).
falLipSyncTranscription: z.boolean().nullable().optional(),
// Audio-to-video model and resolution for music-driven performance takes
// (scene.performanceStyle 'music'). Loosely validated like falModelId: a peer
// on a newer catalog may pin a model this install does not curate, which then
// falls back to the default (OmniHuman v1.5).
falMusicModelId: z.string().min(1).max(200).nullable().optional(),
falMusicResolution: z.string().min(1).max(16).nullable().optional(),
// Runway cutaway model (lib/runwayVideoModels.js), clip length and output
// size. Loosely validated like falModelId; null/omitted = the default model,
// the length covering each shot, that model's default size.
runwayModelId: z.string().min(1).max(64).nullable().optional(),
runwayDuration: z.number().min(1).max(60).nullable().optional(),
runwayResolution: z.string().min(1).max(16).nullable().optional(),
generationMode: z.enum(['image', 'audioReactive', 'suppliedAudio']).optional(),
audioReactiveLora: z.string().max(255).regex(/^[^/\\]+\.safetensors$/i).nullable().optional(),
audioReactiveScale: z.number().min(0).max(2).optional(),
}).strict();
// Timed lyric cues (#8964). Editable, user-owned text: a cue carries its line
// and optional timing against the project's CURRENT audio source. `startSec`
// null means "not yet timed" (plain pasted lyrics, or timings invalidated by an
// audio-source change — see projectsLogic.applyProjectPatch). The id is
// optional on input; the server mints one so edits stay addressable.
// `words` (#9074) is derived karaoke timing. Absent on older records and on
// peers that have not aligned; cleared with the line times when the audio changes.
const timedSec = z.number().min(0).max(36000).nullable().optional();
const lyricWordSchema = z.object({
w: z.string().min(1).max(80),
startSec: z.number().min(0).max(36000),
endSec: z.number().min(0).max(36000),
conf: z.enum(['matched', 'interpolated']),
}).strict().refine((word) => word.endSec >= word.startSec, {
message: 'word endSec must be >= startSec',
});
export const musicVideoLyricCueSchema = z.object({
id: z.string().min(1).max(64).optional(),
text: z.string().max(500),
startSec: timedSec,
endSec: timedSec,
words: z.array(lyricWordSchema).max(400).optional(),
matched: z.number().min(0).max(1).optional(),
suspect: z.boolean().optional(),
}).strict();
// A musical-phrase annotation: a span of the song with an optional visual
// intent (what the picture should do there). Phrase edges are preferred cut
// points for the shot planner and the intent is handed to the prompt seeder.
export const musicVideoPhraseSchema = z.object({
id: z.string().min(1).max(64).optional(),
label: z.string().max(120).optional(),
startSec: timedSec,
endSec: timedSec,
intent: z.string().max(2000).optional(),
}).strict();
// Shot pacing for the planner. `maxShotSec` is capped at the renderer's clip
// capacity (one generated clip); `hookSec` bounds the opening shot so the video opens on a cut.
export const musicVideoPacingSchema = z.object({
minShotSec: z.number().min(0.5).max(60).optional(),
maxShotSec: z.number().min(1).max(120).optional(),
hookSec: z.number().min(0.5).max(60).optional(),
}).strict();
// Lyric-sheet structure: a section header (`[Chorus]`) or a stage direction
// (`[Spoken, close]`) anchored to the index of the lyric line it precedes.
// `kind` is the normalized section part or delivery (see
// services/musicVideo/lyricMarkers.js); a free string so a newer peer's
// vocabulary still validates here.
export const musicVideoLyricMarkerSchema = z.object({
type: z.enum(['section', 'direction']),
label: z.string().trim().min(1).max(120),
kind: z.string().max(32).optional(),
line: z.number().int().min(0).max(2000),
}).strict();
const lyricCueList = z.array(musicVideoLyricCueSchema).max(2000);
const lyricMarkerList = z.array(musicVideoLyricMarkerSchema).max(500);
const phraseList = z.array(musicVideoPhraseSchema).max(500);
// ---- Visual specification + scene takes (#8965) ----------------------------
// A gallery image basename (under data/images). Every generated, uploaded, or
// imported still lands there, so this is the one reference vocabulary the image
// route's `referenceImageFiles` and the peer-sync `image` asset kind share.
const galleryImageName = z.string().min(1).max(256)
.regex(/^[^/\\]+\.(png|jpg|jpeg|webp)$/i, 'must be a gallery image basename (png/jpg/jpeg/webp)');
// A video-history id (the scene clip vocabulary `videoHistoryId` already uses).
const videoHistoryIdSchema = z.string().min(1).max(64).regex(/^[A-Za-z0-9._-]+$/, 'must be a video history id');
// Built-in character style routes (routes/musicVideoCharacterStyles.js).
export const musicVideoCharacterStyleParamsSchema = z.object({ id: z.enum(MUSIC_VIDEO_CHARACTER_STYLE_IDS) }).strict();
// null clears this install's character sheet for the style.
export const musicVideoCharacterStyleReferenceSchema = z.object({ imageId: galleryImageName.nullable() }).strict();
export const MUSIC_VIDEO_REFERENCE_ROLES = ['mood', 'character', 'wardrobe', 'set', 'prop', 'style'];
// How a reference is meant to be used (#8980): `reference` guides the look
// (style/character conditioning), `final-visible` is supplied media meant to
// appear in the finished video as-is, and `motion-reference` is scaffolding
// footage/stills for a hand-drawn or code-rendered pass — never final picture.
export const MUSIC_VIDEO_REFERENCE_USES = ['reference', 'final-visible', 'motion-reference'];
// The image backends accept at most four reference images for most models
// (imageGen/prepareParams.js referenceCap), so a project conditions each
// reference frame on at most this many of its flagged references.
export const MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES = 4;
// One moodboard/reference asset. `condition: true` sends the image to frame
// generation as a real conditioning input (`referenceImageFiles`) rather than
// only describing it in prose.
export const musicVideoVisualReferenceSchema = z.object({
id: z.string().min(1).max(64).optional(),
imageId: galleryImageName,
role: z.enum(MUSIC_VIDEO_REFERENCE_ROLES).optional(),
label: z.string().max(120).optional(),
note: z.string().max(1000).optional(),
condition: z.boolean().optional(),
use: z.enum(MUSIC_VIDEO_REFERENCE_USES).optional(),
}).strict();
export const musicVideoStyleReferencesSchema = z.array(z.object({
imageId: galleryImageName,
caption: z.string().trim().max(500).optional(),
}).strict()).max(8);
// The project's reusable visual specification. A patch merges per sub-field
// (like `concept`), and `references` / `palette` replace their list whole.
export const musicVideoVisualSpecSchema = z.object({
references: z.array(musicVideoVisualReferenceSchema).max(24).optional(),
palette: z.array(z.string().regex(/^#[0-9a-f]{6}$/i, 'palette colors are #rrggbb')).max(12).optional(),
typography: z.string().max(1000).optional(),
cameraRules: z.string().max(2000).optional(),
// An existing Mood Board this project draws inspiration from (display link).
moodBoardId: z.string().max(64).nullable().optional(),
}).strict().refine(
(spec) => (spec.references || []).filter((ref) => ref.condition).length <= MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES,
{ message: `at most ${MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES} references can condition frames`, path: ['references'] },
);
// `endImage` (#11173): a candidate for the scene's optional style-break end frame.
export const MUSIC_VIDEO_TAKE_KINDS = ['image', 'video', 'endImage'];
export const MUSIC_VIDEO_TAKE_STATUSES = ['candidate', 'rejected'];
// A take's intended use (#8980). A `motion-reference` take is scaffolding (e.g.
// generated footage to trace a hand-drawn pass over): it is kept as a candidate
// but never fills the scene's timeline slot automatically.
export const MUSIC_VIDEO_TAKE_USES = ['final', 'motion-reference'];
// Provider label for provenance — free text so a new external tool needs no
// schema change, but bounded to a slug so it can't smuggle a URL or a secret.
const providerSlug = z.string().min(1).max(40).regex(/^[a-z0-9][a-z0-9._-]*$/i, 'provider must be a short slug');
// A candidate asset offered for a scene slot outside the media-job hooks: an
// external-tool import, or a synchronous-lane render the client already holds.
// `assetId` is validated against its kind (gallery basename / history id) and
// then existence-checked by the route before it can reach the record.
export const musicVideoTakeInputSchema = z.object({
kind: z.enum(MUSIC_VIDEO_TAKE_KINDS),
assetId: z.string().min(1).max(256),
// `trimmed`: a clip take cut from a later start frame of another (the shot card's "Start clip here").
source: z.enum(['generated', 'imported', 'trimmed']).optional(),
provider: providerSlug.optional(),
originalName: z.string().max(255).optional(),
sourceImageId: galleryImageName.optional(),
inputAssets: z.array(z.object({ role: z.enum(['crop', 'mask']), assetId: galleryImageName, revision: z.number().int().min(1).max(1000000) }).strict()).max(4).optional(),
use: z.enum(MUSIC_VIDEO_TAKE_USES).optional(),
}).strict().superRefine((take, ctx) => {
const check = take.kind === 'video' ? videoHistoryIdSchema : galleryImageName;
const parsed = check.safeParse(take.assetId);
if (!parsed.success) ctx.addIssue({ code: 'custom', path: ['assetId'], message: parsed.error.issues[0].message });
});
/** One still or clip in a video's media pool, as the asset manager names it. */
const musicVideoPoolAssetSchema = z.object({
kind: z.enum(['image', 'video']),
assetId: z.string().min(1).max(256),
}).strict().superRefine((input, ctx) => {
const parsed = (input.kind === 'video' ? videoHistoryIdSchema : galleryImageName).safeParse(input.assetId);
if (!parsed.success) ctx.addIssue({ code: 'custom', path: ['assetId'], message: parsed.error.issues[0].message });
});
/** A search over a video's media pool by the prompts its stills and clips were made from. */
export const musicVideoPoolSearchQuerySchema = z.object({
q: z.string().trim().min(1).max(200),
}).strict();
/** ★ ingredient (good, not placed) or ✕ bad (to clean up); null clears the mark. */
export const musicVideoPoolMarkSchema = z.object({
items: z.array(musicVideoPoolAssetSchema).min(1).max(500),
mark: z.enum(['ingredient', 'bad']).nullable(),
}).strict();
/** Delete unused stills and clips from the media library (the asset manager's "Delete bad"). */
export const musicVideoPoolDeleteSchema = z.object({
items: z.array(musicVideoPoolAssetSchema).min(1).max(500),
}).strict();
/** File another music video's whole pool (an earlier draft) into this video's collection. */
export const musicVideoPoolImportSchema = z.object({
fromProjectId: z.string().min(1).max(200),
}).strict();
/** Search the whole media library for stills and clips to add to a video's assets. */
export const musicVideoLibrarySearchQuerySchema = z.object({
q: z.string().trim().min(1).max(200),
}).strict();
/** File stills and clips from the media library into a video's assets. */
export const musicVideoPoolAddSchema = z.object({
items: z.array(musicVideoPoolAssetSchema).min(1).max(500),
}).strict();
// Put an unused still or clip from the project's pool on a shot; `withAssetId` is its partner (a still's clip, a clip's still).
// `endImage` puts a still on the shot's end frame; only a start still pairs with a clip.
export const musicVideoPoolUseSchema = z.object({
kind: z.enum(['image', 'video', 'endImage']),
assetId: z.string().min(1).max(256),
withAssetId: z.string().min(1).max(256).optional(),
}).strict().superRefine((input, ctx) => {
if (input.kind === 'endImage' && input.withAssetId !== undefined) {
ctx.addIssue({ code: 'custom', path: ['withAssetId'], message: 'An end frame is placed on its own' });
}
const [still, clip] = input.kind === 'video' ? [input.withAssetId, input.assetId] : [input.assetId, input.withAssetId];
for (const [value, schema, path] of [[still, galleryImageName, input.kind === 'video' ? 'withAssetId' : 'assetId'], [clip, videoHistoryIdSchema, input.kind === 'video' ? 'assetId' : 'withAssetId']]) {
if (value === undefined) continue;
const parsed = schema.safeParse(value);
if (!parsed.success) ctx.addIssue({ code: 'custom', path: [path], message: parsed.error.issues[0].message });
}
});
// Review a take: reject/restore it and/or leave a note for regeneration.
export const musicVideoTakeReviewSchema = z.object({
status: z.enum(MUSIC_VIDEO_TAKE_STATUSES).optional(),
note: z.string().max(1000).nullable().optional(),
}).strict().refine((r) => r.status !== undefined || r.note !== undefined, { message: 'status or note is required' });
// Import externally generated assets (e.g. a Midjourney handoff). Each item is
// an asset the client already stored through the existing gallery upload
// routes; `sceneId` is optional when `originalName` carries the scene file tag
// from the exported handoff manifest.
export const musicVideoHandoffImportSchema = z.object({
provider: providerSlug,
items: z.array(z.object({
kind: z.enum(MUSIC_VIDEO_TAKE_KINDS),
assetId: z.string().min(1).max(256),
sceneId: z.string().min(1).max(64).optional(),
originalName: z.string().max(255).optional(),
use: z.enum(MUSIC_VIDEO_TAKE_USES).optional(),
}).strict()).min(1).max(200),
}).strict();
// Import lyric cues from pasted text: LRC (`[mm:ss.xx] line`), SRT/WebVTT
// cue blocks, or plain lines (untimed). `auto` sniffs the format.
export const musicVideoLyricsImportSchema = z.object({
format: z.enum(['auto', 'lrc', 'srt', 'text']).optional(),
text: z.string().max(200000),
mode: z.enum(['replace', 'append']).optional(),
}).strict();
// Import the linked track's lyric sheet. `replace` swaps the project's lines
// for the sheet; `if-empty` (the autopilot kickoff) imports only when the
// project has no lines yet, so a re-run never overwrites the director's edits.
export const musicVideoLyricsImportTrackSchema = z.object({
mode: z.enum(['replace', 'if-empty']).optional(),
}).strict();
// Word alignment (#9074) runs only when the director clicks. `cueId` re-aligns
// that line; omitted, every line is aligned.
export const musicVideoLyricsAlignSchema = z.object({
cueId: z.string().min(1).max(64).optional(),
separateVocals: z.boolean().optional(),
// A revised song: analyze, separate, align and carry the board across in one job.
retimeSong: z.boolean().optional(),
}).strict();
// ---- Composition manifest (#8984, part of #8966) ---------------------------
// A composed render lays timed text cues over the cut footage; `concat` (and a
// project with no manifest) is the plain clip concatenation. `code` draws the
// whole song as a seekable composition instead of generated footage. Cue text
// is the director's own, rendered as an independent typography layer — never
// baked into generated pixels. See services/musicVideo/composition.js.
// `document` renders a project-owned HTML composition document (its own
// folder under data/music-video/<projectId>/composition/) seeked over the
// song; see services/musicVideo/compositionDocument.js and documentRender.js.
export const MUSIC_VIDEO_COMPOSITION_MODES = ['concat', 'composed', 'code', 'document', 'eidoverse'];
// #9290: 'scene' cuts once per planned shot; 'intercut' re-cuts on section energy and sung words.
export const MUSIC_VIDEO_CUTTING_MODES = ['scene', 'intercut'];
// Shipped starting points a project can copy into its document folder.
export const MUSIC_VIDEO_DOCUMENT_TEMPLATES = ['layered'];
export const MUSIC_VIDEO_DOCUMENT_SOURCES = ['zip', 'directory', 'template', 'generated'];
// One immutable document version: data/music-video/<projectId>/composition/<versionId>.
export const MUSIC_VIDEO_DOCUMENT_DIRECTORY = /^music-video\/[A-Za-z0-9_-]{1,100}\/composition\/[A-Za-z0-9_-]{1,100}$/;
// One section function. Reject the calls that would make a frame depend on
// the clock, entropy, or the network — the preview and the render both seek.
export const MUSIC_VIDEO_CODE_SOURCE_MAX = 20000;
export const MUSIC_VIDEO_CODE_NONDETERMINISTIC = /\bMath\s*\.\s*random\b|\bDate\s*\.\s*now\b|\bperformance\s*\.\s*now\b|\bgetRandomValues\b|\bfetch\s*\(|\bXMLHttpRequest\b|\bWebSocket\b|\bimport\s*\(|\brequire\s*\(/;
export const isDeterministicCodeSource = (source) => typeof source === 'string'
&& source.length > 0
&& source.length <= MUSIC_VIDEO_CODE_SOURCE_MAX
&& !MUSIC_VIDEO_CODE_NONDETERMINISTIC.test(source);
// 'build' (#9291) lays a line down word by word on its sung onsets, the newest word in the accent color.
export const MUSIC_VIDEO_TYPOGRAPHY_TEMPLATES = ['fade', 'rise', 'typewriter', 'pop', 'build'];
export const MUSIC_VIDEO_TYPOGRAPHY_PLACEMENTS = ['upper', 'center', 'lower'];
export const MUSIC_VIDEO_TYPOGRAPHY_EMPHASES = ['subtitle', 'hero'];
export const MUSIC_VIDEO_TYPOGRAPHY_FONTS = ['sans', 'serif', 'mono'];
export const musicVideoTextCueSchema = z.object({
id: z.string().min(1).max(64).optional(),
text: z.string().max(500),
startSec: timedSec,
endSec: timedSec,
template: z.enum(MUSIC_VIDEO_TYPOGRAPHY_TEMPLATES).optional(),
placement: z.enum(MUSIC_VIDEO_TYPOGRAPHY_PLACEMENTS).optional(),
emphasis: z.enum(MUSIC_VIDEO_TYPOGRAPHY_EMPHASES).optional(),
// Sung word onsets for the 'build' template (#9291).
words: z.array(z.object({ w: z.string().min(1).max(60), atSec: z.number().min(0).max(36000) }).strict()).max(80).optional(),
}).strict();
const codeSectionSource = z.string().min(1).max(MUSIC_VIDEO_CODE_SOURCE_MAX)
.refine(isDeterministicCodeSource, 'section source must be deterministic and offline');
export const musicVideoCodeVideoSchema = z.object({
providerId: z.string().max(120).nullable().optional(),
model: z.string().max(200).nullable().optional(),
generatedAt: z.string().max(40).nullable().optional(),
sections: z.array(z.object({
id: z.string().min(1).max(64),
source: codeSectionSource,
}).strict()).max(40),
}).strict();
export const musicVideoCodeGenerateSchema = z.object({
providerId: z.string().max(120).optional(),
model: z.string().max(200).optional(),
effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();
// Where the project's composition document lives. Set only by the import
// routes; a PATCH that carries it back is ignored (the stored pointer wins).
export const musicVideoCompositionDocumentSchema = z.object({
directory: z.string().max(300).regex(MUSIC_VIDEO_DOCUMENT_DIRECTORY, 'directory is a composition document version folder'),
entry: z.literal('index.html').optional(),
updatedAt: z.string().max(40).nullable().optional(),
source: z.object({
kind: z.enum(MUSIC_VIDEO_DOCUMENT_SOURCES),
name: z.string().max(200).nullable().optional(),
}).strict().nullable().optional(),
files: z.number().int().min(0).max(4096).optional(),
bytes: z.number().int().min(0).optional(),
}).strict();
// The optional HUD block a composition document may draw (the shipped
// layered template reads it from PORTOS_MV.composition.overlay).
export const musicVideoCompositionOverlaySchema = z.object({
enabled: z.boolean().optional(),
titleLines: z.array(z.string().max(120)).max(4).optional(),
meter: z.object({
label: z.string().max(40).optional(),
// [songSec, percent] pairs, eased between.
keyframes: z.array(z.tuple([z.number().min(0).max(36000), z.number().min(0).max(100)])).max(200).optional(),
}).strict().nullable().optional(),
ticker: z.array(z.string().max(200)).max(40).optional(),
timecode: z.boolean().optional(),
timecodeStartSec: z.number().min(0).max(86400).optional(),
}).strict();
export const musicVideoNarrativeEventSchema = z.object({
id: z.string().min(1).max(64),
name: z.string().min(1).max(120),
kind: z.enum(NARRATIVE_EVENT_KINDS),
anchor: z.discriminatedUnion('kind', [
z.object({ kind: z.literal('time'), atSec: z.number().min(0).max(36000), offsetSec: z.number().min(-900).max(900).optional() }).strict(),
z.object({ kind: z.literal('onset'), band: z.enum(['low', 'mid', 'high']), index: z.number().int().min(0).max(100000), offsetSec: z.number().min(-900).max(900).optional() }).strict(),
z.object({ kind: z.literal('word'), cueId: z.string().min(1).max(64), wordIndex: z.number().int().min(0).max(1000), offsetSec: z.number().min(-900).max(900).optional() }).strict(),
]).nullable(),
durationSec: z.number().positive().max(900),
narrativeFunction: z.string().min(1).max(1000),
mediumRationale: z.string().min(1).max(1000),
text: z.string().max(500).optional(),
motif: z.string().max(120).optional(),
before: z.string().max(120).optional(),
after: z.string().max(120).optional(),
fromValue: z.number().finite().min(-1000000).max(1000000).optional(),
toValue: z.number().finite().min(-1000000).max(1000000).optional(),
}).strict();
export const musicVideoReactiveSectionSchema = z.object({
sectionId: z.string().min(1).max(64),
gain: z.number().min(0).max(1),
maxGain: z.number().min(0).max(1),
}).strict();
// Scene code is data until the isolated Eidoverse container renders it. No
// executable, host path, output path or remote asset can be selected here.
export const musicVideoEidoverseSceneSchema = z.object({
inlineScript: z.string().trim().min(1).max(100000),
assets: z.record(z.string().regex(/^[A-Za-z0-9_-]{1,80}$/),
z.string().max(300).regex(/^eidoverse\/assets\/(?:[A-Za-z0-9_-][A-Za-z0-9_.-]*\/)*[A-Za-z0-9_-][A-Za-z0-9_.-]*$/))
.refine(assets => Object.keys(assets).length <= 32, 'At most 32 assets').optional(),
}).strict();
// Replaced whole by a project PATCH (the editor sends the full manifest).
export const musicVideoCompositionSchema = z.object({
version: z.literal(1).optional(),
mode: z.enum(MUSIC_VIDEO_COMPOSITION_MODES).optional(),
authoringRenderer: z.enum(['canvas', 'three']).optional(),
// Curated film style grammar the document authoring prompt follows (#10254).
styleGrammarId: knownFilmStyleIdSchema.optional(),
cutting: z.enum(MUSIC_VIDEO_CUTTING_MODES).optional(),
grade: z.object({
preset: z.enum(MUSIC_VIDEO_GRADE_PRESETS).optional(),
grain: z.number().min(0).max(MUSIC_VIDEO_GRADE_MAX_GRAIN).optional(),
sections: z.array(z.object({
sceneId: z.string().min(1).max(120),
preset: z.enum(MUSIC_VIDEO_GRADE_PRESETS),
}).strict()).max(1000).optional(),
}).strict().nullable().optional(),
textCues: z.array(musicVideoTextCueSchema).max(1000).optional(),
style: z.object({
color: z.string().regex(/^#[0-9a-f]{6}$/i, 'color is #rrggbb').optional(),
font: z.enum(MUSIC_VIDEO_TYPOGRAPHY_FONTS).optional(),
accentColor: z.string().regex(/^#[0-9a-f]{6}$/i, 'accentColor is #rrggbb').optional(),
}).strict().optional(),
posterSec: timedSec,
eidoverseScene: musicVideoEidoverseSceneSchema.nullable().optional(),
codeVideo: musicVideoCodeVideoSchema.nullable().optional(),
document: musicVideoCompositionDocumentSchema.nullable().optional(),
documentDraft: musicVideoCompositionDocumentSchema.nullable().optional(),
overlay: musicVideoCompositionOverlaySchema.nullable().optional(),
narrativeEvents: z.array(musicVideoNarrativeEventSchema).max(200).refine((events) => new Set(events.map((event) => event.id)).size === events.length, 'event ids must be unique').optional(),
reactiveSections: z.array(musicVideoReactiveSectionSchema).max(40).refine((sections) => new Set(sections.map((section) => section.sectionId)).size === sections.length, 'section ids must be unique').optional(),
}).strict();
// A relative folder inside data/ to copy a composition document from.
export const musicVideoDocumentDirectoryImportSchema = z.object({
directory: z.string().min(1).max(1024).refine((value) => !value.startsWith('/') && !value.includes('\\') && !value.includes(':')
&& !value.includes('\0') && !value.split('/').some((part) => part === '..' || part === '.' || !part), 'directory must be a relative path inside data'),
}).strict();
export const musicVideoDocumentFileQuerySchema = z.object({
path: z.string().min(1).max(512),
draft: z.literal('1').optional(),
}).strict();
export const musicVideoDocumentDraftQuerySchema = z.object({ draft: z.literal('1').optional() }).strict();
export const musicVideoDocumentCandidateSchema = z.object({
directory: z.string().regex(MUSIC_VIDEO_DOCUMENT_DIRECTORY),
}).strict();
export const musicVideoMixedMediaRegenerateSchema = musicVideoCodeGenerateSchema.extend({
expectedDraft: z.string().regex(MUSIC_VIDEO_DOCUMENT_DIRECTORY),
}).strict();
export const musicVideoDocumentTemplateSchema = z.object({
template: z.enum(MUSIC_VIDEO_DOCUMENT_TEMPLATES).optional(),
}).strict();
// #10589: a shot's structured camera move — a shared camera-movement id
// (lib/cameraMovements.js) with optional speed, end framing, downbeat landing
// and, for a still camera, the reason it holds. Feeds the i2v camera block and
// the layered template's camera rig. `null` clears it.
export const musicVideoSceneCameraSchema = z.object({
move: z.enum(CAMERA_MOVEMENT_VALUES),
speed: z.enum(CAMERA_SPEEDS).optional(),
endFraming: z.enum(CAMERA_FRAMINGS).optional(),
onBeat: z.boolean().optional(),
reason: z.string().trim().max(300).optional(),
}).strict();
// #12763: the Casting cast member a shot features and the variant (age, era, look) its
// frames should show. Conditioning leads with that member's render guides; null clears it.
export const musicVideoSceneCharacterVariantSchema = z.object({
ingredientId: z.string().min(1).max(128),
age: z.number().int().min(0).max(150).optional(),
era: z.enum(CAST_ERAS).optional(),
wardrobeId: z.string().trim().min(1).max(59).optional(),
}).strict();
// Per-scene visual layer (#8985) — footage, a moved still, or a title card;
// see musicVideoLayers.js. Only a composed render honors a non-footage layer.
const sceneLayerFields = {
// The references (visual spec ids) sent with this shot's frame renders; absent or null = the automatic set.
frameReferenceIds: z.array(z.string().min(1).max(128)).max(MUSIC_VIDEO_MAX_CONDITIONING_REFERENCES).nullable().optional(),
characterVariant: musicVideoSceneCharacterVariantSchema.nullable().optional(),
camera: musicVideoSceneCameraSchema.nullable().optional(),
visualLayer: z.enum(MUSIC_VIDEO_VISUAL_LAYERS).optional(),
stillMove: z.enum(MUSIC_VIDEO_STILL_MOVES).optional(),
// How a clip of another shape fills the video's frame (musicVideoLayers.js).
frameFit: z.enum(MUSIC_VIDEO_FRAME_FITS).optional(),
// A footage clip played faster or slower by whole frames a second, and slid against the song by whole frames; null clears it.
speedFps: z.number().int().min(CLIP_SPEED_FPS_RANGE.min).max(CLIP_SPEED_FPS_RANGE.max).nullable().optional(),
offsetFrames: z.number().int().min(CLIP_OFFSET_FRAMES_RANGE.min).max(CLIP_OFFSET_FRAMES_RANGE.max).nullable().optional(),
// The clip plays backwards (a footage shot; never a lip-sync performance).
reverse: z.boolean().nullable().optional(),
// A clip shorter than its shot holds its last frame for the rest of the shot; null clears it.
holdLastFrame: z.boolean().nullable().optional(),
// The shot's own film look (lib/filmLook.js), kept when the video's look changes; null follows the video's.
filmLook: filmLookSchema.nullable().optional(),
// A VHS glitch over the cut into / out of this shot (musicVideoTransitions.js); null clears it.
transitionIn: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),
transitionOut: z.enum(MUSIC_VIDEO_TRANSITIONS).nullable().optional(),
// Glitches at moments inside the shot: `atSec` from the shot's start, `lengthSec` stretching the style; null clears them.
glitches: z.array(z.object({
atSec: z.number().min(0).max(3600),
style: z.enum(MUSIC_VIDEO_TRANSITIONS),
lengthSec: z.number().positive().max(4).nullable().optional(),
})).max(MUSIC_VIDEO_SHOT_GLITCH_LIMIT).nullable().optional(),
// An effect across the cut out of this shot (musicVideoCutEffects.js), kept with its settings while switched off; null clears it.
cutEffect: z.object({
style: z.enum(MUSIC_VIDEO_CUT_EFFECTS),
enabled: z.boolean().optional(),
overlapSec: z.number().min(BEAT_TOGGLE_OVERLAP.min).max(BEAT_TOGGLE_OVERLAP.max).optional(),
rate: z.enum(BEAT_TOGGLE_RATES).optional(),
}).nullable().optional(),
// A code-drawn effect a still shot plays instead of a clip (musicVideoImageEffects.js) and how long
// it takes to finish; null clears it.
imageEffect: z.enum(MUSIC_VIDEO_IMAGE_EFFECTS).nullable().optional(),
imageEffectSec: z.number().min(IMAGE_EFFECT_SEC_RANGE.min).max(IMAGE_EFFECT_SEC_RANGE.max).nullable().optional(),
cardText: z.string().max(500).nullable().optional(),
// #10302: footage that the composition also draws code over; still counts as footage.
codeOverlay: z.boolean().optional(),
// Footage whose clip was rendered from code (an uploaded code render): the board labels it Code.
codeClip: z.boolean().optional(),
cardColor: z.string().regex(/^#[0-9a-f]{6}$/i, 'card color is #rrggbb').nullable().optional(),
// #10583: where a composition document's lyric type may sit in this shot, and the role of its lines.
textZone: z.enum(MUSIC_VIDEO_TEXT_ZONES).nullable().optional(),
lyricRole: z.enum(MUSIC_VIDEO_LYRIC_ROLES).nullable().optional(),
lyricSize: z.enum(MUSIC_VIDEO_LYRIC_SIZES).nullable().optional(),
};
// ---- Pre-production treatment (#8980) --------------------------------------
// The treatment sits between the director's concept/visual spec and the timed
// shot planner: a structured brief, a compiled whole-song arc, per-shot
// direction keyed to the board's real scene ids, and a proof checklist. Its own
// routes edit it (never the generic project PATCH) so every write carries the
// revision it was based on. See services/musicVideo/treatment.js.
export const MUSIC_VIDEO_ASPECT_RATIOS = ['16:9', '9:16', '1:1', '4:5', '2.39:1'];
export const MUSIC_VIDEO_BEAT_ROLES = ['opening', 'build', 'contrast', 'payoff', 'release'];
// Treatment shot categories (the arc's balance axis). Distinct from the scene's
// render-facing `shotMode` (#8977: cutaway | performance) — Apply maps a
// performance direction onto it when the backend can lip-sync.
export const MUSIC_VIDEO_TREATMENT_SHOT_MODES = ['performance', 'cutaway', 'graphic'];
export const MUSIC_VIDEO_SHOT_ROUTES = ['generated', 'supplied-asset', 'code-2d'];
export const MUSIC_VIDEO_NEGATIVE_SPACE = ['none', 'upper', 'center', 'lower'];
export const MUSIC_VIDEO_TYPOGRAPHY_ROLES = ['none', 'subtitle', 'hero'];
export const MUSIC_VIDEO_PROOF_CHECKS = ['identity-continuity', 'readable-text', 'cut-continuity', 'audio-alignment', 'continuous-motion', 'lip-sync'];
export const MUSIC_VIDEO_PROOF_STATUSES = ['proposed', 'passed', 'failed'];
// A manually supplied reference note/URL. The URL is provenance the director
// typed — PortOS never fetches it, and its text is treated as untrusted data.
const referenceUrl = z.string().max(2000).regex(/^https?:\/\/\S+$/i, 'reference URLs must be http(s)');
export const musicVideoTreatmentReferenceNoteSchema = z.object({
id: z.string().min(1).max(64).optional(),
note: z.string().max(1000).optional(),
url: referenceUrl.nullable().optional(),
}).strict();
// Every brief field is optional; a patch merges per field.
export const musicVideoTreatmentBriefSchema = z.object({
audience: z.string().max(500).optional(),
destination: z.string().max(200).optional(),
aspectRatio: z.enum(MUSIC_VIDEO_ASPECT_RATIOS).nullable().optional(),
emotion: z.string().max(500).optional(),
premise: z.string().max(2000).optional(),
hookObjective: z.string().max(1000).optional(),
graphicLanguage: z.string().max(1000).optional(),
mustHave: z.string().max(2000).optional(),
avoid: z.string().max(2000).optional(),
referenceNotes: z.array(musicVideoTreatmentReferenceNoteSchema).max(20).optional(),
}).strict();
const treatmentText = (max) => z.string().max(max).optional();
export const musicVideoTreatmentMotifSchema = z.object({
id: z.string().min(1).max(64).optional(),
name: z.string().max(120),
description: treatmentText(1000),
evolution: treatmentText(1000),
rationale: treatmentText(1000),
}).strict();
export const musicVideoProductionPolicySchema = z.object({
strategy: z.enum(['legacy', 'code-first']).optional(),
maxGeneratedVideoPercent: z.number().min(0).max(100).optional(),
}).strict();
export const musicVideoActionContractSchema = z.custom((value) => value != null && !shotActionContractProblem(value), { message: 'Invalid shot action contract' });
export const musicVideoShotDirectionPatchSchema = z.object({
sceneId: z.string().min(1).max(64),
actionContract: musicVideoActionContractSchema.nullable().optional(),
medium: z.enum(MUSIC_VIDEO_MEDIA).optional(),
mediumRationale: treatmentText(1000),
mediumPinned: z.boolean().optional(),
mode: z.enum(MUSIC_VIDEO_TREATMENT_SHOT_MODES).optional(),
route: z.enum(MUSIC_VIDEO_SHOT_ROUTES).optional(),
focalSubject: treatmentText(500),
framing: treatmentText(500),
negativeSpace: z.enum(MUSIC_VIDEO_NEGATIVE_SPACE).optional(),
typographyRole: z.enum(MUSIC_VIDEO_TYPOGRAPHY_ROLES).optional(),
emphasis: treatmentText(500),
transitionIn: treatmentText(300),
transitionOut: treatmentText(300),
rationale: treatmentText(1000),
suggestedFramePrompt: treatmentText(2000),
suggestedPrompt: treatmentText(2000),
}).strict();
// PATCH /:id/treatment. `baseRevision` is the treatment revision the edit was
// made against (0 before a treatment exists); a mismatch is a 409 so a stale tab
// or a peer's older copy can never overwrite a newer edit. `rebase` accepts the
// project's CURRENT visual spec / lyrics / scene set as the treatment's basis
// without recompiling (an audio change still needs a recompile).
export const musicVideoTreatmentUpdateSchema = z.object({
baseRevision: z.number().int().min(0),
brief: musicVideoTreatmentBriefSchema.optional(),
beats: z.array(z.object({
id: z.string().min(1).max(64),
objective: treatmentText(1000),
rationale: treatmentText(1000),
}).strict()).max(200).optional(),
motifs: z.array(musicVideoTreatmentMotifSchema).max(12).optional(),
shotDirections: z.array(musicVideoShotDirectionPatchSchema).max(500).optional(),
rebase: z.boolean().optional(),
}).strict();
// POST /:id/treatment/compile — an explicit user action. `useAi: false` drafts
// the deterministic treatment only (no provider call at all).
export const musicVideoTreatmentCompileSchema = z.object({
baseRevision: z.number().int().min(0),
useAi: z.boolean().optional(),
providerId: z.string().max(64).optional(),
model: z.string().max(200).optional(),
}).strict();
// POST /:id/treatment/apply. Manually edited scene prompts are kept unless the
// director explicitly lists the scene in `overwrite` with the fingerprint of
// the prompts they reviewed — a prompt edited after the review stays kept.
export const musicVideoTreatmentApplySchema = z.object({
revision: z.number().int().min(0),
overwrite: z.array(z.object({
sceneId: z.string().min(1).max(64),
promptFingerprint: z.string().min(1).max(64),
}).strict()).max(500).optional(),
addTextCues: z.boolean().optional(),
}).strict();
// Record a proof-checklist review. Evidence names a real artifact of this
// project (a scene's clip or frame take, or the final render).
export const musicVideoTreatmentProofReviewSchema = z.object({
baseRevision: z.number().int().min(0),
status: z.enum(MUSIC_VIDEO_PROOF_STATUSES),
evidence: z.object({
videoHistoryId: z.string().min(1).max(64).regex(/^[A-Za-z0-9._-]+$/, 'must be a video history id').optional(),
imageId: galleryImageName.optional(),
note: z.string().max(2000).optional(),
}).strict().optional(),
}).strict();
// ---- Draft excerpt render (#8986) -------------------------------------------
// A director-chosen `[startSec, endSec)` window re-rendered through the same
// composed pipeline as a full render, plus a cut/cue contact sheet and
// timecoded review notes against the excerpt's OWN timeline (0 = its start).
// See services/musicVideo/excerpt.js / excerptRender.js.
export const MUSIC_VIDEO_EXCERPT_NOTE_VERDICTS = ['flagged', 'approved'];
export const musicVideoExcerptRequestSchema = z.object({
startSec: z.number().min(0).max(36000),
endSec: z.number().min(0).max(36000),
// #9280: a social cut renders at another frame and fades its audio edges.
aspect: z.enum(['16:9', '9:16', '1:1']).optional(),
fade: z.boolean().optional(),
}).strict().refine((r) => r.endSec > r.startSec, { message: 'endSec must be greater than startSec' });
// #9280: hook-window suggestions for social cuts.
export const musicVideoSocialCutsQuerySchema = z.object({
count: z.coerce.number().int().min(1).max(10).optional(),
minSec: z.coerce.number().min(3).max(120).optional(),
maxSec: z.coerce.number().min(5).max(180).optional(),
}).strict().refine((q) => q.minSec == null || q.maxSec == null || q.maxSec >= q.minSec, { message: 'maxSec must be at least minSec' });
// #9281: publishing kit — per-platform copy edits, the copy draft request, the chosen thumbnail.
const kitText = (max) => z.string().max(max);
export const musicVideoPublishCopyPatchSchema = z.object({
youtube: z.object({ title: kitText(100), description: kitText(5000), tags: z.array(kitText(60)).max(30) }).partial().strict().optional(),
shorts: z.object({ title: kitText(100), description: kitText(5000) }).partial().strict().optional(),
x: z.object({ hook: kitText(280), story: kitText(25000) }).partial().strict().optional(),
linkedin: z.object({ post: kitText(3000) }).partial().strict().optional(),
facebook: z.object({ post: kitText(63206) }).partial().strict().optional(),
tiktok: z.object({ caption: kitText(2200) }).partial().strict().optional(),
instagram: z.object({ caption: kitText(2200) }).partial().strict().optional(),
reddit: z.object({ title: kitText(300), body: kitText(40000) }).partial().strict().optional(),
stackerNews: z.object({ title: kitText(80), body: kitText(40000) }).partial().strict().optional(),
substack: z.object({ title: kitText(100), subtitle: kitText(250), body: kitText(40000) }).partial().strict().optional(),
notes: kitText(8000).optional(),
// The draft inputs save as they are edited, not only when Draft runs; '' clears a link.
links: z.object({ youtube: z.union([z.string().url().max(500), z.literal('')]), song: z.union([z.string().url().max(500), z.literal('')]) }).partial().strict().optional(),
draftOptions: z.object({
include: z.object({ title: z.boolean(), lyrics: z.boolean(), spend: z.boolean(), chapters: z.boolean(), hashtags: z.boolean() }).partial().strict().optional(),
length: z.enum(['short', 'full']).optional(),
}).strict().optional(),
}).strict();
export const musicVideoPublishCopyDraftSchema = z.object({
providerId: z.string().max(200).nullable().optional(),
model: z.string().max(200).nullable().optional(),
notes: kitText(8000).optional(),
links: z.object({ youtube: z.string().url().max(500), song: z.string().url().max(500) }).partial().strict().optional(),
// What the draft may use beyond the notes and links; omitted keys keep their defaults (title on, the rest off).
include: z.object({ title: z.boolean(), lyrics: z.boolean(), spend: z.boolean(), chapters: z.boolean(), hashtags: z.boolean() }).partial().strict().optional(),
length: z.enum(['short', 'full']).optional(),
// The director agreed to replace posts written or edited by hand since the last draft.
replaceEdited: z.boolean().optional(),
}).strict();
// Plan the promotion as scheduled steps for the artist (Review Hub › Actions).
export const musicVideoPromotionPlanSchema = z.object({
providerId: z.string().max(200).nullable().optional(),
model: z.string().max(200).nullable().optional(),
goal: z.string().trim().max(1500).optional(),
audience: z.string().trim().max(1000).optional(),
days: z.number().int().min(1).max(30).optional(),
}).strict();
export const musicVideoPublishThumbnailSchema = z.object({ filename: z.string().min(1).max(300) }).strict();
// Release cover art: a source (a kit thumbnail or a gallery image) composed
// with the title and artist tag, or a fresh source image from a backend.
const coverArtSourceSchema = z.object({ kind: z.enum(['thumbnail', 'image']), filename: z.string().min(1).max(300) }).strict();
export const musicVideoCoverArtComposeSchema = z.object({
source: coverArtSourceSchema.optional(),
title: z.string().max(60).optional(),
tag: z.string().max(24).optional(),
focusX: z.number().min(0).max(1).optional(),
// false = a finished cover from elsewhere: squared and sized, no title or tag set on it.
lettering: z.boolean().optional(),
}).strict();
// The YouTube thumbnail: a source composed 16:9 with the title in the cover's lettering.
export const musicVideoYoutubeThumbnailComposeSchema = z.object({
source: coverArtSourceSchema.optional(),
title: z.string().max(60).optional(),
focusX: z.number().min(0).max(1).optional(),
focusY: z.number().min(0).max(1).optional(),
lettering: z.boolean().optional(),
}).strict();
// "Paint the title": the image model restyles a frame with the title drawn in. Preview takes no source.
export const musicVideoYoutubeThumbnailPaintPreviewSchema = z.object({
title: z.string().trim().min(1).max(60),
notes: z.string().max(1500).optional(),
}).strict();
export const musicVideoYoutubeThumbnailPaintSchema = musicVideoYoutubeThumbnailPaintPreviewSchema.extend({ source: coverArtSourceSchema }).strict();
export const musicVideoCoverArtDesignSchema = z.object({
direction: z.string().max(1500).optional(),
providerId: z.string().min(1).max(200).optional(),
model: z.string().min(1).max(200).optional(),
}).strict();
// #10345: the Lettering controls. A design is every COVER_DESIGN_OPTIONS field
// plus tracking, colors and the rule; any subset is a patch over the song's
// current design. `typeface` is a free string here (a built-in name or a
// `font:<id>` for an uploaded font) and is resolved against the uploaded fonts
// when the design is normalized.
const coverHex = z.string().regex(/^#[0-9a-f]{6}$/i);
const coverDesignFields = Object.fromEntries(Object.entries(COVER_DESIGN_OPTIONS)
.map(([key, list]) => [key, key === 'typeface' ? z.string().min(1).max(60) : z.enum(list)]));
export const musicVideoCoverDesignSchema = z.object({
...coverDesignFields,
tracking: z.number().min(-0.05).max(0.3),
titleColor: coverHex,
accentColor: coverHex,
rule: z.boolean(),
}).partial().strict();
export const musicVideoCoverDesignSaveSchema = z.object({ design: musicVideoCoverDesignSchema }).strict();
export const musicVideoArtistStyleSaveSchema = z.object({
name: z.string().trim().min(1).max(60),
design: musicVideoCoverDesignSchema,
}).strict();
export const musicVideoArtistStyleDeleteSchema = z.object({ name: z.string().trim().min(1).max(60) }).strict();
export const musicVideoCoverArtGenerateSchema = z.object({
notes: z.string().max(1500).optional(),
reference: z.object({ kind: z.literal('image'), filename: z.string().min(1).max(300) }).strict().optional(),
}).strict();
// #9282: posting to a platform through the PortOS Browser. One strict options
// object covers every target; each target's payload builder reads only its own.
export const MUSIC_VIDEO_PUBLISH_TARGETS = Object.freeze(['youtube', 'shorts', 'tiktok', 'instagram', 'x', 'linkedin', 'facebook', 'reddit', 'stackerNews', 'substack', 'suno', 'sunoHook', 'distrokid']);
export const musicVideoPublishTargetSchema = z.enum(MUSIC_VIDEO_PUBLISH_TARGETS);
const publishUrl = z.string().url().max(500);
// #9287: which platforms the director posts to (opt-in), the account for each,
// and a post's link, reception and notes.
const publishPlatformEntry = z.object({ enabled: z.boolean(), account: z.string().max(100).nullable() }).partial().strict();
// DistroKid also keeps the release answers that repeat on every project ('' or null forgets one).
const rememberedAnswer = z.string().max(100).nullable();
const distrokidPlatformEntry = publishPlatformEntry.extend({
defaults: z.object(Object.fromEntries(DISTROKID_REMEMBERED_OPTIONS.map((k) => [k, rememberedAnswer]))).partial().strict(),
}).partial().strict();
export const musicVideoPublishPlatformsPatchSchema = z.object(Object.fromEntries(MUSIC_VIDEO_PUBLISH_TARGETS
.map((t) => [t, (t === 'distrokid' ? distrokidPlatformEntry : publishPlatformEntry).optional()]))).strict();
export const musicVideoPublishPostSchema = z.object({
url: publishUrl.nullable(),
// Marks the platform done without a link (a DistroKid upload has none until the stores go live).
posted: z.literal(true),
reception: z.enum(['good', 'mixed', 'poor']).nullable(),
notes: z.string().max(2000).nullable(),
// The release's other posts this one now links to (cross-links), added to what it linked already.
links: z.array(musicVideoPublishTargetSchema).max(MUSIC_VIDEO_PUBLISH_TARGETS.length),
}).partial().strict().refine((b) => Object.keys(b).length > 0, { message: 'url, posted, reception, notes or links is required' });
// Whether new drafts list the release's other posts, and which posted platform gets its missing links.
export const musicVideoPublishCrossLinksSchema = z.object({ enabled: z.boolean() }).strict();
export const musicVideoCrossLinkTargetSchema = z.enum(CROSS_LINK_EDIT_TARGETS);
export const musicVideoCrossLinkEditSchema = z.object({}).strict();
export const musicVideoPublishPrepareSchema = z.object({
subreddit: z.string().max(40),
kind: z.enum(['self', 'link', 'video']),
url: publishUrl,
flairId: z.string().max(100),
flairText: z.string().max(64),
firstComment: kitText(10000),
// LinkedIn, Facebook: put the full video and song links in a first comment (default on).
linksComment: z.boolean(),
// Facebook: turn on the post's AI label (default on).
aiLabel: z.boolean(),
territory: z.string().max(40),
// Substack: the publication (name.substack.com or a custom domain); defaults to the account under Where you post.
publication: z.string().trim().min(1).max(200),
songUrl: publishUrl,
pin: z.boolean(),
// Suno Hook: keep the page's lyric overlay (default off: the cut carries its own).
showLyrics: z.boolean(),
prompt: kitText(25000),
storyImage: z.string().min(1).max(300),
cutId: z.string().min(1).max(100),
// Fill a draft for a platform the release was already posted to.
again: z.boolean(),
// DistroKid (the song as a Spotify single): who it is by and the store flags.
artistName: z.string().trim().min(1).max(100),
songwriterFirst: z.string().trim().min(1).max(100),
songwriterLast: z.string().trim().min(1).max(100),
releaseDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
explicit: z.boolean(),
instrumental: z.boolean(),
aiLyrics: z.boolean(),
aiMusic: z.boolean(),
aiVocals: z.boolean(),
genre: z.string().trim().min(1).max(60),
secondaryGenre: z.string().trim().min(1).max(60),
language: z.string().trim().min(1).max(60),
songwriterRole: z.enum(['music', 'lyrics', 'both']),
newArtistProfile: z.boolean(),
preserveCaps: z.boolean(),
performerName: z.string().trim().min(1).max(100),
performerRole: z.string().trim().min(1).max(60),
producerName: z.string().trim().min(1).max(100),
previewStartSec: z.number().min(0).max(3600),
}).partial().strict();
export const musicVideoExcerptNoteSchema = z.object({
atSec: z.number().min(0).max(36000),
note: z.string().min(1).max(2000),
verdict: z.enum(MUSIC_VIDEO_EXCERPT_NOTE_VERDICTS).nullable().optional(),
}).strict();
export const musicVideoExcerptNoteUpdateSchema = z.object({
atSec: z.number().min(0).max(36000).optional(),
note: z.string().min(1).max(2000).optional(),
verdict: z.enum(MUSIC_VIDEO_EXCERPT_NOTE_VERDICTS).nullable().optional(),
}).strict().refine((r) => r.atSec !== undefined || r.note !== undefined || r.verdict !== undefined, { message: 'atSec, note or verdict is required' });
// ---- Selective section revision (#8987) -------------------------------------
// Reject the flagged sections of a reviewed draft excerpt and regenerate only
// those. `sceneIds` names the sections explicitly; omitted, every section
// holding a `flagged` note is revised. See services/musicVideo/revision.js.
export const musicVideoDependencyRepairSchema = z.object({ basis: z.string().min(1).max(128) }).strict();
export const musicVideoRevisionStartSchema = z.object({
sceneIds: z.array(z.string().min(1).max(200)).min(1).max(500).optional(),
}).strict();
// ---- Opt-in automatic review/retries (#8988) --------------------------------
// Every limit is required: a run never picks its own budget. `maxAttempts`
// bounds the reviews (provider calls); `maxGenerations` is the spend limit on
// paid scene-generation jobs. See services/musicVideo/autoReview.js.
export const musicVideoAutoReviewLimitsSchema = z.object({
maxAttempts: z.number().int().min(1).max(10),
maxGenerations: z.number().int().min(0).max(100),
}).strict();
export const musicVideoAutoReviewStartSchema = z.object({
startSec: z.number().min(0).max(36000),
endSec: z.number().min(0).max(36000),
limits: musicVideoAutoReviewLimitsSchema,
providerId: z.string().min(1).max(200).nullable().optional(),
model: z.string().min(1).max(200).nullable().optional(),
}).strict().refine((r) => r.endSec > r.startSec, { message: 'endSec must be greater than startSec' });
// Resume may RAISE either limit (never below what the run already used).
export const musicVideoAutoReviewResumeSchema = z.object({
limits: musicVideoAutoReviewLimitsSchema.partial().optional(),
}).strict();
// ---- Server-owned production run (#9066) -----------------------------------
// The allowed pool: explicit image/video render backends (and models) the run
// may dispatch to — re-checked for eligibility and capability at every
// dispatch. Every limit but the dollar cap is required; the cap is accepted
// only when every metered route has a known price (services/musicVideo/production.js).
const musicVideoProductionRouteSchema = z.discriminatedUnion('kind', [
z.object({ kind: z.literal('image'), mode: z.enum(IMAGE_GEN_MODES), model: z.string().trim().min(1).max(200).nullable().optional() }).strict(),
z.object({ kind: z.literal('video'), mode: z.enum(VIDEO_GEN_MODES), model: z.string().trim().min(1).max(200).nullable().optional() }).strict(),
]);
export const musicVideoProductionLimitsSchema = z.object({
maxGenerations: z.number().int().min(1).max(500),
maxReviewAttempts: z.number().int().min(1).max(10),
spendCapUsd: z.number().min(0).max(100000).nullable().optional(),
}).strict();
// A code-authoring provider pin: both ids are required, effort is optional.
const musicVideoAuthoringSchema = z.object({
providerId: z.string().min(1).max(200),
model: z.string().min(1).max(200),
effort: z.enum(EFFORT_LEVELS).nullable().optional(),
}).strict();
export const musicVideoProductionStartSchema = z.object({
directive: z.string().max(4000).optional(),
pool: z.array(musicVideoProductionRouteSchema).max(12),
limits: musicVideoProductionLimitsSchema,
authoring: musicVideoAuthoringSchema.optional(),
providerId: z.string().min(1).max(200).nullable().optional(),
model: z.string().min(1).max(200).nullable().optional(),
// 'clips': make every still, then stop as `awaiting-video` before any clip.
stopBefore: z.enum(['clips']).nullable().optional(),
}).strict();
// Resume may RAISE a limit; `acceptBasis` continues against a changed creative setup;
// `pool` replaces the allowed routes (e.g. swaps a refused video model), validated like Start.
export const musicVideoProductionResumeSchema = z.object({
limits: musicVideoProductionLimitsSchema.partial().optional(),
acceptBasis: z.boolean().optional(),
pool: z.array(musicVideoProductionRouteSchema).max(12).optional(),
// null goes on to the clips; omitted keeps a running stills-only stop (a finished one goes on).
stopBefore: z.enum(['clips']).nullable().optional(),
}).strict();
// ---- Fully-autonomous run: one prompt → lyrics → Suno song → video --------------
// Suno's Advanced-form options. `excludeStyles: ''` clears the field Suno keeps
// from its last draft; null (resume only) clears a stored option.
const musicVideoSunoOptionsSchema = z.object({
excludeStyles: z.string().trim().max(SUNO_LIMITS.excludeStyles).nullable().optional(),
vocalGender: z.enum(SUNO_VOCAL_GENDERS).nullable().optional(),
model: z.string().trim().regex(SUNO_MODEL_PATTERN, 'A Suno model version such as v6 or v6-wild').nullable().optional(),
maxMode: z.boolean().nullable().optional(),
}).strict();
// Local Music Studio options: model (with optional engine) or code (with chosen language).
export const musicVideoLocalMusicOptionsSchema = z.object({
type: z.enum(LOCAL_MUSIC_TYPES).optional(),
engine: z.string().trim().max(64).nullable().optional(),
language: z.enum(LOCAL_MUSIC_CODE_LANGUAGES).nullable().optional(),
}).strict();
// A provider/model/effort pin for a Music Video text stage. Effort is the union
// of every accepted level; the runner clamps it to the chosen provider's ladder.
export const musicVideoLlmSchema = z.object({
providerId: z.string().trim().min(1).max(200),
model: z.string().trim().min(1).max(200).nullable().optional(),
effort: z.enum(EFFORT_LEVELS).nullable().optional(),
}).strict();
// Per-stage pins (MUSIC_VIDEO_LLM_STAGES): an absent stage keeps its stored pin
// (or, on a start request, uses the direction pin); null clears that stage.
export const musicVideoLlmStagesSchema = z.object(Object.fromEntries(
MUSIC_VIDEO_LLM_STAGES.map((stage) => [stage, musicVideoLlmSchema.nullable().optional()]),
)).strict();
// Production review stages the run may approve by itself (de-duplicated, in
// review order). A non-empty list is approval authority, so the request must
// use an authenticated session (checked by the route); an
// empty list on resume clears the grant.
const musicVideoAutoApproveFields = {
autoApprove: z.array(z.enum(AUTONOMOUS_AUTO_APPROVE_STAGES)).max(AUTONOMOUS_AUTO_APPROVE_STAGES.length * 4)
.transform(normalizeAutoApprove).optional(),
password: z.string().min(1).max(1024).optional(),
};
// The alternate entry point: no track, style or board is picked up front. Tool
// ids are the same catalog the autopilot brief uses; `checkpoints` names the
// stages that park for approval (none = fully unattended).
export const musicVideoAutonomousStartSchema = z.object({
prompt: z.string().trim().min(1).max(AUTONOMOUS_PROMPT_MAX),
name: z.string().trim().min(1).max(AUTONOMOUS_NAME_MAX).optional(),
mediaMode: z.enum(MUSIC_VIDEO_MEDIA_MODES).optional(),
songSource: z.enum(AUTONOMOUS_SONG_SOURCES).optional(),
localFallback: z.boolean().optional(),
localMusic: musicVideoLocalMusicOptionsSchema.nullable().optional(),
instrumental: z.boolean().optional(),
guidance: z.string().max(4000).optional(),
tools: z.array(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS)).max(MUSIC_VIDEO_AUTOMATION_TOOL_IDS.length).optional(),
// Per-tool model pin, e.g. { 'image:local': 'flux-dev' }; absent = the install default.
models: z.partialRecord(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS), z.string().trim().min(1).max(200)).optional(),
budgetUsd: z.number().min(0).max(MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD).nullable().optional(),
limits: z.object({
maxGenerations: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.max).optional(),
maxReviewAttempts: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.max).optional(),
}).strict().optional(),
checkpoints: z.array(z.enum(AUTONOMOUS_CHECKPOINT_IDS)).max(AUTONOMOUS_CHECKPOINT_IDS.length).optional(),
// Reuse this existing mood board instead of generating one from the prompt.
moodBoardId: z.string().trim().min(1).max(64).nullable().optional(),
// Start on this project's song: its audio, analysis and lyric timing are copied,
// so the run writes no lyrics, makes no song and skips re-analysis.
fromProjectId: z.string().trim().min(1).max(80).optional(),
// A built-in character style (musicVideoCharacterStyles.js) cast as protagonist from the start.
characterStyleId: z.enum(MUSIC_VIDEO_CHARACTER_STYLE_IDS).nullable().optional(),
// The LLM that writes the brief and lyrics (blank = an eligible TUI provider, else the
// install's active provider — see services/musicVideo/llmRoute.js).
providerId: z.string().trim().min(1).max(200).nullable().optional(),
model: z.string().trim().min(1).max(200).nullable().optional(),
effort: z.enum(EFFORT_LEVELS).nullable().optional(),
// The separate code-authoring provider a code-rendered video needs.
authoring: musicVideoAuthoringSchema.optional(),
// A provider/model/effort per LLM stage; an unpinned stage uses the direction LLM above.
llmStages: musicVideoLlmStagesSchema.nullable().optional(),
// Review and revise the lyric draft with a second pass (the `lyricsReview` stage
// pin when set, else the direction LLM). Pinning `llmStages.lyricsReview` implies it.
lyricsReview: z.boolean().optional(),
// Orchestrated mode: this provider/model/effort clears every review point a
// director would (no checkpoints). Approval authority — the route requires a
// signed-in session for it.
orchestrator: musicVideoLlmSchema.optional(),
// Make and review every still, then wait for the director before any clip.
stopBeforeVideo: z.boolean().optional(),
origin: z.object({
kind: z.enum(AUTONOMOUS_ORIGINS).optional(),
ideaId: z.string().max(80).nullable().optional(),
ideaTitle: z.string().max(200).nullable().optional(),
}).strict().optional(),
suno: musicVideoSunoOptionsSchema.nullable().optional(),
...musicVideoAutoApproveFields,
}).strict();
// Resume a parked/failed run, or approve the checkpoint it is waiting on.
export const musicVideoAutonomousResumeSchema = z.object({
// Change course mid-run: the brief's prompt and guidance, which production plans shots from.
prompt: z.string().trim().min(1).max(AUTONOMOUS_PROMPT_MAX).optional(),
guidance: z.string().max(4000).optional(),
// Replace the stage output the director edited at a checkpoint.
lyrics: z.string().max(20000).optional(),
style: z.string().max(AUTONOMOUS_PROMPT_MAX).optional(),
// Patch the brief's Suno options, key by key (null clears one).
suno: musicVideoSunoOptionsSchema.optional(),
// Patch the brief's local Music Studio options.
localMusic: musicVideoLocalMusicOptionsSchema.nullable().optional(),
// At the song checkpoint: discard the song and generate a new one.
retakeSong: z.boolean().optional(),
// Swap a tool's model (null clears the pin) and raise or lower the run's limits. A changed
// model at the produce stage starts a new production run with the new pool.
models: z.partialRecord(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS), z.string().trim().min(1).max(200).nullable()).optional(),
limits: z.object({
maxGenerations: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxGenerations.max).optional(),
maxReviewAttempts: z.number().int().min(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.min).max(AUTONOMOUS_LIMIT_BOUNDS.maxReviewAttempts.max).optional(),
}).strict().optional(),
// Add tools to the brief (e.g. a video tool once the stills are approved); the production pool follows.
addTools: z.array(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS)).max(MUSIC_VIDEO_AUTOMATION_TOOL_IDS.length).optional(),
// Replace the brief's auto-approve grant ("auto-approve the rest").
...musicVideoAutoApproveFields,
}).strict();
// A generation kickoff that failed before reaching the queue (#9011) — names
// the rejected section whose claim should clear so the next resume can hand
// it out again immediately instead of waiting out GENERATION_CLAIM_LEASE_MS.
export const musicVideoRevisionReleaseSchema = z.object({
sceneId: z.string().min(1).max(200),
}).strict();
// Optional sound-design bed (#8988): one explicitly chosen music-library track
// mixed UNDER the song. null (or omitted) keeps the song as the sole audio
// master. See services/musicVideo/soundBed.js.
export const musicVideoSoundBedSchema = z.object({
trackId: z.string().min(1).max(64),
volume: z.number().min(0.05).max(1).optional(),
}).strict();
// Automation-first brief: which render tools the agent may use, the director's
// free-text guidance, and a spend cap (null = no cap). A patch merges per
// sub-field; `tools` replaces its list whole. See musicVideoAutomation.js.
export const musicVideoAutomationSchema = z.object({
tools: z.array(z.enum(MUSIC_VIDEO_AUTOMATION_TOOL_IDS)).max(MUSIC_VIDEO_AUTOMATION_TOOL_IDS.length).optional(),
guidance: z.string().max(MUSIC_VIDEO_AUTOMATION_GUIDANCE_MAX).optional(),
budgetUsd: z.number().min(0).max(MUSIC_VIDEO_AUTOMATION_BUDGET_MAX_USD).nullable().optional(),
// Check-in gates: `review` stops the autopilot for the director, `auto`
// approves and continues. Absent = review.
checkins: z.object({
castAndSets: z.enum(MUSIC_VIDEO_CHECKIN_MODES).optional(),
}).strict().optional(),
// The direction/planning LLM (#9545): absent keeps the stored pin, null clears
// it back to Auto (an eligible TUI provider, else the active provider).
llm: musicVideoLlmSchema.nullable().optional(),
// Per-stage LLM pins: merged per stage, a stage set to null clears it.
llmStages: musicVideoLlmStagesSchema.nullable().optional(),
}).strict();
// ---- Development artifacts ("ingredients") ----------------------------------
// Reviewable development files attached to a project (a Cast & Sets sheet, an
// animatic, a treatment, a storyboard). Bytes live on disk; see
// services/musicVideo/devArtifacts.js.
export const MUSIC_VIDEO_DEV_ARTIFACT_KINDS = ['cast-sets', 'animatic', 'treatment', 'storyboard', 'other'];
export const MUSIC_VIDEO_DEV_ARTIFACT_STATUSES = ['pending', 'approved', 'changes-requested'];
const devArtifactNoteText = z.string().trim().min(1).max(2000);
const devArtifactNoteTarget = z.string().trim().max(120).nullable().optional();
// The text fields of a multipart import (the file itself is the `file` part).
// `artifactId` adds a version to that artifact; otherwise kind + title create
// one. `notes` is a JSON array of strings or `{ text, target }` objects.
export const musicVideoDevArtifactImportSchema = z.object({
artifactId: z.string().min(1).max(64).optional(),
kind: z.enum(MUSIC_VIDEO_DEV_ARTIFACT_KINDS).optional(),
title: z.string().trim().min(1).max(200).optional(),
status: z.enum(MUSIC_VIDEO_DEV_ARTIFACT_STATUSES).optional(),
notes: z.preprocess((v) => {
if (typeof v !== 'string') return v;
try { return JSON.parse(v); } catch { return v; }
}, z.array(z.union([
devArtifactNoteText,
z.object({ text: devArtifactNoteText, target: devArtifactNoteTarget }).strict(),
])).max(50)).optional(),
}).strict().refine((b) => b.artifactId || b.kind, { message: 'kind is required for a new artifact', path: ['kind'] });
export const musicVideoDevArtifactNoteSchema = z.object({
text: devArtifactNoteText,
target: devArtifactNoteTarget,
}).strict();
export const musicVideoDevArtifactNoteUpdateSchema = z.object({
resolved: z.boolean(),
}).strict();
export const musicVideoDevArtifactReviewSchema = z.object({
status: z.enum(MUSIC_VIDEO_DEV_ARTIFACT_STATUSES),
note: z.string().trim().max(2000).optional(),
}).strict();
export const musicVideoDevArtifactFileQuerySchema = z.object({
version: z.coerce.number().int().min(1).max(1000).optional(),
}).strict();
// ---- Cast & Sets check-in -----------------------------------------------------
// Start / resume take an optional provider pin for the direction call.
export const musicVideoCastAndSetsStartSchema = z.object({
providerId: z.string().min(1).max(64).optional(),
model: z.string().min(1).max(200).optional(),
effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();
// Regenerate with notes. Omitted notes = the open notes on the sheet. A
// `target` names an image (`character`, `expressions`, `looks`, `cast:<id>`, `set:<id>`,
// `test:<n>`); any other note revises the direction.
export const musicVideoCastAndSetsRegenerateSchema = z.object({
notes: z.array(z.object({
text: devArtifactNoteText,
target: devArtifactNoteTarget,
}).strict()).min(1).max(50).optional(),
providerId: z.string().min(1).max(64).optional(),
model: z.string().min(1).max(200).optional(),
effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();
// Plain-text feedback on a Cast & Sets sheet. No target = the whole sheet
// (standing feedback the direction keeps honoring); a target names one image.
export const musicVideoCastAndSetsFeedbackSchema = z.object({
text: devArtifactNoteText,
target: devArtifactNoteTarget,
providerId: z.string().min(1).max(64).optional(),
model: z.string().min(1).max(200).optional(),
effort: z.enum(EFFORT_LEVELS).optional(),
}).strict();
// Direct edits to a procedural direction. A present text field replaces the
// current value (empty clears it); an absent one keeps it.
const castSetsText = (max) => z.string().max(max);
export const musicVideoCastAndSetsDirectionEditSchema = z.object({
protagonist: z.object({
construction: castSetsText(1000).optional(),
shapeLanguage: castSetsText(500).optional(),
materials: castSetsText(500).optional(),
palette: castSetsText(300).optional(),
movement: castSetsText(1000).optional(),
expressions: z.array(castSetsText(300)).max(8).optional(),
}).strict().optional(),
world: z.object({
layout: castSetsText(1000).optional(),
depth: castSetsText(500).optional(),
lighting: castSetsText(500).optional(),
camera: castSetsText(500).optional(),
transitions: castSetsText(500).optional(),
}).strict().optional(),
sets: z.array(z.object({
id: z.string().min(1).max(64),
imageRole: z.enum(['background', 'texture', 'decoration', 'cutout']),
}).strict()).max(8).optional(),
}).strict();
// The cutting room floor outro (lib/musicVideoStatsOutro.js): an optional scene
// after the song tallying the director's choices; null on the project = off.
export const musicVideoStatsOutroSchema = z.object({
enabled: z.boolean().optional(),
durationSec: z.number().min(STATS_OUTRO_LIMITS.durationMin).max(STATS_OUTRO_LIMITS.durationMax).optional(),
title: z.string().max(STATS_OUTRO_LIMITS.textMax).optional(),
subtitle: z.string().max(STATS_OUTRO_LIMITS.textMax).optional(),
hidden: z.array(z.enum(STATS_OUTRO_LINES.map((line) => line.key))).max(STATS_OUTRO_LINES.length).optional(),
}).strict();
// The opening title card (lib/musicVideoTitleCard.js): song title, artist, year
// in a corner over the opener. Every field is optional (the normalizer fills
// defaults); null on the project = none.
export const musicVideoTitleCardSchema = z.object({
enabled: z.boolean().optional(),
title: z.string().max(TITLE_CARD_LIMITS.textMax).optional(),
artist: z.string().max(TITLE_CARD_LIMITS.textMax).optional(),
year: z.string().max(TITLE_CARD_LIMITS.yearMax).optional(),
extra: z.string().max(TITLE_CARD_LIMITS.textMax).optional(),
quoteTitle: z.boolean().optional(),
startSec: z.number().min(0).max(TITLE_CARD_LIMITS.startMax).optional(),
endSec: z.number().min(0).max(TITLE_CARD_LIMITS.startMax + 60).optional(),
fadeSec: z.number().min(0).max(TITLE_CARD_LIMITS.fadeMax).optional(),
position: z.enum(TITLE_CARD_POSITIONS).optional(),
font: z.enum(TITLE_CARD_FONTS).optional(),
size: z.number().min(TITLE_CARD_LIMITS.sizeMin).max(TITLE_CARD_LIMITS.sizeMax).optional(),
color: z.string().regex(/^#[0-9a-f]{6}$/i, 'color is #rrggbb').optional(),
style: z.enum(TITLE_CARD_STYLES).optional(),
// '' = the look's own colour.
titleColor: z.union([z.literal(''), z.string().regex(/^#[0-9a-f]{6}$/i, 'titleColor is #rrggbb')]).optional(),
accentColor: z.union([z.literal(''), z.string().regex(/^#[0-9a-f]{6}$/i, 'accentColor is #rrggbb')]).optional(),
// The optional second showing at the end of the video (null = not timed yet).
outro: z.boolean().optional(),
outroStartSec: z.number().min(0).max(TITLE_CARD_LIMITS.outroMax).nullable().optional(),
outroEndSec: z.number().min(0).max(TITLE_CARD_LIMITS.outroMax + 60).nullable().optional(),
}).strict();
export const musicVideoProjectCreateSchema = z.object({
mediaMode: z.enum(MUSIC_VIDEO_MEDIA_MODES).optional(),
productionPolicy: musicVideoProductionPolicySchema.optional(),
name: z.string().min(1).max(200),
mode: z.enum(MUSIC_VIDEO_MODES).optional(),
// The source audio: either a music-library track or an uploaded file basename
// under data/music/. At least one is needed before analysis, but a project can
// be created empty and have the track set later via PATCH.
trackId: z.string().max(64).nullable().optional(),
uploadedAudioFilename: z.string().max(256).nullable().optional(),
performanceConditioningSource: z.enum(['master', 'vocal-stem', 'clean-singer-stem']).nullable().optional(),
concept: musicVideoConceptSchema.nullable().optional(),
visualSpec: musicVideoVisualSpecSchema.optional(),
styleReferences: musicVideoStyleReferencesSchema.optional(),
videoSettings: musicVideoVideoSettingsSchema.optional(),
automation: musicVideoAutomationSchema.nullable().optional(),
lyricCues: lyricCueList.optional(),
lyricMarkers: lyricMarkerList.optional(),
phrases: phraseList.optional(),
pacing: musicVideoPacingSchema.nullable().optional(),
composition: musicVideoCompositionSchema.nullable().optional(),
soundBed: musicVideoSoundBedSchema.nullable().optional(),
// The finishing film look (lib/filmLook.js); null = none.
filmLook: filmLookSchema.nullable().optional(),
// The opening title card (lib/musicVideoTitleCard.js); null = none.
titleCard: musicVideoTitleCardSchema.nullable().optional(),
// The cutting room floor outro after the song (lib/musicVideoStatsOutro.js); null = off.
statsOutro: musicVideoStatsOutroSchema.nullable().optional(),
}).strict();
export const musicVideoProjectUpdateSchema = z.object({
mediaMode: z.enum(MUSIC_VIDEO_MEDIA_MODES).optional(),
productionPolicy: musicVideoProductionPolicySchema.optional(),
name: z.string().min(1).max(200).optional(),
mode: z.enum(MUSIC_VIDEO_MODES).optional(),
status: z.enum(MUSIC_VIDEO_STATUSES).optional(),
trackId: z.string().max(64).nullable().optional(),
uploadedAudioFilename: z.string().max(256).nullable().optional(),
performanceConditioningSource: z.enum(['master', 'vocal-stem', 'clean-singer-stem']).nullable().optional(),
concept: musicVideoConceptSchema.nullable().optional(),
visualSpec: musicVideoVisualSpecSchema.optional(),
styleReferences: musicVideoStyleReferencesSchema.optional(),
videoSettings: musicVideoVideoSettingsSchema.optional(),
automation: musicVideoAutomationSchema.nullable().optional(),
renderHistoryId: z.string().max(64).nullable().optional(),
renderError: z.string().max(2000).nullable().optional(),
lyricCues: lyricCueList.optional(),
lyricMarkers: lyricMarkerList.optional(),
phrases: phraseList.optional(),
pacing: musicVideoPacingSchema.nullable().optional(),
composition: musicVideoCompositionSchema.nullable().optional(),
soundBed: musicVideoSoundBedSchema.nullable().optional(),
// The finishing film look (lib/filmLook.js); null = none.
filmLook: filmLookSchema.nullable().optional(),
// The opening title card (lib/musicVideoTitleCard.js); null = none.
titleCard: musicVideoTitleCardSchema.nullable().optional(),
// The cutting room floor outro after the song (lib/musicVideoStatsOutro.js); null = off.
statsOutro: musicVideoStatsOutroSchema.nullable().optional(),
// The Create › Storyboards board this video is planned from; null unlinks.
storyboardId: z.string().regex(STORYBOARD_ID_PATTERN, 'storyboardId must be a storyboard id').nullable().optional(),
}).strict();
// Mark a project finished outside PortOS (or clear the marker). The server
// stamps `markedAt`; the note says where it was made (musicVideoFinishedOutside.js).
export const musicVideoFinishedOutsideSchema = z.object({
finished: z.boolean(),
note: z.string().trim().max(500).optional(),
}).strict();
// Fork a project into its next editable version. The server derives lineage and
// version numbers from the source; callers may only override the display name
// and choose whether generated scene media should remain attached. A video
// variant always clears selected media and starts independent creative setup.
export const musicVideoProjectCloneSchema = z.object({
name: z.string().min(1).max(200).optional(),
includeGeneratedMedia: z.boolean().optional(),
variant: z.enum(['revision', 'video-generation']).optional(),
}).strict();
// Review content is editable; approval records are server-owned and never PATCHable.
export const musicVideoProductionDraftSchema = z.object({
storyboardSource: z.enum(['board', 'document']).optional(),
cast: z.string().max(12000), environments: z.string().max(12000),
visualLanguage: z.string().max(12000), motionLanguage: z.string().max(12000),
implementationPlan: z.string().max(16000).optional(),
guideArtifactId: z.string().max(64).nullable(),
sourceArtifactId: z.string().max(64).nullable().optional(),
lyricsMode: z.enum(['vocal', 'instrumental']), timingStatus: z.enum(['provisional', 'verified']),
timingNotes: z.string().max(4000),
storyboard: z.array(z.object({
id: z.string().max(64).optional(), startSec: timedSec, endSec: timedSec,
sceneId: z.string().max(64).nullable(), lyricCueIds: z.array(z.string().max(64)).max(2000),
action: z.string().max(4000), staging: z.string().max(4000),
camera: z.string().max(4000), transition: z.string().max(4000),
}).strict()).max(2000),
}).strict();
export const musicVideoAlignmentReviewSchema = z.object({
basis: z.string().min(1).max(128), notes: z.string().trim().max(4000).default(''),
}).strict();
export const musicVideoDocumentShotsSchema = z.object({
documentDirectory: z.string().min(1).max(500), audioBasis: z.string().min(1).max(128),
sourceFile: z.string().min(1).max(200),
shots: musicVideoProductionDraftSchema.shape.storyboard.min(1),
}).strict().superRefine((value, ctx) => {
const ids = new Set();
for (const shot of value.shots) {
if (!shot.id?.trim() || ids.has(shot.id) || shot.sceneId != null
|| !Number.isFinite(shot.startSec) || !(shot.endSec > shot.startSec)) {
ctx.addIssue({ code: 'custom', message: 'Document shots need unique source IDs, positive timing and no Board scene binding' });
}
ids.add(shot.id);
}
});
// Start a shot from the previous shot's on-screen out-frame; optionally keep
// the current start frame as its end frame.
export const musicVideoContinueShotSchema = z.object({ keepStillAsEnd: z.boolean().optional() }).strict();
export const musicVideoProductionImportSchema = z.object({ source: z.string().min(2).max(250000) }).strict();
export const musicVideoShotLockSchema = z.object({
sceneIds: z.array(z.string().min(1).max(200)).min(1).max(500),
locked: z.boolean(),
// A video shot locks its still first (ready to render), then its clip.
stage: z.enum(['still', 'video']).optional(),
}).strict();
export const musicVideoProductionApprovalSchema = z.object({
stage: z.enum(['art', 'storyboard', 'proof']), basis: z.string().min(1).max(128),
password: z.string().max(1024).optional(),
proofReview: z.object({
method: z.enum(['playback', 'machine']).optional(),
watchedWithAudio: z.boolean(),
machineEvidence: z.object({
visualReview: z.string().trim().min(40).max(8000),
audioReview: z.string().trim().min(40).max(8000),
limitations: z.string().trim().min(1).max(4000),
}).strict().optional(),
excerptId: z.string().min(1).max(200), filename: z.string().min(1).max(200),
energyComparison: z.string().trim().max(4000).optional(),
timecodedNotes: z.string().trim().max(4000).optional(),
}).strict().optional(),
}).strict();
export const musicVideoProductionProofSchema = z.object({
kind: z.enum(['proof', 'prototype']).optional(),
startSec: z.number().min(0), endSec: z.number().positive(),
}).strict();
// A scene on the director board. `startSec`/`endSec` place it on the timeline;
// `prompt` drives the shot's video; `framePrompt`/`referenceImageId` are the
// reference-frame inputs the i2v generation (Phase 1b) will consume.
// The linked storyboard panel a shot was fitted from (Fit to song), and a
// fingerprint of the panel as it was then, so a later panel edit shows on the shot.
const scenePanelFields = {
panelId: z.string().regex(/^panel-[A-Za-z0-9-]{1,80}$/, 'Invalid panel id').nullable().optional(),
panelRev: z.string().regex(/^[0-9a-z]{1,16}$/, 'Invalid panel revision').nullable().optional(),
panelArt: z.string().regex(/^[^/\\]+\.(png|jpe?g|webp)$/i, 'Panel art must be a gallery image').nullable().optional(),
};
export const musicVideoSceneCreateSchema = z.object({
label: z.string().max(120).optional(),
sectionLabel: z.string().max(120).nullable().optional(),
prompt: z.string().max(8000).optional(),
framePrompt: z.string().max(8000).nullable().optional(),
startSec: z.number().min(0).max(36000).nullable().optional(),
endSec: z.number().min(0).max(36000).nullable().optional(),
beatAligned: z.boolean().optional(),
// #8964: shot-planning fields. `loop` is an explicit, deliberate choice to
// repeat the source clip across a longer authored span; a scene with no
// `loop` key is a pre-#8964 record and keeps the legacy loop-to-fill render.
loop: z.boolean().optional(),
sectionIndex: z.number().int().min(0).max(10000).nullable().optional(),
lyricText: z.string().max(2000).nullable().optional(),
visualIntent: z.string().max(2000).nullable().optional(),
...sceneLayerFields,
// #8977: `performance` = a lip-synced singer that must follow the master
// recording (only a verified source-audio provider can render it); absent or
// `cutaway` = the ordinary image-to-video shot. See lib/musicVideoShotTiming.js.
shotMode: z.enum(MUSIC_VIDEO_SHOT_MODES).optional(),
performanceSpeaker: z.string().trim().max(120).nullable().optional(),
// How a performance follows the song: lip-sync (absent/null) or music-driven motion.
performanceStyle: z.enum(MUSIC_VIDEO_PERFORMANCE_STYLES).nullable().optional(),
...scenePanelFields,
}).strict().refine(
(s) => s.startSec == null || s.endSec == null || s.endSec >= s.startSec,
{ message: 'endSec must be >= startSec', path: ['endSec'] },
);
// The last render failure persisted on a scene by the scene image/video hooks
// (#10154): which lane failed, why (one bounded line), and when.
export const musicVideoSceneLastFailureSchema = z.object({
lane: z.enum(['image', 'video']),
error: z.string().max(300),
at: z.string().max(64),
}).strict();
// Times are nullable here so clearing a Start/End input (the UI sends `null`)
// is accepted. The endSec >= startSec invariant can't be checked on the partial
// patch alone (the paired value may live on the existing record), so the merged
// range is validated in projectsLogic.applySceneUpdate instead.
export const musicVideoSceneUpdateSchema = z.object({
label: z.string().max(120).optional(),
sectionLabel: z.string().max(120).nullable().optional(),
prompt: z.string().max(8000).optional(),
framePrompt: z.string().max(8000).nullable().optional(),
startSec: z.number().min(0).max(36000).nullable().optional(),
endSec: z.number().min(0).max(36000).nullable().optional(),
beatAligned: z.boolean().optional(),
// #8964: shot-planning fields. `loop` is an explicit, deliberate choice to
// repeat the source clip across a longer authored span; a scene with no
// `loop` key is a pre-#8964 record and keeps the legacy loop-to-fill render.
loop: z.boolean().optional(),
sectionIndex: z.number().int().min(0).max(10000).nullable().optional(),
lyricText: z.string().max(2000).nullable().optional(),
visualIntent: z.string().max(2000).nullable().optional(),
...sceneLayerFields,
// #8977: `performance` = a lip-synced singer that must follow the master
// recording (only a verified source-audio provider can render it); absent or
// `cutaway` = the ordinary image-to-video shot. See lib/musicVideoShotTiming.js.
shotMode: z.enum(MUSIC_VIDEO_SHOT_MODES).optional(),
performanceSpeaker: z.string().trim().max(120).nullable().optional(),
// How a performance follows the song: lip-sync (absent/null) or music-driven motion.
performanceStyle: z.enum(MUSIC_VIDEO_PERFORMANCE_STYLES).nullable().optional(),
referenceImageId: z.string().max(256).nullable().optional(),
videoHistoryId: z.string().max(64).nullable().optional(),
// #11173: an optional style-break end frame (the selected `endImage` take)
// and the prompt that renders it from the start frame.
endImageId: z.string().max(256).nullable().optional(),
endFramePrompt: z.string().max(8000).nullable().optional(),
// #10154: the last generation failure the render hooks persisted. The board
// may send `null` to dismiss it; a full object is accepted so a client that
// round-trips the scene doesn't 400.
lastFailure: musicVideoSceneLastFailureSchema.nullable().optional(),
...scenePanelFields,
}).strict();
// Reorder the board: the full set of scene ids in their new order.
export const musicVideoSceneReorderSchema = z.object({
sceneIds: z.array(z.string().min(1).max(64)).min(1).max(500),
}).strict();
// Split an over-long shot on lyric/phrase boundaries (#8977). `backend` is
// the lane the director will render with; omitted/null = the project's pin.
export const musicVideoSceneSplitSchema = z.object({
backend: z.enum(['local', 'grok', 'fal', 'runway']).nullable().optional(),
// Split the shot in two at this song time instead of by the backend's longest take.
atSec: z.number().finite().nonnegative().optional(),
}).strict();
// Move where a shot starts; the shot before it ends there too, so the cut moves and nothing gaps or overlaps.
export const musicVideoSceneStartSchema = z.object({
startSec: z.number().finite().nonnegative(),
}).strict();
// Autonomous shot planner (#1855): propose a scene per analyzed audio section.
// `seedPrompts` (default true) additionally asks the active/given AI provider
// for a first-pass framePrompt/prompt per scene — best-effort, never fails the
// plan itself (see services/musicVideo/planner.js). `providerId`/`model` mirror
// the optional override shape used elsewhere (mediaPromptRefiner, universe
// builder) so a caller can pin a specific provider instead of the active one.
export const musicVideoPlanRequestSchema = z.object({
seedPrompts: z.boolean().optional(),
providerId: z.string().max(64).optional(),
model: z.string().max(200).optional(),
effort: z.enum(EFFORT_LEVELS).optional(),
// Required once the board has scenes (409 PLAN_MODE_REQUIRED otherwise).
mode: z.enum(['replace', 'append']).optional(),
}).strict();
// Manual-tempo fallback (see services/musicVideo/audioAnalysis.js for why bpm
// can come back null from auto-detection). `bpm` range is loosened from the
// detector's own search window for manual entry (20-300 covers everything
// from a ballad to hardcore/gabber); `offsetSec` is the first downbeat, by ear.
export const musicVideoManualAnalysisSchema = z.object({
bpm: z.number().min(20).max(300),
offsetSec: z.number().min(0).max(600).default(0),
}).strict();
// MuScriptor audio → MIDI transcription request (services/audioMidiTranscription.js).
// `model` picks the MuScriptor size tier; the service clamps unknown values to
// its default, this only types the field.
export const musicVideoTranscribeMidiRequestSchema = z.object({
model: z.enum(MUSCRIPTOR_MODELS).optional(),
}).strict();
// The persisted MIDI-transcription pointer (a .mid basename under data/music/,
// produced by the MuScriptor sidecar from the project's source audio; it lives
// with the master audio so the peer-sync asset manifest federates it). Cleared
// alongside audioAnalysis when the audio source changes — it was transcribed
// from the OLD track.
export const musicVideoMidiTranscriptionSchema = z.object({
filename: z.string().min(1).max(256),
model: z.string().max(32).optional(),
createdAt: z.string().max(64).optional(),
}).strict();
// The cached beat/tempo/section map (audioAnalysis.js output). Validated when a
// record round-trips so a hand-edited/legacy project can't carry a malformed
// analysis; the analyzer itself produces this shape.
// Per-band loudness envelopes (0..1 on a fixed fps grid) and onset times for
// the seekable song feature track (#9073). `null`/absent means "not analyzed"
// (an analysis cached before the feature track existed); an empty array is
// never used as that sentinel.
const envelopeSeriesSchema = z.array(z.number().min(0).max(1)).max(200000);
const onsetTimesSchema = z.array(z.number().min(0)).max(100000);
export const musicVideoSongFeaturesSchema = z.object({
envelopes: z.object({
fps: z.number().positive(),
rms: envelopeSeriesSchema,
low: envelopeSeriesSchema,
mid: envelopeSeriesSchema,
high: envelopeSeriesSchema,
}).strict(),
onsets: z.object({
low: onsetTimesSchema,
mid: onsetTimesSchema,
high: onsetTimesSchema,
}).strict(),
// Set when the decode was capped, so the tracks stop before the song does.
truncatedAtSec: z.number().min(0).nullable().optional(),
}).strict();
export const musicVideoAudioAnalysisSchema = z.object({
// Shape version: absent = 1 (pre feature track), 2 = carries `features`.
version: z.number().int().min(1).optional(),
features: musicVideoSongFeaturesSchema.nullable().optional(),
bpm: z.number().nullable(),
beats: z.array(z.number()),
downbeats: z.array(z.number()),
// Compact normalized loudness envelope for the director timeline. Optional
// so cached analyses from older installs remain readable.
waveform: z.array(z.number().min(0).max(1)).max(1024).optional(),
sections: z.array(z.object({
label: z.string(),
startSec: z.number(),
endSec: z.number(),
// Normalized 0..1 section loudness used by the energy-weighted auto-arranger
// (#1915). Additive + optional so older cached analyses still validate.
energy: z.number().min(0).optional(),
// Set when the label came from the aligned lyric sheet ("Chorus") rather
// than the detector ("Section 3"); `analysisLabel` keeps the detector's
// label so a later pass can restore it. Additive, so older analyses validate.
labelSource: z.enum(['analysis', 'lyrics']).optional(),
analysisLabel: z.string().max(120).optional(),
})),
durationSec: z.number(),
// Explain whether the beat grid came from the full track, consensus among
// later rhythmic windows, or the director's manual tap/entry fallback.
tempoSource: z.enum(['full', 'windowed', 'manual']).nullable().optional(),
tempoConfidence: z.number().min(0).max(1).nullable().optional(),
tempoWindow: z.object({
startSec: z.number().min(0),
endSec: z.number().min(0),
}).nullable().optional(),
}).strict();
export const musicVideoPerformanceRepairSchema = z.object({
excerptId: z.string().min(1).max(200),
sourceAssetId: z.string().min(1).max(200),
boundarySec: z.number().finite().min(0).max(36000),
}).strict();
// Preserved intervals have equal duration: insertions/deletions are gaps, never stretch.
export const musicVideoAudioTimingPreviewSchema = z.object({
targetTrackId: z.string().min(1).max(128),
intervals: z.array(z.object({
oldStartSec: z.number().finite().min(0).max(36000),
oldEndSec: z.number().finite().min(0).max(36000),
newStartSec: z.number().finite().min(0).max(36000),
}).strict()).min(1).max(200),
}).strict();
export const musicVideoAudioTimingApplySchema = musicVideoAudioTimingPreviewSchema.extend({
basis: z.string().regex(/^[a-f0-9]{32}$/),
});
export const musicVideoProductionFeedbackSchema = z.object({
stage: z.enum(['art', 'storyboard', 'proof']), basis: z.string().min(1).max(128),
target: z.string().trim().min(1).max(300), text: z.string().trim().min(1).max(8000),
decision: z.enum(['comment', 'structure-accepted', 'request-changes']),
}).strict();
// Act on the shots a song revision flagged (songRevision.js resolveSongRevisionScenes).
export const musicVideoSongSceneActionSchema = musicVideoCastAndSetsStartSchema.extend({
revisionId: z.string().min(1).max(128),
action: z.enum(['replan', 'remove', 'dismiss']),
sceneIds: z.array(z.string().min(1).max(64)).min(1).max(2000).optional(),
}).strict();
export const musicVideoProductionReviseSchema = musicVideoCastAndSetsStartSchema.extend({
stage: z.enum(['art', 'storyboard', 'proof']),
}).strict();
// The input label a stale approval names (`concept`, `scene 3 prompt`, …) — the server finds its stored value.
export const musicVideoProductionRevertSchema = z.object({
stage: z.enum(['art', 'storyboard', 'proof', 'castAndSets']), field: z.string().trim().min(1).max(100),
}).strict();
// Anchor these storyboard shots (every flagged shot when absent) to the lyric lines sung over them.
export const musicVideoLyricAnchorSyncSchema = z.object({
sceneIds: z.array(z.string().min(1).max(64)).min(1).max(2000).optional(),
}).strict();
export const musicVideoProductionFeedbackResolutionSchema = z.object({
feedbackId: z.string().min(1).max(128), resolution: z.string().trim().max(8000).default(''), password: z.string().max(1024).optional(),
}).strict();
// GET /api/music-video query (#10169). Passthrough strings, like the other list
// queries: `parsePagination` clamps `limit`/`offset`, and a malformed `cursor`
// (an offset the summary page issued) falls back to the first page.
export const musicVideoProjectListQuerySchema = z.object({
summary: z.enum(['1', 'true', '0', 'false']).optional(),
limit: z.string().optional(),
offset: z.string().optional(),
cursor: z.string().max(64).optional(),
});