@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/create-audio/audio/add-music.md

@@ -1,253 +1,190 @@
-> 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).
-
-**Navigation:** [Guides](./guides.md) > [Create and Edit Audio](./create-audio/audio.md) > [Add Music](./create-audio/audio/add-music.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).
 
 ---
 
-Add background music and audio tracks to video projects using CE.SDK's audio
-block system for rich multimedia experiences.
-
-![Add Music example showing audio tracks in the timeline](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Add background music and audio tracks to video projects programmatically using
+CE.SDK's headless engine for server-side audio processing.
 
 > **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-audio-add-music-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-audio-add-music-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-audio-add-music-browser/)
-
-Audio blocks are standalone time-based blocks that play alongside video content, independent of video fills. You can add music from the built-in asset library or from custom URLs, position tracks in the composition, configure volume levels, and layer multiple audio tracks for complex soundscapes.
-
-```typescript file=@cesdk_web_examples/guides-create-audio-add-music-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';
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-audio-add-music-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-audio-add-music-server-js)
+
+<NodejsVideoExportNotice {...props} />
+
+Audio blocks are standalone time-based blocks that play alongside video content, independent of video fills. In headless server environments, you can create audio blocks, configure time-based position and volume, and manage multiple audio tracks programmatically using the Engine API.
+
+```typescript file=@cesdk_web_examples/guides-create-audio-add-music-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { config } from 'dotenv';
+
+config();
 
 /**
- * CE.SDK Plugin: Add Music Guide
+ * CE.SDK Server Guide: Add Music
  *
  * Demonstrates adding background music to video projects:
  * - Creating audio blocks programmatically
  * - Setting audio source URIs
  * - Configuring timeline position and duration
- * - Adjusting audio volume
- * - Querying audio assets from the library
- * - Managing audio blocks
+ * - Setting volume levels
+ * - Managing multiple audio blocks
  */
