@imgly/codesign-mcp 0.1.5 → 0.1.6

package/assets/docs/guide/create-video/audio/adjust-volume.md

@@ -1,49 +1,29 @@
-> 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) > [Adjust Volume](./create-video/audio/adjust-volume.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).
 
 ---
 
-Control audio playback volume using CE.SDK's timeline UI and the programmatic
-volume control API, from silent (0.0) to full volume (1.0).
-
-![Audio Volume Adjustment example showing timeline with audio blocks at different volume levels](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+Control audio playback volume programmatically using CE.SDK's headless engine for server-side audio processing, from silent (0.0) to full volume (1.0).
 
 > **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-create-audio-audio-adjust-volume-browser)
-> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-audio-audio-adjust-volume-browser)
-> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-audio-audio-adjust-volume-browser/)
-
-Volume control adjusts how loud or quiet audio plays during playback. CE.SDK uses a normalized 0.0-1.0 range where 0.0 is completely silent and 1.0 is full volume. This applies to both audio blocks and video fills with embedded audio. Volume settings are commonly used for balancing multiple audio sources, creating fade effects, and allowing users to adjust playback levels.
-
-```typescript file=@cesdk_web_examples/guides-create-audio-audio-adjust-volume-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-audio-adjust-volume-server-js)
+>
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-audio-audio-adjust-volume-server-js)
+
+Volume control adjusts how loud or quiet audio plays during playback. CE.SDK uses a normalized 0.0-1.0 range where 0.0 is completely silent and 1.0 is full volume. This applies to both audio blocks and video fills with embedded audio. Server-side volume control is useful for batch audio processing, automated video production, and generating content with pre-configured volume levels.
+
+```typescript file=@cesdk_web_examples/guides-create-audio-audio-adjust-volume-server-js/server-js.ts reference-only
+import CreativeEngine from '@cesdk/node';
+import { config } from 'dotenv';
+
+config();
 
 /**
- * CE.SDK Plugin: Adjust Audio Volume Guide
+ * CE.SDK Server Guide: Adjust Audio Volume
  *
  * Demonstrates audio volume control in CE.SDK:
  * - Setting volume levels with setVolume
@@ -51,146 +31,90 @@ import packageJson from './package.json';
  * - Querying volume and mute states
  * - Volume levels for multiple audio sources
  */
-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: {
-        sourceId: 'ly.img.page.presets',
-        assetId: 'ly.img.page.presets.instagram.story',
-        color: { r: 0, g: 0, b: 0, a: 1 }
-      }
-    });
-
-    const engine = cesdk.engine;
-    const scene = engine.scene.get();
-    const pages = engine.block.findByType('page');
-    const page = pages.length > 0 ? pages[0] : scene;
-
-    // Use a sample audio file
-    const audioUri =
-      'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/dance_harder.m4a';
-
-    // Create an audio block and load the audio file
-    const audioBlock = engine.block.create('audio');
-    engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
-
-    // Wait for audio resource to load
-    await engine.block.forceLoadAVResource(audioBlock);
-
-    // Set volume to 80% (0.8 on a 0.0-1.0 scale)
-    const fullVolumeAudio = engine.block.duplicate(audioBlock);
-    engine.block.appendChild(page, fullVolumeAudio);
-    engine.block.setTimeOffset(fullVolumeAudio, 0);
-    engine.block.setVolume(fullVolumeAudio, 0.8);
-
-    // Set volume to 30% for background music
-    const lowVolumeAudio = engine.block.duplicate(audioBlock);
-    engine.block.appendChild(page, lowVolumeAudio);
-    engine.block.setTimeOffset(lowVolumeAudio, 5);
-    engine.block.setVolume(lowVolumeAudio, 0.3);
-
-    // Mute an audio block (preserves volume setting)
-    const mutedAudio = engine.block.duplicate(audioBlock);
-    engine.block.appendChild(page, mutedAudio);
-    engine.block.setTimeOffset(mutedAudio, 10);
-    engine.block.setVolume(mutedAudio, 1.0);
-    engine.block.setMuted(mutedAudio, true);
-
-    // Query current volume and mute states
-    const currentVolume = engine.block.getVolume(fullVolumeAudio);
-    const isMuted = engine.block.isMuted(mutedAudio);
-    const isForceMuted = engine.block.isForceMuted(mutedAudio);
-
-    // eslint-disable-next-line no-console
-    console.log(`Full volume audio: ${(currentVolume * 100).toFixed(0)}%`);
-    // eslint-disable-next-line no-console
-    console.log(
-      `Low volume audio: ${(
-        engine.block.getVolume(lowVolumeAudio) * 100
-      ).toFixed(0)}%`
-    );
-    // eslint-disable-next-line no-console
-    console.log(
-      `Muted audio - isMuted: ${isMuted}, isForceMuted: ${isForceMuted}`
-    );
-
-    // Remove the original audio block (we only need the duplicates)
-    engine.block.destroy(audioBlock);
-
-    // Zoom to fit all audio blocks
-    engine.scene.zoomToBlock(page, 40, 40, 40, 40);
-  }
-}
 
