Scale Videos

Requirements#

• A valid CE.SDL license key (get your free trial)
• Node.js 18 or newer
• CE.SDK server package: npm install @cesdk/node

What You’ll Learn#

• Scale a video block uniformly or along a single axis.
• Scale blocks together while keeping their relative layout.
• Lock scaling and transformations in templates.

When to Use#

Server-side scaling helps when you need to:

• Emphasise or de-emphasise a clip in a composition.
• Fit footage to a free-form layout without cropping.
• Drive pinch-to-zoom gestures or responsive designs.

How Scaling Works#

Scaling uses the scale(block, scale:number, anchorX, anchorY) function, with the following parameters:

For example:

• A value of 1.0 sets the original block’s size.
• A value of 2.0 makes the block twice as large.

Scale a Video Uniformly#

Scaling uniformly keeps the video’s aspect ratio intact while making it larger or smaller. This allows for applying zoom levels without stretching or squashing the content. For example:

engine.block.scale(blockId, 1.5);

The preceding code:

• Scales the video to 150% of its original size.
• Doesn’t change the origin anchor point.

As a result, the video expands down and to the right.

Anchor Point#

By default, the anchor point for the block when scaling is the top left. The scale function has two optional parameters:

• x to move the anchor point along the width.
• y to move the anchor point along the height.

They can have values between 0.0 and 1.0. For example:

engine.block.scale(blockId, 1.5, 0.5, 0.5)

This function:

1. Scales the video to 150% of its original size.
2. The origin anchor point is 0.5, 0.5, so the video expands from the center.

Scale a Video Non-Uniformly#

Let the Engine Handle Scaling#

To stretch or compress only one axis, thus distorting a video, use width or height function. For example, to scale a video horizontally, you can use:

engine.block.setWidthMode(blockId, 'Absolute');
const width = engine.block.getWidth(blockId) * 1.5;
engine.block.setWidth(blockId, width, true );

The preceding code:

1. Sets the width position as 'Absolute' so width changes use a fixed pixel value instead of a relative layout mode.
2. Reads the current width and multiplies it by 1.5 to compute a new width that’s 150% of the original.
3. Writes the new width back to the block while keeping height in proportion when available.

As a result, it stretches the element horizontally by the calculated factor:

Use this to:

• Create panoramic crops.
• Compensate for aspect ratios during automation.

2. Combine Crop-Scale with a Size Change#

Use setCropScale to explicitly crop the video vertically or horizontally. For example, to create a panoramic video:

await engine.block.setCropScaleX(blockId, 1.5);
await engine.block.setWidthMode(blockId, 'Absolute');
const newWidth = (await engine.block.getWidth(blockId)) * 1.5;
await engine.block.setWidth(blockId, newWidth);

The preceding code:

1. Expands the crop horizontally, so the video content is effectively stretched 150% along the X axis.
2. Switches the block to absolute sizing so width updates use a concrete pixel value instead of a responsive mode.
3. Reads the block’s current width, and multiplies it by 1.5 to compute the target width after the stretch.
4. Writes that new width back to the block so its frame matches the stretched content.

Respect the Existing Crop#

Since the crop defines what portion of the clip stays visible, stretching the block without preserving that crop will reveal unwanted areas or cut off the focal point. Respecting the existing crop keeps the creative intent intact while you change the scale.

await engine.block.setCropScaleX(blockId, 1.5);
await engine.block.setWidthMode(blockId, 'Absolute');
const newWidth = (await engine.block.getWidth(blockId)) * 1.5;
await engine.block.setWidth(blockId, newWidth, true);

In the preceding code, setting maintainCrop: true:

• Keeps the visible region intact.
• Avoids additional distortion.

Consider using setCropScaleX if a template already uses cropping to frame a subject or hide a watermark.

Scale Clips Together#

Group blocks to scale them proportionally:

const groupId = engine.block.group([blockId, textId]);
engine.block.scale(groupId, 1.75, 0.75, 0.5)

The preceding code scales the entire group to 75%. Call engine.block.findAllProperties(groupId) if you are unsure whether a block exposes width/height.

Lock Scaling in Templates#

Lock scaling when you must preserve a template’s layout. This is useful for:

• Brand assets
• Campaign creatives
• Collaboration workflows
• Fixed dimensions swapping editors

When working with templates, prevent users from scaling blocks by turning off the layer/resize scope:

// Prevent scaling/resizing of a block
engine.block.setScopeEnabled(blockId, 'layer/resize', false);

Lock All Transformations#

Available block transformations are the following:

• Move
• Resize
• Rotate

To lock all transformations, use the following function:

// Lock all transforms
engine.block.setTransformLocked(blockId, true);

To check if scaling is currently allowed, log the output if isScopeEnabled:

// Check if resize is enabled
const canResize = engine.block.isScopeEnabled(blockId, 'layer/resize');
console.log('layer/resize scope enabled?', canResize);

Troubleshooting#

API References in this Guide#