@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/edit-video/add-captions.md

@@ -1,259 +1,211 @@
-> 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) > [Create and Edit Videos](./create-video.md) > [Add Captions](./edit-video/add-captions.md)
 
 ---
 
-Add synchronized captions to video projects using CE.SDK's caption system, with support for importing subtitle files, styling with presets, and burning captions into video exports.
+Add synchronized captions to video projects using CE.SDK's caption system in headless mode, with support for importing subtitle files, styling programmatically, and saving scenes with captions.
 
-![Video captions example showing timeline with caption track and styled captions](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
-
-> **Reading time:** 15 minutes
+> **Reading time:** 10 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-create-video-add-captions-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-video-add-captions-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-video-add-captions-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-video-add-captions-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-video-add-captions-server-js)
 
 Captions in CE.SDK follow a hierarchy: **Page → CaptionTrack → Caption blocks**. Each caption has text, timing (time offset and duration), and styling properties. Captions appear and disappear based on their timing, synchronized with video playback.
 
-```typescript file=@cesdk_web_examples/guides-create-video-add-captions-browser/browser.ts reference-only
-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';
+<NodejsVideoExportNotice {...props} />
+
+```typescript file=@cesdk_web_examples/guides-create-video-add-captions-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+// Load environment variables
+config();
 
 /**
- * CE.SDK Plugin: Add Captions Guide
+ * CE.SDK Server Guide: Add Captions
  *
  * Demonstrates adding synchronized captions to video projects:
  * - Importing captions from SRT/VTT files
- * - Creating and styling captions programmatically
- * - Applying caption presets
- * - Controlling caption timing and positioning
- * - Adding animations to captions
+ * - Creating captions programmatically
+ * - Styling captions with typography and background
+ * - Saving scenes with captions for later rendering
  */
-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());
-
-    await cesdk.actions.run('scene.create', {
-      layout: 'DepthStack',
-      page: { width: 1920, height: 1080, unit: 'Pixel' }
-    });
 
-    const engine = cesdk.engine;
-    const page = engine.block.findByType('page')[0];
+// 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 {
+  // Create a scene with a page
+  const scene = engine.scene.create('DepthStack');
+  const page = engine.block.create('page');
+  engine.block.setWidth(page, 1920);
+  engine.block.setHeight(page, 1080);
+  engine.block.appendChild(scene, page);
+
+  // Set page duration to accommodate video content
+  engine.block.setDuration(page, 10);
+
+  // Add a video clip as the base content
+  const videoUrl =
+    'https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4';
+
+  const track = engine.block.create('track');
+  engine.block.appendChild(page, track);
+
+  const videoClip = await engine.block.addVideo(videoUrl, 1920, 1080, {
+    timeline: { duration: 10, timeOffset: 0 }
+  });
+  engine.block.appendChild(track, videoClip);
+  engine.block.fillParent(track);
+
+  // Import captions from SRT file
+  // createCaptionsFromURI parses SRT/VTT and creates caption blocks with timing
+  const captionSrtUrl = 'https://img.ly/static/examples/captions.srt';
+  const captionBlocks = await engine.block.createCaptionsFromURI(captionSrtUrl);
+
+  console.log(`Imported ${captionBlocks.length} captions from SRT file`);
+
+  // Create a caption track and add captions to it
+  // Caption tracks organize captions in the timeline
+  const captionTrack = engine.block.create('//ly.img.ubq/captionTrack');
+  engine.block.appendChild(page, captionTrack);
+
+  // Add each caption block to the track
+  for (const captionId of captionBlocks) {
+    engine.block.appendChild(captionTrack, captionId);
+  }
 
-    engine.block.setDuration(page, 40);
+  console.log(`Caption track created with ${captionBlocks.length} captions`);
 
