Control Audio & Video

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to configure and control audio and video through the block API.

Setup#

This example uses the headless CreativeEngine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

Time Offset and Duration#

The time offset determines when a block becomes active during playback on the scene's timeline, and the duration decides how long this block is active. Page blocks are a special case in that they have an implicitly calculated time offset that is determined by their order and the total duration of their preceding pages. As with any audio/video-related property, not every block supports these properties. Use hasTimeOffset and hasDuration to check.

JavaScript


hasTimeOffset(id: DesignBlockId): boolean

Returns whether the block has a time offset property.

id: The block to query.
Returns true, if the block has a time offset property.

JavaScript


setTimeOffset(id: DesignBlockId, offset: number): void

Set the time offset of the given block relative to its parent. The time offset controls when the block is first active in the scene. The time offset is not supported by the page block.

id: The block whose time offset should be changed.
offset: The new time offset in seconds.

JavaScript


getTimeOffset(id: DesignBlockId): number

Get the time offset of the given block relative to its parent.

id: The block whose time offset should be queried.
Returns the time offset of the block.

JavaScript


hasDuration(id: DesignBlockId): boolean

Returns whether the block has a duration property.

id: The block to query.
Returns true if the block has a duration property.

JavaScript


setDuration(id: DesignBlockId, duration: number): void

Set the playback duration of the given block in seconds. The duration defines for how long the block is active in the scene during playback. The duration is ignored when the scene is not in "Video" mode.

id: The block whose duration should be changed.
duration: The new duration in seconds.

JavaScript


getDuration(id: DesignBlockId): number

Get the playback duration of the given block in seconds.

id: The block whose duration should be returned.
Returns The block's duration.

JavaScript


getTotalSceneDuration(scene: DesignBlockId): number

Returns the total duration (in seconds) of a scene in video mode. The duration is defined by all blocks in the scene.

scene: The scene whose duration is being queried.
Returns the total scene duration.

JavaScript


setNativePixelBuffer(id: number, buffer: HTMLCanvasElement | HTMLVideoElement): void

Update the pixels of the given pixel stream fill block.

id: The pixel stream fill block.
buffer: Use pixel data from a canvas or a video element.

Trim#

You can select a specific range of footage from your audio/video resource by providing a trim offset and a trim length. The footage will loop if the trim's length is shorter than the block's duration. This behavior can also be disabled using the setLooping function.

JavaScript


hasTrim(id: DesignBlockId): boolean

Returns whether the block has trim properties.

id: The block to query.
Returns true, if the block has trim properties.

JavaScript


setTrimOffset(id: DesignBlockId, offset: number): void

Set the trim offset of the given block or fill. Sets the time in seconds within the fill at which playback of the audio or video clip should begin. This requires the video or audio clip to be loaded.

id: The block whose trim should be updated.
offset: The new trim offset.

JavaScript


getTrimOffset(id: DesignBlockId): number

Get the trim offset of this block. * This requires the video or audio clip to be loaded.

id: The block whose trim offset should be queried.
Returns the trim offset in seconds.

JavaScript


setTrimLength(id: DesignBlockId, length: number): void

Set the trim length of the given block or fill. The trim length is the duration of the audio or video clip that should be used for playback. After reaching this value during playback, the trim region will loop. This requires the video or audio clip to be loaded.

id: The object whose trim length should be updated.
length: The new trim length in seconds.

JavaScript


getTrimLength(id: DesignBlockId): number

Get the trim length of the given block or fill.

id: The object whose trim length should be queried.
Returns the trim length of the object.

Playback Control#

You can start and pause playback and seek to a certain point on the scene's timeline. There's also a solo playback mode to preview audio and video blocks individually while the rest of the scene stays frozen. Finally, you can enable or disable the looping behavior of blocks and control their audio volume.

JavaScript


setPlaying(id: DesignBlockId, enabled: boolean): void

Set whether the block should be playing during active playback.

id: The block that should be updated.
enabled: Whether the block should be playing its contents.

JavaScript


isPlaying(id: DesignBlockId): boolean

Returns whether the block is playing during active playback.

id: The block to query.
Returns whether the block is playing during playback.

JavaScript


setSoloPlaybackEnabled(id: DesignBlockId, enabled: boolean): void

Set whether the given block or fill should play its contents while the rest of the scene remains paused. Setting this to true for one block will automatically set it to false on all other blocks.

id: The block or fill to update.
enabled: Whether the block's playback should progress as time moves on.

JavaScript


isSoloPlaybackEnabled(id: DesignBlockId): boolean

Return whether the given block or fill is currently set to play its contents while the rest of the scene remains paused.

id: The block or fill to query.
Returns Whether solo playback is enabled for this block.

JavaScript


hasPlaybackTime(id: DesignBlockId): boolean

Returns whether the block has a playback time property.

id: The block to query.
Returns whether the block has a playback time property.

JavaScript


setPlaybackTime(id: DesignBlockId, time: number): void

Set the playback time of the given block.

id: The block whose playback time should be updated.
time: The new playback time of the block in seconds.

JavaScript


getPlaybackTime(id: DesignBlockId): number

Get the playback time of the given block.

id: The block to query.
Returns the playback time of the block in seconds.

JavaScript


hasPlaybackControl(id: DesignBlockId): boolean

Returns whether the block supports a playback control.

block: The block to query.
Returns Whether the block has playback control.

JavaScript


setLooping(id: DesignBlockId, looping: boolean): void

