@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/open-the-editor/from-video.md

@@ -1,274 +1,266 @@
-> This is one page of the CE.SDK Vanilla JS/TS documentation. For a complete overview, see the [Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
+> This is one page of the CE.SDK Node.js documentation. For a complete overview, see the [Node.js Documentation Index](https://img.ly/docs/cesdk/node.md). For all docs in one file, see [llms-full.txt](./llms-full.txt.md).
 
 **Navigation:** [Guides](./guides.md) > [Open the Editor](./open-the-editor.md) > [Create From Video](./open-the-editor/from-video.md)
 
 ---
 
-Open CE.SDK with a video as the starting point for editing. The scene dimensions match the video resolution and time-based properties are enabled.
-
-![Create From Video example showing CE.SDK with a video loaded for editing](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Create an editable scene from a video file using CE.SDK in headless Node.js
+environments for server-side video processing workflows.
 
 > **Reading time:** 5 minutes
 >
 > **Resources:**
 >
 > - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
-> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-open-the-editor-from-video-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-from-video-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-open-the-editor-from-video-browser/)
-
-CE.SDK creates video editing scenes from a single video URL using `engine.scene.createFromVideo()`. This approach works well for video trimmers, overlay editors, or processing uploaded video files.
-
-```typescript file=@cesdk_web_examples/guides-open-the-editor-from-video-browser/browser.ts reference-only
-import type CreativeEngine from '@cesdk/engine';
-import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
-import {
-  BlurAssetSource,
-  CaptionPresetsAssetSource,
-  ColorPaletteAssetSource,
-  CropPresetsAssetSource,
-  DemoAssetSources,
-  EffectsAssetSource,
-  FiltersAssetSource,
-  PagePresetsAssetSource,
-  StickerAssetSource,
-  TextAssetSource,
-  TextComponentAssetSource,
-  TypefaceAssetSource,
-  UploadAssetSources,
-  VectorShapeAssetSource
-} from '@cesdk/cesdk-js/plugins';
-import { VideoEditorConfig } from './video-editor/plugin';
-import packageJson from './package.json';
-
-// ===== Handle Different Video Sources =====
-// Helper function to create a scene from a blob (e.g., file upload)
-// This pattern is useful when users upload video files via <input type="file">
-// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reference implementation for blob-based video sources; exposed as example pattern in docs.
-async function createSceneFromBlob(
-  engine: CreativeEngine,
-  blob: Blob
-): Promise<number> {
-  const objectURL = URL.createObjectURL(blob);
-  const scene = await engine.scene.createFromVideo(objectURL);
-  // Note: Don't revoke the URL immediately - the engine needs it for rendering
-  // Only revoke when the scene is no longer needed
-  return scene;
-}
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-open-the-editor-from-video-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-open-the-editor-from-video-server-js)
+
+Starting from an existing video allows you to create editable scenes on the server. The `engine.scene.createFromVideo()` method fetches the video, creates a scene with matching dimensions, and sets up pixel-based design units. This is useful for server-side video processing pipelines where you need to prepare scenes for later editing in browser environments.
+
+<NodejsVideoExportNotice {...props} />
+
+```typescript file=@cesdk_web_examples/guides-open-the-editor-from-video-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { mkdirSync, writeFileSync } from 'fs';
+
+// Load environment variables
+config();
+
+/**
+ * CE.SDK Server Guide: Create From Video
+ *
+ * Demonstrates how to create a scene from a video file in headless Node.js
+ * environments. This sets up the scene structure with timeline mode enabled.
+ *
+ * Note: Video frame rendering/export requires browser-level video decoding
+ * which is not available in Node.js. Use the browser version for video
+ * frame export, or save the scene for later use in a browser environment.
+ */
+
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
+
+try {
+  mkdirSync('output', { recursive: true });
+
+  // ========================================
+  // Create Scene from Remote Video URL
+  // ========================================
+  // Load a video directly from a URL
+  const videoUrl = 'https://img.ly/static/ubq_video_samples/bbb.mp4';
+
+  // Create a scene sized to match the video dimensions
+  // Timeline mode is automatically enabled
+  await engine.scene.createFromVideo(videoUrl);
+
+  // The scene structure is ready with video as content
+
+  console.log('✓ Created scene from video URL');
+
+  // ========================================
+  // Working with the Created Scene
+  // ========================================
+  // After creating the scene, access the page for modifications
+  const pages = engine.block.findByType('page');
+  const page = pages[0];
+
+  if (page) {
+    // Get the page dimensions (set from the video)
+    const width = engine.block.getWidth(page);
+    const height = engine.block.getHeight(page);
+    console.log(`Scene dimensions: ${width}x${height}`);
 
-class Example implements EditorPlugin {
-  name = packageJson.name;
-  version = packageJson.version;
-
-  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
-    if (!cesdk) {
-      throw new Error('CE.SDK instance is required for this plugin');
-    }
-
-    await cesdk.addPlugin(new VideoEditorConfig());
-    // Add asset source plugins
-    await cesdk.addPlugin(new BlurAssetSource());
-    await cesdk.addPlugin(new CaptionPresetsAssetSource());
-    await cesdk.addPlugin(new ColorPaletteAssetSource());
-    await cesdk.addPlugin(new CropPresetsAssetSource());
-    await cesdk.addPlugin(
-      new UploadAssetSources({
-        include: [
-          'ly.img.image.upload',
-          'ly.img.video.upload',
-          'ly.img.audio.upload'
-        ]
-      })
-    );
-    await cesdk.addPlugin(
-      new DemoAssetSources({
-        include: [
-          'ly.img.templates.video.*',
-          'ly.img.image.*',
-          'ly.img.audio.*',
-          'ly.img.video.*'
-        ]
-      })
-    );
-    await cesdk.addPlugin(new EffectsAssetSource());
-    await cesdk.addPlugin(new FiltersAssetSource());
-    await cesdk.addPlugin(
-      new PagePresetsAssetSource({
-        include: [
-          'ly.img.page.presets.instagram.*',
-          'ly.img.page.presets.facebook.*',
-          'ly.img.page.presets.x.*',
-          'ly.img.page.presets.linkedin.*',
-          'ly.img.page.presets.pinterest.*',
-          'ly.img.page.presets.tiktok.*',
-          'ly.img.page.presets.youtube.*',
-          'ly.img.page.presets.video.*'
-        ]
-      })
-    );
-    await cesdk.addPlugin(new StickerAssetSource());
-    await cesdk.addPlugin(new TextAssetSource());
-    await cesdk.addPlugin(new TextComponentAssetSource());
-    await cesdk.addPlugin(new TypefaceAssetSource());
-    await cesdk.addPlugin(new VectorShapeAssetSource());
-
-    const engine = cesdk.engine;
-
-    // ===== Create a Scene from a Video URL =====
-    // Video URL to create the scene from
-    const videoUrl = 'https://img.ly/static/ubq_video_samples/bbb.mp4';
-
-    // Create a scene from the video
-    // The scene dimensions match the video resolution
-    // Timeline mode is automatically enabled
-    const scene = await engine.scene.createFromVideo(videoUrl);
-
-    // ===== Work with the Video Block =====
-    // Find the video block that was created
-    // The video is placed inside a graphic block
-    const graphicBlocks = engine.block.findByType('graphic');
-    const videoBlock = graphicBlocks[0];
+    // Get the video duration
+    const duration = engine.block.getDuration(page);
+    console.log(`Video duration: ${duration.toFixed(2)} seconds`);
+  }
+
+  // ========================================
+  // Find and Modify the Video Block
+  // ========================================
+  // The video is placed inside a graphic block
+  const graphicBlocks = engine.block.findByType('graphic');
+  const videoBlock = graphicBlocks[0];
 
+  if (videoBlock) {
     // Modify video block properties
-    // For example, adjust opacity
     engine.block.setOpacity(videoBlock, 0.95);
+    console.log('✓ Found and modified video block');
+  }
 
-    // ===== Control Video Playback =====
-    // Get the video duration
-    const duration = engine.block.getDuration(scene);
-    console.log(`Video duration: ${duration}s`);
+  // ========================================
+  // Save Scene for Later Use
+  // ========================================
+  // Save the scene to a string for storage or transfer
+  const sceneString = await engine.scene.saveToString();
+  writeFileSync('output/video-scene.scene', sceneString);
+  console.log('📄 Saved scene to: output/video-scene.scene');
+
+  // Or save as an archive with embedded assets
+  const archiveBlob = await engine.scene.saveToArchive();
+  const archiveBuffer = Buffer.from(await archiveBlob.arrayBuffer());
+  writeFileSync('output/video-scene.zip', archiveBuffer);
+  console.log('📦 Saved archive to: output/video-scene.zip');
+
+  console.log('\n✓ Create From Video guide completed successfully!');
+  console.log(
+    '\nNote: Video frame export requires browser-level video decoding.'
+  );
+  console.log('Use the saved scene in a browser environment for frame export.');
+} finally {
+  // Always dispose the engine when done
+  engine.dispose();
+  console.log('\n🧹 Engine disposed successfully');
+}
+```
 
-    // Set playback position to 2 seconds
-    const page = engine.block.findByType('page')[0];
-    engine.block.setPlaybackTime(page, 2);
+This guide covers how to create scenes from video files, work with video blocks, and save scenes for later use.
 
-    // Start video playback
-    // engine.block.setPlaying(scene, true);
+## Initialize the Engine
 
-    // Zoom to show the video
-    await engine.scene.zoomToBlock(page);
-  }
-}
+Start by initializing the CE.SDK engine in headless mode. The Node.js package (`@cesdk/node`) provides the same API as the browser version but runs without a visual interface.
 
-export default Example;
+```typescript highlight-setup
+// Initialize CE.SDK engine in headless mode
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE, // Optional (trial mode available)
+});
 ```
 
-This guide covers how to create scenes from video files and control video playback.
+## Create Scene from Video URL
 
-## Create a Scene From a Video URL
+Load a video directly from a URL using `createFromVideo()`. The method fetches the video and creates a scene sized to match its dimensions.
 
-Pass a video URL to `engine.scene.createFromVideo()` to load the video and create a scene with matching dimensions.
+```typescript highlight-create-from-url
+  // Load a video directly from a URL
+  const videoUrl = 'https://img.ly/static/ubq_video_samples/bbb.mp4';
 
-```typescript highlight-create-from-video
-// Video URL to create the scene from
-const videoUrl = 'https://img.ly/static/ubq_video_samples/bbb.mp4';
+  // Create a scene sized to match the video dimensions
+  // Timeline mode is automatically enabled
+  await engine.scene.createFromVideo(videoUrl);
 
-// Create a scene from the video
-// The scene dimensions match the video resolution
-// Timeline mode is automatically enabled
-const scene = await engine.scene.createFromVideo(videoUrl);
+  // The scene structure is ready with video as content
 ```
 
-The scene uses pixel design units and includes a time-based structure. Page dimensions match the video resolution automatically.
+The method returns a promise that resolves once the video is loaded and the scene is ready for processing. The scene's page dimensions automatically match the video resolution.
 
 ## Work With the Video Block
 
-After creating the scene, locate the video block to modify its properties.
+After creating the scene, access the page to get dimensions and find the video block for modifications.
 
-```typescript highlight-find-video-block
-// Find the video block that was created
-// The video is placed inside a graphic block
-const graphicBlocks = engine.block.findByType('graphic');
-const videoBlock = graphicBlocks[0];
-
-// Modify video block properties
-// For example, adjust opacity
-engine.block.setOpacity(videoBlock, 0.95);
+```typescript highlight-work-with-scene
+  // After creating the scene, access the page for modifications
+  const pages = engine.block.findByType('page');
+  const page = pages[0];
+
+  if (page) {
+    // Get the page dimensions (set from the video)
+    const width = engine.block.getWidth(page);
+    const height = engine.block.getHeight(page);
+    console.log(`Scene dimensions: ${width}x${height}`);
+
+    // Get the video duration
+    const duration = engine.block.getDuration(page);
+    console.log(`Video duration: ${duration.toFixed(2)} seconds`);
+  }
 ```
 
-The video is placed inside a graphic block. Use `engine.block.findByType('graphic')` to find it. You can modify properties like opacity, position, or apply effects using the Block API.
+The video is placed inside a graphic block. Use `engine.block.findByType('graphic')` to locate it.
 
-## Control Video Playback
+```typescript highlight-find-video-block
+  // The video is placed inside a graphic block
+  const graphicBlocks = engine.block.findByType('graphic');
+  const videoBlock = graphicBlocks[0];
 
-Use playback controls to start, stop, and seek within the video.
+  if (videoBlock) {
+    // Modify video block properties
+    engine.block.setOpacity(videoBlock, 0.95);
+    console.log('✓ Found and modified video block');
+  }
+```
 
-```typescript highlight-control-playback
-// Get the video duration
-const duration = engine.block.getDuration(scene);
-console.log(`Video duration: ${duration}s`);
+You can modify properties like opacity, position, or apply effects using the Block API.
 
-// Set playback position to 2 seconds
-const page = engine.block.findByType('page')[0];
-engine.block.setPlaybackTime(page, 2);
+## Save Scene for Later Use
 
-// Start video playback
-// engine.block.setPlaying(scene, true);
-```
+Save the scene to a file for storage or transfer to a browser environment for further processing. You can save as a plain string or as an archive with embedded assets.
 
-Call `engine.block.setPlaying()` on the scene to start or stop playback. Use `engine.block.setPlaybackTime()` to jump to a specific position and `engine.block.getDuration()` to get the total video length.
-
-## Handle Different Video Sources
-
-Create scenes from blob URLs when working with file uploads.
-
-```typescript highlight-blob-source
-// Helper function to create a scene from a blob (e.g., file upload)
-// This pattern is useful when users upload video files via <input type="file">
-// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Reference implementation for blob-based video sources; exposed as example pattern in docs.
-async function createSceneFromBlob(
-  engine: CreativeEngine,
-  blob: Blob
-): Promise<number> {
-  const objectURL = URL.createObjectURL(blob);
-  const scene = await engine.scene.createFromVideo(objectURL);
-  // Note: Don't revoke the URL immediately - the engine needs it for rendering
-  // Only revoke when the scene is no longer needed
-  return scene;
-}
-```
+```typescript highlight-save-scene
+  // Save the scene to a string for storage or transfer
+  const sceneString = await engine.scene.saveToString();
+  writeFileSync('output/video-scene.scene', sceneString);
+  console.log('📄 Saved scene to: output/video-scene.scene');
 
-Use `URL.createObjectURL()` to create a blob URL from a File object or fetched blob. This pattern supports file uploads from `<input type="file">` elements. Note that the blob URL must remain valid while the scene is in use - don't revoke it until the scene is no longer needed.
+  // Or save as an archive with embedded assets
+  const archiveBlob = await engine.scene.saveToArchive();
+  const archiveBuffer = Buffer.from(await archiveBlob.arrayBuffer());
+  writeFileSync('output/video-scene.zip', archiveBuffer);
+  console.log('📦 Saved archive to: output/video-scene.zip');
+```
 
-## Scene Configuration
+## Clean Up Resources
 
-Scenes created from video include:
+Always dispose of the engine when done to free system resources.
 
-- Page dimensions matching video resolution
-- Pixel design units
-- Time-based properties enabled
-- A single page with the video graphic block
+```typescript highlight-cleanup
+// Always dispose the engine when done
+engine.dispose();
+```
 
 ## Troubleshooting
 
 **Video fails to load**
 
-Verify the video URL is accessible and check CORS headers allow fetching from the source domain. Ensure the format is supported (MP4, WebM).
+- Verify the video URL is accessible from your server
+- Check network connectivity and firewall rules
+- Ensure the format is supported (MP4, WebM)
 
-**Video plays without audio**
+**Scene dimensions don't match video**
 
-Browser autoplay policies may block audio until user interaction. Verify the video file contains an audio track.
+- Dimensions come from video metadata during load
+- Check the video file has valid dimension metadata
 
-**Scene dimensions don't match video**
+**Memory issues with large videos**
 
-Dimensions come from video metadata during load. Check the video file has valid dimension metadata.
+- Process videos in batches to manage memory usage
+- Dispose of the engine between batch operations
+- Consider extracting specific frames rather than full video processing
+
+**Export failures**
+
+- Ensure the output directory exists before writing
+- Check filesystem permissions
+- Verify sufficient disk space for output files
 
 ## API Reference
 
-| Method                           | Purpose                     |
-| -------------------------------- | --------------------------- |
-| `engine.scene.createFromVideo()` | Create scene from video URL |
-| `engine.block.findByType()`      | Find blocks by type         |
-| `engine.block.setOpacity()`      | Set block opacity           |
-| `engine.block.setPlaying()`      | Start or stop playback      |
-| `engine.block.setPlaybackTime()` | Set playback position       |
-| `engine.block.getDuration()`     | Get video/scene duration    |
-| `engine.scene.get()`             | Get active scene            |
+| Method                           | Purpose                       |
+| -------------------------------- | ----------------------------- |
+| `CreativeEngine.init()`          | Initialize engine instance    |
+| `engine.scene.createFromVideo()` | Create scene from video URL   |
+| `engine.scene.saveToString()`    | Save scene to serialized string |
+| `engine.scene.saveToArchive()`   | Save scene as archive with assets |
+| `engine.block.findByType()`      | Find blocks by type           |
+| `engine.block.getWidth()`        | Get block width               |
+| `engine.block.getHeight()`       | Get block height              |
+| `engine.block.setOpacity()`      | Set block opacity             |
+| `engine.block.getDuration()`     | Get video duration            |
+| `engine.dispose()`               | Clean up engine resources     |
+
+
 
 ---
 
 ## More Resources
 
-- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[Node.js Documentation Index](https://img.ly/docs/cesdk/node.md)** - Browse all Node.js documentation
 - **[Complete Documentation](./llms-full.txt.md)** - Full documentation in one file (for LLMs)
-- **[Web Documentation](./js.md)** - Interactive documentation with examples
-- **[Support](mailto:support@img.ly)** - Contact IMG.LY support
+- **[Web Documentation](./node.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support