libbitsub 1.10.2 → 1.11.0

package/pkg/libbitsub.d.ts

@@ -8,7 +8,9 @@ export class PgsParser {
     free(): void;
     [Symbol.dispose](): void;
     clearCache(): void;
+    feed(data: Uint8Array): number;
     findIndexAtTimestamp(time_ms: number): number;
+    finishFeed(): number;
     getCueCompositionCount(index: number): number;
     getCueCompositionState(index: number): number;
     getCueEndTime(index: number): number;
@@ -18,8 +20,10 @@ export class PgsParser {
     constructor();
     parse(data: Uint8Array): number;
     renderAtIndex(index: number): SubtitleFrame | undefined;
+    reset(): void;
     readonly count: number;
     readonly lastRenderIssue: string;
+    readonly pendingLen: number;
     readonly screenHeight: number;
     readonly screenWidth: number;
 }
@@ -128,6 +132,7 @@ export class VobSubFrame {
 export class VobSubParser {
     free(): void;
     [Symbol.dispose](): void;
+    attachSubData(sub_data: Uint8Array): void;
     clearCache(): void;
     dispose(): void;
     findIndexAtTimestamp(time_ms: number): number;
@@ -137,6 +142,7 @@ export class VobSubParser {
     getCueStartTime(index: number): number;
     getTimestamps(): Float64Array;
     loadFromData(idx_content: string, sub_data: Uint8Array): void;
+    loadFromIdx(idx_content: string): void;
     loadFromMks(mks_data: Uint8Array): void;
     loadFromSubOnly(sub_data: Uint8Array): void;
     constructor();
@@ -147,6 +153,7 @@ export class VobSubParser {
     readonly count: number;
     readonly debandEnabled: boolean;
     readonly hasIdxMetadata: boolean;
+    readonly hasSubData: boolean;
     readonly language: string;
     readonly lastRenderIssue: string;
     readonly screenHeight: number;
@@ -173,7 +180,9 @@ export interface InitOutput {
     readonly init: () => void;
     readonly pgsparser_clearCache: (a: number) => void;
     readonly pgsparser_count: (a: number) => number;
+    readonly pgsparser_feed: (a: number, b: number, c: number) => number;
     readonly pgsparser_findIndexAtTimestamp: (a: number, b: number) => number;
+    readonly pgsparser_finishFeed: (a: number) => number;
     readonly pgsparser_getCueCompositionCount: (a: number, b: number) => number;
     readonly pgsparser_getCueCompositionState: (a: number, b: number) => number;
     readonly pgsparser_getCueEndTime: (a: number, b: number) => number;
@@ -183,7 +192,9 @@ export interface InitOutput {
     readonly pgsparser_lastRenderIssue: (a: number) => [number, number];
     readonly pgsparser_new: () => number;
     readonly pgsparser_parse: (a: number, b: number, c: number) => number;
+    readonly pgsparser_pendingLen: (a: number) => number;
     readonly pgsparser_renderAtIndex: (a: number, b: number) => number;
+    readonly pgsparser_reset: (a: number) => void;
     readonly pgsparser_screenHeight: (a: number) => number;
     readonly pgsparser_screenWidth: (a: number) => number;
     readonly renderresult_compositionCount: (a: number) => number;
@@ -232,6 +243,7 @@ export interface InitOutput {
     readonly vobsubframe_width: (a: number) => number;
     readonly vobsubframe_x: (a: number) => number;
     readonly vobsubframe_y: (a: number) => number;
+    readonly vobsubparser_attachSubData: (a: number, b: number, c: number) => void;
     readonly vobsubparser_clearCache: (a: number) => void;
     readonly vobsubparser_count: (a: number) => number;
     readonly vobsubparser_debandEnabled: (a: number) => number;
@@ -243,9 +255,11 @@ export interface InitOutput {
     readonly vobsubparser_getCueStartTime: (a: number, b: number) => number;
     readonly vobsubparser_getTimestamps: (a: number) => any;
     readonly vobsubparser_hasIdxMetadata: (a: number) => number;
+    readonly vobsubparser_hasSubData: (a: number) => number;
     readonly vobsubparser_language: (a: number) => [number, number];
     readonly vobsubparser_lastRenderIssue: (a: number) => [number, number];
     readonly vobsubparser_loadFromData: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly vobsubparser_loadFromIdx: (a: number, b: number, c: number) => void;
     readonly vobsubparser_loadFromMks: (a: number, b: number, c: number) => [number, number];
     readonly vobsubparser_loadFromSubOnly: (a: number, b: number, c: number) => void;
     readonly vobsubparser_new: () => number;

package/pkg/libbitsub.js

@@ -24,6 +24,16 @@ export class PgsParser {
         const ret = wasm.pgsparser_count(this.__wbg_ptr);
         return ret >>> 0;
     }
+    /**
+     * @param {Uint8Array} data
+     * @returns {number}
+     */
+    feed(data) {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.pgsparser_feed(this.__wbg_ptr, ptr0, len0);
+        return ret >>> 0;
+    }
     /**
      * @param {number} time_ms
      * @returns {number}
@@ -32,6 +42,13 @@ export class PgsParser {
         const ret = wasm.pgsparser_findIndexAtTimestamp(this.__wbg_ptr, time_ms);
         return ret;
     }
+    /**
+     * @returns {number}
+     */
+    finishFeed() {
+        const ret = wasm.pgsparser_finishFeed(this.__wbg_ptr);
+        return ret >>> 0;
+    }
     /**
      * @param {number} index
      * @returns {number}
@@ -110,6 +127,13 @@ export class PgsParser {
         const ret = wasm.pgsparser_parse(this.__wbg_ptr, ptr0, len0);
         return ret >>> 0;
     }
+    /**
+     * @returns {number}
+     */
+    get pendingLen() {
+        const ret = wasm.pgsparser_pendingLen(this.__wbg_ptr);
+        return ret >>> 0;
+    }
     /**
      * @param {number} index
      * @returns {SubtitleFrame | undefined}
@@ -118,6 +142,9 @@ export class PgsParser {
         const ret = wasm.pgsparser_renderAtIndex(this.__wbg_ptr, index);
         return ret === 0 ? undefined : SubtitleFrame.__wrap(ret);
     }
+    reset() {
+        wasm.pgsparser_reset(this.__wbg_ptr);
+    }
     /**
      * @returns {number}
      */
@@ -628,6 +655,14 @@ export class VobSubParser {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_vobsubparser_free(ptr, 0);
     }
+    /**
+     * @param {Uint8Array} sub_data
+     */
+    attachSubData(sub_data) {
+        const ptr0 = passArray8ToWasm0(sub_data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.vobsubparser_attachSubData(this.__wbg_ptr, ptr0, len0);
+    }
     clearCache() {
         wasm.vobsubparser_clearCache(this.__wbg_ptr);
     }
@@ -702,6 +737,13 @@ export class VobSubParser {
         const ret = wasm.vobsubparser_hasIdxMetadata(this.__wbg_ptr);
         return ret !== 0;
     }
+    /**
+     * @returns {boolean}
+     */
+    get hasSubData() {
+        const ret = wasm.vobsubparser_hasSubData(this.__wbg_ptr);
+        return ret !== 0;
+    }
     /**
      * @returns {string}
      */
@@ -743,6 +785,14 @@ export class VobSubParser {
         const len1 = WASM_VECTOR_LEN;
         wasm.vobsubparser_loadFromData(this.__wbg_ptr, ptr0, len0, ptr1, len1);
     }
+    /**
+     * @param {string} idx_content
+     */
+    loadFromIdx(idx_content) {
+        const ptr0 = passStringToWasm0(idx_content, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.vobsubparser_loadFromIdx(this.__wbg_ptr, ptr0, len0);
+    }
     /**
      * @param {Uint8Array} mks_data
      */

package/pkg/libbitsub_bg.wasm.d.ts

@@ -11,7 +11,9 @@ export const __wbg_vobsubparser_free: (a: number, b: number) => void;
 export const init: () => void;
 export const pgsparser_clearCache: (a: number) => void;
 export const pgsparser_count: (a: number) => number;
+export const pgsparser_feed: (a: number, b: number, c: number) => number;
 export const pgsparser_findIndexAtTimestamp: (a: number, b: number) => number;
+export const pgsparser_finishFeed: (a: number) => number;
 export const pgsparser_getCueCompositionCount: (a: number, b: number) => number;
 export const pgsparser_getCueCompositionState: (a: number, b: number) => number;
 export const pgsparser_getCueEndTime: (a: number, b: number) => number;
@@ -21,7 +23,9 @@ export const pgsparser_getTimestamps: (a: number) => any;
 export const pgsparser_lastRenderIssue: (a: number) => [number, number];
 export const pgsparser_new: () => number;
 export const pgsparser_parse: (a: number, b: number, c: number) => number;
+export const pgsparser_pendingLen: (a: number) => number;
 export const pgsparser_renderAtIndex: (a: number, b: number) => number;
+export const pgsparser_reset: (a: number) => void;
 export const pgsparser_screenHeight: (a: number) => number;
 export const pgsparser_screenWidth: (a: number) => number;
 export const renderresult_compositionCount: (a: number) => number;
@@ -70,6 +74,7 @@ export const vobsubframe_screenWidth: (a: number) => number;
 export const vobsubframe_width: (a: number) => number;
 export const vobsubframe_x: (a: number) => number;
 export const vobsubframe_y: (a: number) => number;
+export const vobsubparser_attachSubData: (a: number, b: number, c: number) => void;
 export const vobsubparser_clearCache: (a: number) => void;
 export const vobsubparser_count: (a: number) => number;
 export const vobsubparser_debandEnabled: (a: number) => number;
@@ -81,9 +86,11 @@ export const vobsubparser_getCueFilePosition: (a: number, b: number) => number;
 export const vobsubparser_getCueStartTime: (a: number, b: number) => number;
 export const vobsubparser_getTimestamps: (a: number) => any;
 export const vobsubparser_hasIdxMetadata: (a: number) => number;
+export const vobsubparser_hasSubData: (a: number) => number;
 export const vobsubparser_language: (a: number) => [number, number];
 export const vobsubparser_lastRenderIssue: (a: number) => [number, number];
 export const vobsubparser_loadFromData: (a: number, b: number, c: number, d: number, e: number) => void;
+export const vobsubparser_loadFromIdx: (a: number, b: number, c: number) => void;
 export const vobsubparser_loadFromMks: (a: number, b: number, c: number) => [number, number];
 export const vobsubparser_loadFromSubOnly: (a: number, b: number, c: number) => void;
 export const vobsubparser_new: () => number;

package/pkg/package.json

@@ -5,7 +5,7 @@
     "altqx"
   ],
   "description": "High-performance WASM renderer for graphical subtitles (PGS and VobSub)",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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,170 @@
+/**
+ * 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,
+    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
+
+  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])
+
+  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'