-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.scene.getCurrentPage();
-    if (!page) {
-      throw new Error('No page found in scene');
-    }
-
-    // Set page duration for timeline
-    engine.block.setDuration(page, 30);
-
-    // Enable audio and timeline features for the UI
-    cesdk.feature.enable('ly.img.video.timeline');
-    cesdk.feature.enable('ly.img.video.timeline.audio');
-    cesdk.feature.enable('ly.img.video.timeline.controls.playback');
-
-    // Create an audio block for background music
-    const audioBlock = engine.block.create('audio');
-
-    // Set the audio source file
-    const audioUri =
-      'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/far_from_home.m4a';
-    engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
-
-    // Append audio to the page (makes it part of the timeline)
-    engine.block.appendChild(page, audioBlock);
-
-    // Wait for audio to load to get duration
-    await engine.block.forceLoadAVResource(audioBlock);
-
-    // Get the total duration of the audio file
-    const totalDuration = engine.block.getAVResourceTotalDuration(audioBlock);
-    console.log('Audio total duration:', totalDuration, 'seconds');
-
-    // Set when the audio starts on the timeline (0 = beginning)
-    engine.block.setTimeOffset(audioBlock, 0);
-
-    // Set how long the audio plays (use full duration or page duration)
-    const playbackDuration = Math.min(totalDuration, 30);
-    engine.block.setDuration(audioBlock, playbackDuration);
-
-    // Set the audio volume (0.0 = mute, 1.0 = full volume)
-    engine.block.setVolume(audioBlock, 0.8);
-
-    // Get current volume
-    const currentVolume = engine.block.getVolume(audioBlock);
-    console.log('Audio volume:', currentVolume);
-
-    // Query available audio tracks from the asset library
-    const audioAssets = await engine.asset.findAssets('ly.img.audio', {
-      page: 0,
-      perPage: 10
-    });
-
-    console.log('Available audio assets:', audioAssets.assets.length);
-
-    // Log metadata for each audio asset
-    audioAssets.assets.forEach((asset) => {
-      console.log('Audio asset:', {
-        id: asset.id,
-        label: asset.label,
-        duration: asset.meta?.duration,
-        uri: asset.meta?.uri
-      });
-    });
-
-    // Find all audio blocks in the scene
-    const allAudioBlocks = engine.block.findByType('audio');
-    console.log('Total audio blocks:', allAudioBlocks.length);
-
-    // Get information about each audio block
-    allAudioBlocks.forEach((block, index) => {
-      const uri = engine.block.getString(block, 'audio/fileURI');
-      const timeOffset = engine.block.getTimeOffset(block);
-      const duration = engine.block.getDuration(block);
-      const volume = engine.block.getVolume(block);
-
-      console.log(`Audio block ${index + 1}:`, {
-        uri: uri.split('/').pop(), // Just filename
-        timeOffset: `${timeOffset}s`,
-        duration: `${duration}s`,
-        volume: `${(volume * 100).toFixed(0)}%`
-      });
-    });
-
-    // Example: Remove the second audio block if it exists
-    if (allAudioBlocks.length > 1) {
-      const blockToRemove = allAudioBlocks[1];
-
-      // Destroy the block to remove it and free resources
-      engine.block.destroy(blockToRemove);
-
-      console.log('Removed second audio block');
-    }
 
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
+
+try {
+  // Create a scene with a page for audio content
+  engine.scene.create('DepthStack');
+  const page = engine.block.create('page');
+  engine.block.setWidth(page, 1920);
+  engine.block.setHeight(page, 1080);
+  engine.block.appendChild(engine.scene.get()!, page);
+
+  // Set page duration for timeline (30 seconds)
+  engine.block.setDuration(page, 30);
+
+  // Create an audio block for background music
+  const audioBlock = engine.block.create('audio');
+
+  // Set the audio source file
+  const audioUri =
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/far_from_home.m4a';
+  engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
+
+  // Append audio to the page (makes it part of the timeline)
+  engine.block.appendChild(page, audioBlock);
+
+  // Wait for audio to load to get duration
+  await engine.block.forceLoadAVResource(audioBlock);
+
+  // Get the total duration of the audio file
+  const totalDuration = engine.block.getAVResourceTotalDuration(audioBlock);
+  console.log('Audio total duration:', totalDuration.toFixed(2), 'seconds');
+
+  // Set when the audio starts on the timeline (0 = beginning)
+  engine.block.setTimeOffset(audioBlock, 0);
+
+  // Set how long the audio plays (use full duration or page duration)
+  const playbackDuration = Math.min(totalDuration, 30);
+  engine.block.setDuration(audioBlock, playbackDuration);
+
+  // Set the audio volume (0.0 = mute, 1.0 = full volume)
+  engine.block.setVolume(audioBlock, 0.8);
+
+  // Get current volume
+  const currentVolume = engine.block.getVolume(audioBlock);
+  console.log('Audio volume:', `${(currentVolume * 100).toFixed(0)}%`);
+
+  // Add a second audio track with different settings
+  const secondAudioBlock = engine.block.create('audio');
+  const secondAudioUri =
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/dance_harder.m4a';
+  engine.block.setString(secondAudioBlock, 'audio/fileURI', secondAudioUri);
+  engine.block.appendChild(page, secondAudioBlock);
+
+  // Load and configure the second audio
+  await engine.block.forceLoadAVResource(secondAudioBlock);
+  const secondDuration =
+    engine.block.getAVResourceTotalDuration(secondAudioBlock);
+
+  // Start second audio after the first one ends, at lower volume
+  engine.block.setTimeOffset(secondAudioBlock, playbackDuration);
+  engine.block.setDuration(secondAudioBlock, Math.min(secondDuration, 15));
+  engine.block.setVolume(secondAudioBlock, 0.5);
+
+  // Find all audio blocks in the scene
+  const allAudioBlocks = engine.block.findByType('audio');
+  console.log('\nTotal audio blocks:', allAudioBlocks.length);
+
+  // Get information about each audio block
+  allAudioBlocks.forEach((block, index) => {
+    const uri = engine.block.getString(block, 'audio/fileURI');
+    const timeOffset = engine.block.getTimeOffset(block);
+    const duration = engine.block.getDuration(block);
+    const volume = engine.block.getVolume(block);
+
+    console.log(`\nAudio block ${index + 1}:`);
+    console.log(`  File: ${uri.split('/').pop()}`);
+    console.log(`  Time offset: ${timeOffset.toFixed(2)}s`);
+    console.log(`  Duration: ${duration.toFixed(2)}s`);
+    console.log(`  Volume: ${(volume * 100).toFixed(0)}%`);
+  });
+
+  // Demonstrate removing an audio block
+  if (allAudioBlocks.length > 1) {
+    const blockToRemove = allAudioBlocks[1];
+
+    // Destroy the block to remove it and free resources
+    engine.block.destroy(blockToRemove);
+
+    console.log('\nRemoved second audio block');
     console.log(
-      'Add Music guide initialized. Open the timeline to see audio tracks.'
+      'Remaining audio blocks:',
+      engine.block.findByType('audio').length
     );
   }
-}
 
