@imgly/codesign-mcp 0.1.0

package/assets/docs/guide/edit-video/transform/crop.md

@@ -0,0 +1,380 @@
+> 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 Videos](./create-video.md) > [Transform](./edit-video/transform.md) > [Crop](./edit-video/transform/crop.md)
+
+---
+
+Crop videos to focus on specific areas, remove unwanted edges, or prepare clips for fixed formats like 9:16 stories using programmatic crop transforms.
+
+![Crop videos example showing cropped video content](https://img.ly/docs/cesdk/./assets/browser.hero.webp)
+
+> **Reading time:** 10 minutes
+>
+> **Resources:**
+>
+> - [Download examples](https://github.com/imgly/cesdk-web-examples/archive/refs/tags/release-$UBQ_VERSION$.zip)
+> - [View source on GitHub](https://github.com/imgly/cesdk-web-examples/tree/release-$UBQ_VERSION$/guides-create-video-transform-crop-browser)
+> - [Open in StackBlitz](https://stackblitz.com/github/imgly/cesdk-web-examples/tree/v$UBQ_VERSION$/guides-create-video-transform-crop-browser)
+> - [Live demo](https://img.ly/docs/cesdk/examples/guides-create-video-transform-crop-browser/)
+
+Video cropping in CreativeEditor SDK (CE.SDK) lets you re-frame clips, remove unwanted edges, or adapt footage for platform-specific formats. Unlike resizing or scaling which affects the entire frame uniformly, cropping selects a specific region to display.
+
+```typescript file=@cesdk_web_examples/guides-create-video-transform-crop-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';
+
+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: 720, height: 1280, unit: 'Pixel' }
+    });
+
+    const engine = cesdk.engine;
+
+    // Get the page from the scene
+    const pages = engine.block.findByType('page');
+    const page = pages[0];
+
+    // Add a video using the convenience API - this handles track creation automatically
+    const videoUri =
+      'https://cdn.img.ly/assets/demo/v3/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4';
+    const videoBlock = await engine.block.addVideo(videoUri, 720, 1280);
+
+    // Append the video block to the page (for video scenes, this adds to the track)
+    engine.block.appendChild(page, videoBlock);
+
+    // Set video duration on the timeline
+    engine.block.setDuration(videoBlock, 10);
+
+    // Get the fill to force load the video resource
+    const videoFill = engine.block.getFill(videoBlock);
+    await engine.block.forceLoadAVResource(videoFill);
+
+    // Verify the block supports cropping before applying crop operations
+    const supportsCrop = engine.block.supportsCrop(videoBlock);
+    console.log('Block supports crop:', supportsCrop);
+
+    // Set content fill mode to 'Crop' for manual crop control
+    // This enables the crop transform APIs to take effect
+    engine.block.setContentFillMode(videoBlock, 'Crop');
+
+    // Scale the video content within its frame using uniform scale ratio
+    // Values greater than 1.0 zoom in, values less than 1.0 zoom out
+    engine.block.setCropScaleRatio(videoBlock, 1.1);
+
+    // Pan the video content within the crop frame
+    // Translation values are percentages of the crop frame dimensions
+    // Positive X moves content right, positive Y moves content down
+    engine.block.setCropTranslationX(videoBlock, 0.0);
+    engine.block.setCropTranslationY(videoBlock, 0.0);
+
+    // Rotate the video content within its frame
+    // Rotation is specified in radians (Math.PI = 180 degrees)
+    engine.block.setCropRotation(videoBlock, Math.PI / 90); // 2 degrees
+
+    // Retrieve the current crop state
+    const scaleRatio = engine.block.getCropScaleRatio(videoBlock);
+    const translationX = engine.block.getCropTranslationX(videoBlock);
+    const translationY = engine.block.getCropTranslationY(videoBlock);
+    const rotation = engine.block.getCropRotation(videoBlock);
+
+    console.log('Crop scale ratio:', scaleRatio);
+    console.log('Crop translation X:', translationX);
+    console.log('Crop translation Y:', translationY);
+    console.log('Crop rotation (radians):', rotation);
+
+    // Adjust crop to ensure content fills the frame without letterboxing
+    // The minScaleRatio parameter sets the minimum allowed scale
+    // This corrects any black bars caused by rotation or translation
+    engine.block.adjustCropToFillFrame(videoBlock, 1.1);
+    const finalScale = engine.block.getCropScaleRatio(videoBlock);
+    console.log('Adjusted scale ratio:', finalScale);
+
+    // Flip the video content within its crop frame
+    // This flips the content, not the entire block
+    engine.block.flipCropHorizontal(videoBlock);
+
+    // Lock the crop aspect ratio during interactive editing
+    // When locked, crop handles maintain the current aspect ratio
+    engine.block.setCropAspectRatioLocked(videoBlock, true);
+    const isLocked = engine.block.isCropAspectRatioLocked(videoBlock);
+    console.log('Crop aspect ratio locked:', isLocked);
+
+    // Reset crop to default state (removes all crop transformations)
+    engine.block.resetCrop(videoBlock);
+    // Re-apply a subtle zoom to demonstrate crop is working
+    engine.block.setCropScaleRatio(videoBlock, 1.05);
+
+    // Select the video block to show it in the UI
+    engine.block.select(videoBlock);
+
+    // Set playback time to show video content
+    engine.block.setPlaybackTime(page, 2.0);
+
+    // Zoom to the video block for better visibility of the crop effect
+    cesdk.engine.scene.zoomToBlock(videoBlock, {
+      padding: { left: 0.5, top: 0.5, right: 0.5, bottom: 0.8 }
+    });
+  }
+}
+
+export default Example;
+```
+
+This guide covers programmatic video cropping using scale, translation, and rotation transforms, checking crop support, adjusting crop to fill frames, flipping content, and locking aspect ratios.
+
+## Check Crop Support
+
+Before applying crop operations, verify the block supports cropping using `engine.block.supportsCrop()`. Video blocks with fills support cropping:
+
+```typescript highlight-check-crop-support
+// Verify the block supports cropping before applying crop operations
+const supportsCrop = engine.block.supportsCrop(videoBlock);
+console.log('Block supports crop:', supportsCrop);
+
+// Set content fill mode to 'Crop' for manual crop control
+// This enables the crop transform APIs to take effect
+engine.block.setContentFillMode(videoBlock, 'Crop');
+```
+
+## Scale Crop
+
+Scale the video content within its frame using `engine.block.setCropScaleRatio()`. Values greater than 1.0 zoom in, values less than 1.0 zoom out. This applies a uniform scale to both axes:
+
+```typescript highlight-scale-crop
+// Scale the video content within its frame using uniform scale ratio
+// Values greater than 1.0 zoom in, values less than 1.0 zoom out
+engine.block.setCropScaleRatio(videoBlock, 1.1);
+```
+
+## Translate Crop
+
+Pan the video content within the crop frame using `engine.block.setCropTranslationX()` and `engine.block.setCropTranslationY()`. Translation values are percentages of the crop frame dimensions. Positive X moves content right, positive Y moves content down:
+
+```typescript highlight-translate-crop
+// Pan the video content within the crop frame
+// Translation values are percentages of the crop frame dimensions
+// Positive X moves content right, positive Y moves content down
+engine.block.setCropTranslationX(videoBlock, 0.0);
+engine.block.setCropTranslationY(videoBlock, 0.0);
+```
+
+## Rotate Crop
+
+Rotate the video content within its frame using `engine.block.setCropRotation()`. Rotation is specified in radians where `Math.PI` equals 180 degrees:
+
+```typescript highlight-rotate-crop
+// Rotate the video content within its frame
+// Rotation is specified in radians (Math.PI = 180 degrees)
+engine.block.setCropRotation(videoBlock, Math.PI / 90); // 2 degrees
+```
+
+## Get Crop Values
+
+Retrieve the current crop state to read or restore crop settings using getter methods:
+
+```typescript highlight-get-crop-values
+// Retrieve the current crop state
+const scaleRatio = engine.block.getCropScaleRatio(videoBlock);
+const translationX = engine.block.getCropTranslationX(videoBlock);
+const translationY = engine.block.getCropTranslationY(videoBlock);
+const rotation = engine.block.getCropRotation(videoBlock);
+
+console.log('Crop scale ratio:', scaleRatio);
+console.log('Crop translation X:', translationX);
+console.log('Crop translation Y:', translationY);
+console.log('Crop rotation (radians):', rotation);
+```
+
+## Fill Frame
+
+Adjust the crop to ensure content fills the frame without letterboxing using `engine.block.adjustCropToFillFrame()`. The `minScaleRatio` parameter sets the minimum allowed scale:
+
+```typescript highlight-fill-frame
+// Adjust crop to ensure content fills the frame without letterboxing
+// The minScaleRatio parameter sets the minimum allowed scale
+// This corrects any black bars caused by rotation or translation
+engine.block.adjustCropToFillFrame(videoBlock, 1.1);
+const finalScale = engine.block.getCropScaleRatio(videoBlock);
+console.log('Adjusted scale ratio:', finalScale);
+```
+
+This is useful after applying translations or rotations that might reveal empty areas.
+
+## Flip Crop
+
+Flip the video content horizontally or vertically within its crop frame using `engine.block.flipCropHorizontal()` or `engine.block.flipCropVertical()`. This flips the content, not the block itself:
+
+```typescript highlight-flip-crop
+// Flip the video content within its crop frame
+// This flips the content, not the entire block
+engine.block.flipCropHorizontal(videoBlock);
+```
+
+## Lock Aspect Ratio
+
+Lock the crop aspect ratio during interactive editing using `engine.block.setCropAspectRatioLocked()`. When locked, crop handles maintain the current aspect ratio:
+
+```typescript highlight-lock-aspect-ratio
+// Lock the crop aspect ratio during interactive editing
+// When locked, crop handles maintain the current aspect ratio
+engine.block.setCropAspectRatioLocked(videoBlock, true);
+const isLocked = engine.block.isCropAspectRatioLocked(videoBlock);
+console.log('Crop aspect ratio locked:', isLocked);
+```
+
+## Reset Crop
+
+Reset all crop transformations to their default state using `engine.block.resetCrop()`:
+
+```typescript highlight-reset-crop
+// Reset crop to default state (removes all crop transformations)
+engine.block.resetCrop(videoBlock);
+// Re-apply a subtle zoom to demonstrate crop is working
+engine.block.setCropScaleRatio(videoBlock, 1.05);
+```
+
+## Coordinate System
+
+Crop transforms use normalized values:
+
+| Property    | Value Type          | Description                                      |
+| ----------- | ------------------- | ------------------------------------------------ |
+| Scale       | Float (0.0+)        | 1.0 is original size, 2.0 is double, 0.5 is half |
+| Translation | Float (-1.0 to 1.0) | Percentage of frame dimensions                   |
+| Rotation    | Float (radians)     | Math.PI = 180°, Math.PI/2 = 90°                  |
+
+All crop values are independent of canvas zoom level or timeline duration.
+
+## Combining with Other Transforms
+
+You can combine crop operations with other block transforms like position, rotation, and scale. The crop transforms affect the content within the block, while block transforms affect the block itself on the canvas:
+
+```typescript
+// Crop the content (scales/pans the video within its frame)
+engine.block.setCropScaleRatio(videoBlock, 1.5);
+engine.block.setCropRotation(videoBlock, Math.PI / 12);
+
+// Transform the block itself (moves/rotates the entire block on canvas)
+engine.block.setRotation(videoBlock, Math.PI / 6);
+engine.block.setWidth(videoBlock, 800);
+```
+
+## Troubleshooting
+
+### Crop Functions Not Working
+
+Check if the block supports cropping using `engine.block.supportsCrop()`. Ensure the block has a fill that supports cropping (video, image fills).
+
+### Black Bars After Scaling
+
+Call `engine.block.adjustCropToFillFrame()` or increase the scale ratio so content fully covers the block frame.
+
+### Unexpected Crop Behavior
+
+Verify you're operating on the correct block ID. Check that the video resource has loaded using `engine.block.forceLoadAVResource()` before applying crop transforms.
+
+## API Reference
+
+| Method                                    | Description                      |
+| ----------------------------------------- | -------------------------------- |
+| `engine.block.supportsCrop()`             | Check if block supports cropping |
+| `engine.block.setCropScaleRatio()`        | Set uniform scale ratio          |
+| `engine.block.setCropScaleX()`            | Set horizontal scale             |
+| `engine.block.setCropScaleY()`            | Set vertical scale               |
+| `engine.block.setCropTranslationX()`      | Set horizontal pan               |
+| `engine.block.setCropTranslationY()`      | Set vertical pan                 |
+| `engine.block.setCropRotation()`          | Set rotation in radians          |
+| `engine.block.getCropScaleRatio()`        | Get current scale ratio          |
+| `engine.block.getCropTranslationX()`      | Get horizontal translation       |
+| `engine.block.getCropTranslationY()`      | Get vertical translation         |
+| `engine.block.getCropRotation()`          | Get rotation value               |
+| `engine.block.adjustCropToFillFrame()`    | Auto-adjust to fill frame        |
+| `engine.block.flipCropHorizontal()`       | Flip content horizontally        |
+| `engine.block.flipCropVertical()`         | Flip content vertically          |
+| `engine.block.setCropAspectRatioLocked()` | Lock/unlock aspect ratio         |
+| `engine.block.isCropAspectRatioLocked()`  | Check if aspect ratio locked     |
+| `engine.block.resetCrop()`                | Reset all crop transforms        |
+
+---
+
+## 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/edit-video/transform/flip.md

@@ -0,0 +1,182 @@
+> 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 Videos](./create-video.md) > [Transform](./edit-video/transform.md) > [Flip](./edit-video/transform/flip.md)
+
+---
+
+Use **CE.SDK** to **mirror video clips** horizontally or vertically in your web app. Flip videos to create mirror effects and symmetrical designs using the same API calls to the image-flipping workflow.
+
+## What You’ll Learn
+
+- Flip a video clip **horizontally or vertically**.
+- Use flipping in template or timeline **workflows**.
+- **Reset** or toggle a flip using JavaScript.
+
+## When to Use
+
+Flipping is useful when you need to:
+
+- Create:
+  - **Symmetrical** video layouts
+  - Animated **collages**
+- Align **eyelines** when switching between front and rear cameras.
+- Keep **branded elements** facing inward on split-screen layouts.
+
+## How to Flip Videos
+
+The CreativeEditor represents each video clip as a **graphic** block with:
+
+- Size
+- Transforms
+- Grouping
+- A fill set to a _video_ asset
+
+Use the Engine BlockAPI boolean helpers, common to videos and images.
+
+### Flip Horizontally or Vertically
+
+To flip a video:
+
+1. Call the BlockAPI with `engine.block.SetFipHorizontal` or `engine.block.SetFipVertical`.
+2. Specify the **block ID** to flip.
+3. Set the boolean to `true`.
+
+```ts
+engine.block.setFlipHorizontal(videoBlock, true);
+engine.block.setFlipVertical(videoBlock, true);
+```
+
+<Picture src={flipVideo} style={{ width: '85%' }} alt="Video flipped horizontally" formats={['webp']} />
+
+### Query the Flip Status
+
+To know if a video has already been flipped:
+
+1. Declare a variable for each direction.
+2. Call `engine.block.getFlip<Directions>`.
+3. Specify the block ID.
+
+```ts
+const flippedH = engine.block.getFlipHorizontal(videoBlock);
+const flippedV = engine.block.getFlipVertical(videoBlock);
+```
+
+The response is a boolean stating whether this specific block has already been flipped or not.
+
+> **Note:** Flipping only affects the **visual track**. Audio (either embedded or separate) isn’t reversed, so **lip-sync and sound design stay intact**.
+
+### Flip Clips Together
+
+To simplify the process of rotating multiple blocks, instead of rotating each block individually, you can select and rotate a cluster of blocks simultaneously.
+
+1. Declare a variable for the group of clips using `engine.block.group`.
+2. Specify each clip to include in the group by its block ID.
+3. Apply the flip to the group variable.
+
+For example, to flip three clips together:
+
+```ts
+const groupId = await engine.block.group([clipId1, clipId2, clipId3]);
+engine.block.setFlipVertical(groupId, true);
+```
+
+<Picture src={flipGroup} style={{ width: '85%' }} alt="Grouped video flipped horizontally" formats={['webp']} />
+
+When you flip the group:
+
+- The flip mirrors everything at once.
+- Each clip keeps the same **spacing and order** inside the group.
+
+## Restore or Manage Flip States
+
+The CE.SDK provides ways to reset or toggle a flip. You can either:
+
+- **Reset:** when you want to restore a clip to its original orientation.
+- **Code a toggle:** when you need a quick way to switch the current flip state on and off.
+
+### Reset a Flip
+
+To reset a clip to its default orientation:
+
+1. Call `setFlip<Directions>`.
+2. Specify the clip’s block ID.
+3. Set the boolean to `false`.
+
+For example, to reset a horizontal flip, use the following code:
+
+```ts
+engine.block.setFlipHorizontal(videoBlock, false);
+```
+
+### Switch Flip on or Off
+
+Calling the same flip twice:
+
+- **Doesn't** revert to the original orientation.
+- Issues two flips in the same direction.
+- Leaves the clip mirrored.
+
+To “toggle” the flip in your code:
+
+1. Check if a specific clip is flipped.
+2. Store the value in a variable (for example, `isFlipped`).
+3. Set the opposite of that value in a new `setFlip<Directions>`function.
+
+For example:
+
+```ts
+const isFlipped = await engine.block.getFlipHorizontal(videoBlock);
+engine.block.setFlipHorizontal(videoBlock, !isFlipped);
+```
+
+In the preceding code, the two actions are possible depending on the value stored in `isFlipped`:
+
+- `true`: `!isFlipped` sets the horizontal flip to `false`.
+- `false`: `!isFlipped` sets the horizontal flip to `true`.
+
+You can add a toggle button to your custom UI to let users **quickly test flipping a video horizontally**.
+
+## Lock or Constrain Flipping
+
+CE.SDK provides a way to prevent editors from flipping a video. This can be useful to:
+
+- Avoid accidentally mirroring text.
+- Protect UI mock-ups or frames that must stay in a fixed position.
+- Keep templates brand-locked.
+
+To deactivate flipping, use `setScopeEnabled` with:
+
+- The `"layer/flip"` key
+- The boolean set to `false`
+
+```ts
+engine.block.setScopeEnabled(videoBlock, 'layer/flip', false);
+```
+
+## Troubleshooting
+
+| Issue                                          | Solution                                                                  |
+| ---------------------------------------------- | ------------------------------------------------------------------------- |
+| ❌ Clip appears flipped, but playback is blank | ✅ Make sure the video file has finished loading before applying the flip |
+| ❌ Flip seems ignored                          | ✅ Check whether the parent group is already flipped (flips are relative) |
+| ❌ Users can still flip in UI                  | ✅ Turn off the `"layer/flip"` scope or lock transforms in the template   |
+
+## API Reference Summary
+
+| BlockAPI `engine.block.<>`                        | Purpose                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------- |
+| `setFlipHorizontal(blockId, boolean)`             | Mirror a block left/right or restore the default orientation. |
+| `setFlipVertical(blockId, boolean)`               | Mirror a block top/bottom or restore the default orientation. |
+| `getFlipHorizontal(blockId)`                      | Check whether the block is currently flipped horizontally.    |
+| `getFlipVertical(blockId)`                        | Check whether the block is currently flipped vertically.      |
+| `group(blockIds[])`                               | Group blocks so they can be flipped together.                 |
+| `setScopeEnabled(blockId, "layer/flip", boolean)` | Activate or deactivate flip controls to lock orientation.     |
+
+---
+
+## 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