@twick/visualizer 0.14.0 → 0.14.3

package/src/visualizer.tsx

@@ -1,78 +1,182 @@
-/**
- * Main visualizer component that renders the scene with video, audio, captions and other elements
- * based on the provided input configuration.
- */
-
-import "./global.css";
-import { Rect, makeScene2D, View2D } from "@twick/2d";
-import { all, useScene } from "@twick/core";
-
-import { DEFAULT_BACKGROUND_COLOR, TRACK_TYPES } from "./helpers/constants";
-import { VideoInput } from "./helpers/types";
-import { logger } from "./helpers/log.utils";
-import {
-  makeAudioTrack,
-  makeCaptionTrack,
-  makeElementTrack,
-  makeSceneTrack,
-  makeVideoTrack,
-} from "./components/track";
-
-/**
- * Creates and configures the main scene for video visualization
- * @param {string} name - Name of the scene
- * @param {Function} generator - Generator function that handles scene setup and animation
- * @returns {Scene2D} Configured scene object
- */
-export const scene = makeScene2D("scene", function* (view: View2D) {
-  // Get input configuration from scene variables
-  const input = useScene().variables.get("input", null)() as VideoInput | null;
-  
-  if (input) {
-    logger("Scene updated", input);
-    
-    // Add background rectangle with specified or default color
-    yield view.add(
-      <Rect
-        fill={input.backgroundColor ?? DEFAULT_BACKGROUND_COLOR}
-        size={"100%"}
-      />
-    );
-
-    // Process track elements if present
-    if (input.tracks) {
-      const movie = [];
-      let index = 1;
-
-      // Iterate through each track element and create appropriate visualization
-      for (const track of input.tracks) {
-        switch (track.type) {
-          case TRACK_TYPES.VIDEO:
-            movie.push(makeVideoTrack({ view, track }));
-            break;
-          case TRACK_TYPES.AUDIO:
-            movie.push(makeAudioTrack({ view, track }));
-            break;
-          case TRACK_TYPES.CAPTION:
-            movie.push(
-              makeCaptionTrack({
-                view,
-                track,
-              })
-            );
-            break;
-          case TRACK_TYPES.SCENE:
-            movie.push(makeSceneTrack({ view, track }));
-            break;
-          case TRACK_TYPES.ELEMENT:
-            movie.push(makeElementTrack({ view, track }));
-            break;
-        }
-        index++;
-      }
-      
-      // Execute all track animations in parallel
-      yield* all(...movie);
-    }
-  }
-});
+/**
+ * @twick/visualizer - Professional Video Visualization Library
+ * 
+ * Main visualizer component that renders the scene with video, audio, captions and other elements
+ * based on the provided input configuration. Creates a complete visualization scene with
+ * background, tracks, animations, and effects for professional video content.
+ * 
+ * ## Scene Architecture
+ * 
+ * The visualizer creates a hierarchical scene structure:
+ * ```
+ * Scene
+ * ├── Background Container
+ * ├── Track 1
+ * │   ├── Element 1 (Video/Image/Audio)
+ * │   ├── Element 2 (Text/Caption)
+ * │   └── Element 3 (Shapes/UI)
+ * ├── Track 2
+ * │   └── ...
+ * └── Track N
+ * ```
+ * 
+ * ## Core Features
+ * 
+ * - **Multi-Track Support**: Organize elements into logical tracks
+ * - **Animation System**: Rich animation library with enter/exit effects
+ * - **Text Effects**: Character and word-level text animations
+ * - **Frame Effects**: Visual masking and container transformations
+ * - **Media Support**: Video, image, and audio content management
+ * - **Timing Control**: Precise start/end timing for all elements
+ * 
+ * ## Use Cases
+ * 
+ * - **Video Presentations**: Professional slideshows with animations
+ * - **Content Creation**: Social media videos with effects
+ * - **Educational Content**: Interactive learning materials
+ * - **Marketing Videos**: Branded content with visual effects
+ * - **Live Streaming**: Real-time visual enhancements
+ * 
+ * @packageDocumentation
+ */
+
+import "./global.css";
+import { Rect, makeScene2D, View2D } from "@twick/2d";
+import { all, useScene } from "@twick/core";
+
+import {
+  DEFAULT_BACKGROUND_COLOR,
+  EVENT_TYPES,
+  TRACK_TYPES,
+} from "./helpers/constants";
+import { VideoInput } from "./helpers/types";
+import { logger } from "./helpers/log.utils";
+import {
+  makeAudioTrack,
+  makeCaptionTrack,
+  makeElementTrack,
+  makeSceneTrack,
+  makeVideoTrack,
+} from "./components/track";
+import { dispatchWindowEvent } from "./helpers/event.utils";
+
+/**
+ * @category Core
+ * @description Main scene generator for video visualization
+ * 
+ * Creates and configures the main scene for video visualization. Sets up a scene with 
+ * background, processes track elements, and handles animation generation for video, 
+ * audio, captions, and other visual elements.
+ * 
+ * ## Scene Lifecycle
+ * 
+ * 1. **Input Processing**: Retrieves video input configuration from scene variables
+ * 2. **Background Setup**: Creates background rectangle with specified color
+ * 3. **Track Processing**: Iterates through tracks and creates appropriate visualizations
+ * 4. **Animation Execution**: Runs all track animations in parallel using `all()`
+ * 5. **Event Dispatch**: Sends player update events for status tracking
+ * 
+ * ## Track Types Supported
+ * 
+ * - **VIDEO**: Video content with playback and effects
+ * - **AUDIO**: Audio content with timing and synchronization
+ * - **CAPTION**: Text overlays with styling and animations
+ * - **SCENE**: Scene containers for organization
+ * - **ELEMENT**: Custom elements with animations
+ * 
+ * ## 📊 Performance Features
+ * 
+ * - **Parallel Execution**: All track animations run concurrently
+ * - **Event-Driven**: Real-time status updates via window events
+ * - **Resource Management**: Automatic cleanup and memory optimization
+ * - **Error Handling**: Graceful fallbacks for missing configurations
+ * 
+ * @param name - Name of the scene for identification
+ * @param generator - Generator function that handles scene setup and animation
+ * @returns Configured scene object with all track animations
+ * 
+ * @example
+ * ```js
+ * // Basic scene setup
+ * const scene = makeScene2D("scene", function* (view) {
+ *   // Scene setup and animation logic
+ *   yield* all(...trackAnimations);
+ * });
+ * 
+ * // With video input configuration
+ * const videoScene = makeScene2D("video-scene", function* (view) {
+ *   // Configure scene variables
+ *   useScene().variables.set("input", videoInput);
+ *   useScene().variables.set("playerId", "main-player");
+ *   
+ *   // Scene will automatically process the input
+ * });
+ * ```
+ */
+export const scene = makeScene2D("scene", function* (view: View2D) {
+  // Get input configuration from scene variables
+  const input = useScene().variables.get("input", null)() as VideoInput | null;
+  const playerId = useScene().variables.get("playerId", null)() as
+    | string
+    | null;
+  if (input) {
+    logger("Scene updated", { playerId, input });
+    // Add background rectangle with specified or default color
+    yield view.add(
+      <Rect
+        fill={input.backgroundColor ?? DEFAULT_BACKGROUND_COLOR}
+        size={"100%"}
+      />
+    );
+
+    // Process track elements if present
+    if (input.tracks) {
+      const movie = [];
+      let index = 1;
+
+      // Iterate through each track element and create appropriate visualization
+      for (const track of input.tracks) {
+        switch (track.type) {
+          case TRACK_TYPES.VIDEO:
+            movie.push(makeVideoTrack({ view, track }));
+            break;
+          case TRACK_TYPES.AUDIO:
+            movie.push(makeAudioTrack({ view, track }));
+            break;
+          case TRACK_TYPES.CAPTION:
+            movie.push(
+              makeCaptionTrack({
+                view,
+                track,
+              })
+            );
+            break;
+          case TRACK_TYPES.SCENE:
+            movie.push(makeSceneTrack({ view, track }));
+            break;
+          case TRACK_TYPES.ELEMENT:
+            movie.push(makeElementTrack({ view, track }));
+            break;
+        }
+        index++;
+      }
+      // Execute all track animations in parallel
+      yield* all(...movie);
+      dispatchWindowEvent(EVENT_TYPES.PLAYER_UPDATE, {
+        detail: {
+          status: "ready",
+          playerId: playerId,
+          message: "All elements created",
+        },
+      });
+    } else {
+      dispatchWindowEvent(EVENT_TYPES.PLAYER_UPDATE, {
+        detail: {
+          status: "ready",
+          playerId: playerId,
+          message: "No elements to create",
+        },
+      });
+    }
+  }
+});

