@vibeframe/cli 0.115.1 → 0.115.2

package/dist/commands/_shared/build-cache-model.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/build-cache.d.ts

@@ -19,6 +19,8 @@ export declare function backdropCacheDescriptor(opts: {
     quality: "standard" | "hd";
     size: string;
     ratio?: string;
+    /** Provider-specific image model override — switching models re-keys the asset. */
+    model?: string;
 }): CacheAssetDescriptor;
 export declare function characterCacheDescriptor(opts: {
     name: string;
@@ -26,6 +28,8 @@ export declare function characterCacheDescriptor(opts: {
     provider: string;
     quality: "standard" | "hd";
     size: string;
+    /** Provider-specific image model override — switching models re-keys the asset. */
+    model?: string;
 }): CacheAssetDescriptor;
 export declare function keyframeCacheDescriptor(opts: {
     beatId: string;
@@ -36,6 +40,8 @@ export declare function keyframeCacheDescriptor(opts: {
     ratio?: string;
     /** Character sheet paths used as edit references — changing them re-keys the keyframe. */
     characters?: string[];
+    /** Provider-specific image model override — switching models re-keys the asset. */
+    model?: string;
 }): CacheAssetDescriptor;
 export declare function imageRatioForSize(size: string | undefined): string;
 export declare function videoCacheDescriptor(opts: {

package/dist/commands/_shared/build-plan.d.ts

@@ -109,6 +109,8 @@ export interface CreateBuildPlanOptions {
     imageProvider?: string;
     imageQuality?: "standard" | "hd";
     imageSize?: string;
+    /** Provider-specific image model override — must match executeSceneBuild for cache parity. */
+    imageModel?: string;
     videoProvider?: string;
     musicProvider?: string;
     composer?: string;

package/dist/commands/_shared/footage-assemble.d.ts

@@ -0,0 +1,166 @@
+import type { ReviewAction } from "./review-report.js";
+export interface FootageClipInput {
+    id: string;
+    clipDurationSec: number;
+    narrationDurationSec?: number;
+}
+export interface FootagePlanOptions {
+    /** Crossfade length between segments (seconds). */
+    transitionSec?: number;
+    /** Fade-from/to-black length at the head and tail of the cut (seconds). */
+    fadeSec?: number;
+    /** Gap between a segment becoming dominant and its narration starting. */
+    narrationLeadSec?: number;
+    /** Silence required after narration ends before the segment may end. */
+    narrationTailSec?: number;
+}
+export interface FootageBeatPlan {
+    id: string;
+    clipDurationSec: number;
+    narrationDurationSec?: number;
+    /** Segment length on the timeline (clip, possibly tpad-extended). */
+    segmentDurationSec: number;
+    /** Seconds of last-frame clone added so narration + tail fit. 0 = untouched. */
+    extendedSec: number;
+    /** Timeline position where this segment (and its incoming crossfade) starts. */
+    startSec: number;
+    /** Timeline position where this segment's narration starts (when present). */
+    narrationStartSec?: number;
+}
+export interface FootageTimelinePlan {
+    beats: FootageBeatPlan[];
+    transitionSec: number;
+    fadeSec: number;
+    totalDurationSec: number;
+    warnings: string[];
+}
+export declare const FOOTAGE_DEFAULTS: {
+    readonly transitionSec: 0.5;
+    readonly fadeSec: 0.6;
+    readonly narrationLeadSec: 0.35;
+    readonly narrationTailSec: 0.4;
+    readonly width: 1920;
+    readonly height: 1080;
+    readonly fps: 30;
+    readonly crf: 18;
+    readonly finishCrf: 23;
+    readonly musicVolume: 0.35;
+    readonly duck: {
+        readonly thresholdDb: -30;
+        readonly ratio: 3;
+        readonly attackMs: 20;
+        readonly releaseMs: 200;
+    };
+    /**
+     * The cinematic finish pass: subtle vignette + temporal film grain, applied
+     * before the head/tail fades. These are the field-tested values that pull
+     * provider clips away from the too-clean "AI look"; the fades multiply over
+     * them so blacks stay black.
+     */
+    readonly finish: readonly ["vignette=angle=PI/5", "noise=alls=7:allf=t"];
+    /** Base segment length for a ken-burns keyframe fallback (no clip to probe). */
+    readonly kenburnsSec: 4;
+    /** Slow-push ceiling for the ken-burns zoom. */
+    readonly kenburnsMaxZoom: 1.1;
+};
+/**
+ * Compute segment lengths and timeline offsets from real clip/narration
+ * durations. Deterministic and side-effect free so agents can reason about the
+ * cut from the report alone.
+ *
+ * Timeline model: segment i starts at `start_i = start_{i-1} + seg_{i-1} - T`
+ * (each crossfade overlaps T seconds), so the xfade filter offset for join i
+ * is exactly `start_i`. When clips are too short to host the requested
+ * transition, T is clamped (with a warning) instead of failing the run.
+ */
+export declare function planFootageTimeline(inputs: FootageClipInput[], opts?: FootagePlanOptions): FootageTimelinePlan;
+/** One visual source per beat: a generated clip, or a keyframe still to ken-burns. */
+export interface FootageSource {
+    /** Absolute path to the clip (video) or keyframe still (image). */
+    path: string;
+    kind: "video" | "image";
+}
+export interface FootageAssembleArgsOptions {
+    /** Visual sources in beat order (parallel to `plan.beats`). */
+    sources: FootageSource[];
+    plan: FootageTimelinePlan;
+    /** Absolute narration paths keyed by beat index (sparse — not every beat narrates). */
+    narrationPaths: ReadonlyMap<number, string>;
+    /** Absolute music-bed path; looped and ducked under narration when present. */
+    musicPath?: string;
+    outputPath: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    crf?: number;
+    musicVolume?: number;
+    /** Apply the cinematic finish pass (vignette + film grain) before the fades. */
+    finish?: boolean;
+}
+/**
+ * Build the single-pass FFmpeg invocation: normalize every clip to one
+ * geometry/fps, xfade-chain them at the planned offsets, fade the head and
+ * tail, and mix narration (adelay per beat) over an optional looped,
+ * sidechain-ducked music bed.
+ */
+export declare function buildFootageAssembleArgs(opts: FootageAssembleArgsOptions): string[];
+export interface FootageAssembleOptions {
+    projectDir: string;
+    /** Output path (relative paths resolve against projectDir). Default: renders/footage.mp4. */
+    output?: string;
+    transitionSec?: number;
+    fadeSec?: number;
+    /**
+     * Music bed: an explicit path, `"none"` to disable, or undefined to
+     * auto-detect `assets/music.mp3|wav` then `assets/music-<firstBeat>.mp3|wav`.
+     */
+    music?: string;
+    musicVolume?: number;
+    /** Apply the cinematic finish pass (vignette + film grain). */
+    finish?: boolean;
+    dryRun?: boolean;
+}
+export interface FootageAssembleReport {
+    schemaVersion: "1";
+    kind: "footage-assemble";
+    project: string;
+    output: string;
+    totalDurationSec: number;
+    transitionSec: number;
+    fadeSec: number;
+    beats: Array<FootageBeatPlan & {
+        /** The visual source file (generated clip, or keyframe still on fallback). */
+        clip: string;
+        /** How the segment was produced. */
+        source: "clip" | "keyframe-kenburns";
+        narration?: string;
+    }>;
+    music: {
+        path: string;
+        source: "flag" | "auto";
+        volume: number;
+        ducked: boolean;
+    } | null;
+    /** The finish filters applied before the fades, or null when skipped. */
+    finish: {
+        filters: string[];
+    } | null;
+    warnings: string[];
+    nextActions: ReviewAction[];
+}
+export interface FootageAssembleResult {
+    success: boolean;
+    dryRun: boolean;
+    outputPath: string;
+    reportPath?: string;
+    report?: FootageAssembleReport;
+    error?: string;
+    suggestion?: string;
+}
+/**
+ * Assemble a scene project's generated clips into the footage cut. Probes real
+ * durations, plans the timeline, runs one FFmpeg pass, and writes
+ * `assemble-report.json` so the driving agent can read the cut's anatomy
+ * (offsets, extensions, clamps) without watching the video.
+ */
+export declare function executeFootageAssemble(opts: FootageAssembleOptions): Promise<FootageAssembleResult>;

package/dist/commands/_shared/footage-assemble.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/scene-build.d.ts

@@ -19,6 +19,7 @@
  *     already have one with sub-composition references.
  */
 import { type ImageOptions } from "@vibeframe/ai-providers";
+import { type FootageAssembleReport } from "./footage-assemble.js";
 import type { ComposerProvider } from "./composer-resolve.js";
 import { type ComposePromptsBeat } from "./compose-prompts.js";
 import { type SceneRenderResult } from "./scene-render.js";
@@ -128,6 +129,12 @@ export type SceneBuildProgressEvent = {
     type: "video-failed";
     beatId: string;
     error: string;
+} | {
+    type: "video-fallback";
+    beatId: string;
+    from: string;
+    to: string;
+    reason: string;
 } | {
     type: "video-skipped";
     beatId: string;
@@ -244,7 +251,7 @@ export interface SceneBuildOptions {
      * based on env keys (claude > gemini > openai). Pass an explicit value
      * to require that provider's key.
      */
-    composer?: ComposerProvider | "template";
+    composer?: ComposerProvider | "template" | "footage";
     skipNarration?: boolean;
     skipBackdrop?: boolean;
     skipRender?: boolean;
@@ -271,6 +278,12 @@ export interface SceneBuildOptions {
      * kinetic-type reveals to speech. Pass true to opt out (no transcribe cost).
      */
     skipTranscript?: boolean;
+    /**
+     * Provider-specific image model for backdrops/keyframes/character sheets
+     * (e.g. gemini `flash` | `pro`, openai `gpt-image-2`). Provider default when
+     * omitted; grok has a single model and ignores it.
+     */
+    imageModel?: string;
     /** OpenAI image quality — see `vibe generate image --quality`. */
     imageQuality?: "standard" | "hd";
     /** OpenAI image size. Default 1536x1024 for cinematic 16:9-ish framing. */
@@ -341,6 +354,12 @@ export interface SceneBuildResult {
     /** MP4 path when `skipRender` is false and render succeeded. */
     outputPath?: string;
     renderResult?: SceneRenderResult;
+    /**
+     * The footage composer's cut anatomy (offsets, extensions, clamps) — also
+     * persisted as `assemble-report.json`. Present only when
+     * `composer === "footage"` reached the render phase.
+     */
+    footageReport?: FootageAssembleReport;
     /**
      * Populated only in agent mode when {@link phase} === `"needs-author"`.
      * The host agent should consume this to write each beat's HTML, then
@@ -372,6 +391,12 @@ export interface SceneBuildResult {
     totalLatencyMs: number;
 }
 export declare function executeSceneBuild(opts: SceneBuildOptions): Promise<SceneBuildResult>;
+/**
+ * ByteDance's platform-wide moderation rejects i2v inputs showing a
+ * recognizable face with a deterministic 422 ("likenesses of real people") —
+ * it applies to AI-generated photoreal faces too, and retrying never helps.
+ */
+export declare function isLikenessRejection(error: string | undefined): boolean;
 export type BuildReport = ReturnType<typeof toBuildReport>;
 declare function toBuildReport(projectDir: string, result: SceneBuildResult): {
     schemaVersion: string;

package/dist/commands/_shared/storyboard-parse.d.ts

@@ -104,7 +104,7 @@ export declare function resolveCharacters(frontmatter: ProjectFrontmatter | unde
  * rather than restating it - four surfaces had drifted to four different
  * sub-lists before this became the one list.
  */
-export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset", "characters", "eyebrow", "title", "caption", "kicker", "sub"];
+export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "keyframe", "provider", "motion", "voice", "music", "asset", "characters", "eyebrow", "title", "caption", "kicker", "sub"];
 export type StoryboardCueKey = (typeof STORYBOARD_CUE_KEYS)[number];
 /**
  * Per-beat cues extracted from the first ```yaml fenced block inside a beat
@@ -138,6 +138,12 @@ export interface BeatCues {
      * and shapes the HTML that agent writes.
      */
     motion?: string;
+    /**
+     * Video-provider override for this beat (seedance|runway|kling|veo|grok).
+     * Use to pin a face-visible keyframe to a provider that accepts it (e.g.
+     * `provider: runway` — Seedance's likeness filter rejects face i2v inputs).
+     */
+    provider?: string;
     /** Voice override for this beat (overrides project frontmatter `voice`). */
     voice?: string;
     /** Music prompt or a project-relative path to an existing track. */