@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/insert-media/audio.md

@@ -1,4 +1,4 @@
-> 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) > [Insert Media Assets](./insert-media.md) > [Insert Audio](./insert-media/audio.md)
 
@@ -7,180 +7,139 @@
 Add audio files to video projects using CE.SDK's audio block system for
 background music, sound effects, and voiceovers.
 
-![Insert Audio example showing audio block in the timeline](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-insert-media-audio-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-insert-media-audio-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-insert-media-audio-browser/)
+>
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-insert-media-audio-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-insert-media-audio-server-js)
 
 Audio blocks are time-based blocks that play sound alongside video content. Unlike video fills that attach to graphic blocks, audio blocks exist independently in the composition with their own duration, position, and volume controls.
 
-```typescript file=@cesdk_web_examples/guides-insert-media-audio-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-insert-media-audio-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+
+config();
 
 /**
- * CE.SDK Plugin: Insert Audio Guide
+ * CE.SDK Server Guide: Insert Audio
  *
- * Demonstrates adding audio to video projects:
- * - Creating audio blocks programmatically
+ * Demonstrates inserting audio files into CE.SDK scenes:
+ * - Creating audio blocks
  * - Setting audio source URIs
- * - Configuring timeline position and duration
- * - Adjusting audio volume, mute, and loop settings
- * - Querying and managing audio blocks
+ * - Configuring timeline position (timeOffset, duration)
+ * - Controlling playback (volume, mute, loop)
+ * - Finding and managing 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 == null) {
-      throw new Error('No page found in scene');
-    }
-
-    // Set page duration for timeline
-    engine.block.setDuration(page, 30);
-
-    // Create an audio block and set source
-    const audioUri =
-      'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/far_from_home.m4a';
-    const audioBlock = engine.block.create('audio');
-    engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
-    engine.block.appendChild(page, audioBlock);
-
-    // Load audio resource to access duration
-    await engine.block.forceLoadAVResource(audioBlock);
-    const totalDuration = engine.block.getAVResourceTotalDuration(audioBlock);
-    console.log('Audio total duration:', totalDuration, 'seconds');
-
-    engine.block.setTimeOffset(audioBlock, 0);
-    engine.block.setDuration(audioBlock, Math.min(totalDuration, 30));
-
-    engine.block.setVolume(audioBlock, 0.8);
-    const currentVolume = engine.block.getVolume(audioBlock);
-    console.log('Audio volume:', currentVolume);
-
-    engine.block.setMuted(audioBlock, false);
-    const isMuted = engine.block.isMuted(audioBlock);
-    console.log('Audio muted:', isMuted);
-
-    engine.block.setLooping(audioBlock, false);
-    const isLooping = engine.block.isLooping(audioBlock);
-    console.log('Audio looping:', isLooping);
-
-    const allAudioBlocks = engine.block.findByType('audio');
-    console.log('Total audio blocks:', allAudioBlocks.length);
-
-    // Log 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(),
-        timeOffset: `${timeOffset}s`,
-        duration: `${duration}s`,
-        volume: `${(volume * 100).toFixed(0)}%`
-      });
-    });
-
-    // Create a second audio block to demonstrate removal
-    const tempAudioBlock = engine.block.create('audio');
-    engine.block.appendChild(page, tempAudioBlock);
-
-    engine.block.destroy(tempAudioBlock);
-
-    console.log(
-      'Insert Audio guide initialized. Open the timeline to see audio tracks.'
-    );
+
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+  // license: process.env.CESDK_LICENSE,
+});
+
+try {
+  // Create a scene with a page
+  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);
+
+  // Sample audio file URL
+  const audioUri =
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/far_from_home.m4a';
+
+  // Create an audio block
+  const audioBlock = engine.block.create('audio');
+
+  // Set the audio source file
+  engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
+
+  // Add the audio block to the page
+  engine.block.appendChild(page, audioBlock);
+
+  // Load the audio resource to access its metadata
+  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 playing on the timeline (in seconds)
+  engine.block.setTimeOffset(audioBlock, 0);
+
+  // Set how long the audio plays (in seconds)
+  // Here we use the full audio duration
+  engine.block.setDuration(audioBlock, totalDuration);
+
+  // Query current timeline position
+  const timeOffset = engine.block.getTimeOffset(audioBlock);
+  const duration = engine.block.getDuration(audioBlock);
+  console.log(
+    `Timeline position: starts at ${timeOffset}s, duration ${duration.toFixed(2)}s`
+  );
+
+  // Set audio volume (0.0 = silent, 1.0 = full volume)
+  engine.block.setVolume(audioBlock, 0.8);
+
+  // Query current volume
+  const volume = engine.block.getVolume(audioBlock);
+  console.log(`Volume: ${(volume * 100).toFixed(0)}%`);
+
+  // Mute audio without changing volume setting
+  engine.block.setMuted(audioBlock, true);
+
+  // Check if audio is muted
+  const isMuted = engine.block.isMuted(audioBlock);
+  console.log(`Audio muted: ${isMuted}`);
+
+  // Unmute the audio
+  engine.block.setMuted(audioBlock, false);
+
+  // Enable looping for continuous playback
+  engine.block.setLooping(audioBlock, true);
+
+  // Check if looping is enabled
+  const isLooping = engine.block.isLooping(audioBlock);
+  console.log(`Looping enabled: ${isLooping}`);
+
+  // Find all audio blocks in the scene
+  const audioBlocks = engine.block.findByType('audio');
+  console.log(`Found ${audioBlocks.length} audio block(s)`);
+
+  // Get the audio source URI from each block
+  for (const block of audioBlocks) {
+    const sourceUri = engine.block.getString(block, 'audio/fileURI');
+    console.log(`Audio source: ${sourceUri}`);
   }
-}
 
-export default Example;
+  // Create a second audio block to demonstrate removal
+  const tempAudio = engine.block.create('audio');
+  engine.block.setString(
+    tempAudio,
+    'audio/fileURI',
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/dance_harder.m4a'
+  );
+  engine.block.appendChild(page, tempAudio);
+
+  // Remove the temporary audio block
+  engine.block.destroy(tempAudio);
+  console.log('Temporary audio block removed');
+
+  // Verify only the original audio block remains
+  const remainingBlocks = engine.block.findByType('audio');
+  console.log(`Remaining audio blocks: ${remainingBlocks.length}`);
+
+  console.log('Insert audio guide completed successfully');
+} finally {
+  engine.dispose();
+}
 ```
 
 This guide covers creating audio blocks, configuring time-based properties, controlling playback settings, and managing audio blocks in your scene.
