libbitsub 1.0.0

package/README.md

@@ -0,0 +1,355 @@
+# libbit(map)sub
+
+High-performance WASM renderer for graphical subtitles (PGS and VobSub), written in Rust.
+
+Started as a fork of Arcus92's [libpgs-js](https://github.com/Arcus92/libpgs-js), this project is re-engineered to maximize performance and extend functionality to VobSub, which was not supported by the original library. It remains fully backward compatible (only for PGS - obliviously). Special thanks to the original project for the inspiration!
+
+## Features
+
+- **PGS (Blu-ray)** subtitle parsing and rendering
+- **VobSub (DVD)** subtitle parsing and rendering
+- **High-performance** Rust-based rendering engine compiled to WebAssembly
+- **Zero-copy** data transfer between JS and WASM where possible
+- **Caching** for decoded bitmaps to optimize repeated rendering
+- **TypeScript** support with full type definitions
+
+## Showcase
+
+### PGS (Created using Spp2Pgs)
+
+https://gist.github.com/user-attachments/assets/55ac8e11-1964-4fb9-923e-dcac82dc7703
+
+### Vobsub
+
+https://gist.github.com/user-attachments/assets/a89ae9fe-23e4-4bc3-8cad-16a3f0fea665
+
+## Installation
+
+```bash
+bun add libbitsub
+```
+
+### Setup for Web Workers (Recommended)
+
+For best performance with large subtitle files, copy the WASM files to your public folder so Web Workers can access them:
+
+```bash
+# For Next.js, Vite, or similar frameworks
+mkdir -p public/libbitsub
+cp node_modules/libbitsub/pkg/libbitsub_bg.wasm public/libbitsub/
+cp node_modules/libbitsub/pkg/libbitsub.js public/libbitsub/
+```
+
+This enables off-main-thread parsing which prevents UI freezing when loading large PGS files.
+
+## Prerequisites
+
+To build from source, you need:
+
+- [Rust](https://rustup.rs/) (1.70+)
+- [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/)
+
+```bash
+# Install wasm-pack
+cargo install wasm-pack
+```
+
+## Building
+
+```bash
+# Build WASM module and TypeScript wrapper
+bun run build
+
+# Build WASM only (for development)
+bun run build:wasm
+
+# Build release version (optimized)
+bun run build:wasm:release
+```
+
+## Usage
+
+### Initialize WASM
+
+Before using any renderer, you must initialize the WASM module:
+
+```typescript
+import { initWasm } from 'libbitsub'
+
+// Initialize WASM (do this once at app startup)
+await initWasm()
+```
+
+## High-Level API (Video Integration)
+
+The high-level API automatically handles video synchronization, canvas overlay, and subtitle fetching.
+
+### PGS Subtitles (Video-Integrated)
+
+```typescript
+import { PgsRenderer } from 'libbitsub'
+
+// Create renderer with video element
+const renderer = new PgsRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/movie.sup',
+  workerUrl: '/libbitsub.js', // Optional, kept for API compatibility
+  // Lifecycle callbacks (optional)
+  onLoading: () => console.log('Loading subtitles...'),
+  onLoaded: () => console.log('Subtitles loaded!'),
+  onError: (error) => console.error('Failed to load:', error)
+})
+
+// The renderer automatically:
+// - Fetches the subtitle file
+// - Creates a canvas overlay on the video
+// - Syncs rendering with video playback
+// - Handles resize events
+
+// When done:
+renderer.dispose()
+```
+
+### VobSub Subtitles (Video-Integrated)
+
+```typescript
+import { VobSubRenderer } from 'libbitsub'
+
+// Create renderer with video element
+const renderer = new VobSubRenderer({
+  video: videoElement,
+  subUrl: '/subtitles/movie.sub',
+  idxUrl: '/subtitles/movie.idx', // Optional, defaults to .sub path with .idx extension
+  workerUrl: '/libbitsub.js', // Optional
+  // Lifecycle callbacks (optional)
+  onLoading: () => setIsLoading(true),
+  onLoaded: () => setIsLoading(false),
+  onError: (error) => {
+    setIsLoading(false)
+    console.error('Subtitle error:', error)
+  }
+})
+
+// When done:
+renderer.dispose()
+```
+
+### Subtitle Display Settings
+
+Both `PgsRenderer` and `VobSubRenderer` support real-time customization of subtitle size and position:
+
+```typescript
+// Get current settings
+const settings = renderer.getDisplaySettings()
+console.log(settings)
+// Output: { scale: 1.0, verticalOffset: 0 }
+
+// Update settings
+renderer.setDisplaySettings({
+  scale: 1.2, // 1.2 = 120% size
+  verticalOffset: -10 // -10% (move up 10% of video height)
+})
+
+// Reset to defaults
+renderer.resetDisplaySettings()
+```
+
+**Settings Reference:**
+
+- `scale` (number): Scale factor for subtitles.
+  - `1.0` = 100% (Original size)
+  - `0.5` = 50%
+  - `2.0` = 200%
+  - Range: `0.1` to `3.0`
+
+- `verticalOffset` (number): Vertical position offset as a percentage of video height.
+  - `0` = Original position
+  - Negative values move up (e.g., `-10` moves up by 10% of height)
+  - Positive values move down (e.g., `10` moves down by 10% of height)
+  - Range: `-50` to `50`
+
+## Low-Level API (Programmatic Use)
+
+For more control over rendering, use the low-level parsers directly.
+
+### PGS Subtitles (Low-Level)
+
+```typescript
+import { initWasm, PgsParser } from 'libbitsub'
+
+await initWasm()
+
+const parser = new PgsParser()
+
+// Load PGS data from a .sup file
+const response = await fetch('subtitles.sup')
+const data = new Uint8Array(await response.arrayBuffer())
+parser.load(data)
+
+// Get timestamps
+const timestamps = parser.getTimestamps() // Float64Array in milliseconds
+
+// Render at a specific time
+const subtitleData = parser.renderAtTimestamp(currentTimeInSeconds)
+if (subtitleData) {
+  for (const comp of subtitleData.compositionData) {
+    ctx.putImageData(comp.pixelData, comp.x, comp.y)
+  }
+}
+
+// Clean up
+parser.dispose()
+```
+
+### VobSub Subtitles (Low-Level)
+
+```typescript
+import { initWasm, VobSubParserLowLevel } from 'libbitsub'
+
+await initWasm()
+
+const parser = new VobSubParserLowLevel()
+
+// Load from IDX + SUB files
+const idxResponse = await fetch('subtitles.idx')
+const idxContent = await idxResponse.text()
+const subResponse = await fetch('subtitles.sub')
+const subData = new Uint8Array(await subResponse.arrayBuffer())
+
+parser.loadFromData(idxContent, subData)
+
+// Or load from SUB file only
+// parser.loadFromSubOnly(subData);
+
+// Render
+const subtitleData = parser.renderAtTimestamp(currentTimeInSeconds)
+if (subtitleData) {
+  for (const comp of subtitleData.compositionData) {
+    ctx.putImageData(comp.pixelData, comp.x, comp.y)
+  }
+}
+
+parser.dispose()
+```
+
+### Unified Parser
+
+For handling both formats with a single API:
+
+```typescript
+import { initWasm, UnifiedSubtitleParser } from 'libbitsub'
+
+await initWasm()
+
+const parser = new UnifiedSubtitleParser()
+
+// Load PGS
+parser.loadPgs(pgsData)
+
+// Or load VobSub
+// parser.loadVobSub(idxContent, subData);
+
+console.log(parser.format) // 'pgs' or 'vobsub'
+
+const subtitleData = parser.renderAtTimestamp(time)
+// ... render to canvas
+
+parser.dispose()
+```
+
+## API Reference
+
+### High-Level (Video-Integrated)
+
+#### `PgsRenderer`
+
+- `constructor(options: VideoSubtitleOptions)` - Create video-integrated PGS renderer
+- `getDisplaySettings(): SubtitleDisplaySettings` - Get current display settings
+- `setDisplaySettings(settings: Partial<SubtitleDisplaySettings>): void` - Update display settings
+- `resetDisplaySettings(): void` - Reset display settings to defaults
+- `dispose(): void` - Clean up all resources
+
+#### `VobSubRenderer`
+
+- `constructor(options: VideoVobSubOptions)` - Create video-integrated VobSub renderer
+- `getDisplaySettings(): SubtitleDisplaySettings` - Get current display settings
+- `setDisplaySettings(settings: Partial<SubtitleDisplaySettings>): void` - Update display settings
+- `resetDisplaySettings(): void` - Reset display settings to defaults
+- `dispose(): void` - Clean up all resources
+
+### Low-Level (Programmatic)
+
+#### `PgsParser`
+
+- `load(data: Uint8Array): number` - Load PGS data, returns display set count
+- `getTimestamps(): Float64Array` - Get all timestamps in milliseconds
+- `count: number` - Number of display sets
+- `findIndexAtTimestamp(timeSeconds: number): number` - Find index for timestamp
+- `renderAtIndex(index: number): SubtitleData | undefined` - Render at index
+- `renderAtTimestamp(timeSeconds: number): SubtitleData | undefined` - Render at time
+- `clearCache(): void` - Clear decoded bitmap cache
+- `dispose(): void` - Release resources
+
+#### `VobSubParserLowLevel`
+
+- `loadFromData(idxContent: string, subData: Uint8Array): void` - Load IDX + SUB
+- `loadFromSubOnly(subData: Uint8Array): void` - Load SUB only
+- Same rendering methods as PgsParser
+
+#### `UnifiedSubtitleParser`
+
+- `loadPgs(data: Uint8Array): number` - Load PGS data
+- `loadVobSub(idxContent: string, subData: Uint8Array): void` - Load VobSub
+- `loadVobSubOnly(subData: Uint8Array): void` - Load SUB only
+- `format: 'pgs' | 'vobsub' | null` - Current format
+- Same rendering methods as above
+
+### Types
+
+#### `VideoSubtitleOptions`
+
+```typescript
+interface VideoSubtitleOptions {
+  video: HTMLVideoElement // Video element to sync with
+  subUrl: string // URL to subtitle file
+  workerUrl?: string // Worker URL (for API compatibility)
+  onLoading?: () => void // Called when subtitle loading starts
+  onLoaded?: () => void // Called when subtitle loading completes
+  onError?: (error: Error) => void // Called when subtitle loading fails
+}
+```
+
+#### `VideoVobSubOptions`
+
+```typescript
+interface VideoVobSubOptions extends VideoSubtitleOptions {
+  idxUrl?: string // URL to .idx file (optional)
+}
+```
+
+#### `SubtitleDisplaySettings`
+
+```typescript
+interface SubtitleDisplaySettings {
+  // Scale factor (1.0 = 100%, 0.5 = 50%, 2.0 = 200%)
+  scale: number
+  // Vertical offset as % of video height (-50 to 50)
+  verticalOffset: number
+}
+```
+
+#### `SubtitleData`
+
+```typescript
+interface SubtitleData {
+  width: number // Screen width
+  height: number // Screen height
+  compositionData: SubtitleCompositionData[]
+}
+
+interface SubtitleCompositionData {
+  pixelData: ImageData // RGBA pixel data
+  x: number // X position
+  y: number // Y position
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * libbitsub - High-performance WASM renderer for graphical subtitles
+ *
+ * @packageDocumentation
+ */
+export { PgsRenderer, VobSubRenderer, type VideoSubtitleOptions, type VideoVobSubOptions, type SubtitleRendererStats } from './wrapper';
+export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser } from './wrapper';
+export { initWasm, isWasmInitialized, type SubtitleData, type SubtitleCompositionData, type SubtitleDisplaySettings } from './wrapper';
+export type { RenderResult, SubtitleFrame, VobSubFrame } from './wrapper';
+export { PGSRenderer, VobsubRenderer, UnifiedSubtitleRenderer } from './wrapper';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,WAAW,EACX,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC3B,MAAM,WAAW,CAAA;AAGlB,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAGlF,OAAO,EACL,QAAQ,EACR,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC7B,MAAM,WAAW,CAAA;AAGlB,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAGzE,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * libbitsub - High-performance WASM renderer for graphical subtitles
+ *
+ * @packageDocumentation
+ */
+// High-level video-integrated renderers (compatible with old libpgs-js API)
+export { PgsRenderer, VobSubRenderer } from './wrapper';
+// Low-level parsers for programmatic use
+export { PgsParser, VobSubParserLowLevel, UnifiedSubtitleParser } from './wrapper';
+// Utility exports
+export { initWasm, isWasmInitialized } from './wrapper';
+// Legacy aliases
+export { PGSRenderer, VobsubRenderer, UnifiedSubtitleRenderer } from './wrapper';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4EAA4E;AAC5E,OAAO,EACL,WAAW,EACX,cAAc,EAIf,MAAM,WAAW,CAAA;AAElB,yCAAyC;AACzC,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAA;AAElF,kBAAkB;AAClB,OAAO,EACL,QAAQ,EACR,iBAAiB,EAIlB,MAAM,WAAW,CAAA;AAKlB,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA"}

package/dist/ts/parsers.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Low-level subtitle parsers for libbitsub.
+ * Use these for programmatic access to subtitle data without video integration.
+ */
+import type { SubtitleData } from './types';
+/**
+ * Low-level PGS subtitle parser using WASM.
+ * Use this for programmatic access to PGS data without video integration.
+ */
+export declare class PgsParser {
+    private parser;
+    private timestamps;
+    constructor();
+    /**
+     * Load PGS subtitle data from a Uint8Array.
+     */
+    load(data: Uint8Array): number;
+    /**
+     * Get all timestamps in milliseconds.
+     */
+    getTimestamps(): Float64Array;
+    /**
+     * Get the number of display sets.
+     */
+    get count(): number;
+    /**
+     * Find the display set index for a given timestamp in seconds.
+     */
+    findIndexAtTimestamp(timeSeconds: number): number;
+    /**
+     * Render subtitle at the given index.
+     */
+    renderAtIndex(index: number): SubtitleData | undefined;
+    /**
+     * Render subtitle at the given timestamp in seconds.
+     */
+    renderAtTimestamp(timeSeconds: number): SubtitleData | undefined;
+    /**
+     * Convert WASM frame to SubtitleData.
+     */
+    private convertFrame;
+    /**
+     * Clear internal caches.
+     */
+    clearCache(): void;
+    /**
+     * Dispose of resources.
+     */
+    dispose(): void;
+}
+/**
+ * Low-level VobSub subtitle parser using WASM.
+ * Use this for programmatic access to VobSub data without video integration.
+ */
+export declare class VobSubParserLowLevel {
+    private parser;
+    private timestamps;
+    constructor();
+    /**
+     * Load VobSub from IDX and SUB data.
+     */
+    loadFromData(idxContent: string, subData: Uint8Array): void;
+    /**
+     * Load VobSub from SUB file only.
+     */
+    loadFromSubOnly(subData: Uint8Array): void;
+    /**
+     * Get all timestamps in milliseconds.
+     */
+    getTimestamps(): Float64Array;
+    /**
+     * Get the number of subtitle entries.
+     */
+    get count(): number;
+    /**
+     * Find the subtitle index for a given timestamp in seconds.
+     */
+    findIndexAtTimestamp(timeSeconds: number): number;
+    /**
+     * Render subtitle at the given index.
+     */
+    renderAtIndex(index: number): SubtitleData | undefined;
+    /**
+     * Render subtitle at the given timestamp in seconds.
+     */
+    renderAtTimestamp(timeSeconds: number): SubtitleData | undefined;
+    /**
+     * Convert WASM frame to SubtitleData.
+     */
+    private convertFrame;
+    /**
+     * Clear internal caches.
+     */
+    clearCache(): void;
+    /**
+     * Dispose of resources.
+     */
+    dispose(): void;
+}
+/**
+ * Unified subtitle parser that handles both PGS and VobSub formats.
+ */
+export declare class UnifiedSubtitleParser {
+    private renderer;
+    private timestamps;
+    constructor();
+    /**
+     * Load PGS subtitle data.
+     */
+    loadPgs(data: Uint8Array): number;
+    /**
+     * Load VobSub from IDX and SUB data.
+     */
+    loadVobSub(idxContent: string, subData: Uint8Array): void;
+    /**
+     * Load VobSub from SUB file only.
+     */
+    loadVobSubOnly(subData: Uint8Array): void;
+    /**
+     * Get the current subtitle format.
+     */
+    get format(): 'pgs' | 'vobsub' | null;
+    /**
+     * Get all timestamps in milliseconds.
+     */
+    getTimestamps(): Float64Array;
+    /**
+     * Get the number of subtitle entries.
+     */
+    get count(): number;
+    /**
+     * Find the subtitle index for a given timestamp in seconds.
+     */
+    findIndexAtTimestamp(timeSeconds: number): number;
+    /**
+     * Render subtitle at the given index.
+     */
+    renderAtIndex(index: number): SubtitleData | undefined;
+    /**
+     * Render subtitle at the given timestamp in seconds.
+     */
+    renderAtTimestamp(timeSeconds: number): SubtitleData | undefined;
+    /**
+     * Convert WASM result to SubtitleData.
+     */
+    private convertResult;
+    /**
+     * Clear internal caches.
+     */
+    clearCache(): void;
+    /**
+     * Dispose of resources.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=parsers.d.ts.map

package/dist/ts/parsers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parsers.d.ts","sourceRoot":"","sources":["../../src/ts/parsers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,YAAY,EAQb,MAAM,SAAS,CAAA;AAGhB;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,UAAU,CAAoC;;IAOtD;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IAO9B;;OAEG;IACH,aAAa,IAAI,YAAY;IAI7B;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAKjD;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAStD;;OAEG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAMhE;;OAEG;IACH,OAAO,CAAC,YAAY;IAsCpB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,OAAO,IAAI,IAAI;CAKhB;AAED;;;GAGG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,UAAU,CAAoC;;IAOtD;;OAEG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAM3D;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAM1C;;OAEG;IACH,aAAa,IAAI,YAAY;IAI7B;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAKjD;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAStD;;OAEG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAMhE;;OAEG;IACH,OAAO,CAAC,YAAY;IAmCpB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,OAAO,IAAI,IAAI;CAKhB;AAED;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,UAAU,CAAoC;;IAOtD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;IAOjC;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAMzD;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAMzC;;OAEG;IACH,IAAI,MAAM,IAAI,KAAK,GAAG,QAAQ,GAAG,IAAI,CAKpC;IAED;;OAEG;IACH,aAAa,IAAI,YAAY;IAI7B;;OAEG;IACH,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;OAEG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAKjD;;OAEG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAStD;;OAEG;IACH,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAShE;;OAEG;IACH,OAAO,CAAC,aAAa;IAkCrB;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACH,OAAO,IAAI,IAAI;CAMhB"}