Search Docs
Loading...
Skip to content

Video Captions for SvelteKit

Enhance video creation by importing, customizing, and styling captions directly within the editor.

Design Editor starter kit showing a professional design editing interface

10 mins
estimated time
Download
StackBlitz
GitHub

Prerequisites#

Before you begin, make sure you have the following:

  • Node.js v20+ and npm installed locally – Download Node.js
  • A supported browser – Chrome 114+, Edge 114+, Firefox 115+, Safari 15.6+
    See Browser Support for the full list.
New Project
Existing Project

Get Started#

Start fresh with a standalone Video Captions project. This creates a complete, ready-to-run application.

Step 1: Clone the Repository#

Terminal
git clone https://github.com/imgly/starterkit-video-captions-react-web.git
git clone https://github.com/imgly/starterkit-video-captions-react-web.git

The src/ folder contains the editor code:

src/
├── app/                          # Demo application
├── imgly/
│   ├── config/
│   │   ├── actions.ts                # Export/import actions
│   │   ├── features.ts               # Feature toggles
│   │   ├── i18n.ts                   # Translations
│   │   ├── plugin.ts                 # Main configuration plugin
│   │   ├── settings.ts               # Engine settings
│   │   └── ui/
│   │       ├── canvas.ts                 # Canvas configuration
│   │       ├── components.ts             # Custom component registration
│   │       ├── dock.ts                   # Dock layout configuration
│   │       ├── index.ts                  # Combines UI customization exports
│   │       ├── inspectorBar.ts           # Inspector bar layout
│   │       ├── navigationBar.ts          # Navigation bar layout
│   │       └── panel.ts                  # Panel configuration
│   ├── index.ts                  # Editor initialization function
│   └── plugins/
│       └── auto-caption.ts
└── index.tsx                 # Application entry point

Step 2: Install Dependencies#

Install the required packages:

Terminal
cd starterkit-video-captions-react-web
npm install
cd starterkit-video-captions-react-web
npm install

Step 3: Download Assets#

CE.SDK requires engine assets (fonts, icons, UI elements) to function. These must be served as static files from your project’s public/ directory.

Terminal
curl -O https://cdn.img.ly/packages/imgly/cesdk-js/1.73.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip
curl -O https://cdn.img.ly/packages/imgly/cesdk-js/1.73.0/imgly-assets.zip
unzip imgly-assets.zip -d public/
rm imgly-assets.zip
src/index.tsx
const config = {
  // ...
  baseURL: '/assets'
  // ...
};

Step 4: Run the Development Server#

Terminal
npm run dev
npm run dev

Open http://localhost:5173 in your browser.

Caption Modes#

The Video Captions starter kit supports four distinct workflows for working with video captions:

Autocaption Mode#

Auto-generate captions using AI-powered speech-to-text transcription with ElevenLabs Scribe V2:

src/index.ts
await initVideoCaptionsAutocaptionEditor(cesdk);

This mode:

  • Loads a video with audio ready for transcription
  • Integrates the @imgly/plugin-autocaption-web plugin
  • Configures the ElevenLabs Scribe V2 provider via fal.ai proxy
  • Automatically transcribes speech and generates styled captions
  • Opens the caption inspector panel for editing

Prerequisites:

  • fal.ai API key configured in VITE_AUTOCAPTION_PROXY_URL environment variable
  • Default proxy: https://proxy.img.ly/api/proxy/falai

Blank Mode#

Start with an empty video canvas for manual caption creation:

src/index.ts
await initVideoCaptionsBlankEditor(cesdk);

This mode:

  • Creates a new blank video scene (1280x720)
  • Lets you import your own videos
  • Manually create and style captions from scratch
  • No AI processing required

Import Mode#

Import existing SRT subtitle files and edit them:

src/index.ts
await initVideoCaptionsImportEditor(cesdk);

This mode:

  • Loads a video for caption placement
  • Allows importing SRT files with existing captions
  • Edit timing, styling, and positioning
  • Export back to video with embedded captions

Pre-captioned Mode#

Edit videos that already have embedded captions:

src/index.ts
await initVideoCaptionsPreCaptionedEditor(cesdk);

This mode:

  • Loads a video with captions already embedded
  • Automatically selects the first caption for editing
  • Full access to caption styling and timing controls
  • Refine existing captions without re-transcribing

Autocaption Setup#

