@vibeframe/cli 0.113.10 → 0.113.11

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

@@ -96,6 +96,13 @@ export interface CreateBuildPlanOptions {
     skipVideo?: boolean;
     skipKeyframe?: boolean;
     skipMusic?: boolean;
+    /**
+     * Skip Whisper word-level transcription of narration. Recorded for plan
+     * fidelity; transcription is a negligible-cost step (~$0.002/beat) that only
+     * runs when a beat has narration and an OpenAI key is configured, so it is
+     * not itemised as a separate cost line.
+     */
+    skipTranscript?: boolean;
     ttsProvider?: string;
     voice?: string;
     imageProvider?: string;

package/dist/commands/_shared/compose-prompts.d.ts

@@ -57,6 +57,13 @@ export interface ComposePromptsBeat {
      * agentic and batch paths produce equivalent HTML.
      */
     userPrompt: string;
+    /**
+     * Project-relative path to the beat's Whisper word-level transcript
+     * (`assets/transcript-<id>.json`), present only when the asset stage
+     * transcribed this beat's narration. The host agent can read it for exact
+     * word timings; the same timings are already summarised in `userPrompt`.
+     */
+    transcriptPath?: string;
     /** True when `compositions/scene-<id>.html` already exists on disk. */
     exists: boolean;
 }

package/dist/commands/_shared/compose-scenes-skills.d.ts

@@ -27,6 +27,7 @@
 import { type LintFinding } from "./scene-lint.js";
 import { type Beat } from "./storyboard-parse.js";
 import { type ComposerProvider } from "./composer-resolve.js";
+import type { SceneTranscriptWord } from "./scene-html-emit.js";
 /** Effort level → token caps. Model is per-provider (see MODEL_SETTINGS_BY_PROVIDER). */
 export type ComposeEffort = "low" | "medium" | "high";
 export interface ComposeBeatContext {
@@ -71,6 +72,14 @@ export interface ComposeBeatContext {
      * duration is then only the minimum and is annotated as superseded.
      */
     finalDurationSec?: number;
+    /**
+     * Whisper word-level timings for this beat's narration audio, read from
+     * `assets/transcript-<id>.json` by the asset stage. When present,
+     * {@link buildUserPrompt} surfaces a compact timing table so the composer
+     * can sync caption / kinetic-type word reveals to speech. Folded into the
+     * user prompt, so the compose cache key invalidates when timings change.
+     */
+    transcript?: SceneTranscriptWord[];
 }
 export interface ComposeBeatResult {
     /** Generated HTML (from cache or fresh API call). */
@@ -94,8 +103,28 @@ export interface ComposeBeatResult {
 }
 /** Build the system prompt — skill bundle + DESIGN.md hard-gate. */
 export declare function buildSystemPrompt(ctx: Pick<ComposeBeatContext, "skillBundle" | "designMd">): string;
+/**
+ * Word-level timing entries above this count are downgraded to coarse,
+ * phrase-level anchors in the prompt. A token-budget guard: a 60s narration
+ * can exceed 150 words, and inlining every `[start, "word"]` pair bloats the
+ * prompt (and the cache key) for little composer benefit past a point.
+ */
+export declare const TRANSCRIPT_PROMPT_MAX_WORDS = 120;
+/**
+ * Render narration word timings as a compact, deterministic prompt section.
+ * Token-budget guard (the `oversized` case is the reason this is a function,
+ * not an inline template):
+ *   - no transcript → `""` (section omitted entirely; prompt unchanged).
+ *   - ≤ {@link TRANSCRIPT_PROMPT_MAX_WORDS} → full word-level `[start, "word"]`
+ *     table the composer can map 1:1 to GSAP reveals.
+ *   - more → group into ~`MAX/2` phrase anchors (start time of each phrase),
+ *     tagged "approximate" so the composer paces reveals across the beat
+ *     rather than over-trusting per-word truth.
+ * Pure and stable for a given input → the compose cache stays consistent.
+ */
+export declare function formatTranscriptSection(transcript: SceneTranscriptWord[] | undefined, maxWords?: number): string;
 /** Build the user prompt — instructions + storyboard global + beat body. */
-export declare function buildUserPrompt(ctx: Pick<ComposeBeatContext, "beat" | "storyboardGlobal" | "retryFeedback" | "finalDurationSec">): string;
+export declare function buildUserPrompt(ctx: Pick<ComposeBeatContext, "beat" | "storyboardGlobal" | "retryFeedback" | "finalDurationSec" | "transcript">): string;
 /**
  * Compute the sha256 cache key for a (provider, model, system, user) tuple.
  * Provider id is folded in so switching `--composer` doesn't serve cached

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

@@ -64,6 +64,19 @@ export type SceneBuildProgressEvent = {
     type: "narration-skipped";
     beatId: string;
     reason: string;
+} | {
+    type: "transcript-generated";
+    beatId: string;
+    path: string;
+    wordCount: number;
+} | {
+    type: "transcript-cached";
+    beatId: string;
+    path: string;
+} | {
+    type: "transcript-skipped";
+    beatId: string;
+    reason: string;
 } | {
     type: "backdrop-cached";
     beatId: string;
@@ -254,6 +267,13 @@ export interface SceneBuildOptions {
     skipKeyframe?: boolean;
     /** Skip music generation even when beats declare music cues. */
     skipMusic?: boolean;
+    /**
+     * Skip Whisper word-level transcription of generated narration. Default is
+     * to transcribe whenever narration exists and an OpenAI key is configured,
+     * writing `assets/transcript-<beat>.json` so the composer can sync caption /
+     * kinetic-type reveals to speech. Pass true to opt out (no transcribe cost).
+     */
+    skipTranscript?: boolean;
     /** OpenAI image quality — see `vibe generate image --quality`. */
     imageQuality?: "standard" | "hd";
     /** OpenAI image size. Default 1536x1024 for cinematic 16:9-ish framing. */

package/dist/commands/_shared/transcribe-narration.d.ts

@@ -0,0 +1,23 @@
+import type { SceneTranscriptWord } from "./scene-html-emit.js";
+export interface TranscribeNarrationOptions {
+    /** OpenAI API key for Whisper. */
+    apiKey: string;
+    /** Optional BCP-47 language hint passed to Whisper (auto-detect when unset). */
+    language?: string;
+}
+/**
+ * Transcribe a narration audio file to word-level timings. Returns an empty
+ * array on ANY failure (no words, API error, bad audio) so callers can treat
+ * the absence of timings as "no word-sync available" rather than abort.
+ */
+export declare function transcribeNarrationWords(audioAbsPath: string, opts: TranscribeNarrationOptions): Promise<SceneTranscriptWord[]>;
+/** Canonical per-beat transcript path, relative to the project root. */
+export declare function beatTranscriptRelPath(beatId: string): string;
+/**
+ * Read a previously generated `assets/transcript-<beatId>.json` from disk.
+ * Returns `undefined` when the file is missing or malformed — compose then
+ * proceeds without word timings (identical to a project that never
+ * transcribed). Validates each entry's shape so a hand-edited or partial file
+ * can't inject `NaN`/`undefined` timings into the prompt.
+ */
+export declare function readBeatTranscript(projectDir: string, beatId: string): Promise<SceneTranscriptWord[] | undefined>;

package/dist/commands/_shared/transcribe-narration.test.d.ts

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