@twick/visualizer 0.15.12 → 0.15.14

package/package.json

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

package/src/components/track.tsx

@@ -3,8 +3,8 @@
  * including video, audio, captions, scenes, and elements.
  */
 
-import { Layout, Rect, View2D, Audio } from "@twick/2d";
-import { VisualizerTrack } from "../helpers/types";
+import { Layout, Rect, View2D, Audio, Img, Txt } from "@twick/2d";
+import { VisualizerTrack, WatermarkInput } from "../helpers/types";
 import { all, Color, createRef, ThreadGenerator, waitFor } from "@twick/core";
 import {
   CAPTION_STYLE,
@@ -13,6 +13,7 @@ import {
 } from "../helpers/constants";
 import { logger } from "../helpers/log.utils";
 import elementController from "../controllers/element.controller";
+import watermarkController from "../controllers/watermark.controller";
 import { hexToRGB } from "../helpers/utils";
 
 /**
@@ -218,3 +219,28 @@ export function* makeElementTrack({
   yield* all(...sequence);
   yield elementTrackRef().remove();
 }
+
+/**
+ * Creates a watermark overlay on top of all tracks.
+ * Dispatches to the registered watermark renderer by type (text | image).
+ * Added last to ensure it renders on top of all content.
+ */
+export function* makeWatermarkTrack({
+  view,
+  watermark,
+  duration,
+}: {
+  view: View2D;
+  watermark: WatermarkInput;
+  duration: number;
+}) {
+  if (duration <= 0) return;
+
+  // Add watermark after other tracks have started (ensures it renders on top)
+  yield* waitFor(0.001);
+
+  const renderer = watermarkController.get(watermark.type);
+  if (renderer) {
+    yield* renderer.render({ view, watermark, duration });
+  }
+}

package/src/controllers/watermark.controller.ts

@@ -0,0 +1,35 @@
+import type { WatermarkRendererContract } from "../helpers/watermark.types";
+import { TextWatermarkRenderer } from "../watermark-renderers/text.watermark";
+import { ImageWatermarkRenderer } from "../watermark-renderers/image.watermark";
+
+/**
+ * Registry for watermark renderers. Enables scalable dispatch by type:
+ * watermarkController.get(watermark.type)?.render({ view, watermark, duration }).
+ * Add new watermark types (e.g. svg) by registering a new renderer.
+ */
+export class WatermarkController {
+  private renderers = new Map<string, WatermarkRendererContract>();
+
+  register(renderer: WatermarkRendererContract) {
+    this.renderers.set(renderer.name, renderer);
+  }
+
+  get(name: string): WatermarkRendererContract | undefined {
+    return this.renderers.get(name);
+  }
+
+  list(): string[] {
+    return Array.from(this.renderers.keys());
+  }
+}
+
+const watermarkController = new WatermarkController();
+
+function registerWatermarkRenderers() {
+  watermarkController.register(TextWatermarkRenderer);
+  watermarkController.register(ImageWatermarkRenderer);
+}
+
+registerWatermarkRenderers();
+
+export default watermarkController;

package/src/elements/text.element.tsx

@@ -1,8 +1,8 @@
 import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Txt } from "@twick/2d";
+import { all, Color, createRef, waitFor } from "@twick/core";
+import { Rect, Txt } from "@twick/2d";
 import { addAnimation, addTextEffect } from "../helpers/element.utils";
-import { logger } from "../helpers/log.utils";
+import { hexToRGB } from "../helpers/utils";
 
 /**
  * @group TextElement
@@ -79,26 +79,85 @@ export const TextElement = {
      * });
      * ```
      */