-export default Example;
-```
+  // Export the scene to a file
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
 
-This guide covers how to add music using the built-in audio UI and how to create and configure audio blocks programmatically using the Block API.
+  // Save the scene as a .scene file for later use or rendering
+  const sceneString = await engine.scene.saveToString();
+  writeFileSync(`${outputDir}/scene-with-audio.scene`, sceneString);
 
-## Using the Built-in Audio UI
+  console.log('\nScene saved to output/scene-with-audio.scene');
+  console.log(
+    'The scene contains audio configuration that can be rendered using the CE.SDK Renderer.'
+  );
 
-### Enable Audio Features
+  console.log('\nAdd Music guide complete!');
+} finally {
+  engine.dispose();
+}
+```
+
+This guide covers how to create and configure audio blocks programmatically using the Block API, manage multiple audio tracks, and export scene configurations for rendering.
 
-Audio blocks require timeline support. Enable the audio and timeline features to give users access to audio capabilities through the UI.
+## Setting Up the Engine
 
-```typescript highlight-enable-audio-features
-// Enable audio and timeline features for the UI
-cesdk.feature.enable('ly.img.video.timeline');
-cesdk.feature.enable('ly.img.video.timeline.audio');
-cesdk.feature.enable('ly.img.video.timeline.controls.playback');
+Initialize the CE.SDK engine in headless mode for server-side audio processing.
+
+```typescript highlight=highlight-setup
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
 ```
 
-These features control:
+The headless engine provides full API access to audio functionality without browser dependencies, making it ideal for batch processing, automated workflows, and server-side content generation.
+
+## Creating a Scene
 
-- `ly.img.video.timeline` - Shows the timeline for positioning audio tracks
-- `ly.img.video.timeline.audio` - Enables the audio library in the dock
-- `ly.img.video.timeline.controls.playback` - Adds playback controls for previewing audio
+Create a scene with a page to hold audio content. Set the page dimensions and duration to define the composition length.
 
-### User Workflow
+```typescript highlight=highlight-create-scene
+  // Create a scene with a page for audio content
+  engine.scene.create('DepthStack');
+  const page = engine.block.create('page');
+  engine.block.setWidth(page, 1920);
+  engine.block.setHeight(page, 1080);
+  engine.block.appendChild(engine.scene.get()!, page);
 
-With audio features enabled, users can add music through the interface:
+  // Set page duration for timeline (30 seconds)
+  engine.block.setDuration(page, 30);
+```
 
-1. **Open the dock** - Access the asset library panel
-2. **Select audio category** - Browse available music tracks
-3. **Preview tracks** - Listen to audio before adding
-4. **Drag to timeline** - Add audio to the project
-5. **Position on timeline** - Adjust when audio starts and ends
-6. **Adjust volume** - Use the inspector to set volume levels
+The page duration determines the maximum playback length for the composition. Audio blocks attached to this page participate in the composition.
 
 ## Programmatic Audio Creation
 
@@ -255,39 +192,39 @@ With audio features enabled, users can add music through the interface:
 
 We create audio blocks using `engine.block.create('audio')` and set the source file using the `audio/fileURI` property. The audio block must be appended to a page to become part of the composition.
 
-```typescript highlight-create-audio-block
-// Create an audio block for background music
-const audioBlock = engine.block.create('audio');
+```typescript highlight=highlight-create-audio-block
+  // Create an audio block for background music
+  const audioBlock = engine.block.create('audio');
 
-// Set the audio source file
-const audioUri =
-  'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/far_from_home.m4a';
-engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
+  // Set the audio source file
+  const audioUri =
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/far_from_home.m4a';
+  engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
 
-// Append audio to the page (makes it part of the timeline)
-engine.block.appendChild(page, audioBlock);
+  // Append audio to the page (makes it part of the timeline)
+  engine.block.appendChild(page, audioBlock);
 ```
 