-export default Example;
+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);
+
+  // Use a sample audio file
+  const audioUri =
+    'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/dance_harder.m4a';
+
+  // Create an audio block and load the audio file
+  const audioBlock = engine.block.create('audio');
+  engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
+
+  // Wait for audio resource to load
+  await engine.block.forceLoadAVResource(audioBlock);
+
+  // Set volume to 80% (0.8 on a 0.0-1.0 scale)
+  const fullVolumeAudio = engine.block.duplicate(audioBlock);
+  engine.block.appendChild(page, fullVolumeAudio);
+  engine.block.setTimeOffset(fullVolumeAudio, 0);
+  engine.block.setVolume(fullVolumeAudio, 0.8);
+
+  // Set volume to 30% for background music
+  const lowVolumeAudio = engine.block.duplicate(audioBlock);
+  engine.block.appendChild(page, lowVolumeAudio);
+  engine.block.setTimeOffset(lowVolumeAudio, 5);
+  engine.block.setVolume(lowVolumeAudio, 0.3);
+
+  // Mute an audio block (preserves volume setting)
+  const mutedAudio = engine.block.duplicate(audioBlock);
+  engine.block.appendChild(page, mutedAudio);
+  engine.block.setTimeOffset(mutedAudio, 10);
+  engine.block.setVolume(mutedAudio, 1.0);
+  engine.block.setMuted(mutedAudio, true);
+
+  // Query current volume and mute states
+  const currentVolume = engine.block.getVolume(fullVolumeAudio);
+  const isMuted = engine.block.isMuted(mutedAudio);
+  const isForceMuted = engine.block.isForceMuted(mutedAudio);
+
+  console.log(`Full volume audio: ${(currentVolume * 100).toFixed(0)}%`);
+  console.log(
+    `Low volume audio: ${(engine.block.getVolume(lowVolumeAudio) * 100).toFixed(0)}%`
+  );
+  console.log(
+    `Muted audio - isMuted: ${isMuted}, isForceMuted: ${isForceMuted}`
+  );
+
+  // Remove the original audio block (we only need the duplicates)
+  engine.block.destroy(audioBlock);
+
+  console.log('Audio volume adjustment example complete');
+} finally {
+  engine.dispose();
+}
 ```
 
 This guide covers how to adjust audio volume programmatically using the Engine API, mute and unmute audio, and query volume and mute states.
 
+## Setting Up the Engine
+
+First, initialize the CE.SDK engine in headless mode for server-side processing.
+
+```typescript highlight=highlight-setup
+const engine = await CreativeEngine.init({
+  baseURL: process.env.IMGLY_LOCAL_ASSETS_URL
+});
+```
+
 ## Understanding Volume Concepts
 
 CE.SDK supports volume levels from **0.0** (silent) to **1.0** (full volume), with **1.0** as the default for new audio blocks. Values in between represent proportional volume levels—0.5 is half volume, 0.25 is quarter volume.
 
 **Volume vs Muting**: Setting volume to 0.0 makes audio silent, but muting with `setMuted()` is preferred when you want to temporarily silence audio without losing the volume setting. Unmuting restores the previous volume level.
 
-**Common use cases**: Background music mixing (0.3-0.5 under voiceover), user volume controls, audio balancing for multi-track projects, fade effects (gradually adjusting volume over time), and accessibility features.
+**Common use cases**: Batch audio processing, automated video production with pre-set volume levels, normalizing volume across multiple clips, and creating audio mixes programmatically.
 
 ## Setting Up Audio for Volume Control
 
@@ -198,13 +122,13 @@ CE.SDK supports volume levels from **0.0** (silent) to **1.0** (full volume), wi
 
 We create an audio block and load an audio file by setting its `fileURI` property.
 
-```typescript highlight-create-audio
-// Create an audio block and load the audio file
-const audioBlock = engine.block.create('audio');
-engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
+```typescript highlight=highlight-create-audio
+  // Create an audio block and load the audio file
+  const audioBlock = engine.block.create('audio');
+  engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
 
-// Wait for audio resource to load
-await engine.block.forceLoadAVResource(audioBlock);
+  // Wait for audio resource to load
+  await engine.block.forceLoadAVResource(audioBlock);
 ```
 
 Unlike video or image blocks which use fills, audio blocks store the file URI directly on the block itself using the `audio/fileURI` property. The `forceLoadAVResource` call ensures CE.SDK has downloaded the audio file and loaded its metadata before we manipulate it.
@@ -215,7 +139,7 @@ Unlike video or image blocks which use fills, audio blocks store the file URI di
 
 We can set volume using `setVolume()` with a value between 0.0 and 1.0.
 
-```typescript highlight-set-volume
+```typescript highlight=highlight-set-volume
 // Set volume to 80% (0.8 on a 0.0-1.0 scale)
 const fullVolumeAudio = engine.block.duplicate(audioBlock);
 engine.block.appendChild(page, fullVolumeAudio);