-    // Add a video clip as the base content
-    const videoUrl =
-      'https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4';
+  // Read caption properties (text, timing)
+  if (captionBlocks.length > 0) {
+    const firstCaption = captionBlocks[0];
 
-    const track = engine.block.create('track');
-    engine.block.appendChild(page, track);
+    const text = engine.block.getString(firstCaption, 'caption/text');
+    const offset = engine.block.getTimeOffset(firstCaption);
+    const duration = engine.block.getDuration(firstCaption);
 
-    const videoClip = await engine.block.addVideo(videoUrl, 1920, 1080, {
-      timeline: { duration: 40, timeOffset: 0 }
+    console.log(`First caption: "${text}"`);
+    console.log(`  Time: ${offset}s - ${offset + duration}s`);
+  }
+
+  // Style all captions with consistent formatting
+  for (const captionId of captionBlocks) {
+    // Set font size
+    engine.block.setFloat(captionId, 'caption/fontSize', 48);
+
+    // Center alignment
+    engine.block.setEnum(captionId, 'caption/horizontalAlignment', 'Center');
+    engine.block.setEnum(captionId, 'caption/verticalAlignment', 'Bottom');
+
+    // Enable background for readability
+    engine.block.setBool(captionId, 'backgroundColor/enabled', true);
+    engine.block.setColor(captionId, 'backgroundColor/color', {
+      r: 0,
+      g: 0,
+      b: 0,
+      a: 0.7
     });
-    engine.block.appendChild(track, videoClip);
-    engine.block.fillParent(track);
-
-    // Import captions from SRT file
-    // createCaptionsFromURI parses SRT/VTT and creates caption blocks with timing
-    const captionSrtUrl = 'https://img.ly/static/examples/captions.srt';
-    const captionBlocks =
-      await engine.block.createCaptionsFromURI(captionSrtUrl);
-
-    // eslint-disable-next-line no-console
-    console.log(`Imported ${captionBlocks.length} captions from SRT file`);
-
-    // Adjust caption timing to start at the beginning of the video
-    // The SRT file may have different timing, so we reset to start at 0
-    let currentOffset = 0;
-    for (const captionId of captionBlocks) {
-      const duration = engine.block.getDuration(captionId);
-      engine.block.setTimeOffset(captionId, currentOffset);
-      currentOffset += duration;
-    }
-
-    // Create a caption track and add captions to it
-    // Caption tracks organize captions in the timeline
-    const captionTrack = engine.block.create('//ly.img.ubq/captionTrack');
-    engine.block.appendChild(page, captionTrack);
-
-    // Add each caption block to the track
-    for (const captionId of captionBlocks) {
-      engine.block.appendChild(captionTrack, captionId);
-    }
-
-    // eslint-disable-next-line no-console
-    console.log(`Caption track created with ${captionBlocks.length} captions`);
-
-    // Apply a caption preset for consistent styling
-    // Caption presets provide pre-configured styles (fonts, colors, backgrounds)
-    const captionPresetsSourceId = 'ly.img.caption.presets';
-    const comicPresetId = '//ly.img.caption.presets/comic';
-
-    // Fetch the preset asset
-    const comicPreset = await engine.asset.fetchAsset(
-      captionPresetsSourceId,
-      comicPresetId
-    );
-
-    // Apply preset to the first caption (styling syncs across all captions)
-    if (comicPreset && captionBlocks.length > 0) {
-      await engine.asset.applyToBlock(
-        captionPresetsSourceId,
-        comicPreset,
-        captionBlocks[0]
-      );
-      // eslint-disable-next-line no-console
-      console.log('Applied comic preset to captions');
-    }
-
-    // Position captions at the bottom of the video frame
-    // Caption position and size sync across all captions, so we only set it once
-    if (captionBlocks.length > 0) {
-      const firstCaption = captionBlocks[0];
-
-      // Use percentage-based positioning for responsive layout
-      engine.block.setPositionXMode(firstCaption, 'Percent');
-      engine.block.setPositionYMode(firstCaption, 'Percent');
-      engine.block.setWidthMode(firstCaption, 'Percent');
-      engine.block.setHeightMode(firstCaption, 'Percent');
-
-      // Position at bottom center with padding
-      engine.block.setPositionX(firstCaption, 0.05); // 5% from left
-      engine.block.setPositionY(firstCaption, 0.8); // 80% from top (near bottom)
-      engine.block.setWidth(firstCaption, 0.9); // 90% width
-      engine.block.setHeight(firstCaption, 0.15); // 15% height
-    }
-
-    // Modify a specific caption's text and timing
-    if (captionBlocks.length > 0) {
-      const firstCaption = captionBlocks[0];
-
-      // Get current text
-      const currentText = engine.block.getString(firstCaption, 'caption/text');
-      // eslint-disable-next-line no-console
-      console.log('First caption text:', currentText);
-
-      // Get timing info
-      const offset = engine.block.getTimeOffset(firstCaption);
-      const duration = engine.block.getDuration(firstCaption);
-      // eslint-disable-next-line no-console
-      console.log(`First caption: offset=${offset}s, duration=${duration}s`);
-    }
-
-    // Add fade-in animation to the first caption
-    if (captionBlocks.length > 0) {
-      const firstCaption = captionBlocks[0];
-
-      // Create and apply entry animation
-      const fadeIn = engine.block.createAnimation('fade');
-      engine.block.setDuration(fadeIn, 0.3);
-      engine.block.setInAnimation(firstCaption, fadeIn);
-
-      // eslint-disable-next-line no-console
-      console.log('Added fade-in animation to first caption');
-    }
-
-    // Select the first caption to show it in the inspector
-    if (captionBlocks.length > 0) {
-      engine.block.select(captionBlocks[0]);
-    }
-
-    // Seek to show the first caption at 1 second
-    engine.block.setPlaybackTime(page, 1);
-
-    // Open the caption inspector panel
-    cesdk.ui.openPanel('//ly.img.panel/inspector/caption');
-
-    // eslint-disable-next-line no-console
-    console.log(
-      'Add Captions guide initialized. Captions imported and styled.'
-    );
   }
-}
 
-export default Example;
+  console.log('Applied styling to all captions');
+
+  // Position captions at the bottom of the video frame
+  // Caption position and size sync across all captions, so we only set it once
+  if (captionBlocks.length > 0) {
+    const firstCaption = captionBlocks[0];
+
+    // Use percentage-based positioning for responsive layout
+    engine.block.setPositionXMode(firstCaption, 'Percent');
+    engine.block.setPositionYMode(firstCaption, 'Percent');
+    engine.block.setWidthMode(firstCaption, 'Percent');
+    engine.block.setHeightMode(firstCaption, 'Percent');
+
+    // Position at bottom center with padding
+    engine.block.setPositionX(firstCaption, 0.05); // 5% from left
+    engine.block.setPositionY(firstCaption, 0.8); // 80% from top (near bottom)
+    engine.block.setWidth(firstCaption, 0.9); // 90% width
+    engine.block.setHeight(firstCaption, 0.15); // 15% height
+
+    console.log('Positioned captions at bottom of frame');
+  }
+
+  // Create a caption programmatically (in addition to imported ones)
+  const manualCaption = engine.block.create('//ly.img.ubq/caption');
+  engine.block.appendChild(captionTrack, manualCaption);
+
+  // Set caption text
+  engine.block.setString(manualCaption, 'caption/text', 'Manual caption added');
+
+  // Set timing - appears at 8 seconds for 2 seconds
+  engine.block.setTimeOffset(manualCaption, 8);
+  engine.block.setDuration(manualCaption, 2);
+
+  // Apply same styling
+  engine.block.setFloat(manualCaption, 'caption/fontSize', 48);
+  engine.block.setEnum(manualCaption, 'caption/horizontalAlignment', 'Center');
+  engine.block.setEnum(manualCaption, 'caption/verticalAlignment', 'Bottom');
+  engine.block.setBool(manualCaption, 'backgroundColor/enabled', true);
+  engine.block.setColor(manualCaption, 'backgroundColor/color', {
+    r: 0,
+    g: 0,
+    b: 0,
+    a: 0.7
+  });
+
+  console.log('Created manual caption at 8s');
+
+  // Add entry animation to captions
+  for (const captionId of captionBlocks) {
+    const fadeIn = engine.block.createAnimation('fade');
+    engine.block.setDuration(fadeIn, 0.2);
+    engine.block.setInAnimation(captionId, fadeIn);
+  }
+
+  console.log('Added fade-in animations to captions');
+
+  // Save scene to file for later rendering
+  // The scene preserves all caption data, styling, and animations
+  const sceneString = await engine.scene.saveToString();
+
+  // Save to output directory
+  const outputDir = join(process.cwd(), 'output');
+  await mkdir(outputDir, { recursive: true });
+
+  const outputPath = join(outputDir, 'video-with-captions.scene');
+  await writeFile(outputPath, sceneString);
+
+  console.log(`Scene saved: ${outputPath}`);
+
+  console.log('');
+  console.log('Add Captions guide complete.');
+  console.log('Scene created with:');
+  console.log(`  - ${captionBlocks.length} imported captions`);
+  console.log('  - 1 manually created caption');
+  console.log('  - Consistent styling across all captions');
+  console.log('  - Fade-in animations');
+  console.log('');
+  console.log(
+    'Use CE.SDK Renderer to export this scene as a video with burned-in captions.'
+  );
+} finally {
+  // Always dispose of the engine to free resources
+  engine.dispose();
+}
 ```
 
-This guide covers how to import captions from SRT/VTT files, style them using presets and custom properties, create captions programmatically, and export videos with burned-in captions.
+This guide covers how to import captions from SRT/VTT files, style them using custom properties, create captions programmatically, and save scenes with captions in a headless Node.js environment.
 
 ## Understanding Caption Structure
 
@@ -267,6 +219,38 @@ When you import captions from a subtitle file, CE.SDK automatically creates the
 
 Each caption has two timing properties: **time offset** (when the caption appears) and **duration** (how long it stays visible). These values are in seconds and synchronize with the video playback. A caption with a time offset of 2.0 and duration of 3.0 appears at the 2-second mark and disappears at the 5-second mark.
 
+## Initialize CE.SDK
+
+For headless video processing with captions, we initialize CE.SDK's Node.js engine. This provides full API access without browser dependencies, ideal for server-side automation and batch processing.
+
+```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)
+});
+```
+
+The headless engine gives you complete control over caption operations, perfect for automated workflows, background processing, and server-side video preparation.
+
+## Creating the Scene
+
+Create a scene with page configuration. The `page` option creates a page with the specified dimensions.
+
+```typescript highlight-create-scene
+  // Create a scene with a page
+  const scene = engine.scene.create('DepthStack');
+  const page = engine.block.create('page');
+  engine.block.setWidth(page, 1920);
+  engine.block.setHeight(page, 1080);
+  engine.block.appendChild(scene, page);
+
+  // Set page duration to accommodate video content
+  engine.block.setDuration(page, 10);
+```
+
+Set the page duration to accommodate your video content. The dimensions define the output video resolution.
+
 ## Importing Captions from Subtitle Files
 
 ### Using createCaptionsFromURI
@@ -274,64 +258,55 @@ Each caption has two timing properties: **time offset** (when the caption appear
 The fastest way to add captions is importing from an SRT or VTT subtitle file. CE.SDK parses the file and creates caption blocks with timing already configured.
 
 ```typescript highlight-import-captions