package/tsconfig.json

@@ -1,11 +1,11 @@
-{
-  "extends": "@twick/2d/tsconfig.project.json",
-  "include": ["src"],
-  "compilerOptions": {
-    "noEmit": false,
-    "outDir": "dist",
-    "module": "CommonJS",
-    "skipLibCheck": true,
-    "jsx": "react-jsx"
-  }
-}
+{
+  "extends": "@twick/2d/tsconfig.project.json",
+  "include": ["src"],
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist",
+    "module": "CommonJS",
+    "skipLibCheck": true,
+    "jsx": "react-jsx"
+  }
+}

package/typedoc.json

@@ -1,15 +1,20 @@
-{
-  "$schema": "https://typedoc.org/schema.json",
-  "entryPoints": ["./src/index.ts"],
-  "out": "docs",
-  "name": "@twick/visualizer",
-  "excludePrivate": true,
-  "excludeProtected": true,
-  "excludeExternals": true,
-  "theme": "default",
-  "readme": "README.md",
-  "plugin": ["typedoc-plugin-markdown"],
-  "categorizeByGroup": true,
-  "categoryOrder": ["Core", "Utils", "*"],
-  "hideBreadcrumbs": true
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/visualizer-grouped.ts"],
+  "out": "docs",
+  "name": "@twick/visualizer",
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeExternals": true,
+  "theme": "default",
+  "readme": "README.md",
+  "plugin": ["typedoc-plugin-markdown"],
+  "categorizeByGroup": true,
+  "categoryOrder": ["Core", "FadeAnimation", "RiseAnimation", "BlurAnimation", "BreatheAnimation", "SuccessionAnimation", "PhotoRiseAnimation", "PhotoZoomAnimation", "VideoElement", "ImageElement", "AudioElement", "TextElement", "CaptionElement", "RectElement", "CircleElement", "IconElement", "SceneElement", "TypewriterEffect", "StreamWordEffect", "ElasticEffect", "EraseEffect", "CircleFrameEffect", "RectFrameEffect", "Types", "Interfaces", "Other"],
+  "hideBreadcrumbs": true,
+  "groupOrder": ["Core", "FadeAnimation", "RiseAnimation", "BlurAnimation", "BreatheAnimation", "SuccessionAnimation", "PhotoRiseAnimation", "PhotoZoomAnimation", "VideoElement", "ImageElement", "AudioElement", "TextElement", "CaptionElement", "RectElement", "CircleElement", "IconElement", "SceneElement", "TypewriterEffect", "StreamWordEffect", "ElasticEffect", "EraseEffect", "CircleFrameEffect", "RectFrameEffect", "Types", "Interfaces", "Other"],
+  "sort": ["source-order"],
+  "defaultCategory": "Other",
+  "hideInPageTOC": false,
+  "includeVersion": true
 } 

