To WebM - Vue | IMG.LY Docs

Export your video compositions as WebM files with VP8, VP9 or AV1 video and Opus audio. CE.SDK encodes with WebCodecs, the video encoders of the browser.

5 mins

estimated time

Download

StackBlitz

GitHub

WebM is an open video format. Its codecs, VP8, VP9, AV1, Opus and Vorbis, are royalty-free, so you can encode and publish them without a patent license. CE.SDK renders the page, encodes it with the encoders of the browser, and writes the WebM file in the engine.

import type CreativeEditorSDK from '@cesdk/cesdk-js';
import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
import {
  BlurAssetSource,
  ImageColorsAssetSource,
  ColorPaletteAssetSource,
  CropPresetsAssetSource,
  DemoAssetSources,
  EffectsAssetSource,
  FiltersAssetSource,
  PagePresetsAssetSource,
  StickerAssetSource,
  TextAssetSource,
  TextComponentAssetSource,
  TypefaceAssetSource,
  UploadAssetSources,
  VectorShapeAssetSource
} from '@cesdk/cesdk-js/plugins';
import { DesignEditorConfig } from '@cesdk/core-configs-web/design-editor';
import { AudioCodec, VideoCodec } from '@cesdk/engine';
import packageJson from './package.json';

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 DesignEditorConfig());
    // Add asset source plugins
    await cesdk.addPlugin(new BlurAssetSource());
    await cesdk.addPlugin(new ImageColorsAssetSource());
    await cesdk.addPlugin(new ColorPaletteAssetSource());
    await cesdk.addPlugin(new CropPresetsAssetSource());
    await cesdk.addPlugin(
      new UploadAssetSources({ include: ['ly.img.image.upload'] })
    );
    await cesdk.addPlugin(
      new DemoAssetSources({
        include: [
          'ly.img.templates.blank.*',
          'ly.img.templates.presentation.*',
          'ly.img.templates.print.*',
          'ly.img.templates.social.*',
          'ly.img.image.*'
        ]
      })
    );
    await cesdk.addPlugin(new EffectsAssetSource());
    await cesdk.addPlugin(new FiltersAssetSource());
    await cesdk.addPlugin(new PagePresetsAssetSource());
    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());

    const engine = cesdk.engine;

    cesdk.feature.enable('ly.img.video');
    await engine.scene.load(
      'https://cdn.img.ly/assets/demo/v3/ly.img.video.template/templates/milli-surf-school.scene'
    );
    const page = engine.scene.getCurrentPage();
    if (!page) throw new Error('No page found');

    await cesdk.actions.run('zoom.toPage', { autoFit: true });

    this.setupExportActions(cesdk, page);
  }

  private setupExportActions(cesdk: CreativeEditorSDK, page: number): void {
    const engine = cesdk.engine;

    const runWithDialog = async (
      title: string,
      exportBlob: (
        onProgress: (rendered: number, encoded: number, total: number) => void
      ) => Promise<Blob>
    ): Promise<void> => {
      const dialog = cesdk.utils.showLoadingDialog({
        title,
        message: 'Encoding WebM...',
        progress: 0
      });
      try {
        const blob = await exportBlob((_, encoded, total) => {
          dialog.updateProgress({ value: encoded, max: total });
        });
        dialog.close();
        await cesdk.utils.downloadFile(blob, 'video/webm');
      } catch (error) {
        dialog.showError({ message: 'Export failed' });
        throw error;
      }
    };

    cesdk.ui.insertOrderComponent(
      { in: 'ly.img.navigation.bar', position: 'end' },
      {
        id: 'ly.img.actions.navigationBar',
        children: [
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-builtin',
            label: 'Export Video',
            icon: '@imgly/Save',
            onClick: () => {
              cesdk.actions.run('exportDesign', { mimeType: 'video/webm' });
            }
          },
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-webm',
            label: 'Export WebM',
            icon: '@imgly/Save',
            onClick: () =>
              runWithDialog('Exporting WebM', async (onProgress) => {
                const blob = await engine.block.exportVideo(page, {
                  mimeType: 'video/webm',
                  onProgress
                });
                return blob;
              })
          },
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-webm-checked',
            label: 'Export (checked)',
            icon: '@imgly/Save',
            onClick: () =>
              runWithDialog('Exporting WebM', async (onProgress) => {
                await engine.editor.checkCapabilities();
                const canEncodeWebM =
                  engine.editor.getCapabilityState('vp9Encode') ===
                    'supported' &&
                  engine.editor.getCapabilityState('opusEncode') ===
                    'supported';
                if (!canEncodeWebM) {
                  throw new Error('This browser cannot encode VP9 and Opus');
                }
                return engine.block.exportVideo(page, {
                  mimeType: 'video/webm',
                  onProgress
                });
              })
          },
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-webm-codecs',
            label: 'Export VP8',
            icon: '@imgly/Save',
            onClick: () =>
              runWithDialog('Exporting VP8', async (onProgress) => {
                const blob = await engine.block.exportVideo(page, {
                  mimeType: 'video/webm',
                  videoCodec: VideoCodec.VP8,
                  audioCodec: AudioCodec.Opus,
                  onProgress
                });
                return blob;
              })
          },
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-webm-av1',
            label: 'Export AV1',
            icon: '@imgly/Save',
            onClick: () =>
              runWithDialog('Exporting AV1', async (onProgress) => {
                await engine.editor.checkCapabilities();
                if (
                  engine.editor.getCapabilityState('av1Encode') !== 'supported'
                ) {
                  throw new Error('This browser cannot encode AV1');
                }
                const blob = await engine.block.exportVideo(page, {
                  mimeType: 'video/webm',
                  videoCodec: VideoCodec.AV1,
                  targetWidth: 1280,
                  targetHeight: 720,
                  framerate: 30,
                  videoBitrate: 4_000_000,
                  onProgress
                });
                return blob;
              })
          },
          {
            id: 'ly.img.action.navigationBar',
            key: 'export-audio-webm',
            label: 'Export Audio',
            icon: '@imgly/Save',
            onClick: async () => {
              const audioBlob = await engine.block.exportAudio(page, {
                mimeType: 'audio/webm'
              });
              // downloadFile has no 'audio/webm' type, and 'video/webm' gives the same .webm file.
              await cesdk.utils.downloadFile(audioBlob, 'video/webm');
            }
          }
        ]
      }
    );
  }
}