-// Import captions from SRT file
-// createCaptionsFromURI parses SRT/VTT and creates caption blocks with timing
-const captionSrtUrl = 'https://img.ly/static/examples/captions.srt';
-const captionBlocks = await engine.block.createCaptionsFromURI(captionSrtUrl);
-
-// eslint-disable-next-line no-console
-console.log(`Imported ${captionBlocks.length} captions from SRT file`);
-
-// Adjust caption timing to start at the beginning of the video
-// The SRT file may have different timing, so we reset to start at 0
-let currentOffset = 0;
-for (const captionId of captionBlocks) {
-  const duration = engine.block.getDuration(captionId);
-  engine.block.setTimeOffset(captionId, currentOffset);
-  currentOffset += duration;
-}
+  // Import captions from SRT file
+  // createCaptionsFromURI parses SRT/VTT and creates caption blocks with timing
+  const captionSrtUrl = 'https://img.ly/static/examples/captions.srt';
+  const captionBlocks = await engine.block.createCaptionsFromURI(captionSrtUrl);
+
+  console.log(`Imported ${captionBlocks.length} captions from SRT file`);
 ```
 
 The `createCaptionsFromURI` method downloads the subtitle file, parses the timing and text, and creates a caption track with all captions positioned correctly. It returns an array of caption block IDs for the imported captions.
 
 ### Creating the Caption Track
 
-After importing captions, create a caption track to organize them in the composition. The caption track manages caption positioning and display.
+After importing captions, create a caption track to organize them in the composition.
 
 ```typescript highlight-create-caption-track