Set whether the block should restart from the beginning again or stop.

block: The block or video fill to update.
looping: Whether the block should loop to the beginning or stop.

JavaScript


isLooping(id: DesignBlockId): boolean

Query whether the block is looping.

block: The block to query.
Returns Whether the block is looping.

JavaScript


setMuted(id: DesignBlockId, muted: boolean): void

Set whether the audio of the block is muted.

block: The block or video fill to update.
muted: Whether the audio should be muted.

JavaScript


isMuted(id: DesignBlockId): boolean

Query whether the block is muted.

block: The block to query.
Returns Whether the block is muted.

JavaScript


setVolume(id: DesignBlockId, volume: number): void

Set the audio volume of the given block.

block: The block or video fill to update.
volume: The desired volume with a range of 0, 1.

JavaScript


getVolume(id: DesignBlockId): number

Get the audio volume of the given block.

block: The block to query.
Returns The volume with a range of 0, 1.

JavaScript


getVideoWidth(id: DesignBlockId): number

Get the video width in pixels of the video resource that is attached to the given block.

block: The video fill.
Returns The video width in pixels or an error.

JavaScript


getVideoHeight(id: DesignBlockId): number

Get the video height in pixels of the video resource that is attached to the given block.

block: The video fill.
Returns The video height in pixels or an error.

Resource Control#

Until an audio/video resource referenced by a block is loaded, properties like the duration of the resource aren't available, and accessing those will lead to an error. You can avoid this by forcing the resource you want to access to load using forceLoadAVResource.

JavaScript


forceLoadAVResource(id: DesignBlockId): Promise<void>

Begins loading the required audio and video resource for the given video fill or audio block.

id: The video fill or audio block whose resource should be loaded.
Returns A Promise that resolves once the resource has finished loading.

JavaScript


getAVResourceTotalDuration(id: DesignBlockId): number

Get the duration in seconds of the video or audio resource that is attached to the given block.

id: The video fill or audio block.
Returns The video or audio file duration

Thumbnail Previews#

For a user interface, it can be helpful to have image previews in the form of thumbnails for any given video resource. For videos, the engine can provide one or more frames using generateVideoThumbnailSequence. Simply pass the video fill that references the video resource. In addition to thumbnails of videos, the engine can generate a complete page composition that includes every element on the page over time. To do this pass in the respective page block. The video editor uses these to visually represent and preview pages in the timeline. They can be regenerated whenever an edit is made to a page.

Note: there can be at most one thumbnail generation request per block at any given time. If you don't want to wait for the request to finish before issueing a new request, you can cancel it by calling the returned function.

JavaScript


generateVideoThumbnailSequence(id: DesignBlockId, thumbnailHeight: number, timeBegin: number, timeEnd: number, numberOfFrames: number, onFrame: (frameIndex: number, result: ImageData | Error) => void): () => void

Generate a sequence of thumbnails for the given video fill or page. Note: there can only be one thumbnail generation request in progress for a given block.

id: The video fill or page.
thumbnailHeight: The height of a thumbnail. The width will be calculated from the video aspect ratio.
timeBegin: The time in seconds at which the thumbnail sequence should start.
timeEnd: The time in seconds at which the thumbnail sequence should end.
numberOfFrames: The number of frames to generate.
onFrame: Gets passed the frame index and RGBA image data.
Returns A method that will cancel any thumbnail generation request in progress for this block.


// Time Offset and Duration
engine.block.hasTimeOffset(audio);
engine.block.setTimeOffset(audio, 2);
engine.block.getTimeOffset(audio); /* Returns 2 */

engine.block.hasDuration(page);
engine.block.setDuration(page, 10);
engine.block.getDuration(page); /* Returns 10 */

engine.block.getTotalSceneDuration(scene);

// Trim
engine.block.hasTrim(videoFill);
engine.block.setTrimOffset(videoFill, 1);
engine.block.getTrimOffset(videoFill); /* Returns 1 */
engine.block.setTrimLength(videoFill, 5);
engine.block.getTrimLength(videoFill); /* Returns 5 */

// Playback Control
engine.block.setPlaying(scene, true);
engine.block.isPlaying(scene);

engine.block.setSoloPlaybackEnabled(videoFill, true);
engine.block.isSoloPlaybackEnabled(videoFill);

engine.block.hasPlaybackTime(scene);
engine.block.setPlaybackTime(scene, 1);
engine.block.getPlaybackTime(scene);

engine.block.hasPlaybackControl(videoFill);
engine.block.setLooping(videoFill, true);
engine.block.isLooping(videoFill);
engine.block.setMuted(videoFill, true);
engine.block.isMuted(videoFill);
engine.block.setVolume(videoFill, 0.5); /* 50% volume */
engine.block.getVolume(videoFill);

// Resource Control
await engine.block.forceLoadAVResource(videoFill);
engine.block.getAVResourceTotalDuration(videoFill);
const videoWidth = engine.block.getVideoWidth(videoFill);
const videoHeight = engine.block.getVideoHeight(videoFill);

const cancelThumbnailGeneration = engine.block.generateVideoThumbnailSequence(
  videoFill /* video fill or page */,
  128 /* thumbnail height, width will be calculated from aspect ratio */,
  0.5 /* begin time */,
  9.5 /* end time */,
  10 /* number of thumbnails to generate */,
  async (frame, width, height, imageData) => {
    const image = await createImageBitmap(imageData);
    // Draw the image...
  }
);