-    *create({ containerRef, element, view }: ElementParams) { 
+    *create({ containerRef, element, view }: ElementParams) {
     const elementRef = createRef<any>();
+    const hasBackground =
+      element.props?.backgroundColor != null &&
+      element.props.backgroundColor !== "";
 
     yield* waitFor(element?.s);
-    yield containerRef().add(
-      <Txt
-        ref={elementRef}
-        key={element.id}
-        text={element.t}
-        textWrap={element.props?.textWrap ?? true}
-        textAlign={element.props?.textAlign ?? "center"}
-        {...element.props}
-      />
-    );
-    yield* all(
-      addAnimation({ elementRef: elementRef, element: element, view }),
-      addTextEffect({ elementRef: elementRef, element: element }),
-      waitFor(Math.max(0, element.e - element.s))
-    );
-    yield elementRef().remove();
-}
+
+    if (hasBackground) {
+      const textRef = createRef<Txt>();
+      const wrapperRef = createRef<any>();
+      const innerTextRef = createRef<Txt>();
+
+      yield containerRef().add(
+        <Txt
+          ref={textRef}
+          key={`${element.id}-measure`}
+          text={element.t}
+          textWrap={element.props?.textWrap ?? true}
+          textAlign={element.props?.textAlign ?? "center"}
+          opacity={0}
+          {...element.props}
+        />
+      );
+
+      const bgColor = new Color({
+        ...hexToRGB(element.props!.backgroundColor!),
+        a: element.props?.backgroundOpacity ?? 1,
+      });
+      const paddingX = 20;
+      const paddingY = 4;
+
+      yield containerRef().add(
+        <Rect
+          ref={wrapperRef}
+          key={element.id}
+          fill={bgColor}
+          width={textRef().width() + paddingX}
+          height={textRef().height() + paddingY}
+          padding={[0, paddingX / 2]}
+          alignItems={"center"}
+          justifyContent={"center"}
+          layout
+        >
+          <Txt
+            ref={innerTextRef}
+            text={element.t}
+            textWrap={element.props?.textWrap ?? true}
+            textAlign={element.props?.textAlign ?? "center"}
+            {...element.props}
+          />
+        </Rect>
+      );
+      textRef().remove();
+
+      yield* all(
+        addAnimation({ elementRef: wrapperRef, element: element, view }),
+        addTextEffect({ elementRef: innerTextRef, element: element }),
+        waitFor(Math.max(0, element.e - element.s))
+      );
+      yield wrapperRef().remove();
+    } else {
+      yield containerRef().add(
+        <Txt
+          ref={elementRef}
+          key={element.id}
+          text={element.t}
+          textWrap={element.props?.textWrap ?? true}
+          textAlign={element.props?.textAlign ?? "center"}
+          {...element.props}
+        />
+      );
+      yield* all(
+        addAnimation({ elementRef: elementRef, element: element, view }),
+        addTextEffect({ elementRef: elementRef, element: element }),
+        waitFor(Math.max(0, element.e - element.s))
+      );
+      yield elementRef().remove();
+    }
+  },
   }
   

package/src/helpers/types.ts

@@ -1,19 +1,48 @@
 import { View2D } from "@twick/2d";
 import { Reference, ThreadGenerator, Vector2 } from "@twick/core";
 
+/**
+ * Watermark configuration for overlay on video.
+ * Supports text or image watermarks with position, rotation, and opacity.
+ * Compatible with WatermarkJSON from @twick/timeline.
+ */
+export type WatermarkInput = {
+  type: "text" | "image";
+  position?: Position;
+  rotation?: number;
+  opacity?: number;
+  props: {
+    text?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    textAlign?: string;
+    fontWeight?: number;
+    lineWidth?: number;
+    fontStyle?: string;
+    src?: string;
+    width?: number;
+    height?: number;
+    objectFit?: ObjectFit;
+  };
+};
+
 /**
  * Main input configuration for video visualization.
- * Contains player settings, background color, dimensions, and track definitions
- * for creating complete video visualizations.
+ * Contains player settings, background color, dimensions, track definitions,
+ * and optional watermark for creating complete video visualizations.
  */
 export type VideoInput = {
-  playerId: string,
+  playerId: string;
   backgroundColor: string;
   properties: {
     width: number;
     height: number;
   };
   tracks: VisualizerTrack[];
+  watermark?: WatermarkInput;
 };
 
 /**

package/src/helpers/watermark.types.ts

@@ -0,0 +1,23 @@
+import { View2D } from "@twick/2d";
+import { ThreadGenerator } from "@twick/core";
+import { WatermarkInput } from "./types";
+
+/**
+ * Parameters passed to a watermark renderer.
+ */
+export type WatermarkRendererParams = {
+  view: View2D;
+  watermark: WatermarkInput;
+  duration: number;
+};
+
+/**
+ * Interface for watermark renderers. Register with WatermarkController
+ * to support text, image, or future watermark types (e.g. svg).
+ */
+export interface WatermarkRendererContract {
+  /** Renderer type: "text" | "image" */
+  name: "text" | "image";
+  /** Renders the watermark overlay for the given duration */
+  render(params: WatermarkRendererParams): ThreadGenerator;
+}

package/src/index.ts

@@ -194,3 +194,8 @@ export * from './elements';
 export * from './text-effects';
 export * from './frame-effects';
 
+// Watermark renderer registry (Option B – register custom watermark types)
+export { default as watermarkController } from './controllers/watermark.controller';
+export { WatermarkController } from './controllers/watermark.controller';
+export type { WatermarkRendererContract, WatermarkRendererParams } from './helpers/watermark.types';
+

