libbitsub 1.10.2 → 1.11.0

package/src/integrations/shared.ts

@@ -0,0 +1,170 @@
+/**
+ * Shared player-integration helpers for libbitsub.
+ * Optional adapters build on this surface so the core package stays dependency-free.
+ */
+
+import {
+  createAutoSubtitleRenderer,
+  type AutoVideoSubtitleOptions,
+  type PgsRenderer,
+  type SubtitleDisplaySettings,
+  type SubtitleRendererStats,
+  type VobSubRenderer
+} from '../wrapper'
+
+/** High-level renderer produced by integrations. */
+export type BitSubRenderer = PgsRenderer | VobSubRenderer
+
+/** Subtitle source + renderer options without a bound video element. */
+export type BitSubSourceOptions = Omit<AutoVideoSubtitleOptions, 'video'>
+
+export interface BitSubController {
+  /** Active renderer, or null when no track is loaded. */
+  readonly renderer: BitSubRenderer | null
+  /** Currently bound video element. */
+  readonly video: HTMLVideoElement | null
+  /** Load or replace the active subtitle track. */
+  load(source: BitSubSourceOptions): BitSubRenderer
+  /** Remove the active track without disposing the controller. */
+  clear(): void
+  /** Tear down the renderer and release the controller. */
+  dispose(): void
+  /** Whether {@link dispose} has already been called. */
+  readonly disposed: boolean
+  getDisplaySettings(): SubtitleDisplaySettings | null
+  setDisplaySettings(settings: Partial<SubtitleDisplaySettings>): void
+  resetDisplaySettings(): void
+  getStats(): SubtitleRendererStats | null
+  /** Rebind to another video element, keeping the last source when present. */
+  setVideo(video: HTMLVideoElement | null): void
+}
+
+export interface AttachBitSubOptions extends BitSubSourceOptions {
+  /** When false, skip the initial load even if source fields are present. Default true. */
+  autoLoad?: boolean
+}
+
+function hasSubtitleSource(source: BitSubSourceOptions | undefined): boolean {
+  if (!source) return false
+  return Boolean(source.subUrl || source.subContent || source.idxUrl || source.idxContent || source.fileName)
+}
+
+function assertVideo(video: HTMLVideoElement | null | undefined): HTMLVideoElement {
+  if (!video) {
+    throw new Error('libbitsub integration requires an HTMLVideoElement')
+  }
+  return video
+}
+
+/**
+ * Attach a disposable controller to a video element.
+ * Call {@link BitSubController.load} to start a track, or pass source fields to auto-load.
+ */
+export function attachBitSub(video: HTMLVideoElement, options: AttachBitSubOptions = {}): BitSubController {
+  const { autoLoad = true, ...initialSource } = options
+  let disposed = false
+  let boundVideo: HTMLVideoElement | null = video
+  let renderer: BitSubRenderer | null = null
+  let lastSource: BitSubSourceOptions | null = hasSubtitleSource(initialSource) ? { ...initialSource } : null
+
+  const clearRenderer = (): void => {
+    if (!renderer) return
+    renderer.dispose()
+    renderer = null
+  }
+
+  const controller: BitSubController = {
+    get renderer() {
+      return renderer
+    },
+    get video() {
+      return boundVideo
+    },
+    get disposed() {
+      return disposed
+    },
+    load(source: BitSubSourceOptions): BitSubRenderer {
+      if (disposed) {
+        throw new Error('BitSubController has been disposed')
+      }
+      const activeVideo = assertVideo(boundVideo)
+      if (!hasSubtitleSource(source)) {
+        throw new Error('BitSubController.load requires subUrl, subContent, or a detectable fileName')
+      }
+
+      clearRenderer()
+      lastSource = { ...source }
+      renderer = createAutoSubtitleRenderer({
+        ...source,
+        video: activeVideo
+      })
+      return renderer
+    },
+    clear(): void {
+      if (disposed) return
+      clearRenderer()
+      lastSource = null
+    },
+    dispose(): void {
+      if (disposed) return
+      disposed = true
+      clearRenderer()
+      lastSource = null
+      boundVideo = null
+    },
+    getDisplaySettings(): SubtitleDisplaySettings | null {
+      return renderer?.getDisplaySettings() ?? null
+    },
+    setDisplaySettings(settings: Partial<SubtitleDisplaySettings>): void {
+      renderer?.setDisplaySettings(settings)
+    },
+    resetDisplaySettings(): void {
+      renderer?.resetDisplaySettings()
+    },
+    getStats(): SubtitleRendererStats | null {
+      return renderer?.getStats() ?? null
+    },
+    setVideo(nextVideo: HTMLVideoElement | null): void {
+      if (disposed) {
+        throw new Error('BitSubController has been disposed')
+      }
+
+      if (nextVideo === boundVideo) {
+        // Same element: still materialize a pending source (e.g. delayed autoLoad).
+        if (nextVideo && !renderer && lastSource) {
+          renderer = createAutoSubtitleRenderer({
+            ...lastSource,
+            video: nextVideo
+          })
+        }
+        return
+      }
+
+      const previousSource = lastSource
+      clearRenderer()
+      boundVideo = nextVideo
+
+      if (nextVideo && previousSource) {
+        lastSource = previousSource
+        renderer = createAutoSubtitleRenderer({
+          ...previousSource,
+          video: nextVideo
+        })
+      }
+    }
+  }
+
+  if (autoLoad && lastSource) {
+    controller.load(lastSource)
+  }
+
+  return controller
+}
+
+/** Convenience one-shot helper used by thin player wrappers. */
+export function createBitSubRenderer(video: HTMLVideoElement, source: BitSubSourceOptions): BitSubRenderer {
+  return createAutoSubtitleRenderer({
+    ...source,
+    video: assertVideo(video)
+  })
+}