-// Create a caption track and add captions to it
-// Caption tracks organize captions in the timeline
-const captionTrack = engine.block.create('//ly.img.ubq/captionTrack');
-engine.block.appendChild(page, captionTrack);
-
-// Add each caption block to the track
-for (const captionId of captionBlocks) {
-  engine.block.appendChild(captionTrack, captionId);
-}
+  // Create a caption track and add captions to it
+  // Caption tracks organize captions in the timeline
+  const captionTrack = engine.block.create('//ly.img.ubq/captionTrack');
+  engine.block.appendChild(page, captionTrack);
+
+  // Add each caption block to the track
+  for (const captionId of captionBlocks) {
+    engine.block.appendChild(captionTrack, captionId);
+  }
 
-// eslint-disable-next-line no-console
-console.log(`Caption track created with ${captionBlocks.length} captions`);
+  console.log(`Caption track created with ${captionBlocks.length} captions`);
 ```
 
 Create a caption track with `engine.block.create('//ly.img.ubq/captionTrack')` and append it to the page. Then add each caption block to the track using `appendChild`.
 
-## Using the Built-in Caption UI
-
-### Caption Panel
-
-CE.SDK provides a caption panel in the inspector for visual caption management. When you select a caption, the panel shows timing controls, text editing, and styling options. Users can drag caption edges in the timeline to adjust timing or double-click to edit text.
-
-### Importing via UI
+## Reading Caption Properties
 
-The caption panel includes an import button for uploading SRT or VTT files. The interface guides users through file selection and automatically extracts timing information.
+Retrieve caption properties for processing, validation, or logging.
 
-### Styling with Presets
+```typescript highlight-read-caption-properties
+  // Read caption properties (text, timing)
+  if (captionBlocks.length > 0) {
+    const firstCaption = captionBlocks[0];
 
-Caption presets provide pre-configured styling combinations including font, color, background, and animations. Select a caption and choose from available presets to apply consistent styling. Presets are especially useful for maintaining brand consistency across videos.
+    const text = engine.block.getString(firstCaption, 'caption/text');
+    const offset = engine.block.getTimeOffset(firstCaption);
+    const duration = engine.block.getDuration(firstCaption);
 
-### Editing Text and Timing
+    console.log(`First caption: "${text}"`);
+    console.log(`  Time: ${offset}s - ${offset + duration}s`);
+  }
+```
 
-Double-click a caption in the timeline or panel to edit its text. Drag the edges of caption blocks in the timeline to adjust start time and duration. The timeline provides visual feedback showing caption positions relative to video content.
+Use `getString` for text, `getTimeOffset` for start time, and `getDuration` for display length. These values are useful for validation or synchronization workflows.
 
 ## Creating Captions Programmatically
 
@@ -348,77 +323,65 @@ engine.block.appendChild(page, captionTrack);
 
 Create individual captions with text and timing.
 
-```typescript
-const caption = engine.block.create('//ly.img.ubq/caption');
-engine.block.appendChild(captionTrack, caption);
-
-// Set caption text
-engine.block.setString(caption, 'caption/text', 'Hello, world!');
-
-// Set timing - appears at 2 seconds for 3 seconds
-engine.block.setTimeOffset(caption, 2);
-engine.block.setDuration(caption, 3);
+```typescript highlight-create-caption-manually
+  // Create a caption programmatically (in addition to imported ones)
+  const manualCaption = engine.block.create('//ly.img.ubq/caption');
+  engine.block.appendChild(captionTrack, manualCaption);
+
+  // Set caption text
+  engine.block.setString(manualCaption, 'caption/text', 'Manual caption added');
+
+  // Set timing - appears at 8 seconds for 2 seconds
+  engine.block.setTimeOffset(manualCaption, 8);
+  engine.block.setDuration(manualCaption, 2);
+
+  // Apply same styling
+  engine.block.setFloat(manualCaption, 'caption/fontSize', 48);
+  engine.block.setEnum(manualCaption, 'caption/horizontalAlignment', 'Center');
+  engine.block.setEnum(manualCaption, 'caption/verticalAlignment', 'Bottom');
+  engine.block.setBool(manualCaption, 'backgroundColor/enabled', true);
+  engine.block.setColor(manualCaption, 'backgroundColor/color', {
+    r: 0,
+    g: 0,
+    b: 0,
+    a: 0.7
+  });
+
+  console.log('Created manual caption at 8s');
 ```
 
 Set the caption text using `setString` with the `caption/text` property. Position the caption in time using `setTimeOffset` (when it appears) and `setDuration` (how long it shows).
 
 ## Styling Captions
 
