Insert Audio - Next.js

Add audio files to video projects using CE.SDK’s audio block system for background music, sound effects, and voiceovers.

Insert Audio example showing audio block in the timeline

8 mins

estimated time

Download

StackBlitz

GitHub

Audio blocks are time-based blocks that play sound alongside video content. Unlike video fills that attach to graphic blocks, audio blocks exist independently in the composition with their own duration, position, and volume controls.

import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';

import {
  BlurAssetSource,
  CaptionPresetsAssetSource,
  ColorPaletteAssetSource,
  CropPresetsAssetSource,
  DemoAssetSources,
  EffectsAssetSource,
  FiltersAssetSource,
  PagePresetsAssetSource,
  StickerAssetSource,
  TextAssetSource,
  TextComponentAssetSource,
  TypefaceAssetSource,
  UploadAssetSources,
  VectorShapeAssetSource
} from '@cesdk/cesdk-js/plugins';
import { VideoEditorConfig } from './video-editor/plugin';
import packageJson from './package.json';

/**
 * CE.SDK Plugin: Insert Audio Guide
 *
 * Demonstrates adding audio to video projects:
 * - Creating audio blocks programmatically
 * - Setting audio source URIs
 * - Configuring timeline position and duration
 * - Adjusting audio volume, mute, and loop settings
 * - Querying and managing audio blocks
 */
class Example implements EditorPlugin {
  name = packageJson.name;

  version = packageJson.version;

  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
    if (!cesdk) {
      throw new Error('CE.SDK instance is required for this plugin');
    }
    await cesdk.addPlugin(new VideoEditorConfig());

    // Add asset source plugins
    await cesdk.addPlugin(new BlurAssetSource());
    await cesdk.addPlugin(new CaptionPresetsAssetSource());
    await cesdk.addPlugin(new ColorPaletteAssetSource());
    await cesdk.addPlugin(new CropPresetsAssetSource());
    await cesdk.addPlugin(
      new UploadAssetSources({
        include: ['ly.img.image.upload', 'ly.img.video.upload', 'ly.img.audio.upload']
      })
    );
    await cesdk.addPlugin(
      new DemoAssetSources({
        include: [
          'ly.img.templates.video.*',
          'ly.img.image.*',
          'ly.img.audio.*',
          'ly.img.video.*'
        ]
      })
    );
    await cesdk.addPlugin(new EffectsAssetSource());
    await cesdk.addPlugin(new FiltersAssetSource());
    await cesdk.addPlugin(
      new PagePresetsAssetSource({
        include: [
          'ly.img.page.presets.instagram.*',
          'ly.img.page.presets.facebook.*',
          'ly.img.page.presets.x.*',
          'ly.img.page.presets.linkedin.*',
          'ly.img.page.presets.pinterest.*',
          'ly.img.page.presets.tiktok.*',
          'ly.img.page.presets.youtube.*',
          'ly.img.page.presets.video.*'
        ]
      })
    );
    await cesdk.addPlugin(new StickerAssetSource());
    await cesdk.addPlugin(new TextAssetSource());
    await cesdk.addPlugin(new TextComponentAssetSource());
    await cesdk.addPlugin(new TypefaceAssetSource());
    await cesdk.addPlugin(new VectorShapeAssetSource());

    await cesdk.actions.run('scene.create', {
      layout: 'DepthStack',
      page: { width: 1920, height: 1080, unit: 'Pixel' }
    });

    const engine = cesdk.engine;
    const page = engine.scene.getCurrentPage();
    if (page == null) {
      throw new Error('No page found in scene');
    }

    // Set page duration for timeline
    engine.block.setDuration(page, 30);

    // Create an audio block and set source
    const audioUri =
      'https://cdn.img.ly/assets/demo/v3/ly.img.audio/audios/far_from_home.m4a';
    const audioBlock = engine.block.create('audio');
    engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
    engine.block.appendChild(page, audioBlock);

    // Load audio resource to access duration
    await engine.block.forceLoadAVResource(audioBlock);
    const totalDuration = engine.block.getAVResourceTotalDuration(audioBlock);
    console.log('Audio total duration:', totalDuration, 'seconds');

    engine.block.setTimeOffset(audioBlock, 0);
    engine.block.setDuration(audioBlock, Math.min(totalDuration, 30));

    engine.block.setVolume(audioBlock, 0.8);
    const currentVolume = engine.block.getVolume(audioBlock);
    console.log('Audio volume:', currentVolume);

    engine.block.setMuted(audioBlock, false);
    const isMuted = engine.block.isMuted(audioBlock);
    console.log('Audio muted:', isMuted);