package/src/sample.ts

@@ -26,6 +26,18 @@ export const sample = {
         "orgId": "a251d9971a55"
       },
       "basePath": "carlyn",
+      "watermark": {
+        "id": "e-watermark",
+        "type": "text",
+        "position": { "x": 0, "y": -200 },
+        "opacity": 0.7,
+        "props": {
+          "text": "© Twick SDK",
+          "fontSize": 24,
+          "fontFamily": "Arial",
+          "fill": "#ffffff"
+      }
+    },
       "tracks": [
         {
           "id": "t-scene",

package/src/visualizer.tsx

@@ -57,6 +57,7 @@ import {
   makeElementTrack,
   makeSceneTrack,
   makeVideoTrack,
+  makeWatermarkTrack,
 } from "./components/track";
 import { dispatchWindowEvent } from "./helpers/event.utils";
 
@@ -159,6 +160,25 @@ export const scene = makeScene2D("scene", function* (view: View2D) {
         }
         index++;
       }
+
+      // Add watermark on top of all tracks when present
+      if (input.watermark) {
+        const duration =
+          input.tracks?.length > 0
+            ? Math.max(
+                0,
+                ...input.tracks.flatMap((t) => t.elements || []).map((e) => e.e)
+              )
+            : 10;
+        movie.push(
+          makeWatermarkTrack({
+            view,
+            watermark: input.watermark,
+            duration,
+          })
+        );
+      }
+
       // Execute all track animations in parallel
       yield* all(...movie);
       dispatchWindowEvent(EVENT_TYPES.PLAYER_UPDATE, {

package/src/watermark-renderers/image.watermark.tsx

@@ -0,0 +1,37 @@
+/**
+ * Image watermark renderer for the visualizer.
+ * Renders image overlay with position, rotation, opacity, and dimensions.
+ */
+
+import { Img } from "@twick/2d";
+import { createRef, waitFor } from "@twick/core";
+import type { WatermarkRendererContract } from "../helpers/watermark.types";
+
+export const ImageWatermarkRenderer: WatermarkRendererContract = {
+  name: "image",
+
+  *render({ view, watermark, duration }) {
+    const props = watermark.props;
+    if (!props?.src) return;
+
+    const position = watermark.position ?? { x: 0, y: 0 };
+    const rotation = (watermark.rotation ?? 0) * (Math.PI / 180);
+    const opacity = watermark.opacity ?? 1;
+
+    const watermarkRef = createRef<any>();
+    view.add(
+      <Img
+        ref={watermarkRef}
+        src={props.src}
+        x={position.x}
+        y={position.y}
+        width={props.width}
+        height={props.height}
+        rotation={rotation}
+        opacity={opacity}
+      />
+    );
+
+    yield* waitFor(duration);
+  },
+};

package/src/watermark-renderers/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Watermark renderers registry.
+ * Export renderers and shared types for the watermark controller.
+ */
+
+export { TextWatermarkRenderer } from "./text.watermark";
+export { ImageWatermarkRenderer } from "./image.watermark";

package/src/watermark-renderers/text.watermark.tsx

@@ -0,0 +1,43 @@
+/**
+ * Text watermark renderer for the visualizer.
+ * Renders text overlay with position, rotation, opacity, and text styling.
+ */
+
+import { Txt } from "@twick/2d";
+import { createRef, waitFor } from "@twick/core";
+import type { WatermarkRendererContract } from "../helpers/watermark.types";
+
+export const TextWatermarkRenderer: WatermarkRendererContract = {
+  name: "text",
+
+  *render({ view, watermark, duration }) {
+    const props = watermark.props;
+    if (!props?.text) return;
+
+    const position = watermark.position ?? { x: 0, y: 0 };
+    const rotation = (watermark.rotation ?? 0) * (Math.PI / 180);
+    const opacity = watermark.opacity ?? 1;
+
+    const watermarkRef = createRef<any>();
+    view.add(
+      <Txt
+        ref={watermarkRef}
+        text={props.text}
+        x={position.x}
+        y={position.y}
+        rotation={rotation}
+        opacity={opacity}
+        fontSize={props.fontSize ?? 24}
+        fontFamily={props.fontFamily ?? "Arial"}
+        fill={props.fill ?? "#ffffff"}
+        stroke={props.stroke}
+        lineWidth={props.lineWidth ?? props.strokeWidth ?? 0}
+        textAlign={(props.textAlign as any) ?? "center"}
+        fontWeight={props.fontWeight ?? 400}
+        fontStyle={props.fontStyle ?? "normal"}
+      />
+    );
+
+    yield* waitFor(duration);
+  },
+};