-### Applying Presets
+### Typography
 
-The fastest way to style captions is using presets. Presets provide pre-configured styling including fonts, colors, backgrounds, and effects.
+Control caption appearance with typography properties.
 
-```typescript highlight-apply-preset
-// Apply a caption preset for consistent styling
-// Caption presets provide pre-configured styles (fonts, colors, backgrounds)
-const captionPresetsSourceId = 'ly.img.caption.presets';
-const comicPresetId = '//ly.img.caption.presets/comic';
+```typescript highlight-style-captions
+  // Style all captions with consistent formatting
+  for (const captionId of captionBlocks) {
+    // Set font size
+    engine.block.setFloat(captionId, 'caption/fontSize', 48);
 
-// Fetch the preset asset
-const comicPreset = await engine.asset.fetchAsset(
-  captionPresetsSourceId,
-  comicPresetId
-);
+    // Center alignment
+    engine.block.setEnum(captionId, 'caption/horizontalAlignment', 'Center');
+    engine.block.setEnum(captionId, 'caption/verticalAlignment', 'Bottom');
 
-// Apply preset to the first caption (styling syncs across all captions)
-if (comicPreset && captionBlocks.length > 0) {
-  await engine.asset.applyToBlock(
-    captionPresetsSourceId,
-    comicPreset,
-    captionBlocks[0]
-  );
-  // eslint-disable-next-line no-console
-  console.log('Applied comic preset to captions');
-}
-```
-
-Fetch a preset using `engine.asset.fetchAsset` and apply it with `engine.asset.applyToBlock`. Caption styling automatically syncs across all captions, so applying a preset to one caption styles them all.
-
-### Positioning Captions
-
-Position captions at the bottom of the video frame using percentage-based positioning for responsive layout.
-
-```typescript highlight-position-captions
-// Position captions at the bottom of the video frame
-// Caption position and size sync across all captions, so we only set it once
-if (captionBlocks.length > 0) {
-  const firstCaption = captionBlocks[0];
-
-  // Use percentage-based positioning for responsive layout
-  engine.block.setPositionXMode(firstCaption, 'Percent');
-  engine.block.setPositionYMode(firstCaption, 'Percent');
-  engine.block.setWidthMode(firstCaption, 'Percent');
-  engine.block.setHeightMode(firstCaption, 'Percent');
+    // Enable background for readability
+    engine.block.setBool(captionId, 'backgroundColor/enabled', true);
+    engine.block.setColor(captionId, 'backgroundColor/color', {
+      r: 0,
+      g: 0,
+      b: 0,
+      a: 0.7
+    });
+  }
 
-  // Position at bottom center with padding
-  engine.block.setPositionX(firstCaption, 0.05); // 5% from left
-  engine.block.setPositionY(firstCaption, 0.8); // 80% from top (near bottom)
-  engine.block.setWidth(firstCaption, 0.9); // 90% width
-  engine.block.setHeight(firstCaption, 0.15); // 15% height
-}
+  console.log('Applied styling to all captions');
 ```
 
-Use percentage mode (`setPositionXMode`, `setPositionYMode`) for positions that adapt to different video resolutions. Caption position and size sync across all captions automatically.
+Use `setFloat` for numeric values like `caption/fontSize`, `caption/letterSpacing`, and `caption/lineHeight`. Set alignment with `setEnum` for `caption/horizontalAlignment` (Left, Center, Right) and `caption/verticalAlignment` (Top, Center, Bottom).
 
 ### Background
 
@@ -436,34 +399,6 @@ engine.block.setFloat(captionId, 'caption/maxAutomaticFontSize', 72);
 
 This prevents text from overflowing while maintaining readability.
 
-## Applying Presets Programmatically
-
-### Finding Available Presets
-
-Query available caption presets from the asset library.
-
-```typescript
-const presetsResult = await engine.asset.findAssets('ly.img.caption.presets', {
-  page: 0,
-  perPage: 100
-});
-
-const presets = presetsResult.assets;
-```
-
-The `findAssets` method returns preset metadata including IDs and preview thumbnails.
-
-### Applying a Preset
-
-Apply a preset to a caption using `applyToBlock`.
-
-```typescript
-const preset = presets[0];
-await engine.asset.applyToBlock('ly.img.caption.presets', preset, captionId);
-```
-
-The preset applies all styling properties at once—font, colors, background, and any animations defined in the preset.
-
 ## Caption Animations
 
 ### Adding Entry Animations
@@ -471,18 +406,14 @@ The preset applies all styling properties at once—font, colors, background, an
 Make captions more engaging by adding entry animations.
 
 ```typescript highlight-add-animation
