@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/grid-and-rulers.md

@@ -0,0 +1,222 @@
+> 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).
+
+---
+
+Enable and configure grid overlays, snap-to-grid behavior, and canvas rulers so users can position and align elements with precision in your CE.SDK editor.
+
+> **Reading time:** 5 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-grid-and-rulers-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-grid-and-rulers-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-grid-and-rulers-browser/)
+
+CE.SDK provides a configurable grid overlay and canvas rulers to help users align design elements. The grid renders evenly spaced lines across the page, and snap-to-grid constrains element movement to grid intersections. Rulers display along the top and left edges of the canvas showing measurement units.
+
+```typescript file=@cesdk_web_examples/guides-grid-and-rulers-browser/browser.ts reference-only
+import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
+
+import {
+  BlurAssetSource,
+  ColorPaletteAssetSource,
+  CropPresetsAssetSource,
+  DemoAssetSources,
+  EffectsAssetSource,
+  FiltersAssetSource,
+  PagePresetsAssetSource,
+  StickerAssetSource,
+  TextAssetSource,
+  TextComponentAssetSource,
+  TypefaceAssetSource,
+  UploadAssetSources,
+  VectorShapeAssetSource
+} from '@cesdk/cesdk-js/plugins';
+import { AdvancedEditorConfig } from './advanced-editor/plugin';
+import packageJson from './package.json';
+
+/**
+ * CE.SDK Plugin: Grid & Rulers Guide
+ *
+ * Demonstrates how to configure grid overlay, snap-to-grid,
+ * and canvas rulers for precise element alignment.
+ */
+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 AdvancedEditorConfig());
+
+    // Add asset source plugins
+    await cesdk.addPlugin(new BlurAssetSource());
+    await cesdk.addPlugin(new ColorPaletteAssetSource());
+    await cesdk.addPlugin(new CropPresetsAssetSource());
+    await cesdk.addPlugin(
+      new UploadAssetSources({ include: ['ly.img.image.upload'] })
+    );
+    await cesdk.addPlugin(
+      new DemoAssetSources({
+        include: [
+          'ly.img.templates.blank.*',
+          'ly.img.templates.presentation.*',
+          'ly.img.templates.print.*',
+          'ly.img.templates.social.*',
+          'ly.img.image.*'
+        ]
+      })
+    );
+    await cesdk.addPlugin(new EffectsAssetSource());
+    await cesdk.addPlugin(new FiltersAssetSource());
+    await cesdk.addPlugin(new PagePresetsAssetSource());
+    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', {
+      page: { width: 800, height: 600, unit: 'Pixel' }
+    });
+
+    const engine = cesdk.engine;
+
+    // Show the grid overlay on the canvas
+    engine.editor.setSettingBool('grid/enabled', true);
+
+    // Enable snapping so elements align to grid lines
+    engine.editor.setSettingBool('grid/snapEnabled', true);
+
+    // Set horizontal and vertical grid spacing in design units
+    engine.editor.setSettingFloat('grid/spacingX', 20);
+    engine.editor.setSettingFloat('grid/spacingY', 20);
+
+    // Set a custom grid color with transparency
+    engine.editor.setSettingColor('grid/color', {
+      r: 0.2,
+      g: 0.4,
+      b: 0.8,
+      a: 0.3
+    });
+
+    // Rulers are controlled through the editor's UI store.
+    // The AdvancedEditorConfig plugin enables the 'ly.img.rulers'
+    // feature flag, which makes rulers available in the UI.
+    // Rulers are visible by default when the feature flag is enabled.
+
+    // Add a sample block so the grid and rulers are visible in context
+    const page = engine.block.findByType('page')[0];
+    const block = engine.block.create('graphic');
+    engine.block.setShape(block, engine.block.createShape('rect'));
+    engine.block.setFill(block, engine.block.createFill('color'));
+    engine.block.setWidth(block, 200);
+    engine.block.setHeight(block, 150);
+    engine.block.setPositionX(block, 100);
+    engine.block.setPositionY(block, 100);
+    engine.block.appendChild(page, block);
+
+    console.log('Grid & Rulers guide initialized.');
+  }
+}
+
+export default Example;
+```
+
+## Enable the Grid
+
+Toggle the grid overlay using the `grid/enabled` setting. When enabled, the engine draws a grid of lines across each page based on the configured spacing and color.
+
+```typescript highlight=highlight-enable-grid
+// Show the grid overlay on the canvas
+engine.editor.setSettingBool('grid/enabled', true);
+```
+
+The grid is a visual aid rendered at the engine level. It does not affect the scene content or export output.
+
+## Enable Snap-to-Grid
+
+Snap-to-grid constrains element movement so blocks align to grid lines. Enable it with the `grid/snapEnabled` setting.
+
+```typescript highlight=highlight-snap-to-grid
+// Enable snapping so elements align to grid lines
+engine.editor.setSettingBool('grid/snapEnabled', true);
+```
+
+When snap-to-grid is active, dragging or resizing a block snaps its edges to the nearest grid line. This works independently of the grid overlay visibility, so you can snap to an invisible grid if needed.
+
+## Configure Grid Spacing
+
+Set the horizontal and vertical distance between grid lines using `grid/spacingX` and `grid/spacingY`. Values are in design units (the unit configured for the scene).
+
+```typescript highlight=highlight-grid-spacing
+// Set horizontal and vertical grid spacing in design units
+engine.editor.setSettingFloat('grid/spacingX', 20);
+engine.editor.setSettingFloat('grid/spacingY', 20);
+```
+
+Smaller spacing values produce a finer grid. The default spacing is 32 design units in both directions.
+
+## Configure Grid Color
+
+Change the grid line color using `grid/color`. The color supports an alpha channel, so you can make the grid more or less prominent.
+
+```typescript highlight=highlight-grid-color
+// Set a custom grid color with transparency
+engine.editor.setSettingColor('grid/color', {
+  r: 0.2,
+  g: 0.4,
+  b: 0.8,
+  a: 0.3
+});
+```
+
+## Enable Rulers
+
+Rulers are managed through the `ly.img.rulers` feature flag and the editor's UI store. The Advanced Editor and Video Editor plugins enable rulers by default.
+
+```typescript highlight=highlight-enable-rulers
+// Rulers are controlled through the editor's UI store.
+// The AdvancedEditorConfig plugin enables the 'ly.img.rulers'
+// feature flag, which makes rulers available in the UI.
+// Rulers are visible by default when the feature flag is enabled.
+```
+
+Rulers display along the top and left edges of the canvas. They show tick marks and labels in the scene's design unit, and they update as the user pans and zooms.
+
+## Editor Plugin Defaults
+
+Different editor plugins configure grid and rulers with different defaults:
+
+| Plugin          | Grid Visible | Snap-to-Grid | Rulers |
+| --------------- | ------------ | ------------ | ------ |
+| Advanced Editor | Yes          | Yes          | Yes    |
+| Video Editor    | Yes          | Yes          | Yes    |
+| Design Editor   | No           | No           | No     |
+| Photo Editor    | No           | No           | No     |
+
+To add grid and ruler support to an editor that doesn't enable them by default, set the settings and feature flag manually as shown in the examples above.
+
+## API Reference
+
+| API                | Type  | Default                         | Description                                          |
+| ------------------ | ----- | ------------------------------- | ---------------------------------------------------- |
+| `grid/enabled`     | Bool  | `false`                         | Show or hide the grid overlay                        |
+| `grid/snapEnabled` | Bool  | `false`                         | Enable snapping to grid lines                        |
+| `grid/spacingX`    | Float | `32`                            | Horizontal spacing between grid lines (design units) |
+| `grid/spacingY`    | Float | `32`                            | Vertical spacing between grid lines (design units)   |
+| `grid/color`       | Color | `{ r: 0, g: 0, b: 0, a: 0.12 }` | Grid line color with alpha                           |
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS 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

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

