Composition

A Composition object manages the entire state of a video project and serves as the foundation for any video editing tasks in Diffusion Studio. This guide will walk you through setting up and manipulating a Composition object.

Setting Up a Composition

To begin, import the Composition class from @diffusionstudio/core and create a new instance:

import * as core from '@diffusionstudio/core';
 
const composition = new core.Composition();

When constructing a Composition, you can pass various options. Here are the default values:

{
  height: 1080,
  width: 1920,
  background: '#000000',
  playbackEndBehavior: 'loop',
  licenseKey: undefined,
}

The specified height and width define the canvas size, but these do not dictate the final video resolution, which can be configured with the Encoder.

You can always change the width and height of the Composition after its creation using the resize method.

Visualizing the Composition

To display the Composition within your application, you can attach it to a DOM element. The example below shows how to center the player inside a container and scale it according to the available space:

const container = document.getElementById('player-container') as HTMLDivElement;
const player = document.getElementById('player') as HTMLDivElement;
 
composition.mount(player);
 
const scale = Math.min(
  container.clientWidth / composition.width,
  container.clientHeight / composition.height,
);
 
player.style.width = `${composition.width}px`;
player.style.height = `${composition.height}px`;
player.style.transform = `scale(${scale})`;
player.style.transformOrigin = 'center';

<div id="player-container">
  <div id="player"></div>
</div>

#player-container {
  display: flex;
  justify-content: center;
  align-items: center;
}

This setup ensures that the player is centered and scales to fit within the player-container while maintaining the aspect ratio of the Composition. For production environments, consider using a ResizeObserver  to handle dynamic resizing based on your specific needs.

Note: Since the canvas cannot be added as a child of two different elements, you must remove it from the player before attaching it to another element:

composition.unmount();

Changing the Composition State

Here are some common state manipulations you might perform on a Composition:

Adding Layers

const layer = new Layer();
await composition.add(layer);

add is an asynchronous action because it waits until all contained Clips are initialized.

You can remove the layer again by calling composition.remove(layer)

Adding Clips

Same concept applies to layers, add is an asynchronous action because it waits until the Clip is initialized.

const clip = new VideoClip();
await layer.add(clip);

Taking Screenshots

To capture a screenshot of the current frame:

await composition.seek('10s');
const dataUrl = await composition.screenshot();

Playback Controls

The most essential playback features are easily accessible through the Composition:

await composition.play();
await composition.pause();
await composition.seek(30);

Hint: Use the composition.time() function to conveniently display the current time of the Composition.

Playback Position

To get the current position as a fraction do this:

const position = composition.currentTime / composition.duration;

Whereas both currentTime and duration are in seconds.