@twick/visualizer 0.15.24 → 0.15.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twick/visualizer",
-  "version": "0.15.24",
+  "version": "0.15.25",
   "license": "https://github.com/ncounterspecialist/twick/blob/main/LICENSE.md",
   "scripts": {
     "start": "twick editor --projectFile ./src/live.tsx",
@@ -23,19 +23,19 @@
   },
   "dependencies": {
     "@preact/signals": "^1.2.1",
-    "@twick/2d": "^0.15.24",
-    "@twick/core": "^0.15.24",
-    "@twick/effects": "0.15.24",
-    "@twick/media-utils": "0.15.24",
-    "@twick/renderer": "^0.15.24",
-    "@twick/vite-plugin": "^0.15.24",
+    "@twick/2d": "^0.15.25",
+    "@twick/core": "^0.15.25",
+    "@twick/effects": "0.15.25",
+    "@twick/media-utils": "0.15.25",
+    "@twick/renderer": "^0.15.25",
+    "@twick/vite-plugin": "^0.15.25",
     "crelt": "^1.0.6",
     "date-fns": "^4.1.0",
     "preact": "^10.19.2"
   },
   "devDependencies": {
-    "@twick/cli": "^0.15.24",
-    "@twick/ui": "^0.15.24",
+    "@twick/cli": "^0.15.25",
+    "@twick/ui": "^0.15.25",
     "typescript": "5.4.2",
     "typedoc": "^0.25.8",
     "typedoc-plugin-markdown": "^3.17.1",

package/src/caption-styles/highlight-bg.handler.tsx

@@ -26,11 +26,11 @@ export const highlightBgHandler: CaptionStyleHandler = {
         <Rect
           ref={bgContainerRef}
           fill={_color}
-          width={textRef().width() + (captionProps.bgOffsetWidth ?? 30)}
-          height={textRef().height() + (captionProps.bgOffsetHeight ?? 10)}
+          width={textRef().width() + (captionProps.bgOffsetWidth ?? 20)}
+          height={textRef().height() + (captionProps.bgOffsetHeight ?? 8)}
           margin={captionProps.bgMargin ?? [0, -5]}
           radius={captionProps.bgRadius ?? 10}
-          padding={captionProps.bgPadding ?? [0, 15]}
+          padding={captionProps.bgPadding ?? [0, 10]}
           opacity={0}
           alignItems={"center"}
           justifyContent={"center"}

package/src/caption-styles/index.ts

@@ -7,6 +7,7 @@ import { softBoxHandler } from "./soft-box.handler";
 import { lowerThirdHandler } from "./lower-third.handler";
 import { typewriterHandler } from "./typewriter.handler";
 import { karaokeHandler } from "./karaoke.handler";
+import { karaokeWordHandler } from "./karaoke-word.handler";
 import { popScaleHandler } from "./pop-scale.handler";
 
 /**
@@ -22,6 +23,7 @@ export function registerCaptionStyles(): void {
   registerCaptionStyle(lowerThirdHandler);
   registerCaptionStyle(typewriterHandler);
   registerCaptionStyle(karaokeHandler);
+  registerCaptionStyle(karaokeWordHandler);
   registerCaptionStyle(popScaleHandler);
 }
 

package/src/caption-styles/karaoke-word.handler.tsx

@@ -0,0 +1,54 @@
+import { all, Color, createRef, waitFor } from "@twick/core";
+import { Txt } from "@twick/2d";
+import { hexToRGB } from "../helpers/utils";
+import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
+
+const INACTIVE_OPACITY = 0.45;
+
+
+export const karaokeWordHandler: CaptionStyleHandler = {
+  id: "karaoke-word",
+
+  renderWords({ containerRef, words, caption }) {
+    const captionProps = caption.props;
+
+    const refs: Array<{ textRef: ReturnType<typeof createRef<Txt>> }> = [];
+
+    for (const word of words) {
+      const textRef = createRef<Txt>();
+      containerRef().add(
+        <Txt
+          ref={textRef}
+          {...captionProps}
+          text={word.t}
+          opacity={INACTIVE_OPACITY}
+        />
+      );
+      refs.push({ textRef });
+    }
+
+    return { refs };
+  },
+  *animateWords({ words, refs, caption }) {
+    const textColor = caption.props.colors?.text;
+    const highlightColor = caption.props.colors?.highlight ?? textColor;
+    for (let i = 0; i < words.length; i++) {
+      // Turn the previous word back to base color and remove outline,
+      // so its fill is clearly visible and not dominated by stroke.
+      if (i > 0) {
+        yield* all(
+          refs.refs[i - 1].textRef().fill(textColor, 0),
+          refs.refs[i - 1].textRef().opacity(INACTIVE_OPACITY, 0)
+        );
+      }
+      // Highlight the current word using the highlight color.
+      // Keep its existing lineWidth/stroke so it feels “active”.
+      yield* all(
+        refs.refs[i].textRef().lineWidth(0, 0),
+        refs.refs[i].textRef().fill(highlightColor, 0),
+        refs.refs[i].textRef().opacity(1, 0)
+      );
+      yield* waitFor(Math.max(0, words[i].e - words[i].s));
+    }
+  },
+};

package/src/caption-styles/karaoke.handler.tsx

@@ -1,20 +1,16 @@
-import { Color, createRef, waitFor } from "@twick/core";
+import { all, Color, createRef, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
 import { hexToRGB } from "../helpers/utils";
 import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
 
-const INACTIVE_OPACITY = 0.5;
+const INACTIVE_OPACITY = 0.45;
 
-/**
- * Karaoke: all words visible; current word switches to highlight color (one Txt per word, animate fill).
- * Same ref/animate pattern as word_by_word; no overlay needed.
- */
 export const karaokeHandler: CaptionStyleHandler = {
   id: "karaoke",
 
   renderWords({ containerRef, words, caption }) {
     const captionProps = caption.props;
-    const textColor = captionProps.colors?.text ?? "#ffffff";
+
     const refs: Array<{ textRef: ReturnType<typeof createRef<Txt>> }> = [];
 
     for (const word of words) {
@@ -23,7 +19,6 @@ export const karaokeHandler: CaptionStyleHandler = {
         <Txt
           ref={textRef}
           {...captionProps}
-          fill={textColor}
           text={word.t}
           opacity={INACTIVE_OPACITY}
         />
@@ -35,24 +30,21 @@ export const karaokeHandler: CaptionStyleHandler = {
   },
 
   *animateWords({ words, refs, caption }) {
-    const textColor = caption.props.colors?.text ?? "#ffffff";
-    const highlightColor = caption.props.colors?.highlight ?? "#ff4081";
-    const textColorObj = new Color({ ...hexToRGB(textColor), a: 1 });
-    const highlightColorObj = new Color({ ...hexToRGB(highlightColor), a: 1 });
-    const n = refs.refs.length;
-
+    const textColor = caption.props.colors?.text;
+    const highlightColor = caption.props.colors?.highlight ?? textColor;
     for (let i = 0; i < words.length; i++) {
-      for (let j = 0; j < n; j++) {
-        refs.refs[j].textRef().opacity(INACTIVE_OPACITY);
-        refs.refs[j].textRef().fill(textColorObj);
+      if (i > 0) {
+        yield* all(
+          refs.refs[i - 1].textRef().lineWidth(0, 0),
+          refs.refs[i - 1].textRef().fill(textColor, 0),
+        );
       }
-      refs.refs[i].textRef().opacity(1);
-      refs.refs[i].textRef().fill(highlightColorObj, 0);
+      yield* all(
+        refs.refs[i].textRef().lineWidth(0, 0),
+        refs.refs[i].textRef().fill(highlightColor, 0),
+        refs.refs[i].textRef().opacity(1, 0)
+      );
       yield* waitFor(Math.max(0, words[i].e - words[i].s));
     }
-    for (let j = 0; j < n; j++) {
-      refs.refs[j].textRef().opacity(INACTIVE_OPACITY);
-      refs.refs[j].textRef().fill(textColorObj);
-    }
   },
 };

package/src/caption-styles/lower-third.handler.tsx

@@ -1,4 +1,4 @@
-import { Color, createRef, waitFor } from "@twick/core";
+import { all, Color, createRef, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
 import { hexToRGB } from "../helpers/utils";
 import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
@@ -25,9 +25,17 @@ export const lowerThirdHandler: CaptionStyleHandler = {
     return { refs };
   },
 
-  *animateWords({ words, refs }) {
+  *animateWords({ words, refs, caption }) {
+    const textColor = caption.props.colors?.text;
+    const highlightColor = caption.props.colors?.highlight ?? textColor;
     for (let i = 0; i < words.length; i++) {
-      yield* refs.refs[i].textRef().opacity(1, 0);
+      if (i > 0) {
+        yield* all(refs.refs[i-1].textRef().lineWidth(0, 0), refs.refs[i-1].textRef().fill(textColor, 0));
+
+      }
+      yield* all(
+        refs.refs[i].textRef().fill(highlightColor, 0),
+        refs.refs[i].textRef().opacity(1, 0));
       yield* waitFor(Math.max(0, words[i].e - words[i].s));
     }
   },

package/src/caption-styles/outline-only.handler.tsx

@@ -9,10 +9,11 @@ export const outlineOnlyHandler: CaptionStyleHandler = {
     const captionProps = caption.props;
     const refs: Array<{ textRef: ReturnType<typeof createRef<Txt>> }> = [];
 
+
     for (const word of words) {
       const textRef = createRef<Txt>();
       containerRef().add(
-        <Txt ref={textRef} {...captionProps} text={word.t} opacity={0} />
+        <Txt ref={textRef} {...captionProps} text={word.t} opacity={1} lineWidth={0}/>
       );
       refs.push({ textRef });
     }
@@ -20,9 +21,12 @@ export const outlineOnlyHandler: CaptionStyleHandler = {
     return { refs };
   },
 
-  *animateWords({ words, refs }) {
+  *animateWords({ words, refs, caption }) {
     for (let i = 0; i < words.length; i++) {
-      yield* refs.refs[i].textRef().opacity(1, 0);
+      if(i > 0) {
+        yield* refs.refs[i-1].textRef().lineWidth(0, 0);
+      }
+      yield* refs.refs[i].textRef().lineWidth((caption.props.lineWidth ?? 0.4)*5, 0);
       yield* waitFor(Math.max(0, words[i].e - words[i].s));
     }
   },

package/src/caption-styles/pop-scale.handler.tsx

@@ -1,8 +1,8 @@
-import { createRef, waitFor } from "@twick/core";
+import { all, createRef, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
 import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
 
-const POP_DURATION = 0.2;
+const POP_DURATION = 0.025;
 
 /**
  * Pop: words pop in with a quick opacity fade (same ref/animate pattern as word_by_word).
@@ -26,9 +26,14 @@ export const popScaleHandler: CaptionStyleHandler = {
     return { refs };
   },
 
-  *animateWords({ words, refs }) {
+  *animateWords({ words, refs, caption }) {
+    const textColor = caption.props.colors?.text;
+    const highlightColor = caption.props.colors?.highlight ?? textColor;
     for (let i = 0; i < words.length; i++) {
-      yield* refs.refs[i].textRef().opacity(1, POP_DURATION);
+      if (i > 0) {
+        yield* all(refs.refs[i - 1].textRef().scale(0.95, 0), refs.refs[i - 1].textRef().lineWidth(0, 0), refs.refs[i-1].textRef().fill(textColor, 0))
+      }
+      yield* all(refs.refs[i].textRef().opacity(1, POP_DURATION), refs.refs[i].textRef().fill(highlightColor, 0), refs.refs[i].textRef().lineWidth(0, 0), refs.refs[i].textRef().scale(1.15, POP_DURATION));
       yield* waitFor(Math.max(0, words[i].e - words[i].s - POP_DURATION));
     }
   },

package/src/caption-styles/soft-box.handler.tsx

@@ -1,4 +1,4 @@
-import { Color, createRef, waitFor } from "@twick/core";
+import { all, Color, createRef, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
 import { hexToRGB } from "../helpers/utils";
 import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
@@ -21,9 +21,17 @@ export const softBoxHandler: CaptionStyleHandler = {
     return { refs };
   },
 
-  *animateWords({ words, refs }) {
+  *animateWords({ words, refs, caption }) {
+    const textColor = caption.props.colors?.text;
+    const highlightColor = caption.props.colors?.highlight ?? textColor;
     for (let i = 0; i < words.length; i++) {
-      yield* refs.refs[i].textRef().opacity(1, 0);
+      if (i > 0) {
+        yield* all(refs.refs[i-1].textRef().lineWidth(0, 0), refs.refs[i-1].textRef().fill(textColor, 0));
+
+      }
+      yield* all(
+        refs.refs[i].textRef().fill(highlightColor, 0),
+        refs.refs[i].textRef().opacity(1, 0));
       yield* waitFor(Math.max(0, words[i].e - words[i].s));
     }
   },

package/src/caption-styles/typewriter.handler.tsx

@@ -1,33 +1,79 @@
 import { createRef, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
-import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
+import type {
+  CaptionStyleHandler,
+  RenderWordsParams,
+  AnimateWordsParams,
+} from "./types";
 
 /**
- * Typewriter: words appear one by one (same pattern as word_by_word).
- * Letter-by-letter would require a wrapper per word so prefixes overlay; follow highlight-bg structure if adding later.
+ * Typewriter: phrase-level, letter-by-letter typing effect.
+ * Mirrors the behavior of text-effects/TypewriterEffect but scoped to a
+ * single caption phrase. All words in the phrase are rendered as one
+ * continuous string and revealed character by character over the phrase
+ * duration.
  */
 export const typewriterHandler: CaptionStyleHandler = {
   id: "typewriter",
 
-  renderWords({ containerRef, words, caption }) {
+  renderWords({ containerRef, words, caption }: RenderWordsParams) {
     const captionProps = caption.props;
-    const refs: Array<{ textRef: ReturnType<typeof createRef<Txt>> }> = [];
-
-    for (const word of words) {
-      const textRef = createRef<Txt>();
-      containerRef().add(
-        <Txt ref={textRef} {...captionProps} text={word.t} opacity={0} />
-      );
-      refs.push({ textRef });
-    }
+    const phraseText =
+      caption.t && caption.t.length > 0
+        ? caption.t
+        : words.map((w) => w.t).join(" ");
+
+    const textRef = createRef<Txt>();
+    containerRef().add(
+      <Txt ref={textRef} {...captionProps} text={phraseText} />
+    );
 
-    return { refs };
+    return { refs: [{ textRef }] };
   },
 
-  *animateWords({ words, refs }) {
-    for (let i = 0; i < words.length; i++) {
-      yield* refs.refs[i].textRef().opacity(1, 0);
-      yield* waitFor(Math.max(0, words[i].e - words[i].s));
+  *animateWords({ words, refs }: AnimateWordsParams) {
+    if (!refs.refs.length || !words.length) {
+      return;
+    }
+
+    const textRef = refs.refs[0].textRef;
+    const fullText = textRef().text() ?? "";
+
+    if (!fullText.length) {
+      // Nothing to animate; just keep the text as-is.
+      return;
+    }
+
+    // Compute total phrase duration from word timings.
+    const phraseStart = words[0].s;
+    const phraseEnd = words[words.length - 1].e;
+    const totalDuration = Math.max(0, phraseEnd - phraseStart);
+
+    if (totalDuration <= 0) {
+      textRef().text(fullText);
+      return;
+    }
+
+    // Preserve original size to avoid layout shifts while typing.
+    const size = textRef().size();
+    textRef().text("");
+    textRef().size(size);
+
+    // Left-align for a more natural typing feel.
+    textRef().textAlign("left");
+
+    // Reserve a small buffer at the end so the final state is visible.
+    const bufferTime = Math.min(totalDuration * 0.1, 0.5);
+    const effectiveDuration = Math.max(0.001, totalDuration - bufferTime);
+    const interval = effectiveDuration / fullText.length;
+
+    // Small initial pause before the first character.
+    yield* waitFor(interval);
+
+    // Reveal each character sequentially.
+    for (let i = 0; i < fullText.length; i++) {
+      yield* waitFor(interval);
+      textRef().text(fullText.substring(0, i + 1));
     }
   },
 };

package/src/caption-styles/word-by-word-with-bg.handler.tsx

@@ -1,4 +1,4 @@
-import { Color, createRef, waitFor } from "@twick/core";
+import { all, Color, createRef, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
 import { hexToRGB } from "../helpers/utils";
 import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
@@ -21,9 +21,17 @@ export const wordByWordWithBgHandler: CaptionStyleHandler = {
     return { refs };
   },
 
-  *animateWords({ words, refs }) {
+  *animateWords({ words, refs, caption }) {
+    const textColor = caption.props.colors?.text;
+    const highlightColor = caption.props.colors?.highlight ?? textColor;
     for (let i = 0; i < words.length; i++) {
-      yield* refs.refs[i].textRef().opacity(1, 0);
+      if (i > 0) {
+        yield* all(refs.refs[i-1].textRef().lineWidth(0, 0), refs.refs[i-1].textRef().fill(textColor, 0));
+
+      }
+      yield* all(
+        refs.refs[i].textRef().fill(highlightColor, 0),
+        refs.refs[i].textRef().opacity(1, 0));
       yield* waitFor(Math.max(0, words[i].e - words[i].s));
     }
   },

package/src/caption-styles/word-by-word.handler.tsx

@@ -1,4 +1,4 @@
-import { createRef, waitFor } from "@twick/core";
+import { all, createRef, useLogger, waitFor } from "@twick/core";
 import { Txt } from "@twick/2d";
 import type { CaptionStyleHandler, RenderWordsParams, AnimateWordsParams } from "./types";
 
@@ -20,9 +20,17 @@ export const wordByWordHandler: CaptionStyleHandler = {
     return { refs };
   },
 
-  *animateWords({ words, refs }) {
+  *animateWords({ words, refs, caption }) {
+    const textColor = caption.props.colors?.text;
+    const highlightColor = caption.props.colors?.highlight ?? textColor;
     for (let i = 0; i < words.length; i++) {
-      yield* refs.refs[i].textRef().opacity(1, 0);
+      if (i > 0) {
+        yield* all(refs.refs[i-1].textRef().lineWidth(0, 0), refs.refs[i-1].textRef().fill(textColor, 0));
+
+      }
+      yield* all(
+        refs.refs[i].textRef().fill(highlightColor, 0),
+        refs.refs[i].textRef().opacity(1, 0));
       yield* waitFor(Math.max(0, words[i].e - words[i].s));
     }
   },

package/src/components/track.tsx

@@ -5,7 +5,7 @@
 
 import { Layout, Rect, View2D, Audio, Img, Txt } from "@twick/2d";
 import { VisualizerTrack, WatermarkInput } from "../helpers/types";
-import { all, createRef, ThreadGenerator, waitFor } from "@twick/core";
+import { all, createRef, ThreadGenerator, useLogger, waitFor } from "@twick/core";
 import {
   CAPTION_STYLE,
   DEFAULT_CAPTION_COLORS,
@@ -89,74 +89,93 @@ export function* makeCaptionTrack({
   track: VisualizerTrack;
 }) {
   let prevTime = 0;
+
   const captionTrackRef = createRef<any>();
   view.add(<Layout size={"100%"} ref={captionTrackRef} />);
 
   const tProps = track?.props;
   const defaultCapStyle = "highlight_bg";
+  
+  for (const element of track.elements) {
+    const eProps = element.props ?? {};
+    // wordsMs belongs to caption timing only – keep it out of visual style merging.
+    const { wordsMs, ...elementPropsWithoutWords } = eProps as any;
 
-  const applyToAll = tProps?.applyToAll ?? false;
-
-  const trackDefaultProps =
-    (CAPTION_STYLE[tProps?.capStyle ?? defaultCapStyle] || CAPTION_STYLE[defaultCapStyle] || {}).word || {};
+    const resolvedCapStyle =
+      (elementPropsWithoutWords as any)?.capStyle ?? tProps?.capStyle ?? defaultCapStyle;
 
-  for (const element of track.elements) {
-    const eProps = element.props;
-    const resolvedCapStyle = eProps?.capStyle ?? tProps?.capStyle ?? defaultCapStyle;
-    const rectStyle =
-      (CAPTION_STYLE[resolvedCapStyle] || CAPTION_STYLE[defaultCapStyle] || {}).rect ||
-      {};
+    const styleConfig = CAPTION_STYLE[resolvedCapStyle] || CAPTION_STYLE[defaultCapStyle] || {};
+    const trackDefaultProps = (styleConfig as any).word || {};
+    const rectStyle = (styleConfig as any).rect || {};
     // Cast alignItems/justifyContent as any to satisfy RectProps
     const mappedRectStyle = {
       ...rectStyle,
       justifyContent: rectStyle.justifyContent as any,
       alignItems: rectStyle.alignItems as any,
+      ...(tProps?.rectProps ?? {}),
     };
 
-    const phraseColors = applyToAll ? tProps?.colors : eProps?.colors ?? tProps?.colors ?? DEFAULT_CAPTION_COLORS;
+    // Resolve colors with priority: element.props.colors > track.props.colors > defaults.
+    const elementColors = (elementPropsWithoutWords as any)?.colors;
+    const trackColors = tProps?.colors;
+    const phraseColors = elementColors ?? trackColors ?? DEFAULT_CAPTION_COLORS;
 
-    const resolvedFont = applyToAll ? tProps?.font : eProps?.font ?? tProps?.font ?? DEFAULT_CAPTION_FONT;
-    const defaults = trackDefaultProps as { fontFamily?: string; fontSize?: number; fontWeight?: number };
-    const phraseProps = {
+    // Resolve font with priority: element.props.font > track.props.font > defaults.
+    const elementFont = (elementPropsWithoutWords as any)?.font;
+    const trackFont = tProps?.font;
+    const resolvedFont = elementFont ?? trackFont ?? DEFAULT_CAPTION_FONT;
+
+
+    const basePhraseStyle = {
       ...trackDefaultProps,
-      ...(tProps?.captionProps || {}),
+      ...tProps,
+      ...elementPropsWithoutWords,
+    };
+
+    const bgOpacityFromBase = (basePhraseStyle as any)?.bgOpacity;
+
+    const phraseProps = {
+      ...basePhraseStyle,
       colors: phraseColors,
+      stroke: phraseColors.outlineColor,
       font: resolvedFont,
-      fontFamily: resolvedFont?.family ?? defaults?.fontFamily ?? DEFAULT_CAPTION_FONT.family,
-      fontSize: resolvedFont?.size ?? defaults?.fontSize ?? DEFAULT_CAPTION_FONT.size,
-      fontWeight: resolvedFont?.weight ?? defaults?.fontWeight ?? DEFAULT_CAPTION_FONT.weight,
+      fontFamily:
+        resolvedFont.family,
+      fontSize:
+        resolvedFont.size,
+      fontWeight:
+        resolvedFont.weight,
       fill: phraseColors.text,
       bgColor: phraseColors.bgColor,
-      bgOpacity: tProps?.bgOpacity ?? 1,
+      bgOpacity: bgOpacityFromBase ?? tProps?.bgOpacity ?? 1,
     };
 
     yield* waitFor(element?.s - prevTime);
     const phraseRef = createRef<any>();
+    const rectProps = tProps?.rectProps ?? {};
     captionTrackRef().add(
       <Rect
         ref={phraseRef}
         key={element.id}
         {...mappedRectStyle}
-        x={applyToAll ? tProps?.x : eProps?.x ?? tProps?.x}
-        y={applyToAll ? tProps?.y : eProps?.y ?? tProps?.y}
+        x={basePhraseStyle.x}
+        y={basePhraseStyle.y}
         layout
       />
     );
-    // Allow styles to tweak how phrase-level props are interpreted.
-    // For classic outline, use explicit outlineColor so it is independent
-    // from per-word highlight color.
-    const styledPhraseProps = {
+
+    // Ensure timing metadata (wordsMs) is preserved on the caption props
+    // while keeping it out of the visual style merging above.
+    const captionPropsForElement = {
       ...phraseProps,
-      ...(resolvedCapStyle === "outline_only" && phraseColors?.outlineColor
-        ? { stroke: phraseColors.outlineColor }
-        : {}),
+      ...(wordsMs ? { wordsMs } : {}),
     };
 
     const styleHandler = getCaptionStyleHandler(resolvedCapStyle ?? "");
     if (styleHandler?.preparePhraseContainer) {
       styleHandler.preparePhraseContainer({
         phraseRef,
-        phraseProps: styledPhraseProps,
+        phraseProps,
       });
     }
     yield* elementController.get("caption")?.create({
@@ -165,7 +184,7 @@ export function* makeCaptionTrack({
         ...element,
         t: element.t ?? "",
         capStyle: eProps?.capStyle ?? tProps?.capStyle,
-        props: styledPhraseProps,
+        props: captionPropsForElement,
       },
       view,
     });

package/src/elements/caption.element.tsx

@@ -3,6 +3,43 @@ import { ThreadGenerator } from "@twick/core";
 import { splitPhraseTiming } from "../helpers/caption.utils";
 import { getCaptionStyleHandler, getDefaultCaptionStyleHandler } from "../caption-styles";
 
+function computeWordTimings(caption: ElementParams["caption"]) {
+  if (!caption) {
+    return [];
+  }
+
+  const text = caption.t ?? "";
+  const baseWords = text.split(" ").filter((w) => w.length > 0);
+  if (!baseWords.length) {
+    return [];
+  }
+
+  // wordsMs is stored in milliseconds (absolute along the media timeline).
+  const wordsMs: number[] | undefined = (caption as any)?.props?.wordsMs;
+
+  if (!Array.isArray(wordsMs) || wordsMs.length < baseWords.length) {
+    // Fallback: proportional split across phrase duration.
+    return splitPhraseTiming(caption);
+  }
+
+  const phraseEndSec = caption.e;
+
+  return baseWords.map((word, index) => {
+    const startMs = wordsMs[index];
+    const endMs =
+      index + 1 < wordsMs.length ? wordsMs[index + 1] : phraseEndSec * 1000;
+
+    const startSec = startMs / 1000;
+    const endSec = endMs / 1000;
+
+    return {
+      t: word,
+      s: startSec,
+      e: endSec,
+    };
+  });
+}
+
 /**
  * @group CaptionElement
  * CaptionElement creates and manages styled text overlays in the visualizer scene.
@@ -15,7 +52,7 @@ export const CaptionElement = {
   name: "caption",
 
   *create({ containerRef, caption, containerProps }: ElementParams): ThreadGenerator {
-    const words = splitPhraseTiming(caption);
+    const words = computeWordTimings(caption);
     if (!words?.length) return;
 
     const handler =