@imgly/codesign-mcp 0.1.5 → 0.1.7

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

@@ -1,81 +1,105 @@
-> 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) > [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.
+Run **CE.SDK** in **Node.js server mode** to mirror video blocks programmatically—no client editor required. Flip clips before handing scenes to a browser runtime, enforcing template rules, or running automation jobs that prepare footage for downstream pipelines.
+
+> **Note:** CE.SDK for Node.js runs **headless**. To preview or export H.264/MP4, send the prepared scene to a browser runtime such as CE.SDK Web or Playwright (WebCodecs support) and encode the video there, or render frames into your encoder of choice.
+
+## Requirements
+
+- CE.SDK server package: `npm install @cesdk/node@$UBQ_VERSION$`
+- **Node.js 22** or newer
+- CE.SDK license key and `baseURL` to the CE.SDK asset bundle
 
 ## 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.
+- Flip video blocks **horizontally or vertically** server-side.
+- Mirror multiple clips together during automation jobs.
+- **Reset** or toggle flip states while persisting scene changes.
 
 ## When to Use
 
-Flipping is useful when you need to:
+Server-side flipping helps when you need to:
+
+- Prepare mirrored variants of clips for A/B testing or template variations.
+- Align **eyelines** between front and rear camera footage before export.
+- Keep branded elements facing inward on split-screen layouts that ship from templates.
+
+## Load and Flip Video Blocks
+
+Every video clip sits inside a **graphic** block with a video fill. After initializing the engine and loading a scene, identify the blocks you want to flip:
+
+```js
+import CreativeEngine from '@cesdk/node';
 
-- Create:
-  - **Symmetrical** video layouts
-  - Animated **collages**
-- Align **eyelines** when switching between front and rear cameras.
-- Keep **branded elements** facing inward on split-screen layouts.
+const engine = await CreativeEngine.init({
+  license: process.env.LICENSE_KEY,
+  baseURL: process.env.CESDK_BASE_URL
+});
 
-## How to Flip Videos
+await engine.scene.loadFromURL(
+  'https://cdn.img.ly/assets/demo/v3/ly.img.template/templates/cesdk_video_landscape_1.scene'
+);
 
-The CreativeEditor represents each video clip as a **graphic** block with:
+const graphics = engine.block.findByType('graphic');
+const videoBlocks = graphics.filter(
+  (id) => engine.block.getEnum(id, 'fill/type') === 'video'
+);
+
+if (videoBlocks.length === 0) {
+  throw new Error('No video blocks found in the scene.');
+}
+
+// Apply flips, then persist the scene before disposing of the engine.
+```
+
+Once you have the block IDs, use the flip helpers to mirror each clip as needed. Persist the modified scene with `engine.scene.saveToString()` or `engine.scene.saveToArchive()` before disposing of the engine.
+
+## How Flipping Works
+
+The CreativeEditor represents each video clip as a `graphic` block with:
 
 - Size
 - Transforms
 - Grouping
-- A fill set to a _video_ asset
+- A fill set to a *video* asset
 
-Use the Engine BlockAPI boolean helpers, common to videos and images.
+Use the BlockAPI boolean helpers—identical to the image flip workflow—to mirror or restore clips.
 
 ### 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`.
+Call the flip helper with the block ID and a boolean:
 
-```ts
-engine.block.setFlipHorizontal(videoBlock, true);
-engine.block.setFlipVertical(videoBlock, true);
+```js
+engine.block.setFlipHorizontal(videoBlock, true); // Mirror left/right
+engine.block.setFlipVertical(videoBlock, true);   // Mirror top/bottom
 ```
 
+The flip applies immediately in memory. Save or export the scene after you finish updates so the change appears once you open the scene in a browser runtime.
+
 <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.
+Check the current flip flags before toggling or resetting:
 
-```ts
+```js
 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.
+Both helpers return a boolean that reflects the block’s current orientation.
 
 > **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:
+Avoid repeating the same flip call for every block by grouping the clips first:
 
-```ts
+```js
 const groupId = await engine.block.group([clipId1, clipId2, clipId3]);
 engine.block.setFlipVertical(groupId, true);
 ```
@@ -84,8 +108,9 @@ engine.block.setFlipVertical(groupId, true);
 
 When you flip the group:
 
-- The flip mirrors everything at once.
-- Each clip keeps the same **spacing and order** inside the group.
+- The flip mirrors every child at once.
+- Each clip keeps the same **spacing and order** inside the group hierarchy.
+- Future flips on individual clips stack on top of the group-level flip, so track the group transform before applying more flips.
 
 ## Restore or Manage Flip States
 
@@ -98,43 +123,34 @@ The CE.SDK provides ways to reset or toggle a flip. You can either:
 
 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
+```js
 engine.block.setFlipHorizontal(videoBlock, false);
 ```
 
-### Switch Flip on or Off
+### Switch Flip On or Off
 
 Calling the same flip twice:
 
-- **Doesn't** revert to the original orientation.
+- **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);
+```js
+const isFlipped = 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`:
+In the preceding code, 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**.
+Use this pattern to:
+
+- Script command-line toggles
+- Expose a REST endpoint that flips clips on demand.
 
 ## Lock or Constrain Flipping
 
@@ -149,34 +165,44 @@ To deactivate flipping, use `setScopeEnabled` with:
 - The `"layer/flip"` key
 - The boolean set to `false`
 
-```ts
+```js
 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   |
+| Issue | Solution |
+| --- | --- |
+| ❌ Flip disappears when opening the scene in the browser editor | ✅ Save the scene (`engine.scene.saveToString()` or archive) after flipping and load that exported scene in the client. |
+| ❌ Flip seems ignored | ✅ Check whether the parent group is already flipped; group and block flips stack. |
+| ❌ Users can still flip in UI | ✅ Turn off the `"layer/flip"` scope or lock transforms in the template. |
+| ❌ Automation fails on certain clips | ✅ Ensure each block’s fill type is `video` before calling the flip helpers. |
+
+## Next Steps
+
+Now that you understand how to flip with the CE.SDK, take time to dive into other related features:
+
+- [Create a template](./create-templates.md) to enforce design rules.
+- [Get an overview](./overview.md) of the CE.SDK's video editing features.
 
 ## 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.     |
+| 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 you can flip them 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
+- **[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