Scale Videos in Web Apps

What You’ll Learn#

• Scale videos through JavaScript.
• Scale proportionally or non-uniformly.
• Group elements to scale them together.
• Apply or lock scaling constraints in templates.

When to Use#

Use scaling to:

• Emphasize or de-emphasize a clip in a composition.
• Fit footage to a free-form layout without cropping.
• Drive 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#

To change the clip size without distorting its proportions, use uniform scaling. Uniform scaling multiplies both width and height by the same factor to keep the frame’s aspect ratio intact.

Scaling a video uniformly allows you to:

• Enlarge or shrink footage without altering the content.
• Maintain per-pixel sharpness.
• Align with layout constraints.

CE.SDK lets you use the same high-level API on all graphic blocks, videos included. To scale any block, use:

engine.block.scale(blockId, scaleFactorNumber);

For example, to scale a video block to 150%, add this in your code:

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.

<Picture src=[object Object] style=[object Object] alt=“Scaled video by 150%” formats=webp />

Anchor Point#

The anchor point is the point around which a layer scales. All changes happen around the anchor’s point position. By default, any block’s anchor point is the top left.

To change the anchor point, 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.

Both 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, with the value 1.5.
2. Sets the origin anchor point at the center with 0.5, 0.5.

This way, the video expands from the center.

<Picture src=[object Object] style=[object Object] alt=“Video scaled from the center by 150%” formats=webp />

Scale Videos Non-Uniformly#

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

1. Let the Engine Handle Scaling#

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 as 'Absolute' to edit the video using a fixed pixel value instead of a relative layout mode.
2. Reads the current width.
3. Multiplies it by 1.5 to compute a new width that’s 150% of the original.
4. Writes the new width back to the block.
5. Keeps height in proportion when available.

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

<Picture src=[object Object] style=[object Object] alt=“Video panoramic width increased to 150%” formats=webp />

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: the video content stretches by 150% along the X axis.
2. Switches the block to absolute sizing: width updates use a concrete pixel value, not a responsive one.
3. Reads the block’s current width.
4. Multiplies it by 1.5 to compute the target width after the stretch.
5. Writes the new width back to the block.

After this operation:

• The block’s frame matches the stretched content.
• The stretch has distorted the content.

3. Respect the Existing Crop#

The crop defines which part of the clip stays visible. Stretching the block without preserving its crop might:

• Reveal unwanted areas.
• Cut off the focal point.

Respecting the existing crop changes the scale while keeping the creative intent intact. For example:

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

In the preceding code, the true value activates maintainCrop. This:

• Keeps the visible region intact.
• Avoids distortion.

Consider using maintainCrop if a template already uses cropping to:

• Frame a subject.
• Hide a watermark.

Scale Clips Together#

Grouping blocks is a useful way of scaling 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#

To preserve a template’s layout, consider locking the scaling option. This is useful for:

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

Disable the layer/resize scope when working with templates, to prevent users from scaling blocks. For this, use the setScopeEnabled function:

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

Lock All Transformations#

These are the available block’s transformations with CE.SDK:

• Move
• Resize
• Rotate

To lock all transformations, activate the setTransformLocked setting:

// 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);

In the scenario where:

• Your app uses template-based constraints.
• You need to prevent the layer from overriding template constraints.

Call setGlobalScope to enforce the template’s constraints.

Recap#

API References in this Guide#