package/vite.config.ts

@@ -1,15 +1,15 @@
-import { defineConfig } from "vite";
-import motionCanvas from '@twick/vite-plugin';
-
-export default defineConfig({
-  plugins: [motionCanvas()],
-  build: {
-    rollupOptions: {
-      output: {
-        entryFileNames: '[name].js',
-        chunkFileNames: '[name].js',
-        assetFileNames: '[name].[ext]'
-      }
-    }
-  }
-});
+import { defineConfig } from "vite";
+import motionCanvas from '@twick/vite-plugin';
+
+export default defineConfig({
+  plugins: [motionCanvas()],
+  build: {
+    rollupOptions: {
+      output: {
+        entryFileNames: '[name].js',
+        chunkFileNames: '[name].js',
+        assetFileNames: '[name].[ext]'
+      }
+    }
+  }
+});

package/.turbo/turbo-build.log

@@ -1,19 +0,0 @@
-
-> @twick/visualizer@0.14.0 build C:\GitHub\twick\packages\visualizer
-> tsc && vite build
-
-The CJS build of Vite's Node API is deprecated. See https://vite.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details.
-vite v5.4.19 building for production...
-transforming...
-✓ 1551 modules transformed.
-rendering chunks...
-computing gzip size...
-dist/mp4.wasm      41.99 kB
-dist/project.css    1.35 kB │ gzip:   0.40 kB
-dist/project.js   863.89 kB │ gzip: 250.81 kB
-
-✓ built in 37.73s
-(!) Some chunks are larger than 500 kB after minification. Consider:
-- Using dynamic import() to code-split the application
-- Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks
-- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.

