@juspay/neurolink 9.22.2 → 9.23.0

package/dist/adapters/video/ffmpegAdapter.js

@@ -0,0 +1,206 @@
+/**
+ * Shared FFmpeg Adapter for Video Operations
+ *
+ * Centralizes FFmpeg binary resolution, process execution, and temporary file
+ * management for all video adapter modules (frameExtractor, videoMerger).
+ *
+ * Follows the adapter pattern used in `src/lib/adapters/tts/` and
+ * `src/lib/adapters/providerImageAdapter.ts`.
+ *
+ * @module adapters/video/ffmpegAdapter
+ */
+import { randomUUID } from "node:crypto";
+import { readdirSync, rmdirSync, unlinkSync } from "node:fs";
+import { mkdir, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { logger } from "../../utils/logger.js";
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/** Timeout for frame-extraction FFmpeg operations (30 seconds) */
+export const FFMPEG_FRAME_TIMEOUT_MS = 30_000;
+/** Timeout for merge/concat FFmpeg operations (2 minutes) */
+export const FFMPEG_MERGE_TIMEOUT_MS = 120_000;
+/** Max stdout/stderr buffer for frame extraction (10 MB) */
+export const FFMPEG_FRAME_MAX_BUFFER = 10 * 1024 * 1024;
+/** Max stdout/stderr buffer for merge operations (50 MB) */
+export const FFMPEG_MERGE_MAX_BUFFER = 50 * 1024 * 1024;
+/** FFmpeg JPEG quality scale (2 = high quality, range 2-31) */
+export const JPEG_QUALITY = "2";
+/** Seconds before end-of-video to seek when extracting last frame */
+export const LAST_FRAME_SEEK_OFFSET = "0.5";
+/** Minimum valid MP4 buffer size in bytes (ftyp header = 8 bytes minimum) */
+export const MIN_VIDEO_BUFFER_SIZE = 12;
+/** MP4 ftyp box magic bytes at offset 4: "ftyp" */
+const FTYP_MAGIC = Buffer.from([0x66, 0x74, 0x79, 0x70]);
+// ============================================================================
+// TEMP DIRECTORY MANAGEMENT
+// ============================================================================
+/** Track active temp directories for process cleanup */
+const activeTempDirs = new Set();
+let cleanupRegistered = false;
+/**
+ * Register process-level cleanup handlers once.
+ * Removes all tracked temp directories on abnormal exit.
+ */
+function ensureCleanupRegistered() {
+    if (cleanupRegistered) {
+        return;
+    }
+    cleanupRegistered = true;
+    const cleanup = () => {
+        for (const dir of activeTempDirs) {
+            try {
+                // Sync removal for exit handlers — best-effort only
+                const entries = readdirSync(dir);
+                for (const entry of entries) {
+                    try {
+                        unlinkSync(join(dir, entry));
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+                rmdirSync(dir);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        activeTempDirs.clear();
+    };
+    process.on("exit", cleanup);
+}
+/**
+ * Create a tracked temporary directory for FFmpeg operations.
+ *
+ * @param prefix - Directory name prefix (e.g. "frame", "merge")
+ * @returns Absolute path to the created directory
+ */
+export async function createTrackedTempDir(prefix) {
+    ensureCleanupRegistered();
+    const dir = join(tmpdir(), `neurolink-${prefix}-${randomUUID()}`);
+    await mkdir(dir, { recursive: true });
+    activeTempDirs.add(dir);
+    return dir;
+}
+/**
+ * Clean up temporary files and their parent directory.
+ * Logs failures at debug level instead of swallowing silently.
+ *
+ * @param tempDir - The temporary directory to remove
+ * @param files - File paths within tempDir to delete
+ */
+export async function cleanupTempFiles(tempDir, ...files) {
+    for (const filePath of files) {
+        try {
+            await unlink(filePath);
+        }
+        catch (err) {
+            logger.debug("Failed to clean up temp file", {
+                path: filePath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    try {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+    catch (err) {
+        logger.debug("Failed to remove temp directory", {
+            path: tempDir,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    activeTempDirs.delete(tempDir);
+}
+// ============================================================================
+// FFMPEG BINARY RESOLUTION
+// ============================================================================
+/** Cached FFmpeg binary path to avoid repeated resolution */
+let cachedFfmpegPath = null;
+/**
+ * Resolve the FFmpeg binary path.
+ *
+ * Resolution order:
+ * 1. `FFMPEG_PATH` environment variable
+ * 2. `ffmpeg-static` npm package (optional peer dependency)
+ * 3. System `ffmpeg` on PATH
+ *
+ * @returns Absolute or relative path to the FFmpeg binary
+ */
+export async function getFfmpegPath() {
+    if (cachedFfmpegPath) {
+        return cachedFfmpegPath;
+    }
+    if (process.env.FFMPEG_PATH) {
+        cachedFfmpegPath = process.env.FFMPEG_PATH;
+        return cachedFfmpegPath;
+    }
+    try {
+        const ffmpegStatic = await import("ffmpeg-static");
+        const staticPath = ffmpegStatic.default ?? ffmpegStatic;
+        if (typeof staticPath === "string" && staticPath.length > 0) {
+            cachedFfmpegPath = staticPath;
+            return cachedFfmpegPath;
+        }
+    }
+    catch {
+        // ffmpeg-static not installed — fall through to system binary
+        logger.debug("ffmpeg-static not available, using system ffmpeg binary");
+    }
+    cachedFfmpegPath = "ffmpeg";
+    logger.warn("Using system ffmpeg binary. If video operations fail with ENOENT, install ffmpeg-static or set FFMPEG_PATH.");
+    return cachedFfmpegPath;
+}
+// ============================================================================
+// FFMPEG PROCESS EXECUTION
+// ============================================================================
+/**
+ * Run an FFmpeg command via `child_process.execFile`.
+ *
+ * @param args - FFmpeg CLI arguments (without the binary path)
+ * @param options - Timeout and buffer size overrides
+ * @returns stdout and stderr from the process
+ * @throws Error if the process exits with a non-zero code or times out
+ */
+export async function runFfmpeg(args, options = {}) {
+    const { execFile } = await import("node:child_process");
+    const ffmpegPath = await getFfmpegPath();
+    const timeoutMs = options.timeoutMs ?? FFMPEG_FRAME_TIMEOUT_MS;
+    const maxBuffer = options.maxBuffer ?? FFMPEG_FRAME_MAX_BUFFER;
+    return new Promise((resolve, reject) => {
+        const proc = execFile(ffmpegPath, args, { timeout: timeoutMs, maxBuffer }, (error, stdout, stderr) => {
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve({ stdout: stdout || "", stderr: stderr || "" });
+            }
+        });
+        proc.on("error", reject);
+    });
+}
+// ============================================================================
+// BUFFER VALIDATION
+// ============================================================================
+/**
+ * Validate that a buffer looks like a valid MP4 video.
+ *
+ * Checks minimum size and the presence of an `ftyp` box header.
+ *
+ * @param buffer - Buffer to validate
+ * @returns `true` if the buffer passes basic MP4 validation
+ */
+export function isValidMp4Buffer(buffer) {
+    if (buffer.length < MIN_VIDEO_BUFFER_SIZE) {
+        return false;
+    }
+    // Check for ftyp box: bytes 4-7 should be "ftyp"
+    return buffer.subarray(4, 8).equals(FTYP_MAGIC);
+}
+// ============================================================================
+// FILE I/O HELPERS
+// ============================================================================
+export { writeFile, readFile, join };

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

@@ -0,0 +1,28 @@
+/**
+ * Frame Extractor for Director Mode
+ *
+ * Extracts first and last frames from MP4 video buffers using FFmpeg.
+ * Used by Director Mode to obtain boundary frames for Veo 3.1
+ * first-and-last-frame interpolation transitions.
+ *
+ * Uses the shared FFmpeg adapter for binary resolution, temp file management,
+ * and process execution — following the adapter pattern in `adapters/tts/`.
+ *
+ * @module adapters/video/frameExtractor
+ */
+/**
+ * Extract the first frame from a video buffer as JPEG.
+ *
+ * @param videoBuffer - MP4 video buffer
+ * @returns JPEG image buffer of the first frame
+ * @throws {VideoError} If buffer validation or extraction fails
+ */
+export declare function extractFirstFrame(videoBuffer: Buffer): Promise<Buffer>;
+/**
+ * Extract the last frame from a video buffer as JPEG.
+ *
+ * @param videoBuffer - MP4 video buffer
+ * @returns JPEG image buffer of the last frame
+ * @throws {VideoError} If buffer validation or extraction fails
+ */
+export declare function extractLastFrame(videoBuffer: Buffer): Promise<Buffer>;

package/dist/adapters/video/frameExtractor.js

@@ -0,0 +1,143 @@
+/**
+ * Frame Extractor for Director Mode
+ *
+ * Extracts first and last frames from MP4 video buffers using FFmpeg.
+ * Used by Director Mode to obtain boundary frames for Veo 3.1
+ * first-and-last-frame interpolation transitions.
+ *
+ * Uses the shared FFmpeg adapter for binary resolution, temp file management,
+ * and process execution — following the adapter pattern in `adapters/tts/`.
+ *
+ * @module adapters/video/frameExtractor
+ */
+import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { logger } from "../../utils/logger.js";
+import { cleanupTempFiles, createTrackedTempDir, FFMPEG_FRAME_MAX_BUFFER, FFMPEG_FRAME_TIMEOUT_MS, isValidMp4Buffer, JPEG_QUALITY, join, LAST_FRAME_SEEK_OFFSET, readFile, runFfmpeg, writeFile, } from "./ffmpegAdapter.js";
+import { VIDEO_ERROR_CODES } from "../../constants/videoErrors.js";
+import { VideoError } from "./vertexVideoHandler.js";
+// ============================================================================
+// INTERNAL HELPERS
+// ============================================================================
+/**
+ * Validate a video buffer before FFmpeg processing.
+ *
+ * @throws {VideoError} If the buffer is empty, too small, or not a valid MP4
+ */
+function assertValidVideoBuffer(videoBuffer, operation) {
+    if (!Buffer.isBuffer(videoBuffer) || videoBuffer.length === 0) {
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_FRAME_EXTRACTION_FAILED,
+            message: `Cannot ${operation}: video buffer is empty or not a Buffer`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { operation, bufferSize: videoBuffer?.length ?? 0 },
+        });
+    }
+    if (!isValidMp4Buffer(videoBuffer)) {
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_FRAME_EXTRACTION_FAILED,
+            message: `Cannot ${operation}: buffer does not appear to be a valid MP4 (missing ftyp header)`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: {
+                operation,
+                bufferSize: videoBuffer.length,
+                headerHex: videoBuffer.subarray(0, 12).toString("hex"),
+            },
+        });
+    }
+}
+/**
+ * Core frame extraction logic shared between first/last frame extractors.
+ */
+async function extractFrame(videoBuffer, position) {
+    const startTime = Date.now();
+    assertValidVideoBuffer(videoBuffer, `extract ${position} frame`);
+    const tempDir = await createTrackedTempDir("frame");
+    const inputPath = join(tempDir, "input.mp4");
+    const outputPath = join(tempDir, `${position}_frame.jpg`);
+    try {
+        await writeFile(inputPath, videoBuffer);
+        const args = position === "first"
+            ? [
+                "-y",
+                "-i",
+                inputPath,
+                "-vframes",
+                "1",
+                "-q:v",
+                JPEG_QUALITY,
+                "-f",
+                "image2",
+                outputPath,
+            ]
+            : [
+                "-y",
+                "-sseof",
+                `-${LAST_FRAME_SEEK_OFFSET}`,
+                "-i",
+                inputPath,
+                "-update",
+                "1",
+                "-q:v",
+                JPEG_QUALITY,
+                "-f",
+                "image2",
+                outputPath,
+            ];
+        await runFfmpeg(args, {
+            timeoutMs: FFMPEG_FRAME_TIMEOUT_MS,
+            maxBuffer: FFMPEG_FRAME_MAX_BUFFER,
+        });
+        const frameBuffer = await readFile(outputPath);
+        logger.debug(`Extracted ${position} frame`, {
+            inputSize: videoBuffer.length,
+            frameSize: frameBuffer.length,
+            elapsedMs: Date.now() - startTime,
+        });
+        return frameBuffer;
+    }
+    catch (error) {
+        // Re-throw VideoErrors as-is
+        if (error instanceof VideoError) {
+            throw error;
+        }
+        throw new VideoError({
+            code: VIDEO_ERROR_CODES.DIRECTOR_FRAME_EXTRACTION_FAILED,
+            message: `Failed to extract ${position} frame: ${error instanceof Error ? error.message : String(error)}`,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { position, bufferSize: videoBuffer.length },
+            originalError: error instanceof Error ? error : undefined,
+        });
+    }
+    finally {
+        await cleanupTempFiles(tempDir, inputPath, outputPath);
+    }
+}
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+/**
+ * Extract the first frame from a video buffer as JPEG.
+ *
+ * @param videoBuffer - MP4 video buffer
+ * @returns JPEG image buffer of the first frame
+ * @throws {VideoError} If buffer validation or extraction fails
+ */
+export async function extractFirstFrame(videoBuffer) {
+    return extractFrame(videoBuffer, "first");
+}
+/**
+ * Extract the last frame from a video buffer as JPEG.
+ *
+ * @param videoBuffer - MP4 video buffer
+ * @returns JPEG image buffer of the last frame
+ * @throws {VideoError} If buffer validation or extraction fails
+ */
+export async function extractLastFrame(videoBuffer) {
+    return extractFrame(videoBuffer, "last");
+}

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

@@ -10,35 +10,14 @@
  * @see https://cloud.google.com/vertex-ai/generative-ai/docs/video/generate-videos
  */
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
+import { VIDEO_ERROR_CODES } from "../../constants/videoErrors.js";
 import type { VideoGenerationResult, VideoOutputOptions } from "../../types/multimodal.js";
 import { NeuroLinkError } from "../../utils/errorHandling.js";
 /**
- * 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 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";
-};
+export { VIDEO_ERROR_CODES };
 /**
  * Video generation error class
  * Extends NeuroLinkError for consistent error handling across the SDK
@@ -99,3 +78,24 @@ export declare function isVertexVideoConfigured(): boolean;
  * ```
  */
 export declare function generateVideoWithVertex(image: Buffer, prompt: string, options?: VideoOutputOptions, region?: string): Promise<VideoGenerationResult>;
+/**
+ * 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 declare function generateTransitionWithVertex(firstFrame: Buffer, lastFrame: Buffer, prompt: string, options?: {
+    aspectRatio?: "9:16" | "16:9";
+    resolution?: "720p" | "1080p";
+    audio?: boolean;
+}, durationSeconds?: 4 | 6 | 8, region?: string): Promise<Buffer>;