@@ -0,0 +1,224 @@
+> 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) > [Export Media Assets](./export-save-publish/export.md) > [For Audio Processing](./guides/export-save-publish/export/audio.md)
+
+---
+
+Export audio from pages, video blocks, audio blocks, and tracks to WAV or MP4 format for external processing, transcription, or analysis.
+
+![Audio Export example showing audio export interface in CE.SDK](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **Reading time:** 8 minutes
+>
+> **Resources:**
+>
+> - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-export-audio-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-export-audio-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-export-audio-browser/)
+
+The `exportAudio` API allows you to extract audio from any block that contains audio content. This is particularly useful when integrating with external audio processing services like speech-to-text transcription, audio enhancement, or music analysis platforms.
+
+Audio can be exported from multiple block types:
+
+- **Page blocks** - Export the complete mixed audio composition
+- **Video blocks** - Extract audio tracks from videos
+- **Audio blocks** - Export standalone audio content
+- **Track blocks** - Export audio from specific tracks
+
+## Export Audio
+
+Export audio from any block using the `exportAudio` API:
+
+```javascript
+const page = cesdk.engine.scene.getCurrentPage();
+
+const audioBlob = await cesdk.engine.block.exportAudio(page, {
+  mimeType: 'audio/wav',
+  sampleRate: 48000,
+  numberOfChannels: 2
+});
+```
+
+### Export Options
+
+Configure your audio export with these options:
+
+- **`mimeType`** - `'audio/wav'` (uncompressed) or `'audio/mp4'` (compressed AAC)
+- **`sampleRate`** - Audio quality in Hz (default: 48000)
+- **`numberOfChannels`** - 1 for mono or 2 for stereo
+- **`timeOffset`** - Start time in seconds (default: 0)
+- **`duration`** - Length to export in seconds (0 = entire duration)
+- **`onProgress`** - Callback function receiving `(rendered, encoded, total)` for progress tracking
+
+## Find Audio Sources
+
+To find blocks with audio in your scene:
+
+```javascript
+// Find audio blocks
+const audioBlocks = cesdk.engine.block.findByType('audio');
+
+// Find video blocks with audio
+const videoFills = cesdk.engine.block.findByType('//ly.img.ubq/fill/video');
+const videosWithAudio = videoFills.filter((block) => {
+  try {
+    return cesdk.engine.block.getAudioInfoFromVideo(block).length > 0;
+  } catch {
+    return false;
+  }
+});
+```
+
+## Working with Multi-Track Video Audio
+
+Videos can contain multiple audio tracks (e.g., different languages). CE.SDK provides APIs to inspect and extract specific tracks.
+
+### Check audio track count
+
+```javascript
+const videoFillId = cesdk.engine.block.findByType('//ly.img.ubq/fill/video')[0];
+
+const trackCount = cesdk.engine.block.getAudioTrackCountFromVideo(videoFillId);
+console.log(`Video has ${trackCount} audio track(s)`);
+```
+
+### Get track information
+
+```javascript
+const audioTracks = cesdk.engine.block.getAudioInfoFromVideo(videoFillId);
+
+audioTracks.forEach((track, index) => {
+  console.log(`Track ${index}:`, {
+    channels: track.channels, // 1=mono, 2=stereo
+    sampleRate: track.sampleRate, // Sample rate in Hz
+    language: track.language, // e.g., "en", "es"
+    label: track.label // Track description
+  });
+});
+```
+
+### Extract a specific track
+
+```javascript
+// Create audio block from track 0 (first track)
+const audioBlockId = cesdk.engine.block.createAudioFromVideo(videoFillId, 0);
+
+// Export just this track's audio
+const trackAudioBlob = await cesdk.engine.block.exportAudio(audioBlockId, {
+  mimeType: 'audio/wav'
+});
+```
+
+### Extract all tracks
+
+```javascript
+// Create audio blocks for all tracks
+const audioBlockIds = cesdk.engine.block.createAudiosFromVideo(videoFillId);
+
+// Export each track
+for (let i = 0; i < audioBlockIds.length; i++) {
+  const trackBlob = await cesdk.engine.block.exportAudio(audioBlockIds[i]);
+  console.log(`Track ${i}: ${trackBlob.size} bytes`);
+}
+```
+
+## Complete Workflow: Audio to Captions
+
+A common workflow is to export audio, send it to a transcription service, and use the returned captions in your scene.
+
+### Step 1: Export Audio
+
+```javascript
+const page = cesdk.engine.scene.getCurrentPage();
+
+const audioBlob = await cesdk.engine.block.exportAudio(page, {
+  mimeType: 'audio/wav',
+  sampleRate: 48000,
+  numberOfChannels: 2
+});
+```
+
+### Step 2: Send to Transcription Service
+
+Send the audio to a service that returns SubRip (SRT) format captions:
+
+```javascript
+async function transcribeAudio(audioBlob) {
+  const formData = new FormData();
+  formData.append('audio', audioBlob, 'audio.wav');
+  formData.append('format', 'srt');
+
+  const response = await fetch(
+    'https://api.transcription-service.com/transcribe',
+    {
+      method: 'POST',
+      headers: {
+        Authorization: 'Bearer YOUR_API_KEY'
+      },
+      body: formData
+    }
+  );
+
+  // Returns SRT format text
+  return await response.text();
+}
+
+const srtContent = await transcribeAudio(audioBlob);
+```
+
+### Step 3: Import Captions from SRT
+
+Use the built-in API to create caption blocks from the SRT response:
+
+```javascript
+// Create a file from the SRT text
+const srtFile = new File([srtContent], 'captions.srt', {
+  type: 'application/x-subrip'
+});
+
+// Create object URL and import captions
+const uri = URL.createObjectURL(srtFile);
+const captions = await cesdk.engine.block.createCaptionsFromURI(uri);
+URL.revokeObjectURL(uri);
+
+// Add captions to page
+const page = cesdk.engine.scene.getCurrentPage();
+const captionTrack = cesdk.engine.block.create('//ly.img.ubq/captionTrack');
+
+captions.forEach((caption) => {
+  cesdk.engine.block.appendChild(captionTrack, caption);
+});
+
+cesdk.engine.block.appendChild(page, captionTrack);
+
+// Center the first caption as a reference point
+cesdk.engine.block.alignHorizontally([captions[0]], 'Center');
+cesdk.engine.block.alignVertically([captions[0]], 'Center');
+```
+
+### Other Processing Services
+
+Audio export also supports these workflows:
+
+- **Audio enhancement** - Noise removal, normalization
+- **Music analysis** - Tempo, key, beat detection
+- **Language detection** - Identify spoken language
+- **Speaker diarization** - Identify who spoke when
+
+## Next Steps
+
+Now that you understand audio export, explore related audio and video features:
+
+- [Add Captions](./edit-video/add-captions.md) - Learn how to create and sync caption blocks with audio content
+- [Control Audio and Video](./create-video/control.md) - Master time offset, duration, and playback controls for audio blocks
+- [Trim Video Clips](./edit-video/trim.md) - Apply the same trim concepts to isolate audio segments
+
+---
+
+## More Resources
+
+- **[Vanilla JS/TS Documentation Index](https://img.ly/docs/cesdk/js.md)** - Browse all Vanilla JS/TS documentation
+- **[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