To enable AI-powered caption generation, configure the fal.ai proxy URL:

src/lib/imgly/index.ts
import AutocaptionPlugin from '@imgly/plugin-autocaption-web';
import { ElevenLabsScribeV2 } from '@imgly/plugin-autocaption-web/fal-ai';


// Configure the proxy URL (default: https://proxy.img.ly/api/proxy/falai)
const AUTOCAPTION_PROXY_URL = import.meta.env.VITE_AUTOCAPTION_PROXY_URL ||
  'https://proxy.img.ly/api/proxy/falai';


// Add the autocaption plugin with ElevenLabs Scribe V2 provider
await cesdk.addPlugin(
  AutocaptionPlugin({
    provider: ElevenLabsScribeV2({
      proxyUrl: AUTOCAPTION_PROXY_URL
    })
  })
);

The proxy URL should point to a server that forwards requests to fal.ai with your API key. For production use, deploy your own proxy to keep the API key secure.

Caption Inspector Panel#

The caption inspector panel provides comprehensive controls for editing captions:

// Open the caption inspector panel programmatically
cesdk.ui.openPanel('//ly.img.panel/inspector/caption');

The panel includes:

  • Caption text editor - Edit caption content with live preview
  • Timing controls - Adjust start time and duration
  • Styling options - Font, size, color, background, alignment
  • Positioning - Move captions anywhere on the video
  • Caption presets - Apply pre-designed caption styles

The panel automatically opens when using autocaption mode, but you can open it manually in any mode using the code above.

Set Up a Scene#

Each caption mode has a dedicated init function that handles scene setup automatically.

For custom workflows beyond the predefined modes, you can load content manually:

src/index.ts
// After initialization, load your own video
await cesdk.createFromVideo('https://example.com/video.mp4');


// Or load from a template archive with captions
await cesdk.loadFromArchiveURL('https://example.com/template.zip');


// Or load from a scene file
await cesdk.loadFromURL('https://example.com/scene.json');

The predefined init functions load appropriate scenes:

  • autocaption - Loads a video ready for AI transcription
  • blank - Creates an empty 1280x720 video scene
  • import - Loads a video for SRT import
  • pre-captioned - Loads a video with embedded captions

Customize Assets#

The Video Captions uses asset source plugins to provide built-in libraries for video clips, audio, effects, stickers, and fonts. The starter kit includes a curated selection—customize what’s included based on your needs.

Asset sources are added via plugins in src/index.ts. Enable or disable individual sources:

src/index.ts
import {
  FiltersAssetSource,
  StickerAssetSource,
  TextAssetSource,
  VectorShapeAssetSource,
  EffectsAssetSource,
  // ...
} from '@cesdk/cesdk-js/plugins';


// Add only the sources you need
await cesdk.addPlugin(new FiltersAssetSource());
await cesdk.addPlugin(new StickerAssetSource());
await cesdk.addPlugin(new TextAssetSource());
await cesdk.addPlugin(new VectorShapeAssetSource());
await cesdk.addPlugin(new EffectsAssetSource());
// ...

For production deployments, self-hosting assets is required—the IMG.LY CDN is intended for development only. See Serve Assets for downloading assets, configuring baseURL, and excluding unused sources to optimize load times.

Configure Actions#

Actions are functions that handle user interactions like exporting videos, saving scenes, and importing files. CE.SDK provides built-in actions that you can run directly or override with custom implementations.

Key built-in actions:

  • exportDesign – Export the current video to MP4 format
  • saveScene – Save the scene as a JSON string for later editing
  • importScene – Import a previously saved scene (supports .scene and .cesdk formats)
  • exportScene – Export the scene as a JSON file or .cesdk archive with all assets
  • uploadFile – Handle file uploads with progress tracking

Use cesdk.actions.run() to execute any action:

// Run a built-in action
await cesdk.actions.run('exportDesign', { mimeType: 'video/mp4' });

Import from File Picker#

src/lib/imgly/config/actions.ts
// Let users open videos from their device
cesdk.actions.register('importVideo', async () => {
  const blobURL = await cesdk.utils.loadFile({
    accept: 'video/*',
    returnType: 'objectURL'
  });
  await cesdk.createFromVideo(blobURL);
});

Export and Save#

