@twick/visualizer 0.15.19 → 0.15.21

package/src/controllers/element.controller.ts

@@ -3,6 +3,8 @@ import { CaptionElement } from "../elements/caption.element";
 import { CircleElement } from "../elements/circle.element";
 import { ImageElement } from "../elements/image.element";
 import { RectElement } from "../elements/rect.element";
+import { ArrowElement } from "../elements/arrow.element";
+import { LineElement } from "../elements/line.element";
 import { SceneElement } from "../elements/scene.element";
 import { TextElement } from "../elements/text.element";
 import { VideoElement } from "../elements/video.element";
@@ -33,6 +35,8 @@ export class ElementController {
     elementController.register(AudioElement);
     elementController.register(CircleElement);
     elementController.register(RectElement);
+    elementController.register(ArrowElement);
+    elementController.register(LineElement);
   }
 
   const elementController = new ElementController();  

package/src/elements/arrow.element.tsx

@@ -0,0 +1,75 @@
+import { ElementParams } from "../helpers/types";
+import { all, createRef, waitFor } from "@twick/core";
+import { Layout, Polygon, Rect } from "@twick/2d";
+import { addAnimation } from "../helpers/element.utils";
+import { logger } from "../helpers/log.utils";
+
+const HEAD_OFFSET = 2;
+
+/**
+ * Arrow element: bar + triangle (callout) for the visualizer.
+ * Matches canvas arrow layout: bar from left, triangle overlapping at the tip.
+ */
+export const ArrowElement = {
+  name: "arrow",
+
+  *create({ containerRef, element, view }: ElementParams) {
+    const elementRef = createRef<any>();
+    yield* waitFor(element?.s ?? 0);
+    logger(`ArrowElement: ${element?.id}`);
+
+    const w = element?.props?.width ?? 220;
+    const h = element?.props?.height ?? 14;
+    const fill = element?.props?.fill ?? "#f59e0b";
+    const radius = element?.props?.radius ?? 4;
+    const rotation = element?.props?.rotation ?? 0;
+    const opacity = element?.props?.opacity ?? 1;
+    const cx = element?.props?.x ?? 0;
+    const cy = element?.props?.y ?? 0;
+
+    // Match canvas triangle size: Polygon is inscribed in its size box so appears
+    // smaller than Fabric’s Triangle (which fills its box). Scale up ~1.3×.
+    const HEAD_SIZE_MULT = 1.8 * 1.3;
+    const headSize = h * HEAD_SIZE_MULT;
+    const barLength = w - headSize * 0.5 + HEAD_OFFSET;
+    const barWidth = w;
+
+    // Single group so one ref for animations
+    const arrowGroup = (
+      <Layout
+        ref={elementRef}
+        key={element?.id}
+        x={cx}
+        y={cy}
+        rotation={rotation}
+        opacity={opacity}
+      >
+        <Rect
+          x={-barWidth / 2 + barLength / 2}
+          y={0}
+          width={barLength}
+          height={h}
+          fill={fill}
+          radius={radius}
+        />
+        <Polygon
+          x={barWidth / 2 - headSize * 0.25}
+          y={0}
+          width={headSize}
+          height={headSize}
+          sides={3}
+          fill={fill}
+          rotation={90}
+        />
+      </Layout>
+    );
+
+    yield containerRef().add(arrowGroup);
+
+    yield* all(
+      addAnimation({ elementRef, element: element!, view }),
+      waitFor(Math.max(0, (element?.e ?? 0) - (element?.s ?? 0)))
+    );
+    yield elementRef().remove();
+  },
+};

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/elements/index.ts

@@ -9,5 +9,7 @@ export { AudioElement } from './audio.element';
 export { TextElement } from './text.element';
 export { CaptionElement } from './caption.element';
 export { RectElement } from './rect.element';
+export { ArrowElement } from './arrow.element';
+export { LineElement } from './line.element';
 export { CircleElement } from './circle.element';
 export { SceneElement } from './scene.element';

package/src/elements/line.element.tsx

@@ -0,0 +1,17 @@
+import { ElementParams } from "../helpers/types";
+import { RectElement } from "./rect.element";
+
+/**
+ * LineElement: visualizer representation for line/segment shapes.
+ * Uses the same renderer as RectElement so width/height/fill/rotation
+ * map directly to the exported video.
+ */
+export const LineElement = {
+  name: "line",
+
+  *create(params: ElementParams) {
+    // Delegate to RectElement to reuse rendering and animation behavior.
+    yield* RectElement.create(params);
+  },
+};
+

package/src/elements/text.element.tsx

@@ -122,6 +122,10 @@ export const TextElement = {
           alignItems={"center"}
           justifyContent={"center"}
           layout
+          x={element.props?.x}
+          y={element.props?.y}
+          rotation={element.props?.rotation}
+          opacity={element.props?.opacity}
         >
           <Txt
             ref={innerTextRef}

package/src/helpers/constants.ts

@@ -41,6 +41,7 @@ export const TRACK_TYPES = {
   CAPTION: "caption",
   SCENE: "scene",
   ELEMENT: "element",
+  EFFECT: "effect",
 } as const;
 
 export const CAPTION_STYLE: Record<string, CaptionStyle> = {
@@ -106,6 +107,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 +231,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/project.ts

@@ -1,6 +1,10 @@
 import { makeProject } from "@twick/core";
+import { getActiveEffectsForFrame } from "@twick/effects";
 import { scene } from "./visualizer";
 
-export default makeProject({
+const project = makeProject({
   scenes: [scene],
 });
+(project as import("@twick/core").Project).getActiveEffectsForFrame =
+  getActiveEffectsForFrame;
+export default project;

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';