libbitsub 1.10.2 → 1.12.0

package/src/integrations/hlsjs.ts

@@ -0,0 +1,154 @@
+/**
+ * Optional hls.js adapter for libbitsub bitmap subtitles.
+ *
+ * hls.js handles HLS media and WebVTT/IMSC text tracks; use this helper for
+ * external PGS/VobSub/MKS bitmap overlays on the same media element.
+ *
+ * @example
+ * ```ts
+ * import Hls from 'hls.js'
+ * import { attachBitSubToHls } from 'libbitsub/hlsjs'
+ *
+ * const hls = new Hls()
+ * hls.loadSource(playlistUrl)
+ * hls.attachMedia(video)
+ * const bitsub = attachBitSubToHls(hls, { subUrl: '/subs/movie.sup' })
+ * // later
+ * bitsub.dispose()
+ * ```
+ */
+
+import { attachBitSub, type AttachBitSubOptions, type BitSubController, type BitSubSourceOptions } from './shared'
+
+/** Minimal hls.js surface used by the adapter. */
+export interface HlsLike {
+  media: HTMLMediaElement | null
+  on?(event: string, listener: (...args: unknown[]) => void): void
+  off?(event: string, listener: (...args: unknown[]) => void): void
+  /** hls.js Events map — optional so callers can pass event name strings. */
+  Events?: {
+    MEDIA_ATTACHED?: string
+    MEDIA_DETACHED?: string
+    DESTROYING?: string
+  }
+}
+
+export type BitSubHlsOptions = AttachBitSubOptions
+
+export interface BitSubHlsHandle extends BitSubController {
+  /** Underlying hls.js instance. */
+  readonly hls: HlsLike
+}
+
+function eventName(hls: HlsLike, key: 'MEDIA_ATTACHED' | 'MEDIA_DETACHED' | 'DESTROYING', fallback: string): string {
+  return hls.Events?.[key] ?? fallback
+}
+
+function hasSubtitleSource(source: BitSubSourceOptions): boolean {
+  return Boolean(source.subUrl || source.subContent || source.idxUrl || source.idxContent || source.fileName)
+}
+
+/**
+ * Attach libbitsub to an hls.js instance.
+ * Binds to `hls.media` and re-attaches on MEDIA_ATTACHED when event APIs exist.
+ */
+export function attachBitSubToHls(hls: HlsLike, options: BitSubHlsOptions = {}): BitSubHlsHandle {
+  const initialMedia = hls.media
+  if (initialMedia && !(initialMedia instanceof HTMLVideoElement)) {
+    throw new Error('libbitsub hls.js adapter requires hls.media to be an HTMLVideoElement')
+  }
+
+  // Allow constructing before attachMedia(); load waits until a video is available.
+  const placeholderVideo = initialMedia instanceof HTMLVideoElement ? initialMedia : document.createElement('video')
+  const { autoLoad: initialAutoLoad = true, ...initialSource } = options
+  let lastSource: BitSubSourceOptions = { ...initialSource }
+  let autoLoad = initialAutoLoad
+
+  const controller = attachBitSub(placeholderVideo, {
+    ...initialSource,
+    autoLoad: initialMedia instanceof HTMLVideoElement ? initialAutoLoad : false
+  })
+
+  const bindMedia = (media: HTMLMediaElement | null): void => {
+    if (controller.disposed) return
+    if (media && !(media instanceof HTMLVideoElement)) {
+      throw new Error('libbitsub hls.js adapter requires hls.media to be an HTMLVideoElement')
+    }
+
+    if (!media) {
+      controller.setVideo(null)
+      return
+    }
+
+    // setVideo reloads the last source when present; otherwise load explicitly if autoLoad.
+    const needsExplicitLoad = autoLoad && hasSubtitleSource(lastSource) && controller.renderer === null
+    controller.setVideo(media)
+    if (needsExplicitLoad && controller.renderer === null && hasSubtitleSource(lastSource)) {
+      controller.load(lastSource)
+    }
+  }
+
+  const onMediaAttached = (): void => bindMedia(hls.media)
+  const onMediaDetached = (): void => {
+    if (!controller.disposed) controller.clear()
+  }
+  const onDestroying = (): void => dispose()
+
+  const mediaAttached = eventName(hls, 'MEDIA_ATTACHED', 'hlsMediaAttached')
+  const mediaDetached = eventName(hls, 'MEDIA_DETACHED', 'hlsMediaDetached')
+  const destroying = eventName(hls, 'DESTROYING', 'hlsDestroying')
+
+  hls.on?.(mediaAttached, onMediaAttached)
+  hls.on?.(mediaDetached, onMediaDetached)
+  hls.on?.(destroying, onDestroying)
+
+  if (initialMedia instanceof HTMLVideoElement) {
+    bindMedia(initialMedia)
+  }
+
+  const dispose = (): void => {
+    hls.off?.(mediaAttached, onMediaAttached)
+    hls.off?.(mediaDetached, onMediaDetached)
+    hls.off?.(destroying, onDestroying)
+    controller.dispose()
+  }
+
+  return {
+    hls,
+    get renderer() {
+      return controller.renderer
+    },
+    get video() {
+      return controller.video
+    },
+    get disposed() {
+      return controller.disposed
+    },
+    load: (source) => {
+      lastSource = { ...source }
+      autoLoad = true
+      if (!(controller.video instanceof HTMLVideoElement) || controller.video === placeholderVideo) {
+        const media = hls.media
+        if (media instanceof HTMLVideoElement) {
+          controller.setVideo(media)
+        } else {
+          throw new Error('libbitsub hls.js adapter: call hls.attachMedia(video) before load()')
+        }
+      }
+      return controller.load(source)
+    },
+    clear: () => {
+      autoLoad = false
+      controller.clear()
+    },
+    dispose,
+    getDisplaySettings: () => controller.getDisplaySettings(),
+    setDisplaySettings: (settings) => controller.setDisplaySettings(settings),
+    resetDisplaySettings: () => controller.resetDisplaySettings(),
+    getStats: () => controller.getStats(),
+    setVideo: (video) => controller.setVideo(video)
+  }
+}
+
+export type { AttachBitSubOptions, BitSubController, BitSubSourceOptions, BitSubRenderer } from './shared'
+export { attachBitSub, createBitSubRenderer } from './shared'