-Audio blocks support common formats including M4A, MP3, and WAV. The source URI can point to any accessible URL or local file.
+Audio blocks support common formats including M4A, MP3, and WAV. The source URI can point to any accessible URL.
 
 ### Configure Time Position
 
 Audio blocks have time-based properties that control when and how long they play. We use `setTimeOffset()` to set the start time and `setDuration()` to control playback length.
 
-```typescript highlight-configure-timeline
-// Wait for audio to load to get duration
-await engine.block.forceLoadAVResource(audioBlock);
+```typescript highlight=highlight-configure-timeline
+  // Wait for audio to load to get duration
+  await engine.block.forceLoadAVResource(audioBlock);
 
-// Get the total duration of the audio file
-const totalDuration = engine.block.getAVResourceTotalDuration(audioBlock);
-console.log('Audio total duration:', totalDuration, 'seconds');
+  // Get the total duration of the audio file
+  const totalDuration = engine.block.getAVResourceTotalDuration(audioBlock);
+  console.log('Audio total duration:', totalDuration.toFixed(2), 'seconds');
 
-// Set when the audio starts on the timeline (0 = beginning)
-engine.block.setTimeOffset(audioBlock, 0);
+  // Set when the audio starts on the timeline (0 = beginning)
+  engine.block.setTimeOffset(audioBlock, 0);
 
-// Set how long the audio plays (use full duration or page duration)
-const playbackDuration = Math.min(totalDuration, 30);
-engine.block.setDuration(audioBlock, playbackDuration);
+  // Set how long the audio plays (use full duration or page duration)
+  const playbackDuration = Math.min(totalDuration, 30);
+  engine.block.setDuration(audioBlock, playbackDuration);
 ```
 
 The `forceLoadAVResource()` method ensures the audio file is loaded before we access its duration. This is important when you need to know the total length of the audio file for timing calculations.
@@ -296,42 +233,39 @@ The `forceLoadAVResource()` method ensures the audio file is loaded before we ac
 
 Volume is set using `setVolume()` with values from 0.0 (mute) to 1.0 (full volume). This volume level is applied during export and affects the final rendered output.
 
-```typescript highlight-configure-volume
-// Set the audio volume (0.0 = mute, 1.0 = full volume)
-engine.block.setVolume(audioBlock, 0.8);
+```typescript highlight=highlight-configure-volume
+  // Set the audio volume (0.0 = mute, 1.0 = full volume)
+  engine.block.setVolume(audioBlock, 0.8);
 
-// Get current volume
-const currentVolume = engine.block.getVolume(audioBlock);
-console.log('Audio volume:', currentVolume);
+  // Get current volume
+  const currentVolume = engine.block.getVolume(audioBlock);
+  console.log('Audio volume:', `${(currentVolume * 100).toFixed(0)}%`);
 ```
 
-## Working with Audio Assets
-
-### Query Audio Library
+## Adding Multiple Audio Tracks
 
-CE.SDK provides a demo audio library that you can query using the Asset API. This allows you to build custom audio selection interfaces or programmatically add tracks based on metadata.
+Add multiple audio tracks to create layered soundscapes. Each track can have independent timing, duration, and volume settings.
 
-```typescript highlight-query-audio-assets
-// Query available audio tracks from the asset library
-const audioAssets = await engine.asset.findAssets('ly.img.audio', {
-  page: 0,
-  perPage: 10
-});
+```typescript highlight=highlight-add-second-audio
+  // Add a second audio track with different settings
+  const secondAudioBlock = engine.block.create('audio');
+  const secondAudioUri =
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/dance_harder.m4a';
+  engine.block.setString(secondAudioBlock, 'audio/fileURI', secondAudioUri);
+  engine.block.appendChild(page, secondAudioBlock);
 
-console.log('Available audio assets:', audioAssets.assets.length);
+  // Load and configure the second audio
+  await engine.block.forceLoadAVResource(secondAudioBlock);
+  const secondDuration =
+    engine.block.getAVResourceTotalDuration(secondAudioBlock);
 
