@uploadbox/video 0.4.0

package/src/providers/ffmpeg.ts

@@ -0,0 +1,365 @@
+import type { TranscodingProvider, TranscodingSubmitInput } from "../provider.js";
+import type { TranscodingJob, QualityPreset } from "../types.js";
+import { QUALITY_PRESETS } from "../types.js";
+import { createS3Client } from "@uploadbox/core";
+import { ffprobe, runFFmpeg } from "../ffutils.js";
+import crypto from "crypto";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+
+interface FFmpegProviderOptions {
+  /** Path to ffmpeg binary. @default "ffmpeg" */
+  ffmpegPath?: string;
+  /** Path to ffprobe binary. @default "ffprobe" */
+  ffprobePath?: string;
+  /** Temporary directory for intermediate files. @default os.tmpdir() */
+  tmpDir?: string;
+}
+
+interface JobState {
+  status: TranscodingJob["status"];
+  progress: number;
+  outputKeys: string[];
+  error?: string;
+  abortController?: AbortController;
+}
+
+/**
+ * Local FFmpeg transcoding provider.
+ *
+ * Downloads the source video from S3, transcodes it using a local FFmpeg binary,
+ * and uploads HLS segments, playlists, thumbnails, and sprites back to S3.
+ *
+ * Best for development and small-scale self-hosted deployments.
+ *
+ * @example
+ * ```ts
+ * import { createFFmpegProvider } from "@uploadbox/video/providers/ffmpeg";
+ *
+ * const provider = createFFmpegProvider({ ffmpegPath: "/usr/bin/ffmpeg" });
+ * ```
+ */
+export function createFFmpegProvider(
+  options: FFmpegProviderOptions = {}
+): TranscodingProvider {
+  const {
+    ffmpegPath = "ffmpeg",
+    ffprobePath = "ffprobe",
+    tmpDir = os.tmpdir(),
+  } = options;
+
+  const jobs = new Map<string, JobState>();
+
+  return {
+    name: "ffmpeg-local",
+
+    async submit(input: TranscodingSubmitInput): Promise<{ jobId: string }> {
+      const jobId = crypto.randomUUID();
+      const abortController = new AbortController();
+
+      const jobState: JobState = {
+        status: "pending",
+        progress: 0,
+        outputKeys: [],
+        abortController,
+      };
+      jobs.set(jobId, jobState);
+
+      // Run transcoding in background (don't await)
+      runTranscoding(jobId, input, jobState, abortController.signal).catch(
+        (err) => {
+          jobState.status = "failed";
+          jobState.error = (err as Error).message;
+        }
+      );
+
+      return { jobId };
+    },
+
+    async getJobStatus(jobId: string): Promise<TranscodingJob> {
+      const state = jobs.get(jobId);
+      if (!state) {
+        return {
+          jobId,
+          status: "failed",
+          progress: 0,
+          outputKeys: [],
+          error: "Job not found",
+        };
+      }
+      return {
+        jobId,
+        status: state.status,
+        progress: state.progress,
+        outputKeys: state.outputKeys,
+        error: state.error,
+      };
+    },
+
+    async cancel(jobId: string): Promise<void> {
+      const state = jobs.get(jobId);
+      if (state?.abortController) {
+        state.abortController.abort();
+        state.status = "failed";
+        state.error = "Cancelled";
+      }
+    },
+  };
+
+  async function runTranscoding(
+    jobId: string,
+    input: TranscodingSubmitInput,
+    state: JobState,
+    signal: AbortSignal
+  ): Promise<void> {
+    const workDir = path.join(tmpDir, `uploadbox-video-${jobId}`);
+    await fs.mkdir(workDir, { recursive: true });
+
+    const { GetObjectCommand, PutObjectCommand } = await import("@aws-sdk/client-s3");
+
+    const s3Client = createS3Client({
+      region: input.s3Config.region ?? "us-east-1",
+      bucket: input.sourceBucket,
+      accessKeyId: input.s3Config.accessKeyId,
+      secretAccessKey: input.s3Config.secretAccessKey,
+      endpoint: input.s3Config.endpoint,
+      forcePathStyle: input.s3Config.forcePathStyle,
+    });
+
+    try {
+      state.status = "processing";
+      state.progress = 0;
+      input.onProgress?.({ jobId, percent: 0, message: "Downloading source video" });
+
+      // Download source from S3
+      const sourcePath = path.join(workDir, "source");
+      const getResponse = await s3Client.send(
+        new GetObjectCommand({ Bucket: input.sourceBucket, Key: input.sourceKey })
+      );
+      const body = await getResponse.Body?.transformToByteArray();
+      if (!body) throw new Error("Failed to download source video from S3");
+      await fs.writeFile(sourcePath, body);
+
+      if (signal.aborted) throw new Error("Cancelled");
+
+      // Determine qualities to transcode
+      const qualities = input.options.qualities ?? Object.values(QUALITY_PRESETS);
+      const segmentDuration = input.options.segmentDuration ?? 6;
+      const outputPrefix = input.options.s3OutputPrefix;
+      const totalSteps = qualities.length + 2; // +1 thumbnail, +1 sprite
+      let completedSteps = 0;
+
+      // Transcode each quality
+      const qualityPlaylists: { preset: QualityPreset; playlistKey: string }[] = [];
+
+      for (const preset of qualities) {
+        if (signal.aborted) throw new Error("Cancelled");
+
+        const qualityDir = path.join(workDir, preset.label);
+        await fs.mkdir(qualityDir, { recursive: true });
+
+        input.onProgress?.({
+          jobId,
+          percent: Math.round((completedSteps / totalSteps) * 100),
+          currentQuality: preset.label,
+          message: `Transcoding ${preset.label}`,
+        });
+
+        const segmentPattern = path.join(qualityDir, "segment-%03d.ts");
+        const playlistOutput = path.join(qualityDir, "playlist.m3u8");
+
+        await runFFmpeg([
+          "-i", sourcePath,
+          "-vf", `scale=${preset.width}:${preset.height}:force_original_aspect_ratio=decrease,pad=${preset.width}:${preset.height}:(ow-iw)/2:(oh-ih)/2`,
+          "-c:v", "libx264",
+          "-b:v", `${preset.videoBitrate}`,
+          "-maxrate", `${Math.round(preset.videoBitrate * 1.2)}`,
+          "-bufsize", `${Math.round(preset.videoBitrate * 2)}`,
+          "-r", `${Math.min(preset.maxFrameRate, 60)}`,
+          "-c:a", "aac",
+          "-b:a", `${preset.audioBitrate}`,
+          "-ac", "2",
+          "-hls_time", `${segmentDuration}`,
+          "-hls_playlist_type", "vod",
+          "-hls_segment_filename", segmentPattern,
+          "-f", "hls",
+          playlistOutput,
+        ], { ffmpegPath, signal });
+
+        // Upload segments and playlist to S3
+        const segmentFiles = await fs.readdir(qualityDir);
+        for (const file of segmentFiles) {
+          const filePath = path.join(qualityDir, file);
+          const fileContent = await fs.readFile(filePath);
+          const s3Key = `${outputPrefix}/${preset.label}/${file}`;
+          const contentType = file.endsWith(".m3u8")
+            ? "application/vnd.apple.mpegurl"
+            : "video/MP2T";
+
+          await s3Client.send(
+            new PutObjectCommand({
+              Bucket: input.outputBucket,
+              Key: s3Key,
+              Body: fileContent,
+              ContentType: contentType,
+            })
+          );
+          state.outputKeys.push(s3Key);
+        }
+
+        qualityPlaylists.push({
+          preset,
+          playlistKey: `${outputPrefix}/${preset.label}/playlist.m3u8`,
+        });
+
+        completedSteps++;
+        state.progress = Math.round((completedSteps / totalSteps) * 100);
+      }
+
+      if (signal.aborted) throw new Error("Cancelled");
+
+      // Generate master playlist
+      let masterPlaylist = "#EXTM3U\n#EXT-X-VERSION:3\n";
+      for (const { preset } of qualityPlaylists) {
+        const bandwidth = preset.videoBitrate + preset.audioBitrate;
+        masterPlaylist += `#EXT-X-STREAM-INF:BANDWIDTH=${bandwidth},RESOLUTION=${preset.width}x${preset.height}\n`;
+        masterPlaylist += `${preset.label}/playlist.m3u8\n`;
+      }
+
+      const masterKey = `${outputPrefix}/master.m3u8`;
+      await s3Client.send(
+        new PutObjectCommand({
+          Bucket: input.outputBucket,
+          Key: masterKey,
+          Body: Buffer.from(masterPlaylist),
+          ContentType: "application/vnd.apple.mpegurl",
+        })
+      );
+      state.outputKeys.push(masterKey);
+
+      // Generate poster thumbnail at ~10% duration
+      if (input.options.generateThumbnail !== false) {
+        input.onProgress?.({
+          jobId,
+          percent: Math.round((completedSteps / totalSteps) * 100),
+          message: "Generating thumbnail",
+        });
+
+        const thumbnailPath = path.join(workDir, "thumbnail.jpg");
+
+        // Get duration for timestamp calculation
+        const probeData = await ffprobe(sourcePath, { ffprobePath });
+        const duration = parseFloat(probeData.format?.duration ?? "10");
+        const thumbnailTime = Math.max(0.1, duration * 0.1);
+
+        await runFFmpeg([
+          "-ss", `${thumbnailTime}`,
+          "-i", sourcePath,
+          "-vframes", "1",
+          "-q:v", "2",
+          thumbnailPath,
+        ], { ffmpegPath, signal });
+
+        const thumbContent = await fs.readFile(thumbnailPath);
+        const thumbKey = `${outputPrefix}/thumbnail.jpg`;
+        await s3Client.send(
+          new PutObjectCommand({
+            Bucket: input.outputBucket,
+            Key: thumbKey,
+            Body: thumbContent,
+            ContentType: "image/jpeg",
+          })
+        );
+        state.outputKeys.push(thumbKey);
+        completedSteps++;
+      }
+
+      // Generate sprite sheet + WebVTT
+      if (input.options.generateSpriteSheet !== false) {
+        input.onProgress?.({
+          jobId,
+          percent: Math.round((completedSteps / totalSteps) * 100),
+          message: "Generating sprite sheet",
+        });
+
+        const spritesDir = path.join(workDir, "sprites");
+        await fs.mkdir(spritesDir, { recursive: true });
+
+        // Extract frames every 10 seconds
+        const probeData = await ffprobe(sourcePath, { ffprobePath });
+        const duration = parseFloat(probeData.format?.duration ?? "10");
+
+        const interval = 10;
+        const thumbWidth = 160;
+        const thumbHeight = 90;
+        const cols = 10;
+        const frameCount = Math.ceil(duration / interval);
+        const rows = Math.ceil(frameCount / cols);
+
+        // Generate sprite sheet using a single FFmpeg command
+        await runFFmpeg([
+          "-i", sourcePath,
+          "-vf", `fps=1/${interval},scale=${thumbWidth}:${thumbHeight},tile=${cols}x${rows}`,
+          "-frames:v", "1",
+          "-q:v", "5",
+          path.join(spritesDir, "sprite-sheet.jpg"),
+        ], { ffmpegPath, signal });
+
+        // Upload sprite sheet
+        const spriteContent = await fs.readFile(path.join(spritesDir, "sprite-sheet.jpg"));
+        const spriteKey = `${outputPrefix}/sprites/sprite-sheet.jpg`;
+        await s3Client.send(
+          new PutObjectCommand({
+            Bucket: input.outputBucket,
+            Key: spriteKey,
+            Body: spriteContent,
+            ContentType: "image/jpeg",
+          })
+        );
+        state.outputKeys.push(spriteKey);
+
+        // Generate WebVTT for sprite positions
+        let vtt = "WEBVTT\n\n";
+        for (let i = 0; i < frameCount; i++) {
+          const startTime = i * interval;
+          const endTime = Math.min((i + 1) * interval, duration);
+          const col = i % cols;
+          const row = Math.floor(i / cols);
+          const x = col * thumbWidth;
+          const y = row * thumbHeight;
+
+          vtt += `${formatVttTime(startTime)} --> ${formatVttTime(endTime)}\n`;
+          vtt += `sprite-sheet.jpg#xywh=${x},${y},${thumbWidth},${thumbHeight}\n\n`;
+        }
+
+        const vttKey = `${outputPrefix}/sprites/sprites.vtt`;
+        await s3Client.send(
+          new PutObjectCommand({
+            Bucket: input.outputBucket,
+            Key: vttKey,
+            Body: Buffer.from(vtt),
+            ContentType: "text/vtt",
+          })
+        );
+        state.outputKeys.push(vttKey);
+        completedSteps++;
+      }
+
+      state.status = "completed";
+      state.progress = 100;
+      input.onProgress?.({ jobId, percent: 100, message: "Transcoding complete" });
+    } finally {
+      // Cleanup temp directory
+      await fs.rm(workDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}
+
+function formatVttTime(seconds: number): string {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = Math.floor(seconds % 60);
+  const ms = Math.round((seconds % 1) * 1000);
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}.${String(ms).padStart(3, "0")}`;
+}

package/src/providers/lambda.ts

@@ -0,0 +1,112 @@
+import type { TranscodingProvider, TranscodingSubmitInput } from "../provider.js";
+import type { TranscodingJob } from "../types.js";
+import crypto from "crypto";
+
+interface LambdaProviderOptions {
+  /** AWS region where the Lambda function is deployed. */
+  region: string;
+  /** ARN of the Lambda function that performs transcoding. */
+  functionArn: string;
+  /**
+   * Function to poll job status. The Lambda function should store status
+   * in DynamoDB or a similar store that this function can query.
+   */
+  getStatus: (jobId: string) => Promise<TranscodingJob>;
+  /**
+   * Optional function to cancel a job.
+   */
+  cancelJob?: (jobId: string) => Promise<void>;
+}
+
+/**
+ * AWS Lambda transcoding provider.
+ *
+ * Invokes a user-provided Lambda function asynchronously for transcoding.
+ * The Lambda function is NOT included — users must implement and deploy it themselves.
+ *
+ * The Lambda function receives the same input payload and should:
+ * 1. Download the source video from S3
+ * 2. Transcode to HLS using FFmpeg (via a Lambda layer)
+ * 3. Upload outputs back to S3
+ * 4. Store job status in DynamoDB for polling
+ *
+ * Requires `@aws-sdk/client-lambda` to be installed by the user.
+ *
+ * @example
+ * ```ts
+ * import { createLambdaProvider } from "@uploadbox/video/providers/lambda";
+ *
+ * const provider = createLambdaProvider({
+ *   region: "us-east-1",
+ *   functionArn: "arn:aws:lambda:us-east-1:123456789:function:video-transcode",
+ *   getStatus: async (jobId) => {
+ *     // Query DynamoDB for job status
+ *     const item = await dynamodb.get({ TableName: "jobs", Key: { jobId } });
+ *     return item;
+ *   },
+ * });
+ * ```
+ */
+export function createLambdaProvider(
+  options: LambdaProviderOptions
+): TranscodingProvider {
+  const { region, functionArn, getStatus, cancelJob } = options;
+
+  return {
+    name: "aws-lambda",
+
+    async submit(input: TranscodingSubmitInput): Promise<{ jobId: string }> {
+      // Dynamic import to keep @aws-sdk/client-lambda optional
+      let LambdaClient: any;
+      let InvokeCommand: any;
+      try {
+        const mod = await (Function('return import("@aws-sdk/client-lambda")')() as Promise<any>);
+        LambdaClient = mod.LambdaClient;
+        InvokeCommand = mod.InvokeCommand;
+      } catch {
+        throw new Error(
+          "@aws-sdk/client-lambda is not installed. Run: npm install @aws-sdk/client-lambda"
+        );
+      }
+
+      const lambda = new LambdaClient({
+        region,
+        credentials: {
+          accessKeyId: input.s3Config.accessKeyId,
+          secretAccessKey: input.s3Config.secretAccessKey,
+        },
+      });
+
+      const jobId = crypto.randomUUID();
+
+      const payload = {
+        jobId,
+        sourceKey: input.sourceKey,
+        sourceBucket: input.sourceBucket,
+        outputBucket: input.outputBucket,
+        options: input.options,
+        s3Config: input.s3Config,
+      };
+
+      await lambda.send(
+        new InvokeCommand({
+          FunctionName: functionArn,
+          InvocationType: "Event",
+          Payload: Buffer.from(JSON.stringify(payload)),
+        })
+      );
+
+      return { jobId };
+    },
+
+    async getJobStatus(jobId: string): Promise<TranscodingJob> {
+      return getStatus(jobId);
+    },
+
+    async cancel(jobId: string): Promise<void> {
+      if (cancelJob) {
+        await cancelJob(jobId);
+      }
+    },
+  };
+}

package/src/react/index.ts

@@ -0,0 +1,7 @@
+export { useVideoPlayer } from "./use-video-player.js";
+export type {
+  UseVideoPlayerOptions,
+  VideoPlayerState,
+  QualityLevel,
+  SpritePosition,
+} from "./use-video-player.js";