@@ -190,9 +149,14 @@ This guide covers creating audio blocks, configuring time-based properties, cont
 We create audio blocks using `engine.block.create('audio')` and set the source file with the `audio/fileURI` property. Audio blocks must be appended to a page to become part of the composition.
 
 ```typescript highlight=highlight-create-audio
-const audioBlock = engine.block.create('audio');
-engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
-engine.block.appendChild(page, audioBlock);
+  // Create an audio block
+  const audioBlock = engine.block.create('audio');
+
+  // Set the audio source file
+  engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
+
+  // Add the audio block to the page
+  engine.block.appendChild(page, audioBlock);
 ```
 
 CE.SDK supports WAV and MP4 audio formats (including `.m4a` files). The source URI can point to any accessible URL.
@@ -202,19 +166,26 @@ CE.SDK supports WAV and MP4 audio formats (including `.m4a` files). The source U
 Audio blocks have time-based properties that control when and how long they play. We use `setTimeOffset()` for the start position and `setDuration()` for playback length.
 
 ```typescript highlight=highlight-configure-timeline
-engine.block.setTimeOffset(audioBlock, 0);
-engine.block.setDuration(audioBlock, Math.min(totalDuration, 30));
+  // Set when the audio starts playing on the timeline (in seconds)
+  engine.block.setTimeOffset(audioBlock, 0);
+
+  // Set how long the audio plays (in seconds)
+  // Here we use the full audio duration
+  engine.block.setDuration(audioBlock, totalDuration);
 ```
 
 The `forceLoadAVResource()` method loads the audio file so we can access its total duration. Use `getAVResourceTotalDuration()` to get the full length of the source audio for timing calculations.
 
 ## Adjusting Volume
 
-We set volume using `setVolume()` with values from 0.0 (silent) to 1.0 (full volume). This affects both preview playback and the final exported output.
+We set volume using `setVolume()` with values from 0.0 (silent) to 1.0 (full volume). This affects the final exported output.
 
 ```typescript highlight=highlight-adjust-volume
-engine.block.setVolume(audioBlock, 0.8);
-const currentVolume = engine.block.getVolume(audioBlock);
+  // Set audio volume (0.0 = silent, 1.0 = full volume)
+  engine.block.setVolume(audioBlock, 0.8);
+
+  // Query current volume
+  const volume = engine.block.getVolume(audioBlock);
 ```
 
 ## Muting Audio
@@ -222,8 +193,15 @@ const currentVolume = engine.block.getVolume(audioBlock);
 To temporarily silence audio without removing it, use `setMuted()`. This preserves all other properties while stopping sound output.
 
 ```typescript highlight=highlight-mute-audio
-engine.block.setMuted(audioBlock, false);
-const isMuted = engine.block.isMuted(audioBlock);
+  // Mute audio without changing volume setting
+  engine.block.setMuted(audioBlock, true);
+
+  // Check if audio is muted
+  const isMuted = engine.block.isMuted(audioBlock);
+  console.log(`Audio muted: ${isMuted}`);
+
+  // Unmute the audio
+  engine.block.setMuted(audioBlock, false);
 ```
 
 ## Looping Audio