export default Example;

This guide covers how to export a page to WebM, check that the browser can encode it, choose the codecs, and export the audio alone.

Export to WebM#

Call engine.block.exportVideo() with a page block and set mimeType to 'video/webm'. The method returns a Blob with the encoded WebM file.

const blob = await engine.block.exportVideo(page, {
  mimeType: 'video/webm',
  onProgress
});

Without other options, the export encodes VP9 video and Opus audio. Every other video option, such as targetWidth, framerate, videoBitrate, timeOffset and duration, works the same as for an MP4 export.

Check That the Browser Can Encode WebM#

The browser does the encoding, so what it supports decides what you can export. CE.SDK does not fall back to MP4 or to another codec. When the browser has no encoder for the codec, the export fails with an error.

Call engine.editor.checkCapabilities() once, then read the state of each codec with engine.editor.getCapabilityState(). The state is 'supported' or 'unsupported' after the check.

await engine.editor.checkCapabilities();
const canEncodeWebM =
  engine.editor.getCapabilityState('vp9Encode') ===
    'supported' &&
  engine.editor.getCapabilityState('opusEncode') ===
    'supported';
if (!canEncodeWebM) {
  throw new Error('This browser cannot encode VP9 and Opus');
}

Capability	Codec
`vp8Encode`	VP8
`vp9Encode`	VP9, the default video codec of a WebM export
`av1Encode`	AV1
`opusEncode`	Opus, the default audio codec of a WebM export

