captions.js 0.4.0 → 0.4.2

package/README.md

@@ -1,92 +1,39 @@
-# 📖 captions.js Monorepo Scripts Cheat Sheet
+> [!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**.
 
-This cheat sheet summarizes all the key scripts for working with the `captions.js` monorepo. Use `pnpm` to run scripts in individual packages.
+💌 Want to know when Captions.js is released?
+Star or watch the repo on GitHub to get updates!
 
----
+# Captions.js
 
-## 🌟 General `pnpm` Commands
+Render styled animated captions on canvas — works both on client and server side using Node.js and FFmpeg.
 
-| Command                                     | Description                                                  |
-| ------------------------------------------- | ------------------------------------------------------------ |
-| `pnpm install`                              | Installs all dependencies for all packages in the monorepo.  |
-| `pnpm --filter <package> run <script>`      | Runs a script `<script>` for a specific package `<package>`. |
-| `pnpm build`                                | Builds all packages that have a `build` script.              |
-| `pnpm clean`                                | Cleans build artifacts if a `clean` script is defined.       |
+[**Live Demo**](https://maskin25.github.io/captions.js/)
 
-> **Note:** `<package>` refers to the package name in `packages/`, e.g., `@captions/core`, `captions-demo`, or `captions-storybook`.
+[**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/) -->
 
-## 📦 Package: `@captions/core`
+## Features
 
-| Script  | Command                                   | Description                                                              |
-| ------- | ----------------------------------------- | ------------------------------------------------------------------------ |
-| `build` | `pnpm --filter @captions/core run build`  | Builds the library using `tsup` (CJS, ESM, and TypeScript declarations). |
-| `clean` | `pnpm --filter @captions/core run clean`  | Deletes the build folder (`dist`).                                       |
+- **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.
 
-**Example:**
-```bash
-pnpm --filter @captions/core run build
-```
-
----
+## Installation
 
-## 🎨 Demo App: `captions-demo`
+To install Captions.js, use npm or yarn:
 
-| Script    | Command                                 | Description                                                        |
-| --------- | --------------------------------------- | ------------------------------------------------------------------ |
-| `dev`     | `pnpm --filter captions-demo run dev`     | Runs the demo locally with Vite (default: `http://localhost:5173`). |
-| `build`   | `pnpm --filter captions-demo run build`   | Builds the demo for production into the `dist` folder.             |
-| `preview` | `pnpm --filter captions-demo run preview` | Serves the built demo locally for preview.                         |
-
-**Example:**
 ```bash
-pnpm --filter captions-demo run dev
+npm install captions.js
 ```
 
----
-
-## 📚 Storybook: `captions-storybook`
-
-| Script            | Command                                           | Description                                                |
-| ----------------- | ------------------------------------------------- | ---------------------------------------------------------- |
-| `storybook`       | `pnpm --filter captions-storybook run storybook`  | Runs Storybook locally with Vite (`http://localhost:6006`). |
-| `build-storybook` | `pnpm --filter captions-storybook run build-storybook` | Builds a static Storybook site into `storybook-static`.    |
-| `deploy`          | `pnpm --filter captions-storybook run deploy`     | Builds and deploys Storybook to GitHub Pages.              |
+or
 
-**Example:**
 ```bash
-pnpm --filter captions-storybook run storybook
+yarn add captions.js
 ```
 
----
-
-## ⚡ Tips & Recommendations
-
-1.  **Targeted Scripts:** Always run scripts using `pnpm --filter` to ensure you're using the correct local binaries for that package.
-    ```bash
-    pnpm --filter <package> run <script>
-    ```
-
-2.  **Troubleshooting:** If you encounter issues after updating packages, run this sequence to perform a clean reinstall:
-    ```bash
-    # Clean up all node_modules and lockfile
-    rm -rf node_modules packages/*/node_modules
-    rm pnpm-lock.yaml
-    
-    # Prune the pnpm store and reinstall
-    pnpm store prune
-    pnpm install
-    ```
-
-3.  **Global Build Script (Optional):** For convenience, you can add a global `build` script to the root `package.json` to build the entire monorepo with one command.
-
-    ```json
-    "scripts": {
-      "build": "pnpm --filter @captions/core run build && pnpm --filter captions-demo run build && pnpm --filter captions-storybook run build-storybook"
-    }
-    ```
-    Then, you can simply run:
-    ```bash
-    pnpm run build
-    ```
+For development see [DEVELOPMENT.md](./DEVELOPMENT.md).

package/dist/index.d.mts

@@ -1,3 +1,262 @@
+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"];
+
+/**
+ * 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;
+    };
+}
+/**
+ * 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>;
+
+/**
+ * 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;
+    /** 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;
+
+/**
+ * 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, stylePresets };

package/dist/index.d.ts

@@ -1,3 +1,262 @@
+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"];
+
+/**
+ * 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;
+    };
+}
+/**
+ * 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>;
+
+/**
+ * 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;
+    /** 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;
+
+/**
+ * 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, stylePresets };