@twick/visualizer 0.15.18 → 0.15.20

package/src/elements/caption.element.tsx

@@ -1,176 +1,46 @@
 import { CaptionProps, ElementParams } from "../helpers/types";
-import { Color, createRef, Reference, waitFor } from "@twick/core";
-import { Rect, Txt } from "@twick/2d";
+import { ThreadGenerator } from "@twick/core";
 import { splitPhraseTiming } from "../helpers/caption.utils";
-import { TRANSPARENT_COLOR } from "../helpers/constants";
-import { hexToRGB } from "../helpers/utils";
+import { getCaptionStyleHandler, getDefaultCaptionStyleHandler } from "../caption-styles";
 
 /**
  * @group CaptionElement
  * CaptionElement creates and manages styled text overlays in the visualizer scene.
- * Handles caption rendering, text effects, background styling, and timing
- * for professional video presentations and content creation.
- *
- * Features:
- * - Styled text with custom fonts, colors, and backgrounds
- * - Word-by-word timing and animation
- * - Background highlighting and styling options
- * - Text effects and animations
- * - Automatic timing and synchronization
+ * Delegates rendering and animation to registered caption style handlers.
  *
  * @param containerRef - Reference to the container element
  * @param caption - Caption configuration including text, styling, and timing
- * 
- * @example
- * ```js
- * // Basic caption
- * {
- *   id: "welcome-caption",
- *   type: "caption",
- *   s: 2,
- *   e: 8,
- *   t: "Welcome to our presentation!",
- *   props: {
- *     colors: {
- *       text: "#ffffff",
- *       background: "rgba(0,0,0,0.7)"
- *     },
- *     font: {
- *       family: "Arial",
- *       size: 48,
- *       weight: 600
- *     }
- *   }
- * }
- * 
- * // Caption with background highlighting
- * {
- *   id: "highlighted-caption",
- *   type: "caption",
- *   s: 3,
- *   e: 10,
- *   t: "Important information",
- *   capStyle: "highlight_bg",
- *   props: {
- *     colors: {
- *       text: "#ffffff",
- *       background: "rgba(255,0,0,0.8)"
- *     },
- *     font: {
- *       family: "Helvetica",
- *       size: 36,
- *       weight: 700
- *     },
- *     bgOpacity: 0.9,
- *     bgOffsetWidth: 20,
- *     bgOffsetHeight: 10,
- *     bgMargin: [10, 5],
- *     bgRadius: 15,
- *     bgPadding: [20, 15]
- *   }
- * }
- * ```
  */
 export const CaptionElement = {
   name: "caption",
-  
-  /**
-   * Generator function that creates and manages caption elements in the scene.
-   * Handles caption creation, word timing, styling, and text effects.
-   *
-   * @param params - Element parameters including container reference and caption config
-   * @returns Generator that controls the caption element lifecycle
-   * 
-   * @example
-   * ```js
-   * yield* CaptionElement.create({
-   *   containerRef: mainContainer,
-   *   caption: captionConfig
-   * });
-   * ```
-   */
-  *create({ containerRef, caption, containerProps }: ElementParams) {
+
+  *create({ containerRef, caption, containerProps }: ElementParams): ThreadGenerator {
     const words = splitPhraseTiming(caption);
-    let phraseStart = 0;
-    if (words?.length) {
-      phraseStart = words[0].s;
-    }
-    let wordsState: {
-      refs: Array<{ bgRef?: Reference<any>; textRef: Reference<any> }>;
-      props: CaptionProps[];
-      idx: number;
-      prevTime: number;
-    } = {
-      refs: [],
-      props: [],
-      idx: 0,
-      prevTime: phraseStart,
-    };
+    if (!words?.length) return;
+
+    const handler =
+      getCaptionStyleHandler(caption.capStyle ?? "") ?? getDefaultCaptionStyleHandler();
 
-    // Set container properties
     containerRef().maxWidth(containerProps?.maxWidth ?? "95%");
     containerRef().wrap(containerProps?.wrap ?? "wrap");
     containerRef().justifyContent(containerProps?.justifyContent ?? "center");
     containerRef().alignItems(containerProps?.alignItems ?? "center");
 
-    for (const word of words) {
-      wordsState.props.push(caption.props);
-      const textRef = createRef<Txt>();
-      const captionProps = caption.props;
-      containerRef().add(
-        <Txt ref={textRef} {...captionProps} text={word.t} opacity={0} />
-      );
-      if (caption.capStyle == "highlight_bg") {
-        const bgContainerRef = createRef();
-        const childTextRef = createRef();
-        const _color = new Color({...hexToRGB(captionProps.colors.bgColor), a: captionProps?.bgOpacity ?? 1});
-        containerRef().add(
-          <Rect
-            ref={bgContainerRef}
-            fill={_color}
-            width={textRef().width() + (captionProps.bgOffsetWidth ?? 30)}
-            height={textRef().height() + (captionProps.bgOffsetHeight ?? 10)}
-            margin={captionProps.bgMargin ?? [0, -5]}
-            radius={captionProps.bgRadius ?? 10}
-            padding={captionProps.bgPadding ?? [0, 15]}
-            opacity={0}
-            alignItems={"center"}
-            justifyContent={"center"}
-            layout
-          >
-            <Txt ref={childTextRef} {...captionProps} text={word.t} />
-          </Rect>
-        );
-        textRef().remove();
-        wordsState.refs.push({
-          bgRef: bgContainerRef,
-          textRef: childTextRef,
-        });
-      } else {
-        wordsState.refs.push({
-          textRef: textRef,
-        });
-      }
-      wordsState.prevTime = word.e;
-      wordsState.idx = wordsState.idx + 1;
-    }
+    const captionWithProps = {
+      ...caption,
+      props: caption.props ?? ({} as CaptionProps),
+    };
 
-    wordsState.prevTime = phraseStart;
-    wordsState.idx = 0;
+    const refs = handler.renderWords({
+      containerRef,
+      words,
+      caption: captionWithProps,
+    });
 
-    for (const word of words) {
-      if (caption.capStyle == "highlight_bg") {
-        yield* wordsState.refs[wordsState.idx]?.bgRef?.().opacity(1, 0);
-        yield* waitFor(Math.max(0, word.e - word.s));
-        yield* wordsState.refs[wordsState.idx]
-          ?.bgRef?.()
-          .fill(TRANSPARENT_COLOR, 0);
-      } else {
-        yield* wordsState.refs[wordsState.idx]?.textRef?.().opacity(1, 0);
-        yield* waitFor(Math.max(0, word.e - word.s));
-      }
-      wordsState.prevTime = word.e;
-      wordsState.idx = wordsState.idx + 1;
-    }
+    yield* handler.animateWords({
+      words,
+      refs,
+      caption: captionWithProps,
+    });
   },
 };

package/src/helpers/constants.ts

@@ -106,6 +106,122 @@ export const CAPTION_STYLE: Record<string, CaptionStyle> = {
       fontSize: 46,
     },
   },