-// Log metadata for each audio asset
-audioAssets.assets.forEach((asset) => {
-  console.log('Audio asset:', {
-    id: asset.id,
-    label: asset.label,
-    duration: asset.meta?.duration,
-    uri: asset.meta?.uri
-  });
-});
+  // Start second audio after the first one ends, at lower volume
+  engine.block.setTimeOffset(secondAudioBlock, playbackDuration);
+  engine.block.setDuration(secondAudioBlock, Math.min(secondDuration, 15));
+  engine.block.setVolume(secondAudioBlock, 0.5);
 ```
 
-Each asset includes metadata such as duration, file URI, and thumbnail URL, which you can use to display track information or make programmatic selections.
+When working with multiple audio sources, use different volume levels to create a balanced mix. A common approach is to keep primary audio at higher levels and background music at lower levels.
 
 ## Managing Audio Blocks
 
@@ -339,62 +273,97 @@ Each asset includes metadata such as duration, file URI, and thumbnail URL, whic
 
 Use `findByType('audio')` to retrieve all audio blocks in the scene. This is useful for building audio management interfaces or batch operations.
 
-```typescript highlight-list-audio-blocks
-// Find all audio blocks in the scene
-const allAudioBlocks = engine.block.findByType('audio');
-console.log('Total audio blocks:', allAudioBlocks.length);
-
-// Get information about each audio block
-allAudioBlocks.forEach((block, index) => {
-  const uri = engine.block.getString(block, 'audio/fileURI');
-  const timeOffset = engine.block.getTimeOffset(block);
-  const duration = engine.block.getDuration(block);
-  const volume = engine.block.getVolume(block);
-
-  console.log(`Audio block ${index + 1}:`, {
-    uri: uri.split('/').pop(), // Just filename
-    timeOffset: `${timeOffset}s`,
-    duration: `${duration}s`,
-    volume: `${(volume * 100).toFixed(0)}%`
+```typescript highlight=highlight-list-audio-blocks
+  // Find all audio blocks in the scene
+  const allAudioBlocks = engine.block.findByType('audio');
+  console.log('\nTotal audio blocks:', allAudioBlocks.length);
+
+  // Get information about each audio block
+  allAudioBlocks.forEach((block, index) => {
+    const uri = engine.block.getString(block, 'audio/fileURI');
+    const timeOffset = engine.block.getTimeOffset(block);
+    const duration = engine.block.getDuration(block);
+    const volume = engine.block.getVolume(block);
+
+    console.log(`\nAudio block ${index + 1}:`);
+    console.log(`  File: ${uri.split('/').pop()}`);
+    console.log(`  Time offset: ${timeOffset.toFixed(2)}s`);
+    console.log(`  Duration: ${duration.toFixed(2)}s`);
+    console.log(`  Volume: ${(volume * 100).toFixed(0)}%`);
   });
-});
 ```
 
 ### Remove Audio
 
 To remove an audio block, call `destroy()` which removes it from the scene and frees its resources.
 
-```typescript highlight-remove-audio
-// Example: Remove the second audio block if it exists
-if (allAudioBlocks.length > 1) {
-  const blockToRemove = allAudioBlocks[1];
+```typescript highlight=highlight-remove-audio
+  // Demonstrate removing an audio block
+  if (allAudioBlocks.length > 1) {
+    const blockToRemove = allAudioBlocks[1];
 
-  // Destroy the block to remove it and free resources
-  engine.block.destroy(blockToRemove);
+    // Destroy the block to remove it and free resources
+    engine.block.destroy(blockToRemove);
 
-  console.log('Removed second audio block');
-}
+    console.log('\nRemoved second audio block');
+    console.log(
+      'Remaining audio blocks:',
+      engine.block.findByType('audio').length
+    );
+  }
+```
+
+Always destroy blocks that are no longer needed to prevent memory leaks, especially when processing multiple audio files in batch workflows.
+
+## Exporting Results
+
+Save the scene configuration for later use or rendering. In headless mode, export the scene as a `.scene` file that can be loaded and rendered using the CE.SDK Renderer.
+
+```typescript highlight=highlight-export
+  // Export the scene to a file
+  const outputDir = './output';
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Save the scene as a .scene file for later use or rendering
+  const sceneString = await engine.scene.saveToString();
+  writeFileSync(`${outputDir}/scene-with-audio.scene`, sceneString);
+
+  console.log('\nScene saved to output/scene-with-audio.scene');
+  console.log(
+    'The scene contains audio configuration that can be rendered using the CE.SDK Renderer.'
+  );
 ```
 
-Always destroy blocks that are no longer needed to prevent memory leaks, especially when working with multiple audio files.
+The exported scene contains all audio configuration including source URIs, time positions, durations, and volume levels. Use the CE.SDK Renderer for server-side video rendering with audio.
+
+## Troubleshooting
+
+**Audio Resource Loading Fails**: Verify the audio URI is accessible from the server environment. Check network connectivity and URL validity. Ensure the audio format is supported (M4A, MP3, WAV).
+
+**Duration Returns Zero**: Call `forceLoadAVResource()` before accessing duration. The audio metadata must be loaded first.
+
+**Volume Not Applied**: Ensure volume is set before exporting the scene. Volume settings are stored in the scene and applied during rendering.
+
+**Memory Issues with Multiple Files**: Destroy audio blocks when they are no longer needed. For batch processing, consider processing files in smaller batches.
 
 ## API Reference
 
-| Method                                                      | Description                         |
-| ----------------------------------------------------------- | ----------------------------------- |
-| `feature.enable('ly.img.video.timeline')`                   | Show timeline for audio positioning |
-| `feature.enable('ly.img.video.timeline.audio')`             | Enable audio library in dock        |
-| `feature.enable('ly.img.video.timeline.controls.playback')` | Add playback controls               |
-| `block.create('audio')`                                     | Create a new audio block            |
-| `block.setString(id, 'audio/fileURI', uri)`                 | Set the audio source file           |
-| `block.setTimeOffset(id, seconds)`                          | Set when audio starts playing       |
-| `block.setDuration(id, seconds)`                            | Set audio playback duration         |
-| `block.setVolume(id, volume)`                               | Set volume (0.0 to 1.0)             |
-| `block.getVolume(id)`                                       | Get current volume level            |
-| `block.getAVResourceTotalDuration(id)`                      | Get total audio file duration       |
-| `block.forceLoadAVResource(id)`                             | Force load audio resource           |
-| `block.findByType('audio')`                                 | Find all audio blocks in scene      |
-| `asset.findAssets(sourceId, query)`                         | Query audio assets                  |
+| Method                                      | Description                    |
+| ------------------------------------------- | ------------------------------ |
+| `block.create('audio')`                     | Create a new audio block       |
+| `block.setString(id, 'audio/fileURI', uri)` | Set the audio source file      |
+| `block.appendChild(parent, child)`          | Append audio to page           |
+| `block.setTimeOffset(id, seconds)`          | Set when audio starts playing  |
+| `block.setDuration(id, seconds)`            | Set audio playback duration    |
+| `block.setVolume(id, volume)`               | Set volume (0.0 to 1.0)        |
+| `block.getVolume(id)`                       | Get current volume level       |
+| `block.getAVResourceTotalDuration(id)`      | Get total audio file duration  |
+| `block.forceLoadAVResource(id)`             | Force load audio resource      |
+| `block.findByType('audio')`                 | Find all audio blocks in scene |
+| `block.destroy(id)`                         | Remove audio block             |
+| `scene.saveToString()`                      | Export scene as .scene file    |
 
 ## Audio Type
 
@@ -402,29 +371,34 @@ A block for playing audio content.
 
 This section describes the properties available for the **Audio Type** (`//ly.img.ubq/audio`) block type.
 
-| Property                       | Type     | Default   | Description                                                                                                                                 |
-| ------------------------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `audio/fileURI`                | `String` | `""`      | A URI referencing an audio file.                                                                                                            |
-| `audio/totalDuration`          | `Double` | `"-"`     | The total duration of the audio file., _(read-only)_                                                                                        |
-| `contentFill/mode`             | `Enum`   | `"Cover"` | Defines how content should be resized to fit its container (e.g., Crop, Cover, Contain)., Possible values: `"Crop"`, `"Cover"`, `"Contain"` |
-| `playback/duration`            | `Double` | `null`    | The duration in seconds for which this block should be visible.                                                                             |
-| `playback/looping`             | `Bool`   | `false`   | Whether the medium should start from the beginning again or should stop.                                                                    |
-| `playback/muted`               | `Bool`   | `false`   | Whether the audio is muted.                                                                                                                 |
-| `playback/playing`             | `Bool`   | `false`   | A tag that can be set on elements for their playback time to be progressed.                                                                 |
-| `playback/soloPlaybackEnabled` | `Bool`   | `false`   | A tag for blocks where playback should progress while the scene is paused.                                                                  |
-| `playback/speed`               | `Float`  | `1`       | The playback speed multiplier.                                                                                                              |
-| `playback/time`                | `Double` | `0`       | The current playback time of the block contents in seconds.                                                                                 |
-| `playback/timeOffset`          | `Double` | `0`       | The time in seconds relative to its parent at which this block should first appear.                                                         |
-| `playback/trimLength`          | `Double` | `"-"`     | The relative duration of the clip for playback.                                                                                             |
-| `playback/trimOffset`          | `Double` | `"-"`     | The time within the clip at which playback should begin, in seconds.                                                                        |
-| `playback/volume`              | `Float`  | `1`       | Audio volume with a range of \[0, 1].                                                                                                       |
-| `selected`                     | `Bool`   | `false`   | Indicates if the block is currently selected.                                                                                               |
+| Property                          | Type     | Default    | Description                                                                                                                                                                                           |
+| --------------------------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `audio/fileURI`                   | `String` | `""`       | A URI referencing an audio file.                                                                                                                                                                      |
+| `audio/totalDuration`             | `Double` | `"-"`      | The total duration of the audio file., *(read-only)*                                                                                                                                                  |
+| `contentFill/horizontalAlignment` | `Enum`   | `"Center"` | The horizontal alignment of the content fill inside the block. Only affects `Contain` and `Cover` fill modes; has no visible effect in `Crop` mode., Possible values: `"Left"`, `"Center"`, `"Right"` |
+| `contentFill/mode`                | `Enum`   | `"Cover"`  | Defines how content should be resized to fit its container., Possible values: `"Crop"`, `"Cover"`, `"Contain"`                                                                                        |
+| `contentFill/verticalAlignment`   | `Enum`   | `"Center"` | The vertical alignment of the content fill inside the block. Only affects `Contain` and `Cover` fill modes; has no visible effect in `Crop` mode., Possible values: `"Top"`, `"Center"`, `"Bottom"`   |
+| `playback/duration`               | `Double` | `null`     | The duration in seconds for which this block should be visible.                                                                                                                                       |
+| `playback/looping`                | `Bool`   | `false`    | Whether the medium should start from the beginning again or should stop.                                                                                                                              |
+| `playback/muted`                  | `Bool`   | `false`    | Whether the audio is muted.                                                                                                                                                                           |
+| `playback/playing`                | `Bool`   | `false`    | A tag that can be set on elements for their playback time to be progressed.                                                                                                                           |
+| `playback/soloPlaybackEnabled`    | `Bool`   | `false`    | A tag for blocks where playback should progress while the scene is paused.                                                                                                                            |
+| `playback/speed`                  | `Float`  | `1`        | The playback speed multiplier.                                                                                                                                                                        |
+| `playback/time`                   | `Double` | `0`        | The current playback time of the block contents in seconds.                                                                                                                                           |
+| `playback/timeOffset`             | `Double` | `0`        | The time in seconds relative to its parent at which this block should first appear.                                                                                                                   |
+| `playback/trimLength`             | `Double` | `"-"`      | The relative duration of the clip for playback.                                                                                                                                                       |
+| `playback/trimOffset`             | `Double` | `"-"`      | The time within the clip at which playback should begin, in seconds.                                                                                                                                  |
+| `playback/volume`                 | `Float`  | `1`        | Audio volume with a range of \[0, 1].                                                                                                                                                                  |
+| `selected`                        | `Bool`   | `false`    | Indicates if the block is currently selected.                                                                                                                                                         |
+
+
+
 
 ---
 
 ## 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