src/lib/imgly/config/actions.ts
// Register export action that downloads the edited video
cesdk.actions.register('exportDesign', async (exportOptions) => {
  const { blobs, options } = await cesdk.utils.export(exportOptions);
  await cesdk.utils.downloadFile(blobs[0], options.mimeType);
});

Upload to Your Backend#

src/lib/imgly/config/actions.ts
// Override the built-in exportDesign action to send to your server
cesdk.actions.register('exportDesign', async (exportOptions) => {
  const { blobs } = await cesdk.utils.export(exportOptions);


  const formData = new FormData();
  formData.append('video', blobs[0], 'edited-video.mp4');


  const response = await fetch('/api/upload', {
    method: 'POST',
    body: formData
  });


  const { url } = await response.json();
  console.log('Uploaded to:', url);
});

Customize (Optional)#

Theming#

CE.SDK supports light and dark themes out of the box, plus automatic system preference detection. Switch between themes programmatically:

src/lib/imgly/config/settings.ts
// 'light' | 'dark' | 'system' | (() => 'light' | 'dark')
cesdk.ui.setTheme('dark');

See Theming for custom color schemes, CSS variables, and advanced styling options.

Localization#

Customize UI labels and add support for multiple languages. The i18n system supports translation keys for all UI elements:

src/lib/imgly/config/i18n.ts
// Override specific labels
cesdk.i18n.setTranslations({
  en: {
    'actions.export.video': 'Download Video',
    'common.cancel': 'Cancel',
    'common.apply': 'Apply'
  }
});


// Add a new language
cesdk.i18n.setTranslations({
  de: {
    'actions.export.video': 'Video herunterladen'
  }
});


// Set the active locale
cesdk.i18n.setLocale('de');

See Localization for supported languages, translation key reference, and right-to-left language support.

UI Layout#

CE.SDK Editor UI Areas

Customize the editor interface by modifying the dock, inspector bar, navigation bar, and canvas menu. CE.SDK provides Order APIs to control which components appear and in what sequence.

src/lib/imgly/config/ui/navigationBar.ts
// Get current navigation bar components
const navOrder = cesdk.ui.getNavigationBarOrder();


// Add a custom button to the navigation bar
cesdk.ui.insertNavigationBarOrderComponent(
  'ly.img.spacer',
  { id: 'my-custom-action' },
  'after'
);


// Rearrange dock items
cesdk.ui.setDockOrder([
  'ly.img.assetLibrary.dock',
  'ly.img.separator',
  'my-custom-dock-item'
]);


// Customize the inspector bar
cesdk.ui.setInspectorBarOrder([
  'ly.img.fill.inspectorBar',
  'ly.img.separator',
  'ly.img.filter.inspectorBar'
]);

The Order API methods follow a consistent pattern across all UI areas:

  • get*Order() – Retrieve the current component order
  • set*Order() – Replace the entire order
  • insert*OrderComponent() – Add components relative to existing ones

See Dock, Inspector Bar, Navigation Bar, Canvas Menu, and Canvas for detailed layout customization options.

Custom Components#

Build custom UI components using the builder system and integrate them in the editor. Custom components receive reactive state updates and can interact with the engine API.

src/lib/imgly/config/ui/components.ts
// Register a custom component
cesdk.ui.registerComponent('my-custom-button', ({ builder, engine }) => {
  const selectedBlocks = engine.block.findAllSelected();


  builder.Button('apply-effect', {
    label: 'Apply Effect',
    isDisabled: selectedBlocks.length === 0,
    onClick: () => {
      // Apply custom logic to selected blocks
    }
  });
});


// Add the component to the navigation bar
cesdk.ui.insertNavigationBarOrderComponent(
  'ly.img.spacer',
  'my-custom-button',
  'after'
);

Custom components automatically re-render when the engine state they depend on changes—no manual subscription management required.

See Register New Component for the complete builder API and component patterns.

Settings & Features#

Fine-tune editor behavior through settings and features.

Settings configure core engine behavior—rendering, input handling, and history management:

src/lib/imgly/config/settings.ts
cesdk.engine.editor.setSettingBool('page/dimOutOfPageAreas', true);
cesdk.engine.editor.setSettingBool('mouse/enableZoomControl', true);
cesdk.engine.editor.setSettingBool('features/undoHistory', true);

Features toggle which editing tools and panels appear in the UI:

src/lib/imgly/config/features.ts
// Toggle editor features
cesdk.feature.enable('ly.img.trim', true);
cesdk.feature.enable('ly.img.filter', true);
cesdk.feature.enable('ly.img.adjustment', true);