+  outline_only: {
+    rect: {
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 8,
+    },
+    word: {
+      lineWidth: 0.5,
+      stroke: "#000000",
+      fontWeight: 600,
+      strokeFirst: true,
+      shadowOffset: [0, 0],
+      shadowBlur: 0,
+      fontFamily: "Arial",
+      fill: "#FFFFFF",
+      fontSize: 42,
+    },
+  },
+  soft_box: {
+    rect: {
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 8,
+      padding: [12, 24],
+      radius: 12,
+    },
+    word: {
+      lineWidth: 0.2,
+      stroke: "#000000",
+      fontWeight: 600,
+      strokeFirst: true,
+      shadowOffset: [-1, 1],
+      shadowColor: "rgba(0,0,0,0.3)",
+      shadowBlur: 3,
+      fontFamily: "Montserrat",
+      fill: "#FFFFFF",
+      fontSize: 40,
+    },
+  },
+  lower_third: {
+    rect: {
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 8,
+      padding: [14, 32],
+      radius: 0,
+    },
+    word: {
+      lineWidth: 0.2,
+      stroke: "#000000",
+      fontWeight: 600,
+      strokeFirst: true,
+      shadowOffset: [0, 1],
+      shadowColor: "rgba(0,0,0,0.5)",
+      shadowBlur: 2,
+      fontFamily: "Arial",
+      fill: "#FFFFFF",
+      fontSize: 38,
+    },
+  },
+  typewriter: {
+    rect: {
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 8,
+    },
+    word: {
+      lineWidth: 0.3,
+      stroke: "#000000",
+      fontWeight: 600,
+      strokeFirst: true,
+      shadowOffset: [0, 0],
+      shadowBlur: 0,
+      fontFamily: "Monaco",
+      fill: "#FFFFFF",
+      fontSize: 40,
+    },
+  },
+  karaoke: {
+    rect: {
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 8,
+    },
+    word: {
+      lineWidth: 0.35,
+      stroke: "#000000",
+      fontWeight: 700,
+      strokeFirst: true,
+      shadowOffset: [-2, 2],
+      shadowColor: "#000000",
+      shadowBlur: 4,
+      fontFamily: "Bangers",
+      fill: "#FFFFFF",
+      fontSize: 46,
+    },
+  },
+  pop_scale: {
+    rect: {
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 8,
+    },
+    word: {
+      lineWidth: 0.35,
+      stroke: "#000000",
+      fontWeight: 700,
+      strokeFirst: true,
+      shadowOffset: [-2, 2],
+      shadowColor: "#000000",
+      shadowBlur: 5,
+      fontFamily: "Bangers",
+      fill: "#FFFFFF",
+      fontSize: 46,
+    },
+  },
 };
 
 export const DEFAULT_CAPTION_COLORS = {
@@ -114,9 +230,9 @@ export const DEFAULT_CAPTION_COLORS = {
 };
 
 export const DEFAULT_CAPTION_FONT = {
-  family: "Poppins",
-  size: 48,
-  weight: 400,
+  family: "Bangers",
+  size: 46,
+  weight: 700,
 };
 
 export const TRANSPARENT_COLOR = "#FFFFFF00";

package/src/helpers/types.ts

@@ -180,9 +180,14 @@ export type CaptionProps = {
  * Defines text color, background color, and highlight colors.
  */
 export type CaptionColors = {
+  /** Main text fill color */
   text?: string;
+  /** Background color behind words/boxes */
   bgColor?: string;
+  /** Color used for per-word highlights (e.g. karaoke-style) */
   highlight?: string;
+  /** Stroke/outline color around text (e.g. classic outline style) */
+  outlineColor?: string;
 };
 
 /**

package/src/visualizer-grouped.ts

@@ -52,6 +52,18 @@ export { AudioElement } from './elements/audio.element';
 export { TextElement } from './elements/text.element';
 export { CaptionElement } from './elements/caption.element';
 
+/**
+ * @group Caption Styles
+ * @description Plugin-based caption style handlers for extensible caption rendering
+ */
+export {
+  registerCaptionStyle,
+  registerCaptionStyles,
+  getCaptionStyleHandler,
+  getDefaultCaptionStyleHandler,
+} from './caption-styles';
+export type { CaptionStyleHandler, WordRefs, WordTiming } from './caption-styles';
+
 // Shape and UI elements
 export { RectElement } from './elements/rect.element';
 export { CircleElement } from './elements/circle.element';