@twick/visualizer 0.0.1 → 0.14.0

package/docs/modules.md

@@ -0,0 +1,535 @@
+# @twick/visualizer
+
+## Table of contents
+
+### Interfaces
+
+- [Animation](interfaces/Animation.md)
+- [Element](interfaces/Element.md)
+- [FrameEffectPlugin](interfaces/FrameEffectPlugin.md)
+- [TextEffect](interfaces/TextEffect.md)
+
+### Type Aliases
+
+- [AnimationParams](modules.md#animationparams)
+- [AnimationProps](modules.md#animationprops)
+- [Caption](modules.md#caption)
+- [CaptionColors](modules.md#captioncolors)
+- [CaptionFont](modules.md#captionfont)
+- [CaptionProps](modules.md#captionprops)
+- [CaptionStyle](modules.md#captionstyle)
+- [ElementParams](modules.md#elementparams)
+- [FrameEffect](modules.md#frameeffect)
+- [FrameEffectParams](modules.md#frameeffectparams)
+- [FrameEffectProps](modules.md#frameeffectprops)
+- [FrameState](modules.md#framestate)
+- [MediaType](modules.md#mediatype)
+- [ObjectFit](modules.md#objectfit)
+- [Position](modules.md#position)
+- [Size](modules.md#size)
+- [SizeArray](modules.md#sizearray)
+- [SizeVector](modules.md#sizevector)
+- [TextEffectParams](modules.md#texteffectparams)
+- [TextEffectProps](modules.md#texteffectprops)
+- [VideoInput](modules.md#videoinput)
+- [VisualizerElement](modules.md#visualizerelement)
+- [VisualizerTrack](modules.md#visualizertrack)
+
+### Variables
+
+- [scene](modules.md#scene)
+
+## Type Aliases
+
+### AnimationParams
+
+Ƭ **AnimationParams**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `animate?` | ``"enter"`` \| ``"exit"`` \| ``"both"`` |
+| `containerRef?` | `Reference`\<`any`\> |
+| `direction?` | ``"left"`` \| ``"right"`` \| ``"center"`` \| ``"up"`` \| ``"down"`` |
+| `duration?` | `number` |
+| `elementRef` | `Reference`\<`any`\> |
+| `intensity?` | `number` |
+| `interval?` | `number` |
+| `mode?` | ``"in"`` \| ``"out"`` |
+| `view` | `View2D` |
+
+#### Defined in
+
+[helpers/types.ts:189](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L189)
+
+___
+
+### AnimationProps
+
+Ƭ **AnimationProps**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `animate?` | ``"enter"`` \| ``"exit"`` \| ``"both"`` |
+| `direction?` | ``"left"`` \| ``"right"`` \| ``"center"`` \| ``"up"`` \| ``"down"`` |
+| `duration?` | `number` |
+| `intensity?` | `number` |
+| `interval?` | `number` |
+| `mode?` | ``"in"`` \| ``"out"`` |
+| `name` | `string` |
+
+#### Defined in
+
+[helpers/types.ts:201](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L201)
+
+___
+
+### Caption
+
+Ƭ **Caption**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `capStyle?` | `string` |
+| `e` | `number` |
+| `props?` | [`CaptionProps`](modules.md#captionprops) |
+| `s` | `number` |
+| `t` | `string` |
+
+#### Defined in
+
+[helpers/types.ts:77](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L77)
+
+___
+
+### CaptionColors
+
+Ƭ **CaptionColors**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `background?` | `string` |
+| `highlight?` | `string` |
+| `text?` | `string` |
+
+#### Defined in
+
+[helpers/types.ts:98](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L98)
+
+___
+
+### CaptionFont
+
+Ƭ **CaptionFont**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `family?` | `string` |
+| `size?` | `number` |
+| `style?` | `string` |
+| `weight?` | `number` |
+
+#### Defined in
+
+[helpers/types.ts:104](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L104)
+
+___
+
+### CaptionProps
+
+Ƭ **CaptionProps**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `bgMargin?` | [`number`, `number`] |
+| `bgOffsetHeight?` | `number` |
+| `bgOffsetWidth?` | `number` |
+| `bgOpacity?` | `number` |
+| `bgPadding?` | [`number`, `number`] |
+| `bgRadius?` | `number` |
+| `colors` | [`CaptionColors`](modules.md#captioncolors) |
+| `font` | [`CaptionFont`](modules.md#captionfont) |
+| `x?` | `number` |
+| `y?` | `number` |
+
+#### Defined in
+
+[helpers/types.ts:85](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L85)
+
+___
+
+### CaptionStyle
+
+Ƭ **CaptionStyle**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `rect` | \{ `alignItems?`: `string` ; `gap?`: `number` ; `justifyContent?`: `string` ; `padding?`: [`number`, `number`] ; `radius?`: `number`  } |
+| `rect.alignItems?` | `string` |
+| `rect.gap?` | `number` |
+| `rect.justifyContent?` | `string` |
+| `rect.padding?` | [`number`, `number`] |
+| `rect.radius?` | `number` |
+| `word` | \{ `bgColor?`: `string` ; `bgOffsetHeight?`: `number` ; `bgOffsetWidth?`: `number` ; `fill`: `string` ; `fontFamily`: `string` ; `fontSize`: `number` ; `fontWeight`: `number` ; `lineWidth`: `number` ; `shadowBlur?`: `number` ; `shadowColor?`: `string` ; `shadowOffset?`: `number`[] ; `stroke`: `string` ; `strokeFirst?`: `boolean`  } |
+| `word.bgColor?` | `string` |
+| `word.bgOffsetHeight?` | `number` |
+| `word.bgOffsetWidth?` | `number` |
+| `word.fill` | `string` |
+| `word.fontFamily` | `string` |
+| `word.fontSize` | `number` |
+| `word.fontWeight` | `number` |
+| `word.lineWidth` | `number` |
+| `word.shadowBlur?` | `number` |
+| `word.shadowColor?` | `string` |
+| `word.shadowOffset?` | `number`[] |
+| `word.stroke` | `string` |
+| `word.strokeFirst?` | `boolean` |
+
+#### Defined in
+
+[helpers/types.ts:52](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L52)
+
+___
+
+### ElementParams
+
+Ƭ **ElementParams**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `caption?` | [`Caption`](modules.md#caption) |
+| `containerRef` | `Reference`\<`any`\> |
+| `element?` | [`VisualizerElement`](modules.md#visualizerelement) |
+| `view` | `View2D` |
+| `waitOnStart?` | `boolean` |
+
+#### Defined in
+
+[helpers/types.ts:153](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L153)
+
+___
+
+### FrameEffect
+
+Ƭ **FrameEffect**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `e` | `number` |
+| `name` | `string` |
+| `props` | [`FrameEffectProps`](modules.md#frameeffectprops) |
+| `s` | `number` |
+
+#### Defined in
+
+[helpers/types.ts:34](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L34)
+
+___
+
+### FrameEffectParams
+
+Ƭ **FrameEffectParams**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `containerRef?` | `Reference`\<`any`\> |
+| `elementRef` | `Reference`\<`any`\> |
+| `frameEffect` | [`FrameEffect`](modules.md#frameeffect) |
+| `initFrameState` | [`FrameState`](modules.md#framestate) |
+
+#### Defined in
+
+[helpers/types.ts:216](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L216)
+
+___
+
+### FrameEffectProps
+
+Ƭ **FrameEffectProps**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `elementPosition` | [`Position`](modules.md#position) |
+| `framePosition` | [`Position`](modules.md#position) |
+| `frameShape` | ``"circle"`` \| ``"rect"`` |
+| `frameSize` | [`SizeArray`](modules.md#sizearray) |
+| `objectFit` | [`ObjectFit`](modules.md#objectfit) |
+| `radius` | `number` |
+| `transitionDuration` | `number` |
+| `transitionEasing?` | `string` |
+
+#### Defined in
+
+[helpers/types.ts:41](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L41)
+
+___
+
+### FrameState
+
+Ƭ **FrameState**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `element` | \{ `pos`: `Vector2` ; `scale`: `Vector2` ; `size`: `Vector2`  } |
+| `element.pos` | `Vector2` |
+| `element.scale` | `Vector2` |
+| `element.size` | `Vector2` |
+| `frame` | \{ `pos`: `Vector2` ; `radius`: `number` ; `rotation`: `number` ; `scale`: `Vector2` ; `size`: `Vector2`  } |
+| `frame.pos` | `Vector2` |
+| `frame.radius` | `number` |
+| `frame.rotation` | `number` |
+| `frame.scale` | `Vector2` |
+| `frame.size` | `Vector2` |
+
+#### Defined in
+
+[helpers/types.ts:228](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L228)
+
+___
+
+### MediaType
+
+Ƭ **MediaType**: ``"video"`` \| ``"image"``
+
+#### Defined in
+
+[helpers/types.ts:13](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L13)
+
+___
+
+### ObjectFit
+
+Ƭ **ObjectFit**: ``"contain"`` \| ``"cover"`` \| ``"fill"`` \| ``"none"``
+
+#### Defined in
+
+[helpers/types.ts:15](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L15)
+
+___
+
+### Position
+
+Ƭ **Position**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `x` | `number` |
+| `y` | `number` |
+
+#### Defined in
+
+[helpers/types.ts:29](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L29)
+
+___
+
+### Size
+
+Ƭ **Size**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `height` | `number` |
+| `width` | `number` |
+
+#### Defined in
+
+[helpers/types.ts:22](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L22)
+
+___
+
+### SizeArray
+
+Ƭ **SizeArray**: [`number`, `number`]
+
+#### Defined in
+
+[helpers/types.ts:27](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L27)
+
+___
+
+### SizeVector
+
+Ƭ **SizeVector**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `x` | `number` |
+| `y` | `number` |
+
+#### Defined in
+
+[helpers/types.ts:17](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L17)
+
+___
+
+### TextEffectParams
+
+Ƭ **TextEffectParams**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `bufferTime?` | `number` |
+| `delay?` | `number` |
+| `direction?` | ``"left"`` \| ``"right"`` \| ``"center"`` |
+| `duration?` | `number` |
+| `elementRef` | `Reference`\<`any`\> |
+| `interval?` | `number` |
+
+#### Defined in
+
+[helpers/types.ts:166](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L166)
+
+___
+
+### TextEffectProps
+
+Ƭ **TextEffectProps**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `bufferTime?` | `number` |
+| `delay?` | `number` |
+| `direction?` | ``"left"`` \| ``"right"`` \| ``"center"`` |
+| `duration?` | `number` |
+| `interval?` | `number` |
+| `name` | `string` |
+
+#### Defined in
+
+[helpers/types.ts:175](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L175)
+
+___
+
+### VideoInput
+
+Ƭ **VideoInput**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `backgroundColor` | `string` |
+| `properties` | \{ `height`: `number` ; `width`: `number`  } |
+| `properties.height` | `number` |
+| `properties.width` | `number` |
+| `tracks` | [`VisualizerTrack`](modules.md#visualizertrack)[] |
+
+#### Defined in
+
+[helpers/types.ts:4](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L4)
+
+___
+
+### VisualizerElement
+
+Ƭ **VisualizerElement**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `animation?` | [`AnimationProps`](modules.md#animationprops) |
+| `backgroundColor?` | `string` |
+| `e` | `number` |
+| `frame?` | `any` |
+| `frameEffects?` | [`FrameEffect`](modules.md#frameeffect)[] |
+| `hWords?` | `any` |
+| `id` | `string` |
+| `objectFit?` | ``"contain"`` \| ``"cover"`` \| ``"fill"`` |
+| `props?` | `any` |
+| `s` | `number` |
+| `scale?` | `number` |
+| `t?` | `string` |
+| `textEffect` | [`TextEffectProps`](modules.md#texteffectprops) |
+| `trackId?` | `string` |
+| `type?` | `string` |
+
+#### Defined in
+
+[helpers/types.ts:111](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L111)
+
+___
+
+### VisualizerTrack
+
+Ƭ **VisualizerTrack**: `Object`
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `elements` | [`VisualizerElement`](modules.md#visualizerelement)[] |
+| `id` | `string` |
+| `props?` | \{ `bgOpacity?`: `number` ; `capStyle?`: `string` ; `captionProps?`: [`CaptionProps`](modules.md#captionprops) ; `colors?`: \{ `background?`: `string` ; `highlight?`: `string` ; `text?`: `string`  } ; `font?`: \{ `family?`: `string` ; `size?`: `number` ; `style?`: `string` ; `weight?`: `number`  } ; `x?`: `number` ; `y?`: `number`  } |
+| `props.bgOpacity?` | `number` |
+| `props.capStyle?` | `string` |
+| `props.captionProps?` | [`CaptionProps`](modules.md#captionprops) |
+| `props.colors?` | \{ `background?`: `string` ; `highlight?`: `string` ; `text?`: `string`  } |
+| `props.colors.background?` | `string` |
+| `props.colors.highlight?` | `string` |
+| `props.colors.text?` | `string` |
+| `props.font?` | \{ `family?`: `string` ; `size?`: `number` ; `style?`: `string` ; `weight?`: `number`  } |
+| `props.font.family?` | `string` |
+| `props.font.size?` | `number` |
+| `props.font.style?` | `string` |
+| `props.font.weight?` | `number` |
+| `props.x?` | `number` |
+| `props.y?` | `number` |
+| `type` | `string` |
+
+#### Defined in
+
+[helpers/types.ts:129](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/helpers/types.ts#L129)
+
+## Variables
+
+### scene
+
+• `Const` **scene**: `SceneDescription`\<`ThreadGeneratorFactory`\<`View2D`\>\>
+
+Creates and configures the main scene for video visualization
+
+**`Param`**
+
+Name of the scene
+
+**`Param`**
+
+Generator function that handles scene setup and animation
+
+#### Defined in
+
+[visualizer.tsx:27](https://github.com/ncounterspecialist/twick/blob/7c22d63b8d885bd0a8497127883a5009346a6a6b/packages/visualizer/src/visualizer.tsx#L27)

package/package.json

@@ -1,31 +1,34 @@
-{
-  "name": "@twick/visualizer",
-  "version": "0.0.1",
-  "license": "Apache-2.0",
-  "scripts": {
-    "start": "revideo editor --projectFile ./src/live.tsx",
-    "build": "tsc && vite build",
-    "docs": "typedoc --out docs src/index.ts",
-    "clean": "rimraf .turbo node_modules dist"
-  },
-  "dependencies": {
-    "@preact/signals": "^1.2.1",
-    "@revideo/2d": "^0.10.4",
-    "@revideo/core": "^0.10.4",
-    "@revideo/renderer": "^0.10.4",
-    "@revideo/vite-plugin": "^0.10.4",
-    "date-fns": "^4.1.0",
-    "preact": "^10.19.2",
-    "crelt": "^1.0.6",
-    "@twick/media-utils": "0.0.1"
-  },
-  "devDependencies": {
-    "@revideo/cli": "0.10.4",
-    "@revideo/ui": "0.10.4",
-    "typescript": "5.4.2",
-    "typedoc": "^0.25.8",
-    "typedoc-plugin-markdown": "^3.17.1",
-    "vite-plugin-dts": "^3.7.3",
-    "vite": "^5.1.4"
-  }
-}
+{
+  "name": "@twick/visualizer",
+  "version": "0.14.0",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@preact/signals": "^1.2.1",
+    "@twick/2d": "^0.14.0",
+    "@twick/core": "^0.14.0",
+    "@twick/renderer": "^0.14.0",
+    "@twick/vite-plugin": "^0.14.0",
+    "date-fns": "^4.1.0",
+    "preact": "^10.19.2",
+    "crelt": "^1.0.6",
+    "@twick/media-utils": "0.14.0"
+  },
+  "devDependencies": {
+    "@twick/cli": "0.14.0",
+    "@twick/ui": "0.14.0",
+    "typescript": "5.4.2",
+    "typedoc": "^0.25.8",
+    "typedoc-plugin-markdown": "^3.17.1",
+    "vite-plugin-dts": "^3.7.3",
+    "vite": "^5.1.4"
+  },
+  "scripts": {
+    "start": "twick editor --projectFile ./src/live.tsx",
+    "build": "tsc && vite build",
+    "docs": "typedoc --out docs src/index.ts",
+    "clean": "rimraf .turbo node_modules dist"
+  }
+}

package/src/animations/blur.tsx

@@ -0,0 +1,60 @@
+import { waitFor } from "@twick/core";
+import { AnimationParams } from "../helpers/types";
+
+/**
+ * BlurAnimation applies a blur effect to an element or its container
+ * during enter, exit, or both animations.
+ *
+ * Available animation modes:
+ * - "enter": Starts blurred and gradually becomes clear.
+ * - "exit": Starts clear and gradually becomes blurred.
+ * - "both": Blurs in, clears, then blurs out.
+ *
+ * @param elementRef - Reference to the main element.
+ * @param containerRef - Optional reference to a container element.
+ * @param interval - Duration (in frames or ms) of each blur transition.
+ * @param duration - Total duration of the animation.
+ * @param intensity - Maximum blur strength (default: 25).
+ * @param animate - Animation phase ("enter" | "exit" | "both").
+ */
+export const BlurAnimation = {
+  name: "blur",
+
+  /**
+   * Generator function controlling the blur animation.
+   */
+  *run({
+    elementRef,
+    containerRef,
+    interval,
+    duration,
+    intensity = 25,
+    animate,
+  }: AnimationParams) {
+    // Choose containerRef if provided; otherwise, fallback to elementRef
+    const ref = containerRef ?? elementRef;
+
+    let animationInterval = Math.min(interval, duration);
+    if (animate === "enter") {
+      // Start fully blurred
+      ref().filters.blur(intensity);
+      // Animate to no blur over 'interval'
+      yield* ref().filters.blur(0, animationInterval);
+    } else if (animate === "exit") {
+      // Wait for the time before exit animation starts
+      yield* waitFor(duration - animationInterval);
+      // Animate from no blur to full blur over 'interval'
+      yield* ref().filters.blur(intensity, animationInterval);
+    } else if (animate === "both") {
+      animationInterval = Math.min(interval, duration/2);
+      // Start fully blurred
+      ref().filters.blur(intensity);
+      // Animate to no blur
+      yield* ref().filters.blur(0, animationInterval);
+      // Wait until exit animation
+      yield* waitFor(duration - animationInterval);
+      // Animate to full blur again
+      yield* ref().filters.blur(intensity, animationInterval);
+    }
+  },
+};