package/src/integrations/videojs.ts

@@ -0,0 +1,200 @@
+/**
+ * Optional Video.js plugin for libbitsub bitmap subtitles.
+ *
+ * @example
+ * ```ts
+ * import videojs from 'video.js'
+ * import { registerBitSubPlugin } from 'libbitsub/videojs'
+ *
+ * registerBitSubPlugin(videojs)
+ * const player = videojs('my-video')
+ * player.bitsub({ subUrl: '/subs/movie.sup' })
+ * ```
+ */
+
+import { attachBitSub, type AttachBitSubOptions, type BitSubController, type BitSubSourceOptions } from './shared'
+
+/** Minimal Video.js surface used by the plugin (avoids a hard dependency). */
+export interface VideoJsPlayerLike {
+  ready(callback: (this: this) => void): this
+  el(): HTMLElement | null
+  tech?: (asHtml?: boolean) => { el?: () => HTMLElement | null } | HTMLElement | null | undefined
+  on(type: string, handler: (...args: unknown[]) => void): this
+  off?(type: string, handler: (...args: unknown[]) => void): this
+  addClass?(className: string): void
+  removeClass?(className: string): void
+  trigger?(event: string, data?: unknown): void
+}
+
+export interface VideoJsPluginBase {
+  player: VideoJsPlayerLike
+  options_: unknown
+  dispose(): void
+}
+
+export interface VideoJsPluginConstructor {
+  new (player: VideoJsPlayerLike, options?: unknown): VideoJsPluginBase
+  prototype: VideoJsPluginBase
+}
+
+export interface VideoJsLike {
+  getPlugin(name: string): VideoJsPluginConstructor
+  registerPlugin(name: string, plugin: unknown): void
+}
+
+export type BitSubVideoJsOptions = AttachBitSubOptions
+
+export interface BitSubVideoJsApi {
+  /** Active controller, if any. */
+  controller(): BitSubController | null
+  /** Load or replace the subtitle track. */
+  load(source: BitSubSourceOptions): void
+  /** Clear the current track. */
+  clear(): void
+  /** Dispose plugin-owned resources (also runs on player dispose). */
+  dispose(): void
+  setDisplaySettings(settings: Parameters<BitSubController['setDisplaySettings']>[0]): void
+  getDisplaySettings(): ReturnType<BitSubController['getDisplaySettings']>
+  getStats(): ReturnType<BitSubController['getStats']>
+}
+
+function resolveVideoElement(player: VideoJsPlayerLike): HTMLVideoElement | null {
+  const tech = typeof player.tech === 'function' ? player.tech(true) : undefined
+  const techEl =
+    tech && typeof (tech as { el?: () => HTMLElement | null }).el === 'function'
+      ? (tech as { el: () => HTMLElement | null }).el()
+      : (tech as HTMLElement | null | undefined)
+
+  if (techEl instanceof HTMLVideoElement) return techEl
+
+  const root = player.el()
+  if (!root) return null
+  return root.querySelector('video')
+}
+
+/**
+ * Register the `bitsub` Video.js plugin.
+ * Safe to call multiple times — subsequent calls are no-ops once registered.
+ */
+export function registerBitSubPlugin(videojs: VideoJsLike, pluginName = 'bitsub'): void {
+  const existing = typeof videojs.getPlugin === 'function' ? videojs.getPlugin(pluginName) : undefined
+  // Only skip when a previous registerBitSubPlugin call marked the plugin.
+  if (existing && (existing as { __libbitsubPlugin?: boolean }).__libbitsubPlugin) {
+    return
+  }
+
+  const Plugin = videojs.getPlugin('plugin')
+
+  class BitSubPlugin extends Plugin implements BitSubVideoJsApi {
+    private controllerRef: BitSubController | null = null
+    private readonly onDispose: () => void
+    private readonly onLoadedData: () => void
+    private readonly initialOptions: BitSubVideoJsOptions
+
+    constructor(player: VideoJsPlayerLike, options: BitSubVideoJsOptions = {}) {
+      super(player, options)
+      this.initialOptions = options
+
+      this.onDispose = () => this.disposeController()
+      this.onLoadedData = () => this.ensureController(this.initialOptions, false)
+
+      player.ready(() => {
+        this.ensureController(options, true)
+        player.on('loadeddata', this.onLoadedData)
+        player.on('dispose', this.onDispose)
+        player.addClass?.('vjs-bitsub')
+      })
+    }
+
+    controller(): BitSubController | null {
+      return this.controllerRef
+    }
+
+    load(source: BitSubSourceOptions): void {
+      const controller = this.ensureController({}, false)
+      controller.load(source)
+      this.player.trigger?.('bitsubload', source)
+    }
+
+    clear(): void {
+      this.controllerRef?.clear()
+      this.player.trigger?.('bitsubclear')
+    }
+
+    setDisplaySettings(settings: Parameters<BitSubController['setDisplaySettings']>[0]): void {
+      this.controllerRef?.setDisplaySettings(settings)
+    }
+
+    getDisplaySettings(): ReturnType<BitSubController['getDisplaySettings']> {
+      return this.controllerRef?.getDisplaySettings() ?? null
+    }
+
+    getStats(): ReturnType<BitSubController['getStats']> {
+      return this.controllerRef?.getStats() ?? null
+    }
+
+    override dispose(): void {
+      this.player.off?.('loadeddata', this.onLoadedData)
+      this.player.off?.('dispose', this.onDispose)
+      this.player.removeClass?.('vjs-bitsub')
+      this.disposeController()
+      super.dispose()
+    }
+
+    private disposeController(): void {
+      this.controllerRef?.dispose()
+      this.controllerRef = null
+    }
+
+    private ensureController(options: BitSubVideoJsOptions, allowAutoload: boolean): BitSubController {
+      const video = resolveVideoElement(this.player)
+      if (!video) {
+        throw new Error('libbitsub Video.js plugin could not resolve an HTMLVideoElement')
+      }
+
+      if (this.controllerRef && !this.controllerRef.disposed) {
+        if (this.controllerRef.video !== video) {
+          this.controllerRef.setVideo(video)
+        }
+        return this.controllerRef
+      }
+
+      const { autoLoad = true, ...source } = options
+      this.controllerRef = attachBitSub(video, {
+        ...source,
+        autoLoad: allowAutoload ? autoLoad : false
+      })
+      return this.controllerRef
+    }
+  }
+
+  ;(BitSubPlugin as unknown as { __libbitsubPlugin?: boolean }).__libbitsubPlugin = true
+  videojs.registerPlugin(pluginName, BitSubPlugin)
+}
+
+/**
+ * Ambient augmentation helper for apps using the default plugin name `bitsub`.
+ *
+ * @example
+ * ```ts
+ * import 'libbitsub/videojs' // side-effect free; types only when referenced
+ * // or in a global.d.ts:
+ * // import type {} from 'libbitsub/videojs'
+ * ```
+ *
+ * For full player typing, extend your video.js module:
+ * ```ts
+ * import type { BitSubVideoJsApi, BitSubVideoJsOptions } from 'libbitsub/videojs'
+ * declare module 'video.js' {
+ *   interface VideoJsPlayer {
+ *     bitsub(options?: BitSubVideoJsOptions): BitSubVideoJsApi
+ *   }
+ * }
+ * ```
+ */
+export type VideoJsBitSubPlayer = VideoJsPlayerLike & {
+  bitsub(options?: BitSubVideoJsOptions): BitSubVideoJsApi
+}
+
+export type { AttachBitSubOptions, BitSubController, BitSubSourceOptions, BitSubRenderer } from './shared'
+export { attachBitSub, createBitSubRenderer } from './shared'

package/src/wrapper.ts

@@ -5,6 +5,7 @@
 
 // Re-export all types
 export type {
+  AssetFetchStrategy,
   AutoSubtitleSource,
   AutoVideoSubtitleOptions,
   OpenedSubtitles,
@@ -45,6 +46,8 @@ export { SubtitleDiagnosticError, createSubtitleDiagnosticError, normalizeSubtit
 // Re-export WASM management
 export { initWasm, isWasmInitialized } from './ts/wasm'
 
+export { warmup, ready, isWorkerAvailable, isWorkerReady } from './ts/worker'
+
 // Re-export WebGPU utilities
 export { isWebGPUSupported } from './ts/webgpu-renderer'
 
@@ -60,6 +63,15 @@ export { PgsRenderer, VobSubRenderer, createAutoSubtitleRenderer, type SubtitleR
 // Re-export format detection utilities
 export { detectSubtitleFormat } from './ts/utils'
 
+export {
+  fetchSubtitleAsset,
+  fetchSubtitleText,
+  probeRangeSupport,
+  type AssetFetchOptions,
+  type AssetFetchProgress,
+  type RangeProbeResult
+} from './ts/range-loader'
+
 // =============================================================================
 // Legacy Aliases (for backward compatibility)
 // =============================================================================