Add Labels.addVideo() and support File/Blob sources in video factory (#79)

Enable adding standalone videos to existing Labels projects in the browser
by accepting File/Blob objects throughout the video loading pipeline.

Closes #77

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: talmo

src/io/main.ts

@@ -161,17 +161,19 @@ export async function saveSlpSet(
 /**
  * Load a video file and create a Video object with an active backend.
  *
- * @param filename - Path to video file
+ * @param source - Path to video file, or a browser File object
  * @param options - Video loading options
  * @param options.dataset - HDF5 dataset path for embedded videos
  * @param options.openBackend - Whether to open the backend (default: true)
+ * @param options.backend - Explicit backend selection
  * @returns Video object with backend
  */
 export async function loadVideo(
-  filename: string,
+  source: string | File,
   options?: { dataset?: string; openBackend?: boolean; backend?: VideoBackendType }
 ): Promise<Video> {
-  const backend = await createVideoBackend(filename, {
+  const filename = typeof source === "string" ? source : source.name;
+  const backend = await createVideoBackend(source, {
     dataset: options?.dataset,
     backend: options?.backend,
   });

src/model/labels.ts

@@ -153,12 +153,16 @@ export class Labels {
     });
   }
 
+  addVideo(video: Video): void {
+    if (!this.videos.includes(video)) {
+      this.videos.push(video);
+    }
+  }
+
   append(frame: LabeledFrame): void {
     if (this._lazyFrameList) this.materialize();
     this.labeledFrames.push(frame);
-    if (!this.videos.includes(frame.video)) {
-      this.videos.push(frame.video);
-    }
+    this.addVideo(frame.video);
   }
 
   toDict(options?: { video?: Video | number; skipEmptyFrames?: boolean }) {

src/video/factory.ts

@@ -12,7 +12,7 @@ export type VideoBackendType = "mp4box" | "mediabunny" | "media";
 const MEDIABUNNY_EXTENSIONS = ["webm", "mkv", "ogg", "mov", "mpeg", "avi"];
 
 export async function createVideoBackend(
-  filename: string,
+  source: string | File | Blob,
   options?: {
     dataset?: string;
     embedded?: boolean;
@@ -25,9 +25,16 @@ export async function createVideoBackend(
     backend?: VideoBackendType;
   }
 ): Promise<VideoBackend> {
+  const isBlob = typeof Blob !== "undefined" && source instanceof Blob;
+  const filename = isBlob
+    ? (source as File).name ?? ""
+    : (source as string);
+  const normalized = filename.split("?")[0]?.toLowerCase() ?? "";
+  const ext = normalized.split(".").pop() ?? "";
+
   // HDF5/SLP files always use the HDF5 backend (not overridable)
-  if (options?.embedded || filename.endsWith(".slp") || filename.endsWith(".h5") || filename.endsWith(".hdf5")) {
-    const { file } = await openH5File(filename);
+  if (options?.embedded || ext === "slp" || ext === "h5" || ext === "hdf5") {
+    const { file } = await openH5File(isBlob ? (source as File) : filename);
     const datasetPath = options?.dataset ?? "";
     return new Hdf5VideoBackend({
       filename,
@@ -44,12 +51,14 @@ export async function createVideoBackend(
 
   // User-specified backend override
   if (options?.backend === "mediabunny") {
+    if (isBlob) return MediaBunnyVideoBackend.fromBlob(source as Blob, filename);
     return MediaBunnyVideoBackend.fromUrl(filename);
   }
   if (options?.backend === "mp4box") {
-    return new Mp4BoxVideoBackend(filename);
+    return new Mp4BoxVideoBackend(source);
   }
   if (options?.backend === "media") {
+    if (isBlob) return new MediaVideoBackend(URL.createObjectURL(source as Blob));
     return new MediaVideoBackend(filename);
   }
 
@@ -59,19 +68,18 @@ export async function createVideoBackend(
     typeof window.VideoDecoder !== "undefined" &&
     typeof window.EncodedVideoChunk !== "undefined";
 
-  const normalized = filename.split("?")[0]?.toLowerCase() ?? "";
-  const ext = normalized.split(".").pop() ?? "";
-
   // MP4: prefer Mp4Box (better sequential performance)
   if (supportsWebCodecs && ext === "mp4") {
-    return new Mp4BoxVideoBackend(filename);
+    return new Mp4BoxVideoBackend(source);
   }
 
   // Non-MP4 video formats: use MediaBunny
   if (supportsWebCodecs && MEDIABUNNY_EXTENSIONS.includes(ext)) {
+    if (isBlob) return MediaBunnyVideoBackend.fromBlob(source as Blob, filename);
     return MediaBunnyVideoBackend.fromUrl(filename);
   }
 
   // Fallback: HTML5 video element
+  if (isBlob) return new MediaVideoBackend(URL.createObjectURL(source as Blob));
   return new MediaVideoBackend(filename);
 }

tests/model/labels-add-video.test.ts

@@ -0,0 +1,45 @@
+/* @vitest-environment node */
+import { describe, it, expect } from "vitest";
+import { Labels } from "../../src/model/labels.js";
+import { LabeledFrame } from "../../src/model/labeled-frame.js";
+import { Video } from "../../src/model/video.js";
+
+describe("Labels.addVideo()", () => {
+  it("adds a video to the labels", () => {
+    const labels = new Labels();
+    const video = new Video({ filename: "video.mp4" });
+    labels.addVideo(video);
+    expect(labels.videos).toHaveLength(1);
+    expect(labels.videos[0]).toBe(video);
+  });
+
+  it("does not add duplicate videos", () => {
+    const labels = new Labels();
+    const video = new Video({ filename: "video.mp4" });
+    labels.addVideo(video);
+    labels.addVideo(video);
+    expect(labels.videos).toHaveLength(1);
+  });
+
+  it("adds multiple distinct videos", () => {
+    const labels = new Labels();
+    const v1 = new Video({ filename: "a.mp4" });
+    const v2 = new Video({ filename: "b.mp4" });
+    labels.addVideo(v1);
+    labels.addVideo(v2);
+    expect(labels.videos).toHaveLength(2);
+  });
+
+  it("works alongside append()", () => {
+    const labels = new Labels();
+    const video = new Video({ filename: "video.mp4" });
+    labels.addVideo(video);
+
+    const frame = new LabeledFrame({ video, frameIdx: 0 });
+    labels.append(frame);
+
+    // Video should still appear only once
+    expect(labels.videos).toHaveLength(1);
+    expect(labels.videos[0]).toBe(video);
+  });
+});

tests/video/factory.test.ts

@@ -56,4 +56,19 @@ describe("createVideoBackend", () => {
       createVideoBackend("video.mp4", { backend: "mediabunny" })
     ).rejects.toThrow(/MediaBunny/);
   });
+
+  it("selects MediaBunny for Blob with .webm filename", async () => {
+    const { createVideoBackend } = await import("../../src/video/factory.js");
+    const blob = new Blob(["fake"], { type: "video/webm" });
+    const file = new File([blob], "clip.webm");
+    await expect(createVideoBackend(file)).rejects.toThrow(/MediaBunny/);
+  });
+
+  it("routes Blob to MediaBunny when backend='mediabunny'", async () => {
+    const { createVideoBackend } = await import("../../src/video/factory.js");
+    const file = new File([new Blob(["fake"])], "clip.mp4");
+    await expect(
+      createVideoBackend(file, { backend: "mediabunny" })
+    ).rejects.toThrow(/MediaBunny/);
+  });
 });