@@ -231,16 +209,28 @@ const isMuted = engine.block.isMuted(audioBlock);
 Enable continuous playback with `setLooping()`. When enabled, the audio repeats until the end of the block's duration in the composition.
 
 ```typescript highlight=highlight-loop-audio
-engine.block.setLooping(audioBlock, false);
-const isLooping = engine.block.isLooping(audioBlock);
+  // Enable looping for continuous playback
+  engine.block.setLooping(audioBlock, true);
+
+  // Check if looping is enabled
+  const isLooping = engine.block.isLooping(audioBlock);
+  console.log(`Looping enabled: ${isLooping}`);
 ```
 
 ## Finding Audio Blocks
 
-Use `findByType('audio')` to retrieve all audio blocks in the scene. This is useful for building audio management interfaces or performing batch operations.
+Use `findByType('audio')` to retrieve all audio blocks in the scene. This is useful for batch operations or managing multiple audio tracks.
 
 ```typescript highlight=highlight-find-audio
-const allAudioBlocks = engine.block.findByType('audio');
+  // Find all audio blocks in the scene
+  const audioBlocks = engine.block.findByType('audio');
+  console.log(`Found ${audioBlocks.length} audio block(s)`);
+
+  // Get the audio source URI from each block
+  for (const block of audioBlocks) {
+    const sourceUri = engine.block.getString(block, 'audio/fileURI');
+    console.log(`Audio source: ${sourceUri}`);
+  }
 ```
 
 ## Removing Audio
@@ -248,28 +238,43 @@ const allAudioBlocks = engine.block.findByType('audio');
 To remove an audio block, call `destroy()`. This removes the block from the scene and frees its resources.
 
 ```typescript highlight=highlight-remove-audio
-engine.block.destroy(tempAudioBlock);
+  // Create a second audio block to demonstrate removal
+  const tempAudio = engine.block.create('audio');
+  engine.block.setString(
+    tempAudio,
+    'audio/fileURI',
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/dance_harder.m4a'
+  );
+  engine.block.appendChild(page, tempAudio);
+
+  // Remove the temporary audio block
+  engine.block.destroy(tempAudio);
+  console.log('Temporary audio block removed');
+
+  // Verify only the original audio block remains
+  const remainingBlocks = engine.block.findByType('audio');
+  console.log(`Remaining audio blocks: ${remainingBlocks.length}`);
 ```
 
 ## API Reference
 
-| Method                                                | Description                         |
-| ----------------------------------------------------- | ----------------------------------- |
-| `engine.block.create('audio')`                        | Create a new audio block            |
-| `engine.block.setString(block, 'audio/fileURI', uri)` | Set the audio source file           |
-| `engine.block.appendChild(parent, child)`             | Add audio block to page             |
-| `engine.block.forceLoadAVResource(block)`             | Force load the audio file           |
-| `engine.block.getAVResourceTotalDuration(block)`      | Get total audio duration in seconds |
-| `engine.block.setTimeOffset(block, seconds)`          | Set start position                  |
-| `engine.block.setDuration(block, seconds)`            | Set playback duration               |
-| `engine.block.setVolume(block, volume)`               | Set volume (0.0-1.0)                |
-| `engine.block.getVolume(block)`                       | Get current volume                  |
-| `engine.block.setMuted(block, muted)`                 | Mute or unmute audio                |
-| `engine.block.isMuted(block)`                         | Check if audio is muted             |
-| `engine.block.setLooping(block, loop)`                | Enable/disable looping              |
-| `engine.block.isLooping(block)`                       | Check if looping is enabled         |
-| `engine.block.findByType('audio')`                    | Find all audio blocks               |
-| `engine.block.destroy(block)`                         | Remove audio block from scene       |
+| Method | Description |
+|--------|-------------|
+| `engine.block.create('audio')` | Create a new audio block |
+| `engine.block.setString(block, 'audio/fileURI', uri)` | Set the audio source file |
+| `engine.block.appendChild(parent, child)` | Add audio block to page |
+| `engine.block.forceLoadAVResource(block)` | Force load the audio file |
+| `engine.block.getAVResourceTotalDuration(block)` | Get total audio duration in seconds |
+| `engine.block.setTimeOffset(block, seconds)` | Set start position |
+| `engine.block.setDuration(block, seconds)` | Set playback duration |
+| `engine.block.setVolume(block, volume)` | Set volume (0.0-1.0) |
+| `engine.block.getVolume(block)` | Get current volume |
+| `engine.block.setMuted(block, muted)` | Mute or unmute audio |
+| `engine.block.isMuted(block)` | Check if audio is muted |
+| `engine.block.setLooping(block, loop)` | Enable/disable looping |
+| `engine.block.isLooping(block)` | Check if looping is enabled |
+| `engine.block.findByType('audio')` | Find all audio blocks |
+| `engine.block.destroy(block)` | Remove audio block from scene |
 
 ## Next Steps
 
@@ -281,11 +286,13 @@ engine.block.destroy(tempAudioBlock);
 
 [Store Custom Metadata](./export-save-publish/store-custom-metadata.md) - Save custom data with your scenes
 
+
+
 ---
 
 ## 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