Video Trim & Image Box now available in the Design API (Preview)

Announcements
, ,
1

We’re excited to announce that the @canva/design Apps SDK now supports trim and imageBox when adding videos to a design. It shipped in beta with @canva/design@2.8.1-beta.0.

What’s new

Two new optional properties on VideoElement:

  • trim - set the start and end points of the video.
  • imageBox - crop and scale the source video.

These can be used with videos in:

  • addElementAtPoint() - adding a video directly to the current page.
  • addPage() - videos in a brand-new page.
  • initAppElement() - videos returned from an app element’s render callback.

Apps that don’t set these new fields will see no change in behaviour.

Why it matters

Until now, when your app added a video to a design, the user got the whole clip at the full frame. If you wanted to highlight a particular moment or a particular region the user had to do that editing themselves in Canva after your app added the video. With trim and imageBox your app can add videos that are already framed correctly for their design.

How to use it

Switch to the preview package:

npm install @canva/design@beta

Add a video zoomed in to a corner

const videoElement: VideoElementAtPoint = {
  type: "video",
  ref: "YOUR_VIDEO_REF" as VideoRef,
  altText: { text: "Top-right zoom", decorative: false },
  top: 30,
  left: 30,
  width: 1920,
  height: 1080,
  imageBox: {
    top: 0,
    left: -1920,
    width: 3840,
    height: 2160,
  },
};

await addElementAtPoint(videoElement);

A 1920x1080 source video will be zoomed to double its size, and positioned to only show its top right quarter. The video element in the design will be 1920x1080. Users will be able to adjust the crop themselves with the pre-cropped portions of the video still accessible.

Start a new page with a pre-trimmed video

import { addPage } from "@canva/design";

await addPage({
  title: "Highlight",
  elements: [
    {
      type: "video",
      ref: "YOUR_VIDEO_REF" as VideoRef,
      altText: { text: "Intro clip", decorative: false },
      top: 0,
      left: 0,
      width: 1920,
      height: 1080,
      trim: { startInSeconds: 0, endInSeconds: 10 },
    },
  ],
});

A new page will be created with a video trimmed down to its first 10 seconds.

Render a trimmed-and-cropped video from an app element

import { initAppElement } from "@canva/design";
import type { VideoRef } from "@canva/asset";

type Data = { ref: VideoRef };

const appElement = initAppElement<Data>({
  render: (data) => [
    {
      type: "video",
      ref: data.ref,
      altText: { text: "App-rendered clip", decorative: false },
      top: 30,
      left: 30,
      width: 960,
      height: 540,
      imageBox: {
        top: -270,
        left: -480,
        width: 1920,
        height: 1080,
      },
      trim: { startInSeconds: 2.5, endInSeconds: 10.72 },
    },
  ],
});

This new app element will contain a 1920x1080 video that has been cropped to half its original size, showing its center. The video will be pre-trimmed to play from the 2.5 second mark to the 10.72 second mark.

Docs & details

This is a preview API. Fields may change before GA based on your feedback. Please share what works and what doesn’t in this thread.

Happy editing! :clapper_board: