@juspay/neurolink 9.22.2 → 9.23.0

package/dist/adapters/video/vertexVideoHandler.js

@@ -12,38 +12,17 @@
 import { readFile } from "node:fs/promises";
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 import { TIMEOUTS } from "../../constants/timeouts.js";
+import { VIDEO_ERROR_CODES } from "../../constants/videoErrors.js";
 import { isAbortError, NeuroLinkError, withTimeout, } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
 // ============================================================================
-// VIDEO ERROR CODES
+// VIDEO ERROR CODES (Re-exported for backward compatibility)
 // ============================================================================
 /**
- * Video generation runtime error codes
- *
- * These are for runtime/execution errors during video generation.
- * Pure option/shape validation (missing image option, invalid config values, etc.)
- * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
- *
- * Error categorization:
- * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
- * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
- *
- * Following TTS pattern (TTS_ERROR_CODES + TTSError in ttsProcessor.ts)
+ * Video error codes - re-exported from constants module for backward compatibility.
+ * @see {@link VIDEO_ERROR_CODES} in constants/videoErrors.ts for definitions
  */
-export const VIDEO_ERROR_CODES = {
-    /** Video generation API call failed */
-    GENERATION_FAILED: "VIDEO_GENERATION_FAILED",
-    /** Provider (Vertex AI) not properly configured */
-    PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED",
-    /** Polling for video completion timed out */
-    POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT",
-    /**
-     * Runtime I/O error during input processing.
-     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
-     * NOT for: missing options or invalid config shapes (use parameterValidation).
-     */
-    INVALID_INPUT: "VIDEO_INVALID_INPUT",
-};
+export { VIDEO_ERROR_CODES };
 /**
  * Video generation error class
  * Extends NeuroLinkError for consistent error handling across the SDK
@@ -71,6 +50,8 @@ const VIDEO_GENERATION_TIMEOUT_MS = 180000;
 const POLL_INTERVAL_MS = 5000;
 /** Full model name for Veo 3.1 (IMPORTANT: not just "veo-3.1") */
 const VEO_MODEL = "veo-3.1-generate-001";
+/** Full model name for Veo 3.1 Fast (used for transitions) */
+const VEO_FAST_MODEL = "veo-3.1-fast-generate-001";
 /** Default location for Vertex AI */
 const DEFAULT_LOCATION = "us-central1";
 // ============================================================================
@@ -592,35 +573,185 @@ async function makePollRequest(pollEndpoint, operationName, accessToken, timeout
  * @throws {VideoError} On API error, timeout, or missing video data
  */
 async function pollVideoOperation(operationName, accessToken, project, location, timeoutMs) {
+    return pollOperation(VEO_MODEL, operationName, accessToken, project, location, timeoutMs);
+}
+// ============================================================================
+// TRANSITION GENERATION (Director Mode)
+// ============================================================================
+/**
+ * Generate a transition clip using Veo 3.1 Fast's first-and-last-frame interpolation.
+ *
+ * This calls the Veo API with both `image` (first frame) and `lastFrame` (last frame),
+ * producing a video that smoothly interpolates between the two frames.
+ *
+ * @param firstFrame - JPEG buffer of the first frame (last frame of clip N)
+ * @param lastFrame - JPEG buffer of the last frame (first frame of clip N+1)
+ * @param prompt - Transition prompt describing desired visual flow
+ * @param options - Video output options (resolution, aspect ratio, audio)
+ * @param durationSeconds - Duration of the transition clip (4, 6, or 8)
+ * @param region - Vertex AI region override
+ * @returns Video buffer of the transition clip
+ *
+ * @throws {VideoError} When API returns an error or polling times out
+ */
+export async function generateTransitionWithVertex(firstFrame, lastFrame, prompt, options = {}, durationSeconds = 4, region) {
+    if (!isVertexVideoConfigured()) {
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
+            message: "Vertex AI credentials not configured for transition generation.",
+            category: ErrorCategory.CONFIGURATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+        });
+    }
+    const config = await getVertexConfig();
+    const project = config.project;
+    const location = region || config.location;
     const startTime = Date.now();