package/.turbo/turbo-docs.log

@@ -1,7 +0,0 @@
-
-> @twick/visualizer@0.14.0 docs C:\GitHub\twick\packages\visualizer
-> typedoc --out docs src/index.ts
-
-[info] Loaded plugin typedoc-plugin-markdown
-[warning] You are running with an unsupported TypeScript version! If TypeDoc crashes, this is why. TypeDoc supports 4.6, 4.7, 4.8, 4.9, 5.0, 5.1, 5.2, 5.3, 5.4
-[info] Documentation generated at ./docs

package/LICENSE

@@ -1,197 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
--------------------------------------------------------------------------------
-
-ADDITIONAL TERMS – NO RESALE / NO STANDALONE REDISTRIBUTION
-
-The following additional terms apply to this project:
-
-1. **No Standalone Resale or Licensing**  
-You may not sell, license, sublicense, or otherwise commercially distribute this software, or any modified version of it, as a standalone product, SDK, or developer tool/library.
-
-2. **Permitted Commercial Use**  
-You may use this software in commercial applications, platforms, or services provided that:
-- It is part of a larger product or service with meaningful added value.
-- It is not positioned or marketed as a competing SDK or developer tool.
-
-3. **Cloud Function Restrictions**  
-You may self-host the cloud function components within your application or product. However, you may not offer them as a hosted service, API, or commercial cloud product without obtaining a commercial license.
-
-4. **Trademark and Branding Restrictions**  
-You may not use the name, logo, or branding associated with this project to market, redistribute, or promote your own products without explicit written permission.
-
-For commercial licensing, redistribution rights, or branding permissions, please contact: [contact@kifferai.com]
-

package/dist/project.css

@@ -1 +0,0 @@
-@import"https://fonts.googleapis.com/css2?family=Rubik:ital,wght@0,300..900;1,300..900&display=swap";@import"https://fonts.googleapis.com/css2?family=Mulish:ital,wght@0,200..1000;1,200..1000&display=swap";@import"https://fonts.googleapis.com/css2?family=Luckiest+Guy&family=Mulish:ital,wght@0,200..1000;1,200..1000&family=Playfair+Display:ital,wght@0,400..900;1,400..900&display=swap";@import"https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&display=swap";@import"https://fonts.googleapis.com/css2?family=Bangers&family=Birthstone&family=Corinthia:wght@400;700&family=Imperial+Script&family=Kumar+One+Outline&family=Londrina+Outline&family=Marck+Script&family=Montserrat:ital,wght@0,100..900;1,100..900&family=Pattaya&family=Playfair+Display:ital,wght@0,400..900;1,400..900&family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap";@import"https://fonts.cdnfonts.com/css/peralta";@import"https://fonts.cdnfonts.com/css/impact";@import"https://fonts.cdnfonts.com/css/lumanosimo";@import"https://fonts.cdnfonts.com/css/kapakana";@import"https://fonts.cdnfonts.com/css/handyrush";@import"https://fonts.cdnfonts.com/css/dasher";@import"https://fonts.cdnfonts.com/css/brittany-signature";