captions.js 0.3.0 → 0.3.1

package/README.md

@@ -0,0 +1,39 @@
+> [!WARNING]
+> 🚧 **Captions.js is nearing its first public release**  
+> The library is under active development and a full-featured version is expected around **November 2025**.
+
+💌 Want to know when Captions.js is released?
+Star or watch the repo on GitHub to get updates!
+
+# Captions.js
+
+A modern JavaScript library for adding captions to HTML5 videos with ease.
+
+[**Live Demo**](https://maskin25.github.io/captions.js/)
+
+[**Docs & API Reference**](https://maskin25.github.io/captions.js/docs/)
+
+<!-- [![Storybook](https://raw.githubusercontent.com/storybookjs/brand/refs/heads/main/badge/badge-storybook.svg)](https://main--68e681805917843931c33a87.chromatic.com/) -->
+
+## Features
+
+- **Easy Integration**: Simple API to add captions to your videos.
+- **Customizable Styles**: Fully customizable caption styles via configurations.
+- **Multiple Formats**: Supports various caption formats including WebVTT and SRT.
+- **Responsive Design**: Captions adapt to different screen sizes and orientations.
+
+## Installation
+
+To install Captions.js, use npm or yarn:
+
+```bash
+npm install captions.js
+```
+
+or
+
+```bash
+yarn add captions.js
+```
+
+For development see [DEVELOPMENT.md](./DEVELOPMENT.md).

package/dist/index.d.mts

@@ -1,3 +1,233 @@
+/**
+ * Whitelisted Google Fonts that the renderer knows how to lazy-load.
+ *
+ * @remarks
+ * Restricting the list keeps bundle size predictable across consumers.
+ *
+ * @public
+ */
+declare const googleFontsList: readonly ["Roboto", "Open Sans", "Lato", "Montserrat", "Nunito", "Poppins", "Ubuntu", "PT Sans", "Merriweather Sans", "Lobster", "Amatic SC", "Pacifico", "Raleway", "Cinzel", "Quicksand", "Zilla Slab", "Caveat", "Crimson Pro", "Bebas Neue", "Comfortaa", "Satisfy", "Permanent Marker", "Oswald", "Onset", "Bangers", "Kanit", "Work Sans", "Fira Sans", "Anton", "Playfair Display", "Rubik", "Alumni Sans", "Righteous", "Comico", "Excon", "Kalam", "Tanker", "Arsenal", "Balsamiq Sans", "Bona Nova SC"];
+
+/**
+ * Shared schema describing how a preset styles captions plus rough layout hints.
+ *
+ * @public
+ */
+interface StylePreset {
+    id: number;
+    captionsSettings: {
+        style: {
+            font: {
+                italic: boolean;
+                fontSize: number;
+                fontColor: string;
+                underline: boolean;
+                fontFamily: string;
+                fontWeight: string;
+                fontCapitalize: boolean;
+                fontStrokeColor: string;
+                fontStrokeWidth: number;
+                shadow?: {
+                    fontShadowBlur: number;
+                    fontShadowColor: string;
+                    fontShadowOffsetX: number;
+                    fontShadowOffsetY: number;
+                };
+            };
+            name: string;
+            backgroundColor: string;
+            verticalCoverImg: string;
+            aplifiedWordColor: string;
+        };
+        position: string;
+        animation: string;
+        linesPerPage: number;
+        positionTopOffset?: number;
+    };
+    layoutSettings: {
+        aspectRatio: string;
+        aIAutoLayout: string[];
+        fitLayoutAspectRatio: string;
+    };
+}
+/**
+ * Curated set of presets that ship with captions.js out of the box.
+ *
+ * @remarks
+ * Downstream apps can reference them directly or clone/extend as needed.
+ *
+ * @public
+ */
+declare const stylePresets: StylePreset[];
+
+/**
+ * Server/worker-friendly helper that paints a text string onto a provided canvas.
+ *
+ * @remarks
+ * Uses the same Konva pipeline as the video overlay renderer so the results
+ * match what users see in the browser.
+ *
+ * @param canvas - Destination canvas that should receive the rendered text.
+ * @param text - Arbitrary content that needs to be painted.
+ * @param options - Rendering options that include the style preset.
+ * @returns Resolves once the frame has been painted (always resolves to `true`).
+ */
+declare function renderString(canvas: HTMLCanvasElement, text: string, options: {
+    preset: StylePreset;
+}): Promise<boolean>;
+
+/**
+ * Full styling + animation configuration for a single captions track.
+ *
+ * @public
+ */
+interface CaptionsSettings {
+    style: {
+        name: string;
+        font: {
+            fontFamily: string;
+            fontSize: number;
+            fontWeight: "thin" | "light" | "regular" | "medium" | "bold" | "black";
+            fontColor: string;
+            fontCapitalize: boolean;
+            italic: boolean;
+            underline: boolean;
+            fontStrokeColor: string;
+            fontStrokeWidth: number;
+            shadow: {
+                fontShadowColor: string;
+                fontShadowBlur: number;
+                fontShadowOffsetX: number;
+                fontShadowOffsetY: number;
+            };
+        };
+        aplifiedWordColor: string;
+        backgroundColor: string;
+    };
+    linesPerPage: number;
+    lineSpacing?: number | null;
+    position: "auto" | "top" | "middle" | "bottom";
+    positionTopOffset: number;
+    animation: "none" | "bounce" | "underline" | "box" | "pop" | "scale" | "slide-left" | "slide-up" | "slide-down" | "box-word";
+}
+/**
+ * Single timed word/segment that will be highlighted as audio plays.
+ *
+ * @public
+ */
+interface Caption {
+    word: string;
+    startTime: number;
+    endTime: number;
+    highlightColor?: string;
+}
+
+/**
+ * Configuration passed to the captions runtime when binding to a video element.
+ *
+ * @public
+ */
+type CaptionsOptions = {
+    /** Video element that should receive overlays. */
+    video: HTMLVideoElement;
+    /** Optional custom container to host the Konva stage. */
+    container?: HTMLDivElement;
+    /** Initial preset controlling font, colors, animations. */
+    preset: StylePreset;
+    /** Initial caption track. */
+    captions?: Caption[] | null;
+    /** When false, caller must invoke {@link Captions.enable} manually. */
+    autoEnable?: boolean;
+};
+/**
+ * Imperative controller that owns the Konva stage lifecycle for a single video element.
+ *
+ * @public
+ */
+declare class Captions {
+    private enabled;
+    private readonly video;
+    private readonly providedContainer?;
+    private presetState;
+    private captionsState;
+    private containerElement?;
+    private ownsContainer;
+    private stage;
+    private layer;
+    private resizeObserver?;
+    private animationFrameId;
+    private videoWidth;
+    private videoHeight;
+    private readonly handleResize;
+    private readonly handleMetadata;
+    private readonly animationLoop;
+    /**
+     * Create a controller bound to the provided video element and preset.
+     *
+     * @param options - Complete configuration for the controller.
+     */
+    constructor(options: CaptionsOptions);
+    /**
+     * Mount caption overlays onto the configured video if they are not active yet.
+     */
+    enable(): void;
+    /**
+     * Tear down overlays, observers and animation loops to free resources.
+     */
+    disable(): void;
+    /**
+     * Alias for {@link Captions.disable | disable()} to match typical imperative controller APIs.
+     */
+    destroy(): void;
+    /**
+     * Swap the active preset and re-render with updated typography/colors.
+     *
+     * @param nextPreset - Preset that becomes the new render baseline.
+     */
+    preset(nextPreset: StylePreset): void;
+    /**
+     * Replace the current caption track and repaint without reloading fonts.
+     *
+     * @param nextCaptions - Timed words that should drive the overlay.
+     */
+    captions(nextCaptions: Caption[] | null): void;
+    /**
+     * Whether the Konva overlay is currently attached to the video element.
+     *
+     * @returns `true` when the overlay is mounted on top of the video.
+     */
+    isEnabled(): boolean;
+    private refreshFrame;
+    private loadFontForCurrentPreset;
+    private updateFrame;
+    private syncStageDimensions;
+    private createOverlay;
+}
+/**
+ * Convenience alias for the concrete controller class.
+ *
+ * @public
+ */
+type CaptionsInstance = Captions;
+/**
+ * Factory mirroring the legacy default export for ergonomic imports.
+ *
+ * @param options - Same options accepted by the {@link Captions} constructor.
+ * @returns New controller instance.
+ */
+declare function captionsjs(options: CaptionsOptions): Captions;
+
+/**
+ * Simple canvas demo renderer used only for the docs playground.
+ *
+ * @remarks
+ * Keeps a reference implementation of drawing raw text to a canvas so we can
+ * showcase caption styling without a video element.
+ *
+ * @param ctx - Target 2D context to draw on.
+ * @param text - Arbitrary string that should be painted on the canvas.
+ * @returns Always returns `true` to match the historical API surface.
+ */
 declare function renderCaptions(ctx: CanvasRenderingContext2D, text: string): boolean;
 
-export { renderCaptions };
+export { type Caption, Captions, type CaptionsInstance, type CaptionsOptions, type CaptionsSettings, type StylePreset, captionsjs, captionsjs as default, googleFontsList, renderCaptions, renderString, stylePresets };

package/dist/index.d.ts

@@ -1,3 +1,233 @@
+/**
+ * Whitelisted Google Fonts that the renderer knows how to lazy-load.
+ *
+ * @remarks
+ * Restricting the list keeps bundle size predictable across consumers.
+ *
+ * @public
+ */
+declare const googleFontsList: readonly ["Roboto", "Open Sans", "Lato", "Montserrat", "Nunito", "Poppins", "Ubuntu", "PT Sans", "Merriweather Sans", "Lobster", "Amatic SC", "Pacifico", "Raleway", "Cinzel", "Quicksand", "Zilla Slab", "Caveat", "Crimson Pro", "Bebas Neue", "Comfortaa", "Satisfy", "Permanent Marker", "Oswald", "Onset", "Bangers", "Kanit", "Work Sans", "Fira Sans", "Anton", "Playfair Display", "Rubik", "Alumni Sans", "Righteous", "Comico", "Excon", "Kalam", "Tanker", "Arsenal", "Balsamiq Sans", "Bona Nova SC"];
+
+/**
+ * Shared schema describing how a preset styles captions plus rough layout hints.
+ *
+ * @public
+ */
+interface StylePreset {
+    id: number;
+    captionsSettings: {
+        style: {
+            font: {
+                italic: boolean;
+                fontSize: number;
+                fontColor: string;
+                underline: boolean;
+                fontFamily: string;
+                fontWeight: string;
+                fontCapitalize: boolean;
+                fontStrokeColor: string;
+                fontStrokeWidth: number;
+                shadow?: {
+                    fontShadowBlur: number;
+                    fontShadowColor: string;
+                    fontShadowOffsetX: number;
+                    fontShadowOffsetY: number;
+                };
+            };
+            name: string;
+            backgroundColor: string;
+            verticalCoverImg: string;
+            aplifiedWordColor: string;
+        };
+        position: string;
+        animation: string;
+        linesPerPage: number;
+        positionTopOffset?: number;
+    };
+    layoutSettings: {
+        aspectRatio: string;
+        aIAutoLayout: string[];
+        fitLayoutAspectRatio: string;
+    };
+}
+/**
+ * Curated set of presets that ship with captions.js out of the box.
+ *
+ * @remarks
+ * Downstream apps can reference them directly or clone/extend as needed.
+ *
+ * @public
+ */
+declare const stylePresets: StylePreset[];
+
+/**
+ * Server/worker-friendly helper that paints a text string onto a provided canvas.
+ *
+ * @remarks
+ * Uses the same Konva pipeline as the video overlay renderer so the results
+ * match what users see in the browser.
+ *
+ * @param canvas - Destination canvas that should receive the rendered text.
+ * @param text - Arbitrary content that needs to be painted.
+ * @param options - Rendering options that include the style preset.
+ * @returns Resolves once the frame has been painted (always resolves to `true`).
+ */
+declare function renderString(canvas: HTMLCanvasElement, text: string, options: {
+    preset: StylePreset;
+}): Promise<boolean>;
+
+/**
+ * Full styling + animation configuration for a single captions track.
+ *
+ * @public
+ */
+interface CaptionsSettings {
+    style: {
+        name: string;
+        font: {
+            fontFamily: string;
+            fontSize: number;
+            fontWeight: "thin" | "light" | "regular" | "medium" | "bold" | "black";
+            fontColor: string;
+            fontCapitalize: boolean;
+            italic: boolean;
+            underline: boolean;
+            fontStrokeColor: string;
+            fontStrokeWidth: number;
+            shadow: {
+                fontShadowColor: string;
+                fontShadowBlur: number;
+                fontShadowOffsetX: number;
+                fontShadowOffsetY: number;
+            };
+        };
+        aplifiedWordColor: string;
+        backgroundColor: string;
+    };
+    linesPerPage: number;
+    lineSpacing?: number | null;
+    position: "auto" | "top" | "middle" | "bottom";
+    positionTopOffset: number;
+    animation: "none" | "bounce" | "underline" | "box" | "pop" | "scale" | "slide-left" | "slide-up" | "slide-down" | "box-word";
+}
+/**
+ * Single timed word/segment that will be highlighted as audio plays.
+ *
+ * @public
+ */
+interface Caption {
+    word: string;
+    startTime: number;
+    endTime: number;
+    highlightColor?: string;
+}
+
+/**
+ * Configuration passed to the captions runtime when binding to a video element.
+ *
+ * @public
+ */
+type CaptionsOptions = {
+    /** Video element that should receive overlays. */
+    video: HTMLVideoElement;
+    /** Optional custom container to host the Konva stage. */
+    container?: HTMLDivElement;
+    /** Initial preset controlling font, colors, animations. */
+    preset: StylePreset;
+    /** Initial caption track. */
+    captions?: Caption[] | null;
+    /** When false, caller must invoke {@link Captions.enable} manually. */
+    autoEnable?: boolean;
+};
+/**
+ * Imperative controller that owns the Konva stage lifecycle for a single video element.
+ *
+ * @public
+ */
+declare class Captions {
+    private enabled;
+    private readonly video;
+    private readonly providedContainer?;
+    private presetState;
+    private captionsState;
+    private containerElement?;
+    private ownsContainer;
+    private stage;
+    private layer;
+    private resizeObserver?;
+    private animationFrameId;
+    private videoWidth;
+    private videoHeight;
+    private readonly handleResize;
+    private readonly handleMetadata;
+    private readonly animationLoop;
+    /**
+     * Create a controller bound to the provided video element and preset.
+     *
+     * @param options - Complete configuration for the controller.
+     */
+    constructor(options: CaptionsOptions);
+    /**
+     * Mount caption overlays onto the configured video if they are not active yet.
+     */
+    enable(): void;
+    /**
+     * Tear down overlays, observers and animation loops to free resources.
+     */
+    disable(): void;
+    /**
+     * Alias for {@link Captions.disable | disable()} to match typical imperative controller APIs.
+     */
+    destroy(): void;
+    /**
+     * Swap the active preset and re-render with updated typography/colors.
+     *
+     * @param nextPreset - Preset that becomes the new render baseline.
+     */
+    preset(nextPreset: StylePreset): void;
+    /**
+     * Replace the current caption track and repaint without reloading fonts.
+     *
+     * @param nextCaptions - Timed words that should drive the overlay.
+     */
+    captions(nextCaptions: Caption[] | null): void;
+    /**
+     * Whether the Konva overlay is currently attached to the video element.
+     *
+     * @returns `true` when the overlay is mounted on top of the video.
+     */
+    isEnabled(): boolean;
+    private refreshFrame;
+    private loadFontForCurrentPreset;
+    private updateFrame;
+    private syncStageDimensions;
+    private createOverlay;
+}
+/**
+ * Convenience alias for the concrete controller class.
+ *
+ * @public
+ */
+type CaptionsInstance = Captions;
+/**
+ * Factory mirroring the legacy default export for ergonomic imports.
+ *
+ * @param options - Same options accepted by the {@link Captions} constructor.
+ * @returns New controller instance.
+ */
+declare function captionsjs(options: CaptionsOptions): Captions;
+
+/**
+ * Simple canvas demo renderer used only for the docs playground.
+ *
+ * @remarks
+ * Keeps a reference implementation of drawing raw text to a canvas so we can
+ * showcase caption styling without a video element.
+ *
+ * @param ctx - Target 2D context to draw on.
+ * @param text - Arbitrary string that should be painted on the canvas.
+ * @returns Always returns `true` to match the historical API surface.
+ */
 declare function renderCaptions(ctx: CanvasRenderingContext2D, text: string): boolean;
 
-export { renderCaptions };
+export { type Caption, Captions, type CaptionsInstance, type CaptionsOptions, type CaptionsSettings, type StylePreset, captionsjs, captionsjs as default, googleFontsList, renderCaptions, renderString, stylePresets };