package/src/integrations/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Optional player integrations for libbitsub.
+ * Prefer deep imports (`libbitsub/videojs`, `libbitsub/shaka`, `libbitsub/hlsjs`, `libbitsub/react`)
+ * so unused peer dependencies stay out of your bundle.
+ */
+
+export {
+  attachBitSub,
+  createBitSubRenderer,
+  type AttachBitSubOptions,
+  type BitSubController,
+  type BitSubRenderer,
+  type BitSubSourceOptions
+} from './shared'
+
+export {
+  registerBitSubPlugin,
+  type BitSubVideoJsApi,
+  type BitSubVideoJsOptions,
+  type VideoJsBitSubPlayer,
+  type VideoJsLike,
+  type VideoJsPlayerLike
+} from './videojs'
+
+export { attachBitSubToShaka, type BitSubShakaHandle, type BitSubShakaOptions, type ShakaPlayerLike } from './shaka'
+
+export { attachBitSubToHls, type BitSubHlsHandle, type BitSubHlsOptions, type HlsLike } from './hlsjs'
+
+export {
+  BitSubOverlay,
+  useBitSub,
+  type BitSubOverlayProps,
+  type BitSubReactSource,
+  type UseBitSubOptions,
+  type UseBitSubResult
+} from './react'

package/src/integrations/react.tsx