    engine.block.setLooping(audioBlock, false);
    const isLooping = engine.block.isLooping(audioBlock);
    console.log('Audio looping:', isLooping);

    const allAudioBlocks = engine.block.findByType('audio');
    console.log('Total audio blocks:', allAudioBlocks.length);

    // Log information about each audio block
    allAudioBlocks.forEach((block, index) => {
      const uri = engine.block.getString(block, 'audio/fileURI');
      const timeOffset = engine.block.getTimeOffset(block);
      const duration = engine.block.getDuration(block);
      const volume = engine.block.getVolume(block);

      console.log(`Audio block ${index + 1}:`, {
        uri: uri.split('/').pop(),
        timeOffset: `${timeOffset}s`,
        duration: `${duration}s`,
        volume: `${(volume * 100).toFixed(0)}%`
      });
    });

    // Create a second audio block to demonstrate removal
    const tempAudioBlock = engine.block.create('audio');
    engine.block.appendChild(page, tempAudioBlock);

    engine.block.destroy(tempAudioBlock);

    console.log(
      'Insert Audio guide initialized. Open the timeline to see audio tracks.'
    );
  }
}

export default Example;

This guide covers creating audio blocks, configuring time-based properties, controlling playback settings, and managing audio blocks in your scene.

Creating an Audio Block#

We create audio blocks using engine.block.create('audio') and set the source file with the audio/fileURI property. Audio blocks must be appended to a page to become part of the composition.

const audioBlock = engine.block.create('audio');
engine.block.setString(audioBlock, 'audio/fileURI', audioUri);
engine.block.appendChild(page, audioBlock);

CE.SDK supports WAV and MP4 audio formats (including .m4a files). The source URI can point to any accessible URL.

Configuring Time Position#

Audio blocks have time-based properties that control when and how long they play. We use setTimeOffset() for the start position and setDuration() for playback length.

engine.block.setTimeOffset(audioBlock, 0);
engine.block.setDuration(audioBlock, Math.min(totalDuration, 30));

The forceLoadAVResource() method loads the audio file so we can access its total duration. Use getAVResourceTotalDuration() to get the full length of the source audio for timing calculations.

Adjusting Volume#

We set volume using setVolume() with values from 0.0 (silent) to 1.0 (full volume). This affects both preview playback and the final exported output.

engine.block.setVolume(audioBlock, 0.8);
const currentVolume = engine.block.getVolume(audioBlock);

Muting Audio#

To temporarily silence audio without removing it, use setMuted(). This preserves all other properties while stopping sound output.

engine.block.setMuted(audioBlock, false);
const isMuted = engine.block.isMuted(audioBlock);

Looping Audio#

Enable continuous playback with setLooping(). When enabled, the audio repeats until the end of the block’s duration in the composition.

engine.block.setLooping(audioBlock, false);
const isLooping = engine.block.isLooping(audioBlock);

Finding Audio Blocks#

Use findByType('audio') to retrieve all audio blocks in the scene. This is useful for building audio management interfaces or performing batch operations.

const allAudioBlocks = engine.block.findByType('audio');

Removing Audio#

To remove an audio block, call destroy(). This removes the block from the scene and frees its resources.

engine.block.destroy(tempAudioBlock);

API Reference#

Method	Description
`engine.block.create('audio')`	Create a new audio block
`engine.block.setString(block, 'audio/fileURI', uri)`	Set the audio source file
`engine.block.appendChild(parent, child)`	Add audio block to page
`engine.block.forceLoadAVResource(block)`	Force load the audio file
`engine.block.getAVResourceTotalDuration(block)`	Get total audio duration in seconds
`engine.block.setTimeOffset(block, seconds)`	Set start position
`engine.block.setDuration(block, seconds)`	Set playback duration
`engine.block.setVolume(block, volume)`	Set volume (0.0-1.0)
`engine.block.getVolume(block)`	Get current volume
`engine.block.setMuted(block, muted)`	Mute or unmute audio
`engine.block.isMuted(block)`	Check if audio is muted
`engine.block.setLooping(block, loop)`	Enable/disable looping
`engine.block.isLooping(block)`	Check if looping is enabled
`engine.block.findByType('audio')`	Find all audio blocks
`engine.block.destroy(block)`	Remove audio block from scene

Next Steps#

Insert Media Overview - Learn about adding different media types to your projects

Split Video - Split video clips on the timeline

Load Scene - Save and reload your scenes with audio

Store Custom Metadata - Save custom data with your scenes