-// Add fade-in animation to the first caption
-if (captionBlocks.length > 0) {
-  const firstCaption = captionBlocks[0];
-
-  // Create and apply entry animation
-  const fadeIn = engine.block.createAnimation('fade');
-  engine.block.setDuration(fadeIn, 0.3);
-  engine.block.setInAnimation(firstCaption, fadeIn);
+  // Add entry animation to captions
+  for (const captionId of captionBlocks) {
+    const fadeIn = engine.block.createAnimation('fade');
+    engine.block.setDuration(fadeIn, 0.2);
+    engine.block.setInAnimation(captionId, fadeIn);
+  }
 
-  // eslint-disable-next-line no-console
-  console.log('Added fade-in animation to first caption');
-}
+  console.log('Added fade-in animations to captions');
 ```
 
 Create an animation using `createAnimation` with types like 'fade', 'slide', or 'scale'. Set the animation duration and apply it with `setInAnimation`.
@@ -498,92 +429,84 @@ CE.SDK supports several animation types for captions:
 
 Set loop animations with `setLoopAnimation` for continuous effects, or exit animations with `setOutAnimation` for departure transitions.
 
-## Reading Caption Properties
+## Saving the Scene
 
-### Getting Text and Timing
+After adding captions, save the scene to a `.scene` file for later use or rendering with the CE.SDK Renderer service.
 
-Retrieve caption properties to display in custom UI or for processing.
+```typescript highlight-save-scene
+  // Save scene to file for later rendering
+  // The scene preserves all caption data, styling, and animations
+  const sceneString = await engine.scene.saveToString();
 