No browser encodes Vorbis, so a WebM export on the web uses Opus audio.

Choose the Codecs#

Set videoCodec and audioCodec to choose the codecs. Import the VideoCodec and AudioCodec values from @cesdk/engine.

import { AudioCodec, VideoCodec } from '@cesdk/engine';

VP8 is the oldest of the three video codecs, and almost every player decodes it.

const blob = await engine.block.exportVideo(page, {
  mimeType: 'video/webm',
  videoCodec: VideoCodec.VP8,
  audioCodec: AudioCodec.Opus,
  onProgress
});

AV1 makes the smallest file at the same quality, but it takes the longest to encode. Check av1Encode before you offer it.

await engine.editor.checkCapabilities();
if (
  engine.editor.getCapabilityState('av1Encode') !== 'supported'
) {
  throw new Error('This browser cannot encode AV1');
}
const blob = await engine.block.exportVideo(page, {
  mimeType: 'video/webm',
  videoCodec: VideoCodec.AV1,
  targetWidth: 1280,
  targetHeight: 720,
  framerate: 30,
  videoBitrate: 4_000_000,
  onProgress
});

A WebM file holds VP8, VP9 or AV1 video and Opus or Vorbis audio. When you ask for a codec that WebM cannot hold, such as H.264 or AAC, the export fails with an error. It does not change the codec for you.

Export the Audio Only#

Call engine.block.exportAudio() with mimeType set to 'audio/webm' to get the sound of a block as a WebM file with Opus audio.

const audioBlob = await engine.block.exportAudio(page, {
  mimeType: 'audio/webm'
});

Built-in Export Action#

The built-in exportDesign action takes the same options. Pass mimeType: 'video/webm' to export the current page as WebM with a progress dialog and a download prompt.

cesdk.actions.run('exportDesign', { mimeType: 'video/webm' });

WebM Export Options#

Option	Description
`mimeType`	`'video/webm'` for a WebM file.
`videoCodec`	`VideoCodec.Auto` (default), `VP8`, `VP9` or `AV1`. `Auto` picks VP9 for WebM.
`audioCodec`	`AudioCodec.Auto` (default) or `Opus`. `Auto` picks Opus for WebM.
`exportAlpha`	Not available in the browser. The export fails when it is `true`.
`onProgress`	Callback that receives `(renderedFrames, encodedFrames, totalFrames)`.

The other options are the same as for an MP4 export. The MP4 guide lists them.

Troubleshooting#

The export fails in one browser but works in another. The browser has no encoder for the codec. Check the capability state first, and offer an MP4 export when vp9Encode is 'unsupported'.
The export fails with ENCODE.VIDEO_CODEC_CONTAINER_MISMATCH or ENCODE.AUDIO_CODEC_CONTAINER_MISMATCH. The codec does not fit the file type. Use VP8, VP9 or AV1 and Opus for WebM, or leave the codecs at Auto.
The export fails with ENCODE.VIDEO_ALPHA_UNSUPPORTED. The browser cannot keep transparency in a WebM file. Remove exportAlpha, or export with transparency on Android, iOS, macOS or with @cesdk/node-native.

API Reference#

Method	Description
`engine.block.exportVideo(blockId, options)`	Export a page block as a WebM video
`engine.block.exportAudio(blockId, options)`	Export the sound of a block as a WebM audio file
`engine.editor.checkCapabilities()`	Measure which codecs the browser encodes
`engine.editor.getCapabilityState(capability)`	Read the state of one codec after the check
`cesdk.actions.run('exportDesign', options)`	Run the built-in export action with a progress dialog

Next Steps#

Export to MP4 - Export with H.264 or HEVC, and see every video export option
Export Overview - Compare all supported export formats
Export Audio - Export audio tracks separately
Partial Export - Export specific blocks or timeline segments