@@ -229,7 +153,7 @@ Setting volume to 0.8 (80%) is useful when you want prominent audio that isn't a
 
 For background music that should be audible but not prominent, use lower volume levels.
 
-```typescript highlight-set-low-volume
+```typescript highlight=highlight-set-low-volume
 // Set volume to 30% for background music
 const lowVolumeAudio = engine.block.duplicate(audioBlock);
 engine.block.appendChild(page, lowVolumeAudio);
@@ -245,7 +169,7 @@ At 0.3 (30%) volume, the audio is clearly audible but stays in the background. T
 
 Use `setMuted()` to mute audio without changing its volume setting. This is useful for toggle controls.
 
-```typescript highlight-mute-audio
+```typescript highlight=highlight-mute-audio
 // Mute an audio block (preserves volume setting)
 const mutedAudio = engine.block.duplicate(audioBlock);
 engine.block.appendChild(page, mutedAudio);
@@ -260,22 +184,19 @@ When you mute an audio block, the volume setting (1.0 in this case) is preserved
 
 You can query the current volume and mute states at any time.
 
-```typescript highlight-query-volume
-// Query current volume and mute states
-const currentVolume = engine.block.getVolume(fullVolumeAudio);
-const isMuted = engine.block.isMuted(mutedAudio);
-const isForceMuted = engine.block.isForceMuted(mutedAudio);
-
-// eslint-disable-next-line no-console
-console.log(`Full volume audio: ${(currentVolume * 100).toFixed(0)}%`);
-// eslint-disable-next-line no-console
-console.log(
-  `Low volume audio: ${(engine.block.getVolume(lowVolumeAudio) * 100).toFixed(
-    0
-  )}%`
-);
-// eslint-disable-next-line no-console
-console.log(`Muted audio - isMuted: ${isMuted}, isForceMuted: ${isForceMuted}`);
+```typescript highlight=highlight-query-volume
+  // Query current volume and mute states
+  const currentVolume = engine.block.getVolume(fullVolumeAudio);
+  const isMuted = engine.block.isMuted(mutedAudio);
+  const isForceMuted = engine.block.isForceMuted(mutedAudio);
+
+  console.log(`Full volume audio: ${(currentVolume * 100).toFixed(0)}%`);
+  console.log(
+    `Low volume audio: ${(engine.block.getVolume(lowVolumeAudio) * 100).toFixed(0)}%`
+  );
+  console.log(
+    `Muted audio - isMuted: ${isMuted}, isForceMuted: ${isForceMuted}`
+  );
 ```
 
 Use `getVolume()` to read the current volume level, `isMuted()` to check if the block is muted by the user, and `isForceMuted()` to check if the engine has automatically muted the block due to playback rules.
@@ -294,53 +215,21 @@ When working with multiple audio sources, use different volume levels to create
 
 **Sound effects as accents**: Set sound effects to 0.5-0.8 depending on how prominent they should be in the mix.
 
-## Building Volume Controls
-
-### Volume Slider
-
-When building a volume slider UI, map the slider value directly to the 0.0-1.0 range. Display percentages (0-100%) for user-friendly labels.
-
-```typescript
-// Example: Update volume from slider (0-100)
-const sliderValue = 75; // User drags slider to 75%
-const volume = sliderValue / 100; // Convert to 0.0-1.0
-engine.block.setVolume(audioBlock, volume);
-```
-
-### Mute Toggle
-
-Implement mute buttons using `setMuted()` and indicate the current state using `isMuted()`. Show a different icon when `isForceMuted()` returns true to indicate the engine has automatically muted the audio.
-
-```typescript
-// Example: Toggle mute state
-const currentlyMuted = engine.block.isMuted(audioBlock);
-engine.block.setMuted(audioBlock, !currentlyMuted);
-
-// Check if engine force-muted (e.g., high playback speed)
-if (engine.block.isForceMuted(audioBlock)) {
-  // Show "force muted" indicator
-}
-```
-
 ## Troubleshooting
 
-### Volume Changes Not Audible
-
-Check if the block is muted with `isMuted()` or force muted with `isForceMuted()`. Also verify the audio resource has loaded successfully.
+**Volume Changes Not Audible**: Check if the block is muted with `isMuted()` or force muted with `isForceMuted()`. Also verify the audio resource has loaded successfully.
 
-### Force Muted State
+**Force Muted State**: Video fills at playback speeds above 3.0x are automatically force muted by the engine. Reduce the playback speed to restore audio output.
 
-Video fills at playback speeds above 3.0x are automatically force muted by the engine. Reduce the playback speed to restore audio output.
+**Volume Not Persisting**: Ensure you're setting volume on the correct block ID. Volume settings are block-specific and don't propagate to duplicates or other instances.
 
-### Volume Not Persisting
 
-Ensure you're setting volume on the correct block ID. Volume settings are block-specific and don't propagate to duplicates or other instances.
 
 ---
 
 ## 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