sleap-io.js

JavaScript/TypeScript utilities for reading and writing SLEAP .slp files with streaming-friendly access patterns and a lightweight data model. This is the JS companion to the Python library at https://github.com/talmolab/sleap-io.

Intent

• Make SLP parsing available in browsers and serverless runtimes.
• Support streaming-first workflows for large .slp/.pkg.slp files.
• Provide a minimal data model and codecs that mirror sleap-io behavior.
• Enable client-side visualization and analysis pipelines.

Features

• SLP read/write with format compatibility (format 1.0–1.7, including embedded frames via HDF5 video datasets).
• Browser-compatible SLP writing via saveSlpToBytes().
• Streaming-friendly file access (URL, File, FileSystemFileHandle, Blob).
• Core data model (Labels, LabeledFrame, Instance, Skeleton, Video, etc.).
• ROI, segmentation mask, and bounding box annotations with GeoJSON I/O.
• Video backends accept string, File, or Blob sources.
• Browser-safe: Node.js-only dependencies (skia-canvas, child_process) are dynamically imported, so bundlers can tree-shake them.
• Dictionary and numpy codecs for interchange.
• Demo app for quick inspection.

Quickstart

npm install
npm run build

Load and save SLP

import { loadSlp, saveSlp, saveSlpToBytes } from "sleap-io.js";

const labels = await loadSlp("/path/to/session.slp", { openVideos: false });

// Save to file (Node.js/Electron)
await saveSlp(labels, "/tmp/session-roundtrip.slp", { embed: false });

// Save to bytes (works in browsers too)
const bytes: Uint8Array = await saveSlpToBytes(labels);

Load video

import { loadVideo, Mp4BoxVideoBackend } from "sleap-io.js";

// From file path (Node.js) or URL (browser)
const video = await loadVideo("/path/to/video.mp4", { openBackend: false });
video.close();

// Mp4BoxVideoBackend also accepts File or Blob (browser)
const backend = new Mp4BoxVideoBackend(file); // File or Blob

Lite mode (Workers-compatible)

For environments that don't support WebAssembly compilation (e.g., Cloudflare Workers), use the /lite entry point:

import { loadSlpMetadata, validateSlpBuffer } from "@talmolab/sleap-io.js/lite";

// Load metadata without pose coordinates
const metadata = await loadSlpMetadata(buffer);
console.log(metadata.skeletons);     // Full skeleton definitions
console.log(metadata.counts);        // { labeledFrames, instances, points, predictedPoints }
console.log(metadata.provenance);    // { sleap_version, ... }

// Quick validation
validateSlpBuffer(buffer);  // throws on invalid

The lite module uses jsfive (pure JavaScript) instead of h5wasm (WebAssembly), enabling use in restricted environments. It can read all metadata but not pose coordinates or video frames.

Architecture

• I/O layer: loadSlp/saveSlp wrap the HDF5 reader/writer in src/codecs/slp.
• Data model: src/model mirrors sleap-io classes and supports numpy/dict codecs.
• Backends: src/video provides browser media and embedded HDF5 decoding.
• Streaming: src/codecs/slp/h5.ts selects URL/File/FS handle strategies.

Environments and Streaming

• Env1 (Static SPA): Browser-only usage with URL streaming (CORS + Range) or the File System Access API.
• Env2 (Server/Worker): Server-side or worker environments that stream .slp from URLs or byte buffers.
• Env3 (Local Node/Electron): Optional local filesystem access for Node/Electron.

Streaming can be tuned with:

await loadSlp(url, { h5: { stream: "auto", filenameHint: "session.slp" } });

Demo

The demo in demo/ loads the built package from dist/. Build first, then serve the repo with a static server and open demo/index.html:

npm run build

Release & Publishing

This package uses npm Trusted Publishing. The first publish must be done manually to unlock the npm package settings:

1. First-time publish (one-time):

npm login
npm publish --access public

2. Enable Trusted Publisher at https://www.npmjs.com/package/@talmolab/sleap-io.js/access.

After that, GitHub Releases trigger the publish workflow automatically.

Links

• Python sleap-io: https://github.com/talmolab/sleap-io
• Docs: https://io.sleap.ai