Rotate Videos

Requirements#

• CE.SDK server package: npm install @cesdk/node
• Node.js 18 or newer
• A valid CE.SDK license key

What You’ll Learn#

• Rotate a video block to an exact angle.
• Lock rotation globally or per block in template workflows.
• Rotate a group of clips together.
• Rotate live camera previews that use PixelStreamFill.

When to Use#

Server-side rotation helps when you need to:

• Normalise orientation for clips captured on different devices.
• Enforce brand-safe layouts that should freeze rotation.
• Generate rotated variants of the same footage during batch jobs.

How Rotation Works#

Call block.setRotation with the target angle in radians:

// Rotate the clip by 90°
await engine.block.setRotation(blockId, Math.PI / 2);

• Since Math.PI = 180°, Math.PI / 2 sets a 90° rotation angle.
• Use positive values for counterclockwise rotation.

setRotation applies the rotation to the entire block. To rotate only the media inside a frame, combine rotation with cropping.

Read Rotation Values#

Read the current rotation if you need to build incremental adjustments:

const currentRotation = await engine.block.getRotation(blockId);

For a 90° rotation, currentRotation logs the rotation in radians (1.5707963705062866).

Convert Degrees and Radians#

Most automation inputs arrive as degrees, but the CE.SDK API expects radians. Converting between the two lets you:

• Accept human-friendly degrees.
• Pass the correct radian values to setRotation.
• Turn the engine’s radian results back into degrees when you log or display them.

Conversion operations can be useful for:

• UX controls
• Brand guidelines
• Orientation metadata

Helpers keep scripts readable when you start from degree-based inputs:

const toRadians = (degrees) => (degrees * Math.PI) / 180;
const toDegrees = (radians) => (radians * 180) / Math.PI;

const targetRadians = toRadians(45); // 0.785398...
await engine.block.setRotation(blockId, targetRadians);

console.log('Video rotation is', toDegrees(targetRadians), '°');

The preceding code:

1. Defines degree↔radian helpers.
2. Converts 45° to radians.
3. Applies that rotation to the block.
4. Logs the resulting angle back in degrees.

Rotating Blocks Together#

To spin or tilt different blocks without redoing individual offsets:

• Group the blocks.
• Rotate the parent group.

This keeps their layout intact. For example:

const groupId = engine.block.group([titleText, clipId]);
await engine.block.setRotation(groupId, Math.PI / 8);

Every child block inherits the group’s rotation. This is especially useful for spinning, along clips:

• Titles
• Overlays
• Different shots

Lock Rotation#

When the editor is loaded in a server-managed or server-orchestrated workflow, there’s an option to prevent users from rotating elements. You can deactivate rotations in the UI from the Node.js backend, and still rotate elements through the CE.SDK API engine.

For this, use setSettingBool:

Hide Rotation handles#

Use the 'controlGizmo/showRotateHandles' setting key:

await engine.editor?.setSettingBool('controlGizmo/showRotateHandles', false);

Lock Rotation in Templates#

Prevent template editors from rotating specific blocks by disabling the rotate scope. For this, use setScopeEnabled:

// Disable rotation for a single block
engine.block.setScopeEnabled(videoBlockId, 'layer/rotate', false);

Lock All transforms#

If the clip should stay fixed in place, set setTransformLocked to true:

engine.block.setTransformLocked(blockId, true);

Check if the Template Allows Rotation#

Audit the template settings by checking whether rotation is currently allowed:

const canRotate = engine.block.isScopeEnabled(blockId, 'layer/rotate');
console.log('Rotation enabled?', canRotate);

Troubleshooting#

API References in this Guide#