-    // Use fetchPredictOperation endpoint - this is MODEL-SPECIFIC
-    const pollEndpoint = `https://${location}-aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/publishers/google/models/${VEO_MODEL}:fetchPredictOperation`;
+    const aspectRatio = options.aspectRatio || "16:9";
+    const resolution = options.resolution || "720p";
+    const generateAudio = options.audio ?? true;
+    logger.debug("Starting transition clip generation", {
+        model: VEO_FAST_MODEL,
+        durationSeconds,
+        firstFrameSize: firstFrame.length,
+        lastFrameSize: lastFrame.length,
+        promptLength: prompt.length,
+    });
+    try {
+        const firstFrameBase64 = firstFrame.toString("base64");
+        const lastFrameBase64 = lastFrame.toString("base64");
+        const firstMime = detectMimeType(firstFrame);
+        const lastMime = detectMimeType(lastFrame);
+        const accessToken = await getAccessToken();
+        // Use Veo 3.1 Fast for transitions (faster with minimal quality difference)
+        const endpoint = `https://${location}-aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/publishers/google/models/${VEO_FAST_MODEL}:predictLongRunning`;
+        const requestBody = {
+            instances: [
+                {
+                    prompt: prompt,
+                    image: {
+                        bytesBase64Encoded: firstFrameBase64,
+                        mimeType: firstMime,
+                    },
+                    lastFrame: {
+                        bytesBase64Encoded: lastFrameBase64,
+                        mimeType: lastMime,
+                    },
+                },
+            ],
+            parameters: {
+                sampleCount: 1,
+                durationSeconds: durationSeconds,
+                aspectRatio: aspectRatio,
+                resolution: resolution,
+                generateAudio: generateAudio,
+            },
+        };
+        const controller = new AbortController();
+        const requestTimeout = setTimeout(() => controller.abort(), 30000);
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    "Content-Type": "application/json; charset=utf-8",
+                },
+                body: JSON.stringify(requestBody),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            clearTimeout(requestTimeout);
+            if (isAbortError(error)) {
+                throw new VideoError({
+                    code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+                    message: "Transition generation request timed out after 30 seconds",
+                    category: ErrorCategory.EXECUTION,
+                    severity: ErrorSeverity.MEDIUM,
+                    retriable: true,
+                });
+            }
+            throw error;
+        }
+        clearTimeout(requestTimeout);
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+                message: `Transition API error: ${response.status} - ${errorText}`,
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: response.status >= 500,
+                context: { status: response.status, error: errorText },
+            });
+        }
+        const operation = await response.json();
+        const operationName = operation.name;
+        if (!operationName) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+                message: "Transition API did not return an operation name",
+                category: ErrorCategory.EXECUTION,
+                severity: ErrorSeverity.MEDIUM,
+                retriable: false,
+            });
+        }
+        // Poll with Veo Fast model endpoint
+        const remainingTime = VIDEO_GENERATION_TIMEOUT_MS - (Date.now() - startTime);
+        const videoBuffer = await pollTransitionOperation(operationName, accessToken, project, location, Math.max(1000, remainingTime));
+        logger.debug("Transition clip generated", {
+            processingTime: Date.now() - startTime,
+            videoSize: videoBuffer.length,
+        });
+        return videoBuffer;
+    }
+    catch (error) {
+        if (error instanceof VideoError) {
+            throw error;
+        }
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_TRANSITION_FAILED,
+            message: `Transition generation failed: ${error instanceof Error ? error.message : String(error)}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: true,
+            originalError: error instanceof Error ? error : undefined,
+        });
+    }
+}
+/**
+ * Common polling helper that handles both video and transition operations.
+ * Accepts a model name to construct the appropriate endpoint.
+ */
+async function pollOperation(modelOrEndpoint, operationName, accessToken, project, location, timeoutMs) {
+    const startTime = Date.now();
+    const pollEndpoint = `https://${location}-aiplatform.googleapis.com/v1/projects/${project}/locations/${location}/publishers/google/models/${modelOrEndpoint}:fetchPredictOperation`;
     while (Date.now() - startTime < timeoutMs) {
         const result = await makePollRequest(pollEndpoint, operationName, accessToken);
         if (result.done) {
             return extractVideoFromResult(result, operationName);
         }
-        const elapsed = Date.now() - startTime;
-        logger.debug("Polling video operation...", {
+        logger.debug("Polling operation...", {
             operationName,
-            elapsed,
-            remainingMs: timeoutMs - elapsed,
+            elapsed: Date.now() - startTime,
         });
-        // Wait before next poll
         await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
     }
-    // Timeout reached
     throw new VideoError({
         code: VIDEO_ERROR_CODES.POLL_TIMEOUT,
-        message: `Video generation timed out after ${Math.round(timeoutMs / 1000)}s while polling for completion`,
+        message: `Operation timed out after ${Math.round(timeoutMs / 1000)}s`,
         category: ErrorCategory.TIMEOUT,
-        severity: ErrorSeverity.HIGH,
+        severity: ErrorSeverity.MEDIUM,
         retriable: true,
-        context: {
-            operationName,
-            timeoutMs,
-            provider: "vertex",
-            suggestion: "Try again - video generation can take 1-3 minutes. Consider using a shorter duration or lower resolution.",
-        },
+        context: { operationName, timeoutMs },
     });
 }
+/**
+ * Poll Vertex AI operation for transition clip completion.
+ * Uses the Veo Fast model fetchPredictOperation endpoint.
+ */
+async function pollTransitionOperation(operationName, accessToken, project, location, timeoutMs) {
+    return pollOperation(VEO_FAST_MODEL, operationName, accessToken, project, location, timeoutMs);
+}

package/dist/adapters/video/videoMerger.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Video Merger for Director Mode
+ *
+ * Concatenates multiple MP4 video buffers into a single MP4 using FFmpeg's
+ * concat demuxer for lossless concatenation when codecs match.
+ *
+ * Uses the shared FFmpeg adapter for binary resolution, temp file management,
+ * and process execution — following the adapter pattern in `adapters/tts/`.
+ *
+ * @module adapters/video/videoMerger
+ */
+/**
+ * Merge multiple MP4 video buffers into a single MP4.
+ *
+ * Uses FFmpeg concat demuxer for lossless concatenation. If codecs don't match
+ * (unlikely since all clips come from Veo), falls back to re-encoding with H.264.
+ *
+ * @param videoBuffers - Array of MP4 video buffers to concatenate in order
+ * @returns Merged MP4 video buffer
+ * @throws {VideoError} If merge fails or no valid buffers provided
+ */
+export declare function mergeVideoBuffers(videoBuffers: Buffer[]): Promise<Buffer>;

package/dist/adapters/video/videoMerger.js

@@ -0,0 +1,171 @@
+/**
+ * Video Merger for Director Mode
+ *
+ * Concatenates multiple MP4 video buffers into a single MP4 using FFmpeg's
+ * concat demuxer for lossless concatenation when codecs match.
+ *
+ * Uses the shared FFmpeg adapter for binary resolution, temp file management,
+ * and process execution — following the adapter pattern in `adapters/tts/`.
+ *
+ * @module adapters/video/videoMerger
+ */
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { logger } from "../../utils/logger.js";
+import { cleanupTempFiles, createTrackedTempDir, FFMPEG_MERGE_MAX_BUFFER, FFMPEG_MERGE_TIMEOUT_MS, isValidMp4Buffer, join, readFile, runFfmpeg, writeFile, } from "./ffmpegAdapter.js";
+import { VIDEO_ERROR_CODES } from "../../constants/videoErrors.js";
+import { VideoError } from "./vertexVideoHandler.js";
+// ============================================================================
+// INTERNAL HELPERS
+// ============================================================================
+/**
+ * Write clip buffers to temp files and build the FFmpeg concat list.
+ *
+ * @returns Paths of all written clip files
+ */
+async function writeClipsAndBuildConcatList(videoBuffers, tempDir, concatListPath) {
+    const inputPaths = [];
+    const concatLines = [];
+    for (let i = 0; i < videoBuffers.length; i++) {
+        const inputPath = join(tempDir, `clip_${i}.mp4`);
+        await writeFile(inputPath, videoBuffers[i]);
+        inputPaths.push(inputPath);
+        // Normalize backslashes to forward slashes for FFmpeg, then escape single quotes
+        const safePath = inputPath.replace(/\\/g, "/").replace(/'/g, "'\\''");
+        concatLines.push(`file '${safePath}'`);
+    }
+    await writeFile(concatListPath, concatLines.join("\n"));
+    return inputPaths;
+}
+/**
+ * Attempt lossless concat, falling back to H.264 re-encode on failure.
+ */
+async function concatWithFallback(concatListPath, outputPath) {
+    const ffmpegOpts = {
+        timeoutMs: FFMPEG_MERGE_TIMEOUT_MS,
+        maxBuffer: FFMPEG_MERGE_MAX_BUFFER,
+    };
+    try {
+        // Try lossless concat first (fastest — no re-encoding)
+        await runFfmpeg([
+            "-y",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            concatListPath,
+            "-c",
+            "copy",
+            outputPath,
+        ], ffmpegOpts);
+    }
+    catch (concatError) {
+        // Fallback: re-encode with H.264 if codecs mismatch
+        logger.warn("Lossless concat failed, falling back to H.264 re-encoding", {
+            error: concatError instanceof Error
+                ? concatError.message
+                : String(concatError),
+        });
+        await runFfmpeg([
+            "-y",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            concatListPath,
+            "-c:v",
+            "libx264",
+            "-preset",
+            "fast",
+            "-crf",
+            "18",
+            "-c:a",
+            "aac",
+            "-b:a",
+            "192k",
+            "-movflags",
+            "+faststart",
+            outputPath,
+        ], ffmpegOpts);
+    }
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+/**
+ * Merge multiple MP4 video buffers into a single MP4.
+ *
+ * Uses FFmpeg concat demuxer for lossless concatenation. If codecs don't match
+ * (unlikely since all clips come from Veo), falls back to re-encoding with H.264.
+ *
+ * @param videoBuffers - Array of MP4 video buffers to concatenate in order
+ * @returns Merged MP4 video buffer
+ * @throws {VideoError} If merge fails or no valid buffers provided
+ */
+export async function mergeVideoBuffers(videoBuffers) {
+    if (videoBuffers.length === 0) {
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_MERGE_FAILED,
+            message: "No video buffers provided to merge",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+        });
+    }
+    // Validate each input buffer
+    for (let i = 0; i < videoBuffers.length; i++) {
+        if (!isValidMp4Buffer(videoBuffers[i])) {
+            throw new VideoError({
+                code: VIDEO_ERROR_CODES.DIRECTOR_MERGE_FAILED,
+                message: `Clip ${i} is not a valid MP4 buffer (missing ftyp header or too small)`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    clipIndex: i,
+                    bufferSize: videoBuffers[i].length,
+                    headerHex: videoBuffers[i].subarray(0, 12).toString("hex"),
+                },
+            });
+        }
+    }
+    if (videoBuffers.length === 1) {
+        return videoBuffers[0];
+    }
+    const startTime = Date.now();
+    const tempDir = await createTrackedTempDir("merge");
+    const concatListPath = join(tempDir, "concat.txt");
+    const outputPath = join(tempDir, "merged.mp4");
+    let inputPaths = [];
+    try {
+        inputPaths = await writeClipsAndBuildConcatList(videoBuffers, tempDir, concatListPath);
+        await concatWithFallback(concatListPath, outputPath);
+        const mergedBuffer = await readFile(outputPath);
+        logger.info("Video merge complete", {
+            inputClips: videoBuffers.length,
+            totalInputSize: videoBuffers.reduce((sum, b) => sum + b.length, 0),
+            outputSize: mergedBuffer.length,
+            elapsedMs: Date.now() - startTime,
+        });
+        return mergedBuffer;
+    }
+    catch (error) {
+        // Re-throw VideoErrors as-is
+        if (error instanceof VideoError) {
+            throw error;
+        }
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_MERGE_FAILED,
+            message: `Video merge failed: ${error instanceof Error ? error.message : String(error)}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { clipCount: videoBuffers.length },
+            originalError: error instanceof Error ? error : undefined,
+        });
+    }
+    finally {
+        await cleanupTempFiles(tempDir, concatListPath, outputPath, ...inputPaths);
+    }
+}

package/dist/constants/index.d.ts

@@ -191,4 +191,5 @@ export declare const CONSTANTS_METADATA: {
     readonly COMPATIBILITY: "backward_compatible";
 };
 export { AIProviderName, OpenRouterModels, BedrockModels, OpenAIModels, AzureOpenAIModels, VertexModels, GoogleAIModels, AnthropicModels, MistralModels, OllamaModels, LiteLLMModels, HuggingFaceModels, SageMakerModels, APIVersions, ErrorCategory, ErrorSeverity, AnthropicBetaFeature, TOKEN_EXPIRY_BUFFER_MS, } from "./enums.js";
+export { VIDEO_ERROR_CODES } from "./videoErrors.js";
 export type { ClaudeSubscriptionTier, AnthropicAuthMethod, } from "../types/subscriptionTypes.js";

package/dist/constants/index.js

@@ -203,3 +203,5 @@ ErrorCategory, ErrorSeverity,
 AnthropicBetaFeature, 
 // OAuth Constants
 TOKEN_EXPIRY_BUFFER_MS, } from "./enums.js";
+// ===== ERROR CODES =====
+export { VIDEO_ERROR_CODES } from "./videoErrors.js";

package/dist/constants/videoErrors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Video Generation Error Codes
+ *
+ * Centralized error codes for video generation operations.
+ * These are for runtime/execution errors during video generation.
+ *
+ * Pure option/shape validation (missing image option, invalid config values, etc.)
+ * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ *
+ * Error categorization:
+ * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
+ * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
+ *
+ * @module constants/videoErrors
+ */
+export declare const VIDEO_ERROR_CODES: {
+    /** Video generation API call failed */
+    readonly GENERATION_FAILED: "VIDEO_GENERATION_FAILED";
+    /** Provider (Vertex AI) not properly configured */
+    readonly PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED";
+    /** Polling for video completion timed out */
+    readonly POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT";
+    /**
+     * Runtime I/O error during input processing.
+     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
+     * NOT for: missing options or invalid config shapes (use parameterValidation).
+     */
+    readonly INVALID_INPUT: "VIDEO_INVALID_INPUT";
+    /** Invalid segment structure (missing prompt or image) */
+    readonly DIRECTOR_SEGMENT_MISMATCH: "DIRECTOR_SEGMENT_MISMATCH";
+    /** Too many segments requested */
+    readonly DIRECTOR_SEGMENT_LIMIT_EXCEEDED: "DIRECTOR_SEGMENT_LIMIT_EXCEEDED";
+    /** Invalid transition duration (must be 4, 6, or 8) */
+    readonly DIRECTOR_INVALID_TRANSITION_DURATION: "DIRECTOR_INVALID_TRANSITION_DURATION";
+    /** A main clip generation call failed (fatal) */
+    readonly DIRECTOR_CLIP_FAILED: "DIRECTOR_CLIP_FAILED";
+    /** Frame extraction from clip failed */
+    readonly DIRECTOR_FRAME_EXTRACTION_FAILED: "DIRECTOR_FRAME_EXTRACTION_FAILED";
+    /** Transition clip generation failed (non-fatal, falls back to hard cut) */
+    readonly DIRECTOR_TRANSITION_FAILED: "DIRECTOR_TRANSITION_FAILED";
+    /** Video merge/concatenation failed */
+    readonly DIRECTOR_MERGE_FAILED: "DIRECTOR_MERGE_FAILED";
+    /** Pipeline timeout (overall) */
+    readonly DIRECTOR_PIPELINE_TIMEOUT: "DIRECTOR_PIPELINE_TIMEOUT";
+};

package/dist/constants/videoErrors.js

@@ -0,0 +1,46 @@
+/**
+ * Video Generation Error Codes
+ *
+ * Centralized error codes for video generation operations.
+ * These are for runtime/execution errors during video generation.
+ *
+ * Pure option/shape validation (missing image option, invalid config values, etc.)
+ * is handled by parameterValidation.ts using ERROR_CODES from errorHandling.ts.
+ *
+ * Error categorization:
+ * - INVALID_INPUT → ErrorCategory.execution (runtime I/O failures)
+ * - parameterValidation errors → ErrorCategory.validation (schema/option issues)
+ *
+ * @module constants/videoErrors
+ */
+export const VIDEO_ERROR_CODES = {
+    /** Video generation API call failed */
+    GENERATION_FAILED: "VIDEO_GENERATION_FAILED",
+    /** Provider (Vertex AI) not properly configured */
+    PROVIDER_NOT_CONFIGURED: "VIDEO_PROVIDER_NOT_CONFIGURED",
+    /** Polling for video completion timed out */
+    POLL_TIMEOUT: "VIDEO_POLL_TIMEOUT",
+    /**
+     * Runtime I/O error during input processing.
+     * Used for: failed URL fetch, failed file read, corrupt/unreadable buffer.
+     * NOT for: missing options or invalid config shapes (use parameterValidation).
+     */
+    INVALID_INPUT: "VIDEO_INVALID_INPUT",
+    // Director Mode error codes
+    /** Invalid segment structure (missing prompt or image) */
+    DIRECTOR_SEGMENT_MISMATCH: "DIRECTOR_SEGMENT_MISMATCH",
+    /** Too many segments requested */
+    DIRECTOR_SEGMENT_LIMIT_EXCEEDED: "DIRECTOR_SEGMENT_LIMIT_EXCEEDED",
+    /** Invalid transition duration (must be 4, 6, or 8) */
+    DIRECTOR_INVALID_TRANSITION_DURATION: "DIRECTOR_INVALID_TRANSITION_DURATION",
+    /** A main clip generation call failed (fatal) */
+    DIRECTOR_CLIP_FAILED: "DIRECTOR_CLIP_FAILED",
+    /** Frame extraction from clip failed */
+    DIRECTOR_FRAME_EXTRACTION_FAILED: "DIRECTOR_FRAME_EXTRACTION_FAILED",
+    /** Transition clip generation failed (non-fatal, falls back to hard cut) */
+    DIRECTOR_TRANSITION_FAILED: "DIRECTOR_TRANSITION_FAILED",
+    /** Video merge/concatenation failed */
+    DIRECTOR_MERGE_FAILED: "DIRECTOR_MERGE_FAILED",
+    /** Pipeline timeout (overall) */
+    DIRECTOR_PIPELINE_TIMEOUT: "DIRECTOR_PIPELINE_TIMEOUT",
+};

package/dist/core/baseProvider.js

@@ -1055,7 +1055,7 @@ export class BaseProvider {
     async handleVideoGeneration(options, startTime) {
         // Dynamic imports to avoid loading video dependencies unless needed
         const { generateVideoWithVertex, VideoError, VIDEO_ERROR_CODES } = await import("../adapters/video/vertexVideoHandler.js");
-        const { validateVideoGenerationInput, validateImageForVideo } = await import("../utils/parameterValidation.js");
+        const { validateVideoGenerationInput, validateImageForVideo, validateDirectorModeInput, } = await import("../utils/parameterValidation.js");
         const { ErrorFactory } = await import("../utils/errorHandling.js");
         // Build GenerateOptions for validation
         const generateOptions = {
@@ -1064,6 +1064,47 @@ export class BaseProvider {
             provider: options.provider,
             model: options.model,
         };
+        // ===== DIRECTOR MODE =====
+        // Route to Director pipeline when segments are provided
+        if (generateOptions.input?.segments &&
+            Array.isArray(generateOptions.input.segments) &&
+            generateOptions.input.segments.length > 0) {
+            // Type narrowing: segments is guaranteed to exist here
+            const segments = generateOptions.input.segments;
+            const directorValidation = validateDirectorModeInput(generateOptions);
+            if (!directorValidation.isValid) {
+                throw ErrorFactory.invalidParameters("director-mode", new Error(directorValidation.errors
+                    .map((e) => e.message)
+                    .join("; ")), { errors: directorValidation.errors });
+            }
+            if (directorValidation.warnings.length > 0) {
+                for (const warning of directorValidation.warnings) {
+                    logger.warn(`Director Mode warning: ${warning}`);
+                }
+            }
+            const { executeDirectorPipeline, DIRECTOR_PIPELINE_TIMEOUT_MS } = await import("../adapters/video/directorPipeline.js");
+            // Use caller's timeout if provided, otherwise use default Director timeout
+            const directorTimeout = options.timeout ?? DIRECTOR_PIPELINE_TIMEOUT_MS;
+            const videoResult = await this.executeWithTimeout(() => executeDirectorPipeline(segments, generateOptions.output?.video ?? {}, generateOptions.output?.director ?? {}, options.region), { timeout: directorTimeout, operationType: "generate" });
+            // Build content summary with metadata
+            const joinedPrompts = generateOptions.input.segments
+                .map((s) => s.prompt)
+                .join(" → ");
+            const segmentCount = videoResult.metadata?.segmentCount ??
+                generateOptions.input.segments.length;
+            const transitionCount = videoResult.metadata?.transitionCount ?? Math.max(0, segmentCount - 1);
+            const totalDuration = videoResult.metadata?.duration ?? 0;
+            const contentSummary = `${joinedPrompts} — duration: ${totalDuration}s, segments: ${segmentCount}, transitions: ${transitionCount}`;
+            const baseResult = {
+                content: contentSummary,
+                provider: "vertex",
+                model: options.model || "veo-3.1-generate-001",
+                usage: { input: 0, output: 0, total: 0 },
+                video: videoResult,
+            };
+            return await this.enhanceResult(baseResult, options, startTime);
+        }
+        // ===== STANDARD SINGLE-CLIP VIDEO GENERATION =====
         // Validate video generation input
         const validation = validateVideoGenerationInput(generateOptions);
         if (!validation.isValid) {

package/dist/lib/adapters/video/directorPipeline.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Director Mode Pipeline Orchestrator
+ *
+ * Orchestrates multi-segment video generation: parallel clip generation,
+ * parallel frame extraction + transition generation, and sequential merge.
+ *
+ * Error severity semantics:
+ * - HIGH: Fatal — clip generation / merge failures that abort the pipeline
+ * - MEDIUM: Non-fatal — transition / frame-extraction failures that degrade
+ *   to a hard cut but do not abort the pipeline
+ *
+ * @module adapters/video/directorPipeline
+ */
+import type { DirectorModeOptions, DirectorSegment, VideoGenerationResult, VideoOutputOptions } from "../../types/multimodal.js";
+/** Default timeout for entire Director Mode pipeline (10 minutes) */
+export declare const DIRECTOR_PIPELINE_TIMEOUT_MS = 600000;
+/**
+ * Execute the full Director Mode pipeline.
+ *
+ * Pipeline stages:
+ * 1. Parallel clip generation (concurrency = 2, circuit breaker after 2 failures)
+ * 2. Parallel frame extraction + transition generation
+ * 3. Sequential merge into single MP4
+ *
+ * @param segments - Array of DirectorSegment objects (2-10)
+ * @param videoOptions - Video output options (resolution, length, aspectRatio, audio)
+ * @param directorOptions - Director Mode options (transition prompts/durations)
+ * @param region - Vertex AI region override
+ * @returns VideoGenerationResult with merged video and Director metadata
+ */
+export declare function executeDirectorPipeline(segments: DirectorSegment[], videoOptions?: VideoOutputOptions, directorOptions?: DirectorModeOptions, region?: string): Promise<VideoGenerationResult>;