@@ -0,0 +1,176 @@
+/**
+ * Optional React bindings for libbitsub bitmap subtitles.
+ *
+ * Peer dependency: react >= 18
+ *
+ * @example
+ * ```tsx
+ * import { useRef } from 'react'
+ * import { useBitSub } from 'libbitsub/react'
+ *
+ * function Player({ src, subUrl }: { src: string; subUrl: string }) {
+ *   const videoRef = useRef<HTMLVideoElement>(null)
+ *   useBitSub(videoRef, { subUrl })
+ *   return (
+ *     <div style={{ position: 'relative' }}>
+ *       <video ref={videoRef} src={src} controls playsInline />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * Prefer either `useBitSub` *or* `BitSubOverlay` for a given video — not both.
+ */
+
+import { useEffect, useRef, useState, type CSSProperties, type ReactElement, type RefObject } from 'react'
+import { attachBitSub, type AttachBitSubOptions, type BitSubController, type BitSubSourceOptions } from './shared'
+import type { SubtitleDisplaySettings, SubtitleDiagnosticWarning, SubtitleRendererEvent } from '../wrapper'
+
+export type BitSubReactSource = BitSubSourceOptions
+
+export interface UseBitSubOptions extends BitSubReactSource {
+  /** When false, do not load even if source fields are set. Default true. */
+  enabled?: boolean
+}
+
+export interface UseBitSubResult {
+  controller: BitSubController | null
+  error: Error | null
+}
+
+function sourceKey(source: BitSubReactSource | null | undefined): string {
+  if (!source) return ''
+  return JSON.stringify({
+    subUrl: source.subUrl ?? null,
+    idxUrl: source.idxUrl ?? null,
+    fileName: source.fileName ?? null,
+    hasSubContent: Boolean(source.subContent),
+    hasIdxContent: Boolean(source.idxContent),
+    cacheLimit: source.cacheLimit ?? null,
+    timeOffset: source.timeOffset ?? null,
+    frameAwareSync: source.frameAwareSync ?? null,
+    backend: source.backend ?? null,
+    devicePixelRatioCap: source.devicePixelRatioCap ?? null,
+    offscreenRender: source.offscreenRender ?? null,
+    streamingLoad: source.streamingLoad ?? null,
+    rangeRequests: source.rangeRequests ?? null,
+    debug: source.debug ?? null,
+    displaySettings: source.displaySettings ?? null,
+    prefetchWindow: source.prefetchWindow ?? null
+  })
+}
+
+/**
+ * Bind a libbitsub renderer to a video element ref for the lifetime of the source.
+ * Cleans up automatically on unmount or when the source identity changes.
+ */
+export function useBitSub(
+  videoRef: RefObject<HTMLVideoElement | null>,
+  options: UseBitSubOptions | null
+): UseBitSubResult {
+  const controllerRef = useRef<BitSubController | null>(null)
+  const [controller, setController] = useState<BitSubController | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+
+  const onEventRef = useRef<((event: SubtitleRendererEvent) => void) | undefined>(undefined)
+  const onWarningRef = useRef<((warning: SubtitleDiagnosticWarning) => void) | undefined>(undefined)
+  const onErrorRef = useRef<((error: Error) => void) | undefined>(undefined)
+  const onLoadingRef = useRef<(() => void) | undefined>(undefined)
+  const onLoadedRef = useRef<(() => void) | undefined>(undefined)
+
+  onEventRef.current = options?.onEvent
+  onWarningRef.current = options?.onWarning
+  onErrorRef.current = options?.onError
+  onLoadingRef.current = options?.onLoading
+  onLoadedRef.current = options?.onLoaded
+
+  const enabled = options?.enabled !== false
+  const key = sourceKey(options)
+  const displaySettings = options?.displaySettings
+  const container = options?.container
+  const canvas = options?.canvas
+
+  useEffect(() => {
+    setError(null)
+    const video = videoRef.current
+    if (!video || !options || !enabled) {
+      controllerRef.current?.dispose()
+      controllerRef.current = null
+      setController(null)
+      return
+    }
+
+    const {
+      enabled: _enabled,
+      onEvent: _onEvent,
+      onWarning: _onWarning,
+      onError: _onError,
+      onLoading: _onLoading,
+      onLoaded: _onLoaded,
+      ...source
+    } = options
+
+    const attachOptions: AttachBitSubOptions = {
+      ...source,
+      onEvent: (event) => onEventRef.current?.(event),
+      onWarning: (warning) => onWarningRef.current?.(warning),
+      onError: (err) => {
+        setError(err)
+        onErrorRef.current?.(err)
+      },
+      onLoading: () => onLoadingRef.current?.(),
+      onLoaded: () => onLoadedRef.current?.()
+    }
+
+    try {
+      const next = attachBitSub(video, attachOptions)
+      controllerRef.current = next
+      setController(next)
+      return () => {
+        next.dispose()
+        if (controllerRef.current === next) {
+          controllerRef.current = null
+          setController(null)
+        }
+      }
+    } catch (err) {
+      const resolved = err instanceof Error ? err : new Error(String(err))
+      setError(resolved)
+      onErrorRef.current?.(resolved)
+      controllerRef.current = null
+      setController(null)
+    }
+    // key captures source identity; callback props stay fresh via refs
+  }, [videoRef, key, enabled, container, canvas])
+
+  useEffect(() => {
+    if (displaySettings) {
+      controllerRef.current?.setDisplaySettings(displaySettings)
+    }
+  }, [displaySettings])
+
+  return { controller, error }
+}
+
+export interface BitSubOverlayProps extends UseBitSubOptions {
+  videoRef: RefObject<HTMLVideoElement | null>
+  /** Optional class name applied to a zero-size host span for debugging. */
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Declarative overlay helper. Renders nothing visible itself — libbitsub attaches
+ * its canvas next to the video element. Useful when you want JSX-configured tracks.
+ */
+export function BitSubOverlay(props: BitSubOverlayProps): ReactElement | null {
+  const { videoRef, className, style, ...options } = props
+  useBitSub(videoRef, options)
+
+  if (!className && !style) return null
+  return <span className={className} style={{ display: 'none', ...style }} aria-hidden='true' />
+}
+
+export type { AttachBitSubOptions, BitSubController, BitSubSourceOptions, BitSubRenderer } from './shared'
+export { attachBitSub, createBitSubRenderer } from './shared'
+export type { SubtitleDisplaySettings }

package/src/integrations/shaka.ts

@@ -0,0 +1,92 @@
+/**
+ * Optional Shaka Player adapter for libbitsub bitmap subtitles.
+ *
+ * Bitmap PGS/VobSub tracks are not native Shaka text tracks — this helper
+ * overlays libbitsub on the player media element.
+ *
+ * @example
+ * ```ts
+ * import shaka from 'shaka-player'
+ * import { attachBitSubToShaka } from 'libbitsub/shaka'
+ *
+ * const player = new shaka.Player(video)
+ * await player.load(manifestUri)
+ * const bitsub = attachBitSubToShaka(player, { subUrl: '/subs/movie.sup' })
+ * // later
+ * bitsub.dispose()
+ * ```
+ */
+
+import { attachBitSub, type AttachBitSubOptions, type BitSubController } from './shared'
+
+/** Minimal Shaka Player surface used by the adapter. */
+export interface ShakaPlayerLike {
+  getMediaElement(): HTMLMediaElement | null
+  addEventListener?(type: string, listener: (...args: unknown[]) => void): void
+  removeEventListener?(type: string, listener: (...args: unknown[]) => void): void
+}
+
+export type BitSubShakaOptions = AttachBitSubOptions
+
+export interface BitSubShakaHandle extends BitSubController {
+  /** Underlying Shaka player reference. */
+  readonly player: ShakaPlayerLike
+}
+
+/**
+ * Attach libbitsub to a Shaka Player instance.
+ * Rebinds automatically when Shaka swaps the media element (if event APIs exist).
+ */
+export function attachBitSubToShaka(player: ShakaPlayerLike, options: BitSubShakaOptions = {}): BitSubShakaHandle {
+  const media = player.getMediaElement()
+  if (!(media instanceof HTMLVideoElement)) {
+    throw new Error('libbitsub Shaka adapter requires a player with an HTMLVideoElement media element')
+  }
+
+  const controller = attachBitSub(media, options)
+
+  const onLoaded = (): void => {
+    if (controller.disposed) return
+    const next = player.getMediaElement()
+    if (next instanceof HTMLVideoElement) {
+      controller.setVideo(next)
+    }
+  }
+
+  const onUnloading = (): void => {
+    if (!controller.disposed) controller.clear()
+  }
+
+  player.addEventListener?.('loaded', onLoaded)
+  player.addEventListener?.('unloading', onUnloading)
+
+  const dispose = (): void => {
+    player.removeEventListener?.('loaded', onLoaded)
+    player.removeEventListener?.('unloading', onUnloading)
+    controller.dispose()
+  }
+
+  return {
+    player,
+    get renderer() {
+      return controller.renderer
+    },
+    get video() {
+      return controller.video
+    },
+    get disposed() {
+      return controller.disposed
+    },
+    load: (source) => controller.load(source),
+    clear: () => controller.clear(),
+    dispose,
+    getDisplaySettings: () => controller.getDisplaySettings(),
+    setDisplaySettings: (settings) => controller.setDisplaySettings(settings),
+    resetDisplaySettings: () => controller.resetDisplaySettings(),
+    getStats: () => controller.getStats(),
+    setVideo: (video) => controller.setVideo(video)
+  }
+}
+
+export type { AttachBitSubOptions, BitSubController, BitSubSourceOptions, BitSubRenderer } from './shared'
+export { attachBitSub, createBitSubRenderer } from './shared'

package/src/integrations/shared.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared player-integration helpers for libbitsub.
+ * Optional adapters build on this surface so the core package stays dependency-free.
+ */
+
+import {
+  createAutoSubtitleRenderer,
+  type AutoVideoSubtitleOptions,
+  type DvbRenderer,
+  type PgsRenderer,
+  type SubtitleDisplaySettings,
+  type SubtitleRendererStats,
+  type VobSubRenderer
+} from '../wrapper'
+
+/** High-level renderer produced by integrations. */
+export type BitSubRenderer = PgsRenderer | VobSubRenderer | DvbRenderer
+
+/** 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)
+  })
+}