See Settings and Features for the complete reference.

Explore Plugins#

CE.SDK has a rich plugin ecosystem that extends the editor with powerful capabilities. Plugins can add new features, integrate third-party services, or customize editor behavior.

AI Integration#

Extend the editor with generative AI capabilities for text-to-image generation, image enhancement, and intelligent editing features. CE.SDK integrates with various AI providers.

src/lib/imgly/config/plugin.ts
import AIPlugin from '@imgly/plugin-ai-generation';


// Configure AI generation
await cesdk.addPlugin(AIPlugin({
  provider: 'your-ai-provider',
  apiKey: 'your-api-key'
}));

See AI Integration for provider setup and supported AI features.

Custom Asset Sources#

Connect external asset libraries like Unsplash, Getty Images, or your own content management system. Asset sources let users browse and insert content from any source.

src/lib/imgly/config/plugin.ts
import UnsplashAssetSource from '@imgly/plugin-unsplash';


// Add Unsplash integration
await cesdk.addPlugin(UnsplashAssetSource({
  accessKey: 'your-unsplash-access-key'
}));

See Custom Asset Sources for integration patterns.

Discover More Plugins#

Explore the full plugin ecosystem in the IMG.LY plugins repository. Available plugins include:

  • Vectorizer – Convert raster images to vectors
  • Design Presets – Pre-built design templates
  • Social Media Templates – Platform-specific sizing
  • And more – Check the repository for the latest additions

Key Capabilities#

The Video Captions starter kit includes everything needed for professional video captioning.

AI Caption Generation

AI Caption Generation

Auto-generate accurate captions using ElevenLabs Scribe V2 speech-to-text technology.

Caption Styling

Caption Styling

Customize fonts, colors, backgrounds, alignment, and positioning with professional presets.

SRT Import/Export

SRT Import/Export

Import existing SRT subtitle files and export captions in standard subtitle formats.

Timeline Control

Timeline Control

Precise timing controls for caption start time and duration with visual timeline feedback.

Caption Inspector

Caption Inspector

Dedicated inspector panel for editing caption text, timing, styling, and positioning.

Video Export

Video Export

Export videos with embedded captions to MP4 format with customizable quality settings.


Troubleshooting#

Editor doesn’t load#

  • Check the container element exists: Ensure your container element is in the DOM before calling create()
  • Verify the baseURL: Assets must be accessible from the CDN or your self-hosted location
  • Check console errors: Look for CORS or network errors in browser developer tools

Autocaption doesn’t work#

  • Check fal.ai API key: Verify your API key is configured correctly in the proxy URL
  • Verify proxy URL: Ensure VITE_AUTOCAPTION_PROXY_URL points to a working proxy server
  • Check network requests: Look for failed requests to the fal.ai API in DevTools Network tab
  • Video has no audio: The autocaption feature requires audio to transcribe

Caption Inspector doesn’t open#

  • Check video captions feature: Ensure features/videoCaptionsEnabled is set to true in settings
  • Verify caption mode: The inspector opens automatically in autocaption mode
  • Open manually: Use cesdk.ui.openPanel('//ly.img.panel/inspector/caption') to open it programmatically

SRT import fails#

  • Check file format: Ensure the SRT file follows standard subtitle formatting
  • Verify encoding: SRT files should use UTF-8 encoding
  • Check timestamps: Timestamps must be in the format HH:MM:SS,mmm --> HH:MM:SS,mmm

Captions don’t appear in export#

  • Wait for caption rendering: Ensure captions are visible in the editor before exporting
  • Check caption timing: Verify caption start times and durations are correct
  • Export as MP4: Captions are embedded in the video during MP4 export

Video export takes too long#

  • Reduce resolution: Lower output resolution significantly improves encoding speed
  • Shorten clip length: Longer videos take proportionally longer to encode
  • Check system resources: Video encoding is CPU-intensive; close other applications

Watermark appears in production#

  • Add your license key: Set the license property in your configuration
  • Sign up for a trial: Get a free trial license at img.ly/forms/free-trial

Next Steps#

  • Configuration – Complete list of initialization options
  • Serve Assets – Self-host engine assets for production
  • Actions – Build custom export and save workflows
  • Theming – Customize colors and appearance
  • Localization – Add translations and language support