@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/get-started/vanilla.md

@@ -0,0 +1,235 @@
+> 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:** [Get Started](./get-started/overview.md) > [Quickstart Node.js](./get-started/vanilla.md)
+
+---
+
+This guide walks you through integrating the **CreativeEditor SDK (CE.SDK)
+Engine** in a **Node.js environment using Vanilla JavaScript (CommonJS or ES
+modules)**, enabling you to process images and designs programmatically. By
+the end of this guide, you’ll have a working Node.js script that **loads a
+scene, modifies it, and exports it as an image**.
+
+<CesdkOverview />
+
+## Who Is This Guide For?
+
+This guide is for developers who:
+
+- Need to perform **image editing and scene manipulation programmatically** in a **Node.js** environment using **plain JavaScript**.
+- Want to use **CE.SDK’s Node.js package** for automation or backend processing **without TypeScript or additional frameworks**.
+- Prefer **a script-based approach** for **design generation and image exports**.
+
+## What You’ll Achieve
+
+- Install and configure **CE.SDK Engine** for **Node.js**.
+- Load and manipulate **design scenes** programmatically using **plain JavaScript**.
+- Export designs as **PNG images** without requiring a UI.
+
+> **Note:** Please note that the Node.js executable is not capable of processing or
+> exporting video.
+
+## Prerequisites
+
+Before getting started, ensure you have:
+
+- **Node.js v22 or later** installed. ([Download Node.js](https://nodejs.org/)).
+- A valid **CE.SDK license key** - Required for engine initialization. [Start a free trial](https://img.ly/forms/free-trial) to get your license key.
+
+## Step 1: Set Up Your Project
+
+Create a new project folder and navigate into it:
+
+```bash
+mkdir my-cesdk-node-project
+cd my-cesdk-node-project
+```
+
+Next, create a new `index.js` file manually or by running:
+
+```bash
+touch index.js
+```
+
+## Step 2: Install CE.SDK for Node.js
+
+Run the following command to install the required packages:
+
+```bash
+npm install @cesdk/node@$UBQ_VERSION$
+```
+
+Your project structure should now look like this:
+
+```
+/my-cesdk-node-project
+  ├── node_modules
+  ├── index.js
+  └── package.json
+```
+
+For your `index.js`, you can either use ES modules or CommonJS. Both versions are shown below.
+
+### index.js (ES Modules)
+
+If your project is using **ES modules**, change the `package.json` file to include:
+
+```json
+{
+  "type": "module"
+}
+```
+
+Then, modify **`index.js`** to use ES modules **(import syntax)**:
+
+```js
+import fs from 'fs/promises';
+import CreativeEngine from '@cesdk/node';
+
+// Configuration for the engine
+const config = {
+  // license: 'YOUR_CESDK_LICENSE_KEY', // Replace with your CE.SDK license key
+  baseURL: `https://cdn.img.ly/packages/imgly/cesdk-node/${CreativeEngine.version}/assets`,
+};
+
+try {
+  // Initialize CE.SDK Engine
+  const engine = await CreativeEngine.init(config);
+  console.log('CE.SDK Engine initialized');
+
+  try {
+    // Load a scene from a URL
+    await engine.scene.loadFromURL(
+      'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene',
+    );
+
+    // Find the first page in the scene
+    const [page] = engine.block.findByType('page');
+
+    // Export the scene as a PNG image
+    const blob = await engine.block.export(page, { mimeType: 'image/png' });
+    const arrayBuffer = await blob.arrayBuffer();
+
+    // Save the exported image to the file system
+    await fs.writeFile('./example-output.png', Buffer.from(arrayBuffer));
+
+    console.log('Export completed: example-output.png');
+  } catch (error) {
+    console.error('Error processing scene:', error);
+  } finally {
+    // Dispose of the engine to free resources
+    engine.dispose();
+  }
+} catch (initError) {
+  console.error('Failed to initialize CE.SDK Engine:', initError.message);
+  process.exit(1);
+}
+```
+
+### index.js (CommonJS)
+
+Modify your `index.js` file to initialize CE.SDK Engine and process a scene using CommonJS **(require syntax)**:
+
+```js
+const fs = require('fs/promises');
+const CreativeEngine = require('@cesdk/node');
+
+const { MimeType } = CreativeEngine;
+
+// Configuration for the engine
+const config = {
+  // license: 'YOUR_CESDK_LICENSE_KEY', // Replace with your CE.SDK license key
+  baseURL: `https://cdn.img.ly/packages/imgly/cesdk-node/${CreativeEngine.version}/assets`,
+};
+
+// Initialize CE.SDK Engine
+CreativeEngine.init(config)
+  .then(async engine => {
+    console.log('CE.SDK Engine initialized');
+
+    try {
+      // Load a scene from a URL
+      await engine.scene.loadFromURL(
+        'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_instagram_photo_1.scene',
+      );
+
+      // Find the first page in the scene
+      const [page] = engine.block.findByType('page');
+
+      // Export the scene as a PNG image
+      const blob = await engine.block.export(page, { mimeType: 'image/png' });
+      const arrayBuffer = await blob.arrayBuffer();
+
+      // Save the exported image to the file system
+      await fs.writeFile('./example-output.png', Buffer.from(arrayBuffer));
+
+      console.log('Export completed: example-output.png');
+    } catch (error) {
+      console.error('Error processing scene:', error);
+    } finally {
+      // Dispose of the engine to free resources
+      engine.dispose();
+    }
+  })
+  .catch(initError => {
+    console.error('Failed to initialize CE.SDK Engine:', initError.message);
+    process.exit(1);
+  });
+```
+
+## Step 3: Run the Script
+
+Once everything is set up, run your script using:
+
+```bash
+node index.js
+```
+
+This code processes the scene and generates an image file named **`example-output.png`** in your project directory.
+
+## Troubleshooting & Common Errors
+
+**❌ Error: `fetch is not defined`**
+
+- If using **Node.js v16 or lower**, this error can occur. We only support Node.js v22 and above.
+
+**❌ Error: `Invalid license key`**
+
+- Verify that your **license key** is correct and not expired.
+
+**❌ Error: `SyntaxError: Cannot use import statement outside a module`**
+
+- If using **ES modules**, ensure `"type": "module"` is set in `package.json`.
+- If using **CommonJS**, ensure `require()` is used instead of `import`.
+
+## Development Best Practices
+
+- **Always handle initialization errors** - CE.SDK initialization can fail for various reasons. Common reasons are:
+
+- Invalid license
+
+- Network issues
+
+- **Dispose resources** - Always call `engine.dispose()` in a `finally` block to free memory.
+
+- **Use async/await** - The async/await pattern is generally cleaner than promise chains for CE.SDK operations.
+
+## Next Steps
+
+Congratulations! You’ve successfully integrated **CE.SDK Engine in Node.js** using **plain JavaScript**. Next, explore:
+
+- [Serve assets from your server](./serve-assets.md)
+- [Import media](./import-media/concepts.md)
+- [Automating creative workflows](./automation/overview.md)
+- [Running on AWS Lambda](./get-started/vanilla-aws-lambda.md)
+
+
+
+---
+
+## More Resources
+
+- **[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](./node.md)** - Interactive documentation with examples
+- **[Support](mailto:support@img.ly)** - Contact IMG.LY support

package/assets/docs/guide/guides/export-save-publish/export/audio.md

@@ -1,23 +1,12 @@
-> 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) > [Export Media Assets](./export-save-publish/export.md) > [For Audio Processing](./guides/export-save-publish/export/audio.md)
 
 ---
 
-Export audio from pages, video blocks, audio blocks, and tracks to WAV or MP4 format for external processing, transcription, or analysis.
+Export audio from pages, video blocks, audio blocks, and tracks to WAV or MP4 format for external processing, transcription, or analysis in server-side Node.js applications.
 
-![Audio Export example showing audio export interface in CE.SDK](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
-> **Reading time:** 8 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-export-audio-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-export-audio-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-export-audio-browser/)
-
-The `exportAudio` API allows you to extract audio from any block that contains audio content. This is particularly useful when integrating with external audio processing services like speech-to-text transcription, audio enhancement, or music analysis platforms.
+The `exportAudio` API allows you to extract audio from any block that contains audio content. This is particularly useful when building server-side workflows that integrate with external audio processing services like speech-to-text transcription, audio enhancement, or music analysis platforms.
 
 Audio can be exported from multiple block types:
 
@@ -31,13 +20,15 @@ Audio can be exported from multiple block types:
 Export audio from any block using the `exportAudio` API:
 
 ```javascript
-const page = cesdk.engine.scene.getCurrentPage();
+const page = engine.scene.getCurrentPage();
 
-const audioBlob = await cesdk.engine.block.exportAudio(page, {
+const audioBuffer = await engine.block.exportAudio(page, {
   mimeType: 'audio/wav',
   sampleRate: 48000,
   numberOfChannels: 2
 });
+
+console.log(`Exported ${audioBuffer.byteLength} bytes`);
 ```
 
 ### Export Options
@@ -49,7 +40,7 @@ Configure your audio export with these options:
 - **`numberOfChannels`** - 1 for mono or 2 for stereo
 - **`timeOffset`** - Start time in seconds (default: 0)
 - **`duration`** - Length to export in seconds (0 = entire duration)
-- **`onProgress`** - Callback function receiving `(rendered, encoded, total)` for progress tracking
+- **`onProgress`** - Callback receiving `(rendered, encoded, total)` for progress tracking
 
 ## Find Audio Sources
 
@@ -57,13 +48,13 @@ To find blocks with audio in your scene:
 
 ```javascript
 // Find audio blocks
-const audioBlocks = cesdk.engine.block.findByType('audio');
+const audioBlocks = engine.block.findByType('audio');
 
 // Find video blocks with audio
-const videoFills = cesdk.engine.block.findByType('//ly.img.ubq/fill/video');
-const videosWithAudio = videoFills.filter((block) => {
+const videoFills = engine.block.findByType('//ly.img.ubq/fill/video');
+const videosWithAudio = videoFills.filter(block => {
   try {
-    return cesdk.engine.block.getAudioInfoFromVideo(block).length > 0;
+    return engine.block.getAudioInfoFromVideo(block).length > 0;
   } catch {
     return false;
   }
@@ -77,23 +68,23 @@ Videos can contain multiple audio tracks (e.g., different languages). CE.SDK pro
 ### Check audio track count
 
 ```javascript
-const videoFillId = cesdk.engine.block.findByType('//ly.img.ubq/fill/video')[0];
+const videoFillId = engine.block.findByType('//ly.img.ubq/fill/video')[0];
 
-const trackCount = cesdk.engine.block.getAudioTrackCountFromVideo(videoFillId);
+const trackCount = engine.block.getAudioTrackCountFromVideo(videoFillId);
 console.log(`Video has ${trackCount} audio track(s)`);
 ```
 
 ### Get track information
 
 ```javascript
-const audioTracks = cesdk.engine.block.getAudioInfoFromVideo(videoFillId);
+const audioTracks = engine.block.getAudioInfoFromVideo(videoFillId);
 
 audioTracks.forEach((track, index) => {
   console.log(`Track ${index}:`, {
-    channels: track.channels, // 1=mono, 2=stereo
-    sampleRate: track.sampleRate, // Sample rate in Hz
-    language: track.language, // e.g., "en", "es"
-    label: track.label // Track description
+    channels: track.channels,
+    sampleRate: track.sampleRate,
+    language: track.language || 'unknown',
+    label: track.label || `Track ${index}`
   });
 });
 ```
@@ -102,10 +93,10 @@ audioTracks.forEach((track, index) => {
 
 ```javascript
 // Create audio block from track 0 (first track)
-const audioBlockId = cesdk.engine.block.createAudioFromVideo(videoFillId, 0);
+const audioBlockId = engine.block.createAudioFromVideo(videoFillId, 0);
 
 // Export just this track's audio
-const trackAudioBlob = await cesdk.engine.block.exportAudio(audioBlockId, {
+const trackAudioBuffer = await engine.block.exportAudio(audioBlockId, {
   mimeType: 'audio/wav'
 });
 ```
@@ -114,12 +105,12 @@ const trackAudioBlob = await cesdk.engine.block.exportAudio(audioBlockId, {
 
 ```javascript
 // Create audio blocks for all tracks
-const audioBlockIds = cesdk.engine.block.createAudiosFromVideo(videoFillId);
+const audioBlockIds = engine.block.createAudiosFromVideo(videoFillId);
 
 // Export each track
 for (let i = 0; i < audioBlockIds.length; i++) {
-  const trackBlob = await cesdk.engine.block.exportAudio(audioBlockIds[i]);
-  console.log(`Track ${i}: ${trackBlob.size} bytes`);
+  const trackBuffer = await engine.block.exportAudio(audioBlockIds[i]);
+  console.log(`Track ${i}: ${trackBuffer.byteLength} bytes`);
 }
 ```
 
@@ -130,9 +121,9 @@ A common workflow is to export audio, send it to a transcription service, and us
 ### Step 1: Export Audio
 
 ```javascript
-const page = cesdk.engine.scene.getCurrentPage();
+const page = engine.scene.getCurrentPage();
 
-const audioBlob = await cesdk.engine.block.exportAudio(page, {
+const audioBuffer = await engine.block.exportAudio(page, {
   mimeType: 'audio/wav',
   sampleRate: 48000,
   numberOfChannels: 2
@@ -144,27 +135,31 @@ const audioBlob = await cesdk.engine.block.exportAudio(page, {
 Send the audio to a service that returns SubRip (SRT) format captions:
 
 ```javascript
-async function transcribeAudio(audioBlob) {
+import FormData from 'form-data';
+import fetch from 'node-fetch';
+
+async function transcribeAudio(audioBuffer) {
   const formData = new FormData();
-  formData.append('audio', audioBlob, 'audio.wav');
+  formData.append('audio', Buffer.from(audioBuffer), {
+    filename: 'audio.wav',
+    contentType: 'audio/wav'
+  });
   formData.append('format', 'srt');
 
-  const response = await fetch(
-    'https://api.transcription-service.com/transcribe',
-    {
-      method: 'POST',
-      headers: {
-        Authorization: 'Bearer YOUR_API_KEY'
-      },
-      body: formData
-    }
-  );
+  const response = await fetch('https://api.transcription-service.com/transcribe', {
+    method: 'POST',
+    headers: {
+      'Authorization': 'Bearer YOUR_API_KEY',
+      ...formData.getHeaders()
+    },
+    body: formData
+  });
 
   // Returns SRT format text
   return await response.text();
 }
 
-const srtContent = await transcribeAudio(audioBlob);
+const srtContent = await transcribeAudio(audioBuffer);
 ```
 
 ### Step 3: Import Captions from SRT
@@ -172,29 +167,33 @@ const srtContent = await transcribeAudio(audioBlob);
 Use the built-in API to create caption blocks from the SRT response:
 
 ```javascript
-// Create a file from the SRT text
-const srtFile = new File([srtContent], 'captions.srt', {
-  type: 'application/x-subrip'
-});
+import fs from 'fs/promises';
+import path from 'path';
+
+// Save SRT to temporary file
+const tempPath = path.join(process.cwd(), 'temp-captions.srt');
+await fs.writeFile(tempPath, srtContent);
+
+// Import captions from file URI
+const uri = `file://${tempPath}`;
+const captions = await engine.block.createCaptionsFromURI(uri);
 
-// Create object URL and import captions
-const uri = URL.createObjectURL(srtFile);
-const captions = await cesdk.engine.block.createCaptionsFromURI(uri);
-URL.revokeObjectURL(uri);
+// Clean up temporary file
+await fs.unlink(tempPath);
 
 // Add captions to page
-const page = cesdk.engine.scene.getCurrentPage();
-const captionTrack = cesdk.engine.block.create('//ly.img.ubq/captionTrack');
+const page = engine.scene.getCurrentPage();
+const captionTrack = engine.block.create('//ly.img.ubq/captionTrack');
 
-captions.forEach((caption) => {
-  cesdk.engine.block.appendChild(captionTrack, caption);
+captions.forEach(caption => {
+  engine.block.appendChild(captionTrack, caption);
 });
 
-cesdk.engine.block.appendChild(page, captionTrack);
+engine.block.appendChild(page, captionTrack);
 
 // Center the first caption as a reference point
-cesdk.engine.block.alignHorizontally([captions[0]], 'Center');
-cesdk.engine.block.alignVertically([captions[0]], 'Center');
+engine.block.alignHorizontally([captions[0]], 'Center');
+engine.block.alignVertically([captions[0]], 'Center');
 ```
 
 ### Other Processing Services
@@ -206,6 +205,19 @@ Audio export also supports these workflows:
 - **Language detection** - Identify spoken language
 - **Speaker diarization** - Identify who spoke when
 
+## Save to file
+
+Save exported audio to the file system:
+
+```javascript
+import fs from 'fs/promises';
+
+async function saveAudio(audioBuffer, fileName = 'exported_audio.wav') {
+  await fs.writeFile(fileName, Buffer.from(audioBuffer));
+  console.log(`Audio saved to: ${fileName}`);
+}
+```
+
 ## Next Steps
 
 Now that you understand audio export, explore related audio and video features:
@@ -214,11 +226,13 @@ Now that you understand audio export, explore related audio and video features:
 - [Control Audio and Video](./create-video/control.md) - Master time offset, duration, and playback controls for audio blocks
 - [Trim Video Clips](./edit-video/trim.md) - Apply the same trim concepts to isolate audio segments
 
+
+
 ---
 
 ## 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

package/assets/docs/guide/guides.md

@@ -1,21 +1,22 @@
-> 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)
 
 ---
 
+
+
+
+
 ---
 
 ## Related Pages
 
 - [Configuration](./configuration.md) - Learn how to configure CE.SDK to match your application's functional, visual, and performance requirements.
-- [Actions API](./actions.md) - Learn how to use the Actions API to register and customize action handlers in CE.SDK
 - [Settings](./settings.md) - Explore all configurable editor settings and learn how to read, update, and observe them via the Settings API.
 - [Serve Assets](./serve-assets.md) - Configure CE.SDK to load engine and content assets from your own servers instead of the IMG.LY CDN for production deployments.
 - [Engine Interface](./engine-interface.md) - Understand CE.SDK's architecture and learn when to use direct Engine access for automation workflows
 - [Automate Workflows](./automation.md) - Automate repetitive editing tasks using CE.SDK’s headless APIs to generate assets at scale.
-- [AI Integration](./user-interface/ai-integration.md) - Integrate external AI services into CE.SDK to enhance creative workflows and power advanced features.
-- [User Interface](./user-interface.md) - Use CE.SDK’s customizable, production-ready UI or replace it entirely with your own interface.
 - [Open the Editor](./open-the-editor.md) - Learn how to load and create scenes, set the zoom level, and configure file proxies or URI resolvers.
 - [Insert Media Into Scenes](./insert-media.md) - Understand how insertion works, how inserted media behave within scenes, and how to control them via UI or code.
 - [Import Media](./import-media.md) - Learn how to import, manage, and customize assets from local, remote, or camera sources in CE.SDK.
@@ -24,7 +25,6 @@
 - [Store Custom Metadata](./export-save-publish/store-custom-metadata.md) - Attach, retrieve, and manage custom key-value metadata on design blocks in CE.SDK.
 - [Edit Image](./edit-image.md) - Use CE.SDK to crop, transform, annotate, or enhance images with editing tools and programmatic APIs.
 - [Create Videos](./create-video.md) - Learn how to create and customize videos in CE.SDK using scenes, assets, and time-based editing.
-- [Audio](./create-audio/audio.md) - Create audio in videos
 - [Text](./text.md) - Add, style, and customize text layers in your design using CE.SDK’s flexible text editing tools.
 - [Create and Edit Shapes](./shapes.md) - Draw custom vector shapes, combine them with boolean operations, and insert QR codes into your designs.
 - [Create and Edit Stickers](./stickers.md) - Create and customize stickers using image fills for icons, logos, emoji, and multi-color graphics.
@@ -37,13 +37,14 @@
 - [Animation](./animation.md) - Add motion to designs with support for keyframes, timeline editing, and programmatic animation control.
 - [Rules](./rules.md) - Define and enforce layout, branding, and safety rules to ensure consistent and compliant designs.
 - [Conversion](./conversion.md) - Convert designs into different formats such as PDF, PNG, MP4, and more using CE.SDK tools.
-- [Improve Performance](./performance.md) - Optimize CE.SDK browser integration with code splitting, source sets for large assets, export workers, and lifecycle best practices.
+- [Improve Performance](./performance.md) - Optimize CE.SDK server integration with code splitting, memory monitoring, export timeouts, and lifecycle best practices for Node.js.
+
 
 ---
 
 ## 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