captions.js 0.1.0-alpha → 0.1.0

package/README.md

@@ -1,17 +1,19 @@
 > [!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**.
+> The library is under active development and a full-featured version is expected around **January 2026**.
 
 💌 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.
+Render styled animated captions on canvas — works both on client and server side using Node.js and FFmpeg.
 
 [**Live Demo**](https://maskin25.github.io/captions.js/)
 
-[![Storybook](https://raw.githubusercontent.com/storybookjs/brand/refs/heads/main/badge/badge-storybook.svg)](https://main--68e681805917843931c33a87.chromatic.com/)
+[**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
 

package/dist/index.d.mts

@@ -1,3 +1,236 @@
+import Konva from 'konva';
+
+/**
+ * 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"];
+
+/**
+ * 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;
+            };
+        };
+        verticalCoverImg?: string;
+        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;
+}
+
+/**
+ * Shared schema describing how a preset styles captions plus rough layout hints.
+ *
+ * @public
+ */
+interface StylePreset {
+    id: number;
+    captionsSettings: CaptionsSettings;
+    layoutSettings: {
+        aspectRatio: string;
+        aIAutoLayout: string[];
+        fitLayoutAspectRatio: string;
+    };
+}
+/**
+ * Names of all available style presets.
+ */
+type StylePresetName = "Karaoke" | "Beasty" | "Safari" | "Acid" | "Popline" | "Desert" | "Hook" | "Sky" | "Flamingo" | "Deep Diver B&W" | "New" | "Banger" | "Catchy" | "Karaoke 2" | "Karaoke 3" | "From" | "Classic" | "Classic Big" | "Crazy" | "Acid 2" | "Marvel" | "Lovly" | "Old Money" | "Cinema" | "Marker";
+/**
+ * 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>;
+
+/**
+ * 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;
+    /** Show debug bounding boxes around lines/blocks. */
+    debug?: 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 debug;
+    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;
+
+declare enum LayoutType {
+    'Fill' = "fill",
+    'Fit' = "fit",
+    'Split' = "split",
+    'Three' = "three",
+    'Four' = "four",
+    'ScreenShare' = "screenShare"
+}
+type AspectRatioType = typeof aspectRatios[number];
+interface LayoutSettings {
+    aspectRatio: AspectRatioType;
+    aIAutoLayout: LayoutType[];
+    fitLayoutCropAspectRatio: AspectRatioType;
+}
+declare const aspectRatios: readonly ["1:1", "9:16", "16:9"];
+
+type RenderFrameFn = (captionsSettings: CaptionsSettings, layoutSettings: LayoutSettings, captions: Caption[], currentTime: number, targetSize: [number, number], layer: Konva.Layer, toCoef?: number, debug?: boolean) => void;
+
+declare const renderFrame: RenderFrameFn;
+declare const renderStylePreset: (stylePreset: StylePreset, size: [number, number], frames: number[], text?: string) => Promise<string[]>;
+
+/**
+ * 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, type StylePresetName, captionsjs, captionsjs as default, googleFontsList, renderCaptions, renderFrame, renderString, renderStylePreset, stylePresets };

package/dist/index.d.ts

@@ -1,3 +1,236 @@
+import Konva from 'konva';
+
+/**
+ * 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"];
+
+/**
+ * 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;
+            };
+        };
+        verticalCoverImg?: string;
+        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;
+}
+
+/**
+ * Shared schema describing how a preset styles captions plus rough layout hints.
+ *
+ * @public
+ */
+interface StylePreset {
+    id: number;
+    captionsSettings: CaptionsSettings;
+    layoutSettings: {
+        aspectRatio: string;
+        aIAutoLayout: string[];
+        fitLayoutAspectRatio: string;
+    };
+}
+/**
+ * Names of all available style presets.
+ */
+type StylePresetName = "Karaoke" | "Beasty" | "Safari" | "Acid" | "Popline" | "Desert" | "Hook" | "Sky" | "Flamingo" | "Deep Diver B&W" | "New" | "Banger" | "Catchy" | "Karaoke 2" | "Karaoke 3" | "From" | "Classic" | "Classic Big" | "Crazy" | "Acid 2" | "Marvel" | "Lovly" | "Old Money" | "Cinema" | "Marker";
+/**
+ * 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>;
+
+/**
+ * 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;
+    /** Show debug bounding boxes around lines/blocks. */
+    debug?: 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 debug;
+    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;
+
+declare enum LayoutType {
+    'Fill' = "fill",
+    'Fit' = "fit",
+    'Split' = "split",
+    'Three' = "three",
+    'Four' = "four",
+    'ScreenShare' = "screenShare"
+}
+type AspectRatioType = typeof aspectRatios[number];
+interface LayoutSettings {
+    aspectRatio: AspectRatioType;
+    aIAutoLayout: LayoutType[];
+    fitLayoutCropAspectRatio: AspectRatioType;
+}
+declare const aspectRatios: readonly ["1:1", "9:16", "16:9"];
+
+type RenderFrameFn = (captionsSettings: CaptionsSettings, layoutSettings: LayoutSettings, captions: Caption[], currentTime: number, targetSize: [number, number], layer: Konva.Layer, toCoef?: number, debug?: boolean) => void;
+
+declare const renderFrame: RenderFrameFn;
+declare const renderStylePreset: (stylePreset: StylePreset, size: [number, number], frames: number[], text?: string) => Promise<string[]>;
+
+/**
+ * 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, type StylePresetName, captionsjs, captionsjs as default, googleFontsList, renderCaptions, renderFrame, renderString, renderStylePreset, stylePresets };