-```typescript highlight-modify-caption
-// Modify a specific caption's text and timing
-if (captionBlocks.length > 0) {
-  const firstCaption = captionBlocks[0];
+  // Save to output directory
+  const outputDir = join(process.cwd(), 'output');
+  await mkdir(outputDir, { recursive: true });
 
-  // Get current text
-  const currentText = engine.block.getString(firstCaption, 'caption/text');
-  // eslint-disable-next-line no-console
-  console.log('First caption text:', currentText);
+  const outputPath = join(outputDir, 'video-with-captions.scene');
+  await writeFile(outputPath, sceneString);
 
-  // Get timing info
-  const offset = engine.block.getTimeOffset(firstCaption);
-  const duration = engine.block.getDuration(firstCaption);
-  // eslint-disable-next-line no-console
-  console.log(`First caption: offset=${offset}s, duration=${duration}s`);
-}
+  console.log(`Scene saved: ${outputPath}`);
 ```
 
-Use `getString` for text, `getTimeOffset` for start time, and `getDuration` for display length. These values are useful for building custom caption editors or synchronization tools.
-
-## Exporting Videos with Captions
+The scene file preserves all caption data including text, timing, styling, and animations. You can load this scene later for further editing or send it to the CE.SDK Renderer for video export.
 
-### Burned-In Captions
+## Resource Cleanup
 
-When you export a video, captions are burned into the video as pixels. They become part of the video image and cannot be turned off by viewers. This ensures captions display correctly on any platform.
+Always dispose of the engine when processing is complete to free resources.
 
