@talmolab/sleap-io.js 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -18,13 +18,16 @@ declare class Video {
     backendMetadata: Record<string, unknown>;
     sourceVideo: Video | null;
     openBackend: boolean;
+    private _embedded;
     constructor(options: {
         filename: string | string[];
         backend?: VideoBackend | null;
         backendMetadata?: Record<string, unknown>;
         sourceVideo?: Video | null;
         openBackend?: boolean;
+        embedded?: boolean;
     });
+    get hasEmbeddedImages(): boolean;
     get originalVideo(): Video | null;
     get shape(): [number, number, number, number] | null;
     get fps(): number | null;
@@ -259,6 +262,10 @@ interface StreamingH5Options {
     /** Filename hint for the HDF5 file. */
     filenameHint?: string;
 }
+/**
+ * Source types supported by the streaming HDF5 file.
+ */
+type StreamingH5Source = string | ArrayBuffer | Uint8Array | File;
 /**
  * A streaming HDF5 file handle that uses a Web Worker for range request access.
  *
@@ -280,12 +287,33 @@ declare class StreamingH5File {
      */
     init(options?: StreamingH5Options): Promise<void>;
     /**
-     * Open a remote HDF5 file for streaming access.
+     * Open a remote HDF5 file for streaming access via URL.
      *
      * @param url - URL to the HDF5 file (must support HTTP range requests)
      * @param options - Optional settings
      */
     open(url: string, options?: StreamingH5Options): Promise<void>;
+    /**
+     * Open a local File object using WORKERFS (zero-copy).
+     *
+     * @param file - File object from file input or drag-and-drop
+     * @param options - Optional settings
+     */
+    openLocal(file: File, options?: StreamingH5Options): Promise<void>;
+    /**
+     * Open an HDF5 file from an ArrayBuffer or Uint8Array.
+     *
+     * @param buffer - ArrayBuffer or Uint8Array containing the HDF5 file data
+     * @param options - Optional settings
+     */
+    openBuffer(buffer: ArrayBuffer | Uint8Array, options?: StreamingH5Options): Promise<void>;
+    /**
+     * Open an HDF5 file from any supported source.
+     *
+     * @param source - URL string, File, ArrayBuffer, or Uint8Array
+     * @param options - Optional settings
+     */
+    openAny(source: StreamingH5Source, options?: StreamingH5Options): Promise<void>;
     /**
      * Whether a file is currently open.
      */
@@ -341,6 +369,29 @@ declare function isStreamingSupported(): boolean;
  * @returns A StreamingH5File instance
  */
 declare function openStreamingH5(url: string, options?: StreamingH5Options): Promise<StreamingH5File>;
+/**
+ * Open an HDF5 file from any supported source using a Web Worker.
+ *
+ * This is the recommended way to open HDF5 files in the browser as it
+ * offloads all h5wasm operations to a Web Worker, avoiding main thread blocking.
+ *
+ * @param source - URL string, File object, ArrayBuffer, or Uint8Array
+ * @param options - Optional settings
+ * @returns A StreamingH5File instance
+ *
+ * @example
+ * ```typescript
+ * // From URL
+ * const file = await openH5Worker("https://example.com/data.h5");
+ *
+ * // From File (file input)
+ * const file = await openH5Worker(inputElement.files[0]);
+ *
+ * // From ArrayBuffer
+ * const file = await openH5Worker(arrayBuffer);
+ * ```
+ */
+declare function openH5Worker(source: StreamingH5Source, options?: StreamingH5Options): Promise<StreamingH5File>;
 
 /**
  * Video backend for embedded images in HDF5 files accessed via streaming.
@@ -348,6 +399,10 @@ declare function openStreamingH5(url: string, options?: StreamingH5Options): Pro
  * This backend uses StreamingH5File (Web Worker + range requests) instead of
  * a synchronous h5wasm File object, making it suitable for browser environments
  * where the SLP file is loaded via HTTP range requests.
+ *
+ * Supports two data storage formats:
+ * 1. vlen-encoded: Array of individual frame blobs (each index = one frame)
+ * 2. Contiguous buffer: Single buffer with all frames concatenated
  */
 declare class StreamingHdf5VideoBackend implements VideoBackend {
     filename: string;
@@ -356,10 +411,11 @@ declare class StreamingHdf5VideoBackend implements VideoBackend {
     fps?: number;
     private h5file;
     private datasetPath;
-    private frameNumbers;
+    private frameNumberToIndex;
     private format;
     private channelOrder;
     private cachedData;
+    private frameOffsets;
     constructor(options: {
         filename: string;
         h5file: StreamingH5File;
@@ -391,27 +447,36 @@ type OpenH5Options = {
 /**
  * Load an SLP file.
  *
- * When loading from a URL in a browser with `h5.stream` set to 'range' or 'auto',
- * this function automatically uses HTTP range requests for efficient streaming.
- * Only the annotation data needed is downloaded, not the entire file.
+ * In browser environments, this function automatically uses a Web Worker for all
+ * HDF5 operations, keeping the main thread responsive. For URLs, it uses HTTP
+ * range requests to download only the data needed rather than the entire file.
+ *
+ * In Node.js, this uses the native h5wasm bindings directly.
  *
  * @param source - Path, URL, ArrayBuffer, File, or FileSystemFileHandle
  * @param options - Loading options
- * @param options.openVideos - Whether to open video backends (default: true, but false for streaming)
+ * @param options.openVideos - Whether to open video backends (default: true)
  * @param options.h5 - HDF5 options including streaming mode
  * @param options.h5.stream - 'auto' | 'range' | 'download' (default: 'auto')
  *
  * @example
  * ```typescript
- * // Load from URL with streaming (uses range requests automatically)
- * const labels = await loadSlp('https://example.com/labels.slp', {
- *   h5: { stream: 'range' }
- * });
+ * // Browser: Load from URL (automatically uses Worker + range requests)
+ * const labels = await loadSlp('https://example.com/labels.slp');
+ *
+ * // Browser: Load from file input (automatically uses Worker)
+ * const labels = await loadSlp(fileInput.files[0]);
+ *
+ * // Browser: Load from ArrayBuffer (automatically uses Worker)
+ * const labels = await loadSlp(arrayBuffer);
  *
- * // Force full download
+ * // Force full download instead of range requests
  * const labels = await loadSlp('https://example.com/labels.slp', {
  *   h5: { stream: 'download' }
  * });
+ *
+ * // Node.js: Load from file path
+ * const labels = await loadSlp('/path/to/file.slp');
  * ```
  */
 declare function loadSlp(source: SlpSource, options?: {
@@ -738,28 +803,38 @@ interface StreamingSlpOptions {
     openVideos?: boolean;
 }
 /**
- * Read an SLP file using HTTP range requests for efficient streaming.
+ * Read an SLP file using a Web Worker for efficient, non-blocking HDF5 access.
  *
- * This function downloads only the data needed (metadata, frames, instances, points)
- * rather than the entire file.
+ * This function offloads all h5wasm operations to a Web Worker, keeping the
+ * main thread responsive. For URLs, it uses HTTP range requests to download
+ * only the data needed rather than the entire file.
  *
  * When `openVideos` is true, video backends are created for embedded videos,
  * allowing frame data to be retrieved. The underlying HDF5 file remains open
  * until all video backends are closed.
  *
- * @param url - URL to the SLP file (must support HTTP range requests)
+ * @param source - URL, File, ArrayBuffer, or Uint8Array containing the SLP file
  * @param options - Optional settings
  * @returns Labels object with all annotation data
  *
  * @example
  * ```typescript
- * // Load with video backends for embedded images
+ * // Load from URL with video backends
  * const labels = await readSlpStreaming('https://example.com/labels.slp', {
  *   openVideos: true
  * });
- * const frame = await labels.video.getFrame(0);
+ *
+ * // Load from File object (file input)
+ * const labels = await readSlpStreaming(fileInput.files[0], {
+ *   openVideos: true
+ * });
+ *
+ * // Load from ArrayBuffer
+ * const labels = await readSlpStreaming(arrayBuffer, {
+ *   filenameHint: 'data.slp'
+ * });
  * ```
  */
-declare function readSlpStreaming(url: string, options?: StreamingSlpOptions): Promise<Labels>;
+declare function readSlpStreaming(source: StreamingH5Source, options?: StreamingSlpOptions): Promise<Labels>;
 
-export { Camera, CameraGroup, type ColorScheme, type ColorSpec, FrameGroup, Instance, InstanceContext, InstanceGroup, LabeledFrame, Labels, type LabelsDict, LabelsSet, MARKER_FUNCTIONS, type MarkerShape, Mp4BoxVideoBackend, NAMED_COLORS, PALETTES, type PaletteName, PredictedInstance, type RGB, type RGBA, RecordingSession, RenderContext, type RenderOptions, Skeleton, StreamingH5File, StreamingHdf5VideoBackend, SuggestionFrame, Track, Video, type VideoBackend, type VideoFrame, type VideoOptions, checkFfmpeg, decodeYamlSkeleton, determineColorScheme, drawCircle, drawCross, drawDiamond, drawSquare, drawTriangle, encodeYamlSkeleton, fromDict, fromNumpy, getMarkerFunction, getPalette, isStreamingSupported, labelsFromNumpy, loadSlp, loadVideo, makeCameraFromDict, openStreamingH5, readSlpStreaming, renderImage, renderVideo, resolveColor, rgbToCSS, rodriguesTransformation, saveImage, saveSlp, toDataURL, toDict, toJPEG, toNumpy, toPNG };
+export { Camera, CameraGroup, type ColorScheme, type ColorSpec, FrameGroup, Instance, InstanceContext, InstanceGroup, LabeledFrame, Labels, type LabelsDict, LabelsSet, MARKER_FUNCTIONS, type MarkerShape, Mp4BoxVideoBackend, NAMED_COLORS, PALETTES, type PaletteName, PredictedInstance, type RGB, type RGBA, RecordingSession, RenderContext, type RenderOptions, Skeleton, StreamingH5File, type StreamingH5Source, StreamingHdf5VideoBackend, SuggestionFrame, Track, Video, type VideoBackend, type VideoFrame, type VideoOptions, checkFfmpeg, decodeYamlSkeleton, determineColorScheme, drawCircle, drawCross, drawDiamond, drawSquare, drawTriangle, encodeYamlSkeleton, fromDict, fromNumpy, getMarkerFunction, getPalette, isStreamingSupported, labelsFromNumpy, loadSlp, loadVideo, makeCameraFromDict, openH5Worker, openStreamingH5, readSlpStreaming, renderImage, renderVideo, resolveColor, rgbToCSS, rodriguesTransformation, saveImage, saveSlp, toDataURL, toDict, toJPEG, toNumpy, toPNG };

package/dist/index.js

@@ -85,12 +85,17 @@ var Video = class {
   backendMetadata;
   sourceVideo;
   openBackend;
+  _embedded;
   constructor(options) {
     this.filename = options.filename;
     this.backend = options.backend ?? null;
     this.backendMetadata = options.backendMetadata ?? {};
     this.sourceVideo = options.sourceVideo ?? null;
     this.openBackend = options.openBackend ?? true;
+    this._embedded = options.embedded ?? false;
+  }
+  get hasEmbeddedImages() {
+    return this._embedded;
   }
   get originalVideo() {
     if (!this.sourceVideo) return null;
@@ -1208,6 +1213,8 @@ var Mp4BoxVideoBackend = class {
 
 // src/video/streaming-hdf5-video.ts
 var isBrowser3 = typeof window !== "undefined" && typeof document !== "undefined";
+var PNG_MAGIC = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+var JPEG_MAGIC = new Uint8Array([255, 216, 255]);
 var StreamingHdf5VideoBackend = class {
   filename;
   dataset;
@@ -1215,39 +1222,58 @@ var StreamingHdf5VideoBackend = class {
   fps;
   h5file;
   datasetPath;
-  frameNumbers;
+  frameNumberToIndex;
   format;
   channelOrder;
   cachedData;
+  frameOffsets;
+  // For contiguous buffer: byte offsets of each frame
   constructor(options) {
     this.filename = options.filename;
     this.h5file = options.h5file;
     this.datasetPath = options.datasetPath;
     this.dataset = options.datasetPath;
-    this.frameNumbers = options.frameNumbers ?? [];
+    const frameNumbers = options.frameNumbers ?? [];
+    this.frameNumberToIndex = new Map(frameNumbers.map((num, idx) => [num, idx]));
     this.format = options.format ?? "png";
     this.channelOrder = options.channelOrder ?? "RGB";
     this.shape = options.shape;
     this.fps = options.fps;
     this.cachedData = null;
+    this.frameOffsets = null;
   }
   async getFrame(frameIndex) {
-    const index = this.frameNumbers.length ? this.frameNumbers.indexOf(frameIndex) : frameIndex;
-    if (index < 0) return null;
+    const index = this.frameNumberToIndex.size > 0 ? this.frameNumberToIndex.get(frameIndex) : frameIndex;
+    if (index === void 0) return null;
     if (!this.cachedData) {
       try {
         const data = await this.h5file.getDatasetValue(this.datasetPath);
-        this.cachedData = data.value;
+        this.cachedData = normalizeVideoData(data.value, data.shape);
+        if (isContiguousEncodedBuffer(this.cachedData, this.format, this.shape)) {
+          this.frameOffsets = findEncodedFrameOffsets(
+            this.cachedData,
+            this.format,
+            this.shape?.[0] ?? 0
+          );
+        }
       } catch {
         return null;
       }
     }
-    const entry = this.cachedData[index];
-    if (entry == null) return null;
-    const rawBytes = toUint8Array(entry);
-    if (!rawBytes) return null;
+    let rawBytes;
+    if (this.frameOffsets && this.frameOffsets.length > index) {
+      const buffer = this.cachedData;
+      const start = this.frameOffsets[index];
+      const end = index + 1 < this.frameOffsets.length ? this.frameOffsets[index + 1] : buffer.length;
+      rawBytes = buffer.slice(start, end);
+    } else {
+      const entry = this.cachedData[index];
+      if (entry == null) return null;
+      rawBytes = toUint8Array(entry);
+    }
+    if (!rawBytes || rawBytes.length === 0) return null;
     if (isEncodedFormat(this.format)) {
-      const decoded = await decodeImageBytes(rawBytes, this.format);
+      const decoded = await decodeImageBytes(rawBytes, this.format, this.channelOrder);
       return decoded ?? rawBytes;
     }
     const image = decodeRawFrame(rawBytes, this.shape, this.channelOrder);
@@ -1255,8 +1281,55 @@ var StreamingHdf5VideoBackend = class {
   }
   close() {
     this.cachedData = null;
+    this.frameOffsets = null;
   }
 };
+function normalizeVideoData(value, _shape) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const arr = value;
+    return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+  }
+  return [];
+}
+function isContiguousEncodedBuffer(data, format, shape) {
+  if (!isEncodedFormat(format)) return false;
+  if (!(data instanceof Uint8Array)) return false;
+  if (data.length < 8) return false;
+  const isPng = matchesMagic(data, PNG_MAGIC);
+  const isJpeg = matchesMagic(data, JPEG_MAGIC);
+  if (!isPng && !isJpeg) return false;
+  if (shape) {
+    const frameCount = shape[0];
+    if (frameCount > 1 && data.length > 1e4) {
+      return true;
+    }
+  }
+  return true;
+}
+function matchesMagic(buffer, magic) {
+  if (buffer.length < magic.length) return false;
+  for (let i = 0; i < magic.length; i++) {
+    if (buffer[i] !== magic[i]) return false;
+  }
+  return true;
+}
+function findEncodedFrameOffsets(buffer, format, expectedFrameCount) {
+  const offsets = [];
+  const magic = format.toLowerCase() === "png" ? PNG_MAGIC : JPEG_MAGIC;
+  for (let i = 0; i <= buffer.length - magic.length; i++) {
+    if (matchesMagic(buffer.subarray(i), magic)) {
+      offsets.push(i);
+      i += magic.length - 1;
+      if (expectedFrameCount > 0 && offsets.length >= expectedFrameCount) {
+        break;
+      }
+    }
+  }
+  return offsets;
+}
 function toUint8Array(entry) {
   if (entry instanceof Uint8Array) return entry;
   if (entry instanceof ArrayBuffer) return new Uint8Array(entry);
@@ -1271,12 +1344,29 @@ function isEncodedFormat(format) {
   const normalized = format.toLowerCase();
   return normalized === "png" || normalized === "jpg" || normalized === "jpeg";
 }
-async function decodeImageBytes(bytes, format) {
+async function decodeImageBytes(bytes, format, channelOrder) {
   if (!isBrowser3 || typeof createImageBitmap === "undefined") return null;
   const mime = format.toLowerCase() === "png" ? "image/png" : "image/jpeg";
   const safeBytes = new Uint8Array(bytes);
   const blob = new Blob([safeBytes.buffer], { type: mime });
-  return createImageBitmap(blob);
+  const bitmap = await createImageBitmap(blob);
+  const useBgr = channelOrder.toUpperCase() === "BGR";
+  if (!useBgr) {
+    return bitmap;
+  }
+  const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return bitmap;
+  ctx.drawImage(bitmap, 0, 0);
+  const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
+  const data = imageData.data;
+  for (let i = 0; i < data.length; i += 4) {
+    const r = data[i];
+    const b = data[i + 2];
+    data[i] = b;
+    data[i + 2] = r;
+  }
+  return imageData;
 }
 function decodeRawFrame(bytes, shape, channelOrder) {
   if (!isBrowser3 || !shape) return null;
@@ -1304,7 +1394,8 @@ function decodeRawFrame(bytes, shape, channelOrder) {
 // src/codecs/slp/h5-worker.ts
 var H5_WORKER_CODE = `
 // h5wasm streaming worker
-// Uses createLazyFile for HTTP range request streaming
+// Handles all HDF5 operations in a Web Worker to avoid main thread blocking
+// Supports: URL streaming (range requests), local files (WORKERFS), and ArrayBuffers
 
 let h5wasmModule = null;
 let FS = null;
@@ -1322,8 +1413,18 @@ self.onmessage = async function(e) {
         break;
 
       case 'openUrl':
-        const result = await openRemoteFile(payload.url, payload.filename);
-        respond(id, result);
+        const urlResult = await openRemoteFile(payload.url, payload.filename);
+        respond(id, urlResult);
+        break;
+
+      case 'openLocal':
+        const localResult = await openLocalFile(payload.file, payload.filename);
+        respond(id, localResult);
+        break;
+
+      case 'openBuffer':
+        const bufferResult = await openBufferFile(payload.buffer, payload.filename);
+        respond(id, bufferResult);
         break;
 
       case 'getKeys':
@@ -1414,6 +1515,66 @@ async function openRemoteFile(url, filename = 'data.h5') {
   };
 }
 
+async function openLocalFile(file, filename) {
+  if (!h5wasmModule) {
+    throw new Error('h5wasm not initialized');
+  }
+
+  // Close any existing file
+  closeFile();
+
+  // Use provided filename or file.name
+  const fname = filename || file.name || 'local.h5';
+
+  // Create mount point for WORKERFS
+  mountPath = '/local-' + Date.now();
+  FS.mkdir(mountPath);
+
+  // Mount the file using WORKERFS (zero-copy access)
+  FS.mount(FS.filesystems.WORKERFS, { files: [file] }, mountPath);
+
+  // Open with h5wasm
+  const filePath = mountPath + '/' + fname;
+  currentFile = new h5wasm.File(filePath, 'r');
+
+  return {
+    success: true,
+    path: currentFile.path,
+    filename: currentFile.filename,
+    keys: currentFile.keys()
+  };
+}
+
+async function openBufferFile(buffer, filename = 'data.h5') {
+  if (!h5wasmModule) {
+    throw new Error('h5wasm not initialized');
+  }
+
+  // Close any existing file
+  closeFile();
+
+  // Write buffer to virtual filesystem
+  const data = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  mountPath = '/buffer-' + Date.now() + '/' + filename;
+
+  // Create parent directory
+  const dir = mountPath.substring(0, mountPath.lastIndexOf('/'));
+  FS.mkdir(dir);
+
+  // Write file to virtual FS
+  FS.writeFile(mountPath, data);
+
+  // Open with h5wasm
+  currentFile = new h5wasm.File(mountPath, 'r');
+
+  return {
+    success: true,
+    path: currentFile.path,
+    filename: currentFile.filename,
+    keys: currentFile.keys()
+  };
+}
+
 function getKeys(path) {
   if (!currentFile) throw new Error('No file open');
   const item = path === '/' || !path ? currentFile : currentFile.get(path);
@@ -1421,19 +1582,38 @@ function getKeys(path) {
   return item.keys ? item.keys() : [];
 }
 
+function serializeAttrValue(attr) {
+  if (!attr) return null;
+  // h5wasm Attribute objects have a .value property
+  const val = attr.value !== undefined ? attr.value : attr;
+  // Convert Uint8Array to string for JSON attributes
+  if (val instanceof Uint8Array) {
+    return { value: new TextDecoder().decode(val) };
+  }
+  // Wrap primitive values to preserve structure
+  return { value: val };
+}
+
 function getAttr(path, name) {
   if (!currentFile) throw new Error('No file open');
   const item = path === '/' || !path ? currentFile : currentFile.get(path);
   if (!item) throw new Error('Path not found: ' + path);
   const attrs = item.attrs;
-  return attrs?.[name] || null;
+  const attr = attrs?.[name];
+  return serializeAttrValue(attr);
 }
 
 function getAttrs(path) {
   if (!currentFile) throw new Error('No file open');
   const item = path === '/' || !path ? currentFile : currentFile.get(path);
   if (!item) throw new Error('Path not found: ' + path);
-  return item.attrs || {};
+  const rawAttrs = item.attrs || {};
+  // Serialize all attributes for proper transfer through postMessage
+  const serialized = {};
+  for (const key of Object.keys(rawAttrs)) {
+    serialized[key] = serializeAttrValue(rawAttrs[key]);
+  }
+  return serialized;
 }
 
 function getDatasetMeta(path) {
@@ -1586,7 +1766,7 @@ var StreamingH5File = class {
     await this.send("init", { h5wasmUrl: options?.h5wasmUrl });
   }
   /**
-   * Open a remote HDF5 file for streaming access.
+   * Open a remote HDF5 file for streaming access via URL.
    *
    * @param url - URL to the HDF5 file (must support HTTP range requests)
    * @param options - Optional settings
@@ -1598,6 +1778,51 @@ var StreamingH5File = class {
     this._keys = result.keys || [];
     this._isOpen = true;
   }
+  /**
+   * Open a local File object using WORKERFS (zero-copy).
+   *
+   * @param file - File object from file input or drag-and-drop
+   * @param options - Optional settings
+   */
+  async openLocal(file, options) {
+    await this.init(options);
+    const filename = options?.filenameHint || file.name || "data.h5";
+    const result = await this.send("openLocal", { file, filename });
+    this._keys = result.keys || [];
+    this._isOpen = true;
+  }
+  /**
+   * Open an HDF5 file from an ArrayBuffer or Uint8Array.
+   *
+   * @param buffer - ArrayBuffer or Uint8Array containing the HDF5 file data
+   * @param options - Optional settings
+   */
+  async openBuffer(buffer, options) {
+    await this.init(options);
+    const filename = options?.filenameHint || "data.h5";
+    const data = buffer instanceof Uint8Array ? buffer.buffer : buffer;
+    const result = await this.send("openBuffer", { buffer: data, filename });
+    this._keys = result.keys || [];
+    this._isOpen = true;
+  }
+  /**
+   * Open an HDF5 file from any supported source.
+   *
+   * @param source - URL string, File, ArrayBuffer, or Uint8Array
+   * @param options - Optional settings
+   */
+  async openAny(source, options) {
+    if (typeof source === "string") {
+      return this.open(source, options);
+    }
+    if (typeof File !== "undefined" && source instanceof File) {
+      return this.openLocal(source, options);
+    }
+    if (source instanceof ArrayBuffer || source instanceof Uint8Array) {
+      return this.openBuffer(source, options);
+    }
+    throw new Error("Unsupported source type for StreamingH5File");
+  }
   /**
    * Whether a file is currently open.
    */
@@ -1677,6 +1902,14 @@ async function openStreamingH5(url, options) {
   await file.open(url, options);
   return file;
 }
+async function openH5Worker(source, options) {
+  if (!isStreamingSupported()) {
+    throw new Error("Web Worker HDF5 access requires Worker/Blob/URL support");
+  }
+  const file = new StreamingH5File();
+  await file.openAny(source, options);
+  return file;
+}
 
 // src/codecs/slp/h5.ts
 var isNode = typeof process !== "undefined" && !!process.versions?.node;
@@ -1815,6 +2048,8 @@ function getH5FileSystem(module) {
 
 // src/video/hdf5-video.ts
 var isBrowser4 = typeof window !== "undefined" && typeof document !== "undefined";
+var PNG_MAGIC2 = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+var JPEG_MAGIC2 = new Uint8Array([255, 216, 255]);
 var Hdf5VideoBackend = class {
   filename;
   dataset;
@@ -1822,36 +2057,55 @@ var Hdf5VideoBackend = class {
   fps;
   file;
   datasetPath;
-  frameNumbers;
+  frameNumberToIndex;
   format;
   channelOrder;
   cachedData;
+  frameOffsets;
   constructor(options) {
     this.filename = options.filename;
     this.file = options.file;
     this.datasetPath = options.datasetPath;
     this.dataset = options.datasetPath;
-    this.frameNumbers = options.frameNumbers ?? [];
+    const frameNumbers = options.frameNumbers ?? [];
+    this.frameNumberToIndex = new Map(frameNumbers.map((num, idx) => [num, idx]));
     this.format = options.format ?? "png";
     this.channelOrder = options.channelOrder ?? "RGB";
     this.shape = options.shape;
     this.fps = options.fps;
     this.cachedData = null;
+    this.frameOffsets = null;
   }
   async getFrame(frameIndex) {
     const dataset = this.file.get(this.datasetPath);
     if (!dataset) return null;
-    const index = this.frameNumbers.length ? this.frameNumbers.indexOf(frameIndex) : frameIndex;
-    if (index < 0) return null;
+    const index = this.frameNumberToIndex.size > 0 ? this.frameNumberToIndex.get(frameIndex) : frameIndex;
+    if (index === void 0) return null;
     if (!this.cachedData) {
-      this.cachedData = dataset.value;
+      const value = dataset.value;
+      this.cachedData = normalizeVideoData2(value);
+      if (isContiguousEncodedBuffer2(this.cachedData, this.format, this.shape)) {
+        this.frameOffsets = findEncodedFrameOffsets2(
+          this.cachedData,
+          this.format,
+          this.shape?.[0] ?? 0
+        );
+      }
+    }
+    let rawBytes;
+    if (this.frameOffsets && this.frameOffsets.length > index) {
+      const buffer = this.cachedData;
+      const start = this.frameOffsets[index];
+      const end = index + 1 < this.frameOffsets.length ? this.frameOffsets[index + 1] : buffer.length;
+      rawBytes = buffer.slice(start, end);
+    } else {
+      const entry = this.cachedData[index];
+      if (entry == null) return null;
+      rawBytes = toUint8Array2(entry);
     }
-    const entry = this.cachedData[index];
-    if (entry == null) return null;
-    const rawBytes = toUint8Array2(entry);
-    if (!rawBytes) return null;
+    if (!rawBytes || rawBytes.length === 0) return null;
     if (isEncodedFormat2(this.format)) {
-      const decoded = await decodeImageBytes2(rawBytes, this.format);
+      const decoded = await decodeImageBytes2(rawBytes, this.format, this.channelOrder);
       return decoded ?? rawBytes;
     }
     const image = decodeRawFrame2(rawBytes, this.shape, this.channelOrder);
@@ -1859,8 +2113,55 @@ var Hdf5VideoBackend = class {
   }
   close() {
     this.cachedData = null;
+    this.frameOffsets = null;
   }
 };
+function normalizeVideoData2(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const arr = value;
+    return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
+  }
+  return [];
+}
+function isContiguousEncodedBuffer2(data, format, shape) {
+  if (!isEncodedFormat2(format)) return false;
+  if (!(data instanceof Uint8Array)) return false;
+  if (data.length < 8) return false;
+  const isPng = matchesMagic2(data, PNG_MAGIC2);
+  const isJpeg = matchesMagic2(data, JPEG_MAGIC2);
+  if (!isPng && !isJpeg) return false;
+  if (shape) {
+    const frameCount = shape[0];
+    if (frameCount > 1 && data.length > 1e4) {
+      return true;
+    }
+  }
+  return true;
+}
+function matchesMagic2(buffer, magic) {
+  if (buffer.length < magic.length) return false;
+  for (let i = 0; i < magic.length; i++) {
+    if (buffer[i] !== magic[i]) return false;
+  }
+  return true;
+}
+function findEncodedFrameOffsets2(buffer, format, expectedFrameCount) {
+  const offsets = [];
+  const magic = format.toLowerCase() === "png" ? PNG_MAGIC2 : JPEG_MAGIC2;
+  for (let i = 0; i <= buffer.length - magic.length; i++) {
+    if (matchesMagic2(buffer.subarray(i), magic)) {
+      offsets.push(i);
+      i += magic.length - 1;
+      if (expectedFrameCount > 0 && offsets.length >= expectedFrameCount) {
+        break;
+      }
+    }
+  }
+  return offsets;
+}
 function toUint8Array2(entry) {
   if (entry instanceof Uint8Array) return entry;
   if (entry instanceof ArrayBuffer) return new Uint8Array(entry);
@@ -1873,12 +2174,29 @@ function isEncodedFormat2(format) {
   const normalized = format.toLowerCase();
   return normalized === "png" || normalized === "jpg" || normalized === "jpeg";
 }
-async function decodeImageBytes2(bytes, format) {
+async function decodeImageBytes2(bytes, format, channelOrder) {
   if (!isBrowser4 || typeof createImageBitmap === "undefined") return null;
   const mime = format.toLowerCase() === "png" ? "image/png" : "image/jpeg";
   const safeBytes = new Uint8Array(bytes);
   const blob = new Blob([safeBytes.buffer], { type: mime });
-  return createImageBitmap(blob);
+  const bitmap = await createImageBitmap(blob);
+  const useBgr = channelOrder.toUpperCase() === "BGR";
+  if (!useBgr) {
+    return bitmap;
+  }
+  const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return bitmap;
+  ctx.drawImage(bitmap, 0, 0);
+  const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
+  const data = imageData.data;
+  for (let i = 0; i < data.length; i += 4) {
+    const r = data[i];
+    const b = data[i + 2];
+    data[i] = b;
+    data[i + 2] = r;
+  }
+  return imageData;
 }
 function decodeRawFrame2(bytes, shape, channelOrder) {
   if (!isBrowser4 || !shape) return null;
@@ -1942,7 +2260,7 @@ async function readSlp(source, options) {
     const labelsPath = typeof source === "string" ? source : options?.h5?.filenameHint ?? "slp-data.slp";
     const skeletons = parseSkeletons(metadataJson);
     const tracks = readTracks(file.get("tracks_json"));
-    const videos = await readVideos(file.get("videos_json"), labelsPath, options?.openVideos ?? true, file);
+    const videos = await readVideos(file.get("videos_json"), labelsPath, options?.openVideos ?? true, file, formatId);
     const suggestions = readSuggestions(file.get("suggestions_json"), videos);
     const framesData = normalizeStructDataset(file.get("frames"));
     const instancesData = normalizeStructDataset(file.get("instances"));
@@ -1995,11 +2313,12 @@ function readTracks(dataset) {
   }
   return tracks;
 }
-async function readVideos(dataset, labelsPath, openVideos, file) {
+async function readVideos(dataset, labelsPath, openVideos, file, formatId) {
   if (!dataset) return [];
   const values = dataset.value ?? [];
   const videos = [];
-  for (const entry of values) {
+  for (let videoIndex = 0; videoIndex < values.length; videoIndex++) {
+    const entry = values[videoIndex];
     if (!entry) continue;
     const parsed = typeof entry === "string" ? JSON.parse(entry) : JSON.parse(textDecoder.decode(entry));
     const backendMeta = parsed.backend ?? {};
@@ -2010,14 +2329,26 @@ async function readVideos(dataset, labelsPath, openVideos, file) {
       embedded = true;
       filename = labelsPath;
     }
+    if (embedded && !datasetPath) {
+      datasetPath = findVideoDataset(file, videoIndex);
+    }
+    const channelOrder = backendMeta.channel_order ?? (formatId < 1.4 ? "BGR" : "RGB");
+    let format = backendMeta.format;
+    if (!format && datasetPath) {
+      const videoDs = file.get(datasetPath);
+      if (videoDs) {
+        const attrs = videoDs.attrs ?? {};
+        format = attrs.format?.value ?? attrs.format;
+      }
+    }
     let backend = null;
     if (openVideos) {
       backend = await createVideoBackend(filename, {
         dataset: datasetPath ?? void 0,
         embedded,
         frameNumbers: readFrameNumbers(file, datasetPath),
-        format: backendMeta.format,
-        channelOrder: backendMeta.channel_order,
+        format,
+        channelOrder,
         shape: backendMeta.shape,
         fps: backendMeta.fps
       });
@@ -2029,7 +2360,8 @@ async function readVideos(dataset, labelsPath, openVideos, file) {
         backend,
         backendMetadata: backendMeta,
         sourceVideo,
-        openBackend: openVideos
+        openBackend: openVideos,
+        embedded
       })
     );
   }
@@ -2043,6 +2375,28 @@ function readFrameNumbers(file, datasetPath) {
   const values = frameDataset.value ?? [];
   return Array.from(values).map((v) => Number(v));
 }
+function findVideoDataset(file, videoIndex) {
+  const explicitPath = `video${videoIndex}/video`;
+  if (file.get(explicitPath)) {
+    return explicitPath;
+  }
+  const keys = file.keys?.() ?? [];
+  for (const key of keys) {
+    if (key.startsWith("video")) {
+      const candidatePath = `${key}/video`;
+      if (file.get(candidatePath)) {
+        if (videoIndex === 0) {
+          return candidatePath;
+        }
+        const keyIndex = parseInt(key.slice(5), 10);
+        if (!isNaN(keyIndex) && keyIndex === videoIndex) {
+          return candidatePath;
+        }
+      }
+    }
+  }
+  return null;
+}
 function readSuggestions(dataset, videos) {
   if (!dataset) return [];
   const values = dataset.value ?? [];
@@ -2322,17 +2676,18 @@ function slicePoints(data, start, end, predicted = false) {
 }
 
 // src/codecs/slp/read-streaming.ts
-async function readSlpStreaming(url, options) {
+async function readSlpStreaming(source, options) {
   if (!isStreamingSupported()) {
     throw new Error("Streaming HDF5 requires Web Worker support (browser environment)");
   }
-  const file = await openStreamingH5(url, {
+  const file = await openH5Worker(source, {
     h5wasmUrl: options?.h5wasmUrl,
     filenameHint: options?.filenameHint
   });
   const openVideos = options?.openVideos ?? false;
+  const sourcePath = typeof source === "string" ? source : typeof File !== "undefined" && source instanceof File ? source.name : options?.filenameHint ?? "slp-data.slp";
   try {
-    return await readFromStreamingFile(file, url, options?.filenameHint, openVideos);
+    return await readFromStreamingFile(file, sourcePath, options?.filenameHint, openVideos);
   } finally {
     if (!openVideos) {
       await file.close();
@@ -2348,7 +2703,7 @@ async function readFromStreamingFile(file, url, filenameHint, openVideos = false
   const labelsPath = filenameHint ?? url.split("/").pop()?.split("?")[0] ?? "slp-data.slp";
   const skeletons = parseSkeletons(metadataJson);
   const tracks = await readTracksStreaming(file);
-  const videos = await readVideosStreaming(file, labelsPath, openVideos);
+  const videos = await readVideosStreaming(file, labelsPath, openVideos, formatId);
   const suggestions = await readSuggestionsStreaming(file, videos);
   const framesData = await readStructDatasetStreaming(file, "frames");
   const instancesData = await readStructDatasetStreaming(file, "instances");
@@ -2386,45 +2741,123 @@ async function readTracksStreaming(file) {
     return [];
   }
 }
-async function readVideosStreaming(file, labelsPath, openVideos = false) {
+async function readVideosStreaming(file, labelsPath, openVideos = false, formatId = 1) {
   try {
     const keys = file.keys();
     if (!keys.includes("videos_json")) return [];
     const data = await file.getDatasetValue("videos_json");
     const values = normalizeDatasetArray(data.value);
     const metadataList = parseVideosMetadata(values, labelsPath);
-    return metadataList.map((meta) => {
+    const videos = [];
+    for (let videoIndex = 0; videoIndex < metadataList.length; videoIndex++) {
+      const meta = metadataList[videoIndex];
       const shape = meta.frameCount && meta.height && meta.width && meta.channels ? [meta.frameCount, meta.height, meta.width, meta.channels] : void 0;
+      let datasetPath = meta.dataset;
+      if (meta.embedded && !datasetPath) {
+        datasetPath = await findVideoDatasetStreaming(file, videoIndex) ?? void 0;
+      }
+      const channelOrder = meta.channelOrder ?? (formatId < 1.4 ? "BGR" : "RGB");
+      let format = meta.format;
+      if (!format && datasetPath) {
+        try {
+          const attrs = await file.getAttrs(datasetPath);
+          const formatAttr = attrs.format;
+          if (formatAttr) {
+            format = typeof formatAttr === "string" ? formatAttr : formatAttr?.value;
+          }
+        } catch {
+        }
+      }
       let backend = null;
-      if (openVideos && meta.embedded && meta.dataset) {
+      if (openVideos && meta.embedded && datasetPath) {
+        const frameNumbers = await readFrameNumbersStreaming(file, datasetPath);
         backend = new StreamingHdf5VideoBackend({
           filename: meta.filename,
           h5file: file,
-          datasetPath: meta.dataset,
-          format: meta.format ?? "png",
-          channelOrder: meta.channelOrder ?? "RGB",
+          datasetPath,
+          frameNumbers,
+          format: format ?? "png",
+          channelOrder,
           shape,
           fps: meta.fps
         });
       }
-      return new Video({
+      videos.push(new Video({
         filename: meta.filename,
         backend,
         backendMetadata: {
-          dataset: meta.dataset,
-          format: meta.format,
+          dataset: datasetPath,
+          format,
           shape,
           fps: meta.fps,
-          channel_order: meta.channelOrder
+          channel_order: channelOrder
         },
         sourceVideo: meta.sourceVideo ? new Video({ filename: meta.sourceVideo.filename }) : null,
-        openBackend: openVideos && meta.embedded
-      });
-    });
+        openBackend: openVideos && meta.embedded,
+        embedded: meta.embedded
+      }));
+    }
+    return videos;
   } catch {
     return [];
   }
 }
+async function readFrameNumbersStreaming(file, datasetPath) {
+  try {
+    const groupPath = datasetPath.endsWith("/video") ? datasetPath.slice(0, -6) : datasetPath;
+    const frameNumbersPath = `${groupPath}/frame_numbers`;
+    const groupKeys = await file.getKeys(groupPath);
+    if (!groupKeys.includes("frame_numbers")) {
+      return [];
+    }
+    const data = await file.getDatasetValue(frameNumbersPath);
+    const values = data.value;
+    if (Array.isArray(values)) {
+      return values.map((v) => Number(v));
+    }
+    if (ArrayBuffer.isView(values)) {
+      return Array.from(values).map(Number);
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+async function findVideoDatasetStreaming(file, videoIndex) {
+  try {
+    const explicitPath = `video${videoIndex}/video`;
+    const explicitGroupPath = `video${videoIndex}`;
+    try {
+      const groupKeys = await file.getKeys(explicitGroupPath);
+      if (groupKeys.includes("video")) {
+        return explicitPath;
+      }
+    } catch {
+    }
+    const rootKeys = file.keys();
+    for (const key of rootKeys) {
+      if (key.startsWith("video")) {
+        try {
+          const groupKeys = await file.getKeys(key);
+          if (groupKeys.includes("video")) {
+            const candidatePath = `${key}/video`;
+            if (videoIndex === 0) {
+              return candidatePath;
+            }
+            const keyIndex = parseInt(key.slice(5), 10);
+            if (!isNaN(keyIndex) && keyIndex === videoIndex) {
+              return candidatePath;
+            }
+          }
+        } catch {
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function readSuggestionsStreaming(file, videos) {
   try {
     const keys = file.keys();
@@ -2936,29 +3369,44 @@ function createMatrixDataset(file, name, rows, fieldNames, dtype) {
 }
 
 // src/io/main.ts
-function isProbablyUrl2(source) {
-  return typeof source === "string" && /^https?:\/\//i.test(source);
+function isNode3() {
+  return typeof process !== "undefined" && !!process.versions?.node;
 }
-function isBrowser5() {
-  return typeof window !== "undefined" && typeof Worker !== "undefined";
+function isBrowserWithWorkerSupport() {
+  return typeof window !== "undefined" && isStreamingSupported();
 }
 async function loadSlp(source, options) {
   const streamMode = options?.h5?.stream ?? "auto";
-  if (isProbablyUrl2(source) && isBrowser5() && isStreamingSupported() && (streamMode === "range" || streamMode === "auto")) {
-    try {
-      return await readSlpStreaming(source, {
-        filenameHint: options?.h5?.filenameHint,
-        openVideos: options?.openVideos ?? true
-      });
-    } catch (e) {
-      if (streamMode === "auto") {
-        console.warn("Streaming failed, falling back to full download:", e);
-      } else {
-        throw e;
+  const openVideos = options?.openVideos ?? true;
+  if (isBrowserWithWorkerSupport() && !isNode3() && streamMode !== "download") {
+    let streamingSource;
+    if (typeof source === "string") {
+      streamingSource = source;
+    } else if (source instanceof ArrayBuffer || source instanceof Uint8Array) {
+      streamingSource = source;
+    } else if (typeof File !== "undefined" && source instanceof File) {
+      streamingSource = source;
+    } else if (typeof FileSystemFileHandle !== "undefined" && "getFile" in source) {
+      streamingSource = await source.getFile();
+    } else {
+      streamingSource = null;
+    }
+    if (streamingSource !== null) {
+      try {
+        return await readSlpStreaming(streamingSource, {
+          filenameHint: options?.h5?.filenameHint,
+          openVideos
+        });
+      } catch (e) {
+        if (streamMode === "auto") {
+          console.warn("[sleap-io] Worker-based loading failed, falling back to main thread:", e);
+        } else {
+          throw e;
+        }
       }
     }
   }
-  return readSlp(source, { openVideos: options?.openVideos ?? true, h5: options?.h5 });
+  return readSlp(source, { openVideos, h5: options?.h5 });
 }
 async function saveSlp(labels, filename, options) {
   await writeSlp(filename, labels, {
@@ -3850,6 +4298,7 @@ export {
   loadSlp,
   loadVideo,
   makeCameraFromDict,
+  openH5Worker,
   openStreamingH5,
   pointsEmpty,
   pointsFromArray,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talmolab/sleap-io.js",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "private": false,
   "type": "module",
   "exports": {