-```typescript
-const videoBlob = await engine.block.exportVideo(page, {
-  mimeType: 'video/mp4'
-});
+```typescript highlight-cleanup
+// Always dispose of the engine to free resources
+engine.dispose();
 ```
 
-The export process renders each frame with captions overlaid at the correct timing. Export time depends on video length and resolution.
-
-> **Note:** For accessibility, consider also providing separate subtitle files (SRT/VTT) alongside burned-in captions. This allows viewers to customize caption appearance in their video player.
+Use a try/finally pattern to ensure cleanup happens even if an error occurs during processing.
 
 ## Troubleshooting
 
-| Issue                | Cause                          | Solution                                           |
-| -------------------- | ------------------------------ | -------------------------------------------------- |
+| Issue | Cause | Solution |
+| --- | --- | --- |
 | Captions not visible | Not in caption track hierarchy | Check `getParent()`: page → captionTrack → caption |
-| Wrong timing         | Time offset/duration incorrect | Verify `getTimeOffset()` and `getDuration()`       |
-| Import fails         | Unsupported format             | Use valid SRT or VTT file                          |
-| Styling not applying | Property path wrong            | Use `caption/` prefix for caption properties       |
+| Wrong timing | Time offset/duration incorrect | Verify `getTimeOffset()` and `getDuration()` |
+| Import fails | Unsupported format | Use valid SRT or VTT file |
+| Styling not applying | Property path wrong | Use `caption/` prefix for caption properties |
 
 ### Captions Not Appearing
 
-If captions don't show in the preview, verify the caption hierarchy. Each caption must be a child of a caption track, which must be a child of the page. Use `getParent()` to trace the hierarchy.
+If captions don't appear in the exported video, verify the caption hierarchy. Each caption must be a child of a caption track, which must be a child of the page. Use `getParent()` to trace the hierarchy.
 
-Also check that the playhead position matches caption timing. Captions only appear during their time offset and duration window.
+Also check that caption timing falls within the page duration. Captions outside the page's time range won't appear in the export.
 
 ### Import Errors
 
-If `createCaptionsFromURI` fails, verify the URL is accessible and returns valid SRT or VTT content. Common issues include CORS restrictions and malformed subtitle files. Test the URL in a browser to confirm accessibility.
+If `createCaptionsFromURI` fails, verify the URL is accessible from your server and returns valid SRT or VTT content. Common issues include network restrictions and malformed subtitle files. Test the URL with curl to confirm accessibility.
 
 ## API Reference
 
-| Method                                              | Purpose                           |
-| --------------------------------------------------- | --------------------------------- |
-| `engine.block.createCaptionsFromURI(uri)`           | Import captions from SRT/VTT file |
-| `engine.block.create('//ly.img.ubq/captionTrack')`  | Create caption track container    |
-| `engine.block.create('//ly.img.ubq/caption')`       | Create caption block              |
-| `engine.block.setString(id, property, value)`       | Set caption text                  |
-| `engine.block.setTimeOffset(id, offset)`            | Set caption start time            |
-| `engine.block.setDuration(id, duration)`            | Set caption display duration      |
-| `engine.block.setFloat(id, property, value)`        | Set font size, spacing            |
-| `engine.block.setEnum(id, property, value)`         | Set alignment                     |
-| `engine.block.setBool(id, property, value)`         | Enable background                 |
-| `engine.block.setColor(id, property, value)`        | Set colors                        |
-| `engine.block.createAnimation(type)`                | Create animation                  |
-| `engine.block.setInAnimation(id, animation)`        | Set entry animation               |
-| `engine.block.exportVideo(id, options)`             | Export video with captions        |
-| `engine.asset.findAssets(sourceId, params)`         | Find presets                      |
-| `engine.asset.applyToBlock(sourceId, asset, block)` | Apply preset                      |
+| Method | Purpose |
+| --- | --- |
+| `engine.scene.create()` | Create a scene |
+| `engine.block.createCaptionsFromURI(uri)` | Import captions from SRT/VTT file |
+| `engine.block.create('//ly.img.ubq/captionTrack')` | Create caption track container |
+| `engine.block.create('//ly.img.ubq/caption')` | Create caption block |
+| `engine.block.setString(id, property, value)` | Set caption text |
+| `engine.block.setTimeOffset(id, offset)` | Set caption start time |
+| `engine.block.setDuration(id, duration)` | Set caption display duration |
+| `engine.block.setFloat(id, property, value)` | Set font size, spacing |
+| `engine.block.setEnum(id, property, value)` | Set alignment |
+| `engine.block.setBool(id, property, value)` | Enable background |
+| `engine.block.setColor(id, property, value)` | Set colors |
+| `engine.block.createAnimation(type)` | Create animation |
+| `engine.block.setInAnimation(id, animation)` | Set entry animation |
+| `engine.scene.saveToString()` | Save scene to string |
+| `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