Video captions have become an essential part of digital content, improving accessibility and engagement. With CE.SDK’s caption presets feature, you can offer your users a selection of predefined caption styles that they can apply with a single click.
This guide will show you how to add your own custom caption presets by updating the content.json file that CE.SDK uses to discover available presets. This approach allows you to extend the existing caption presets functionality without implementing a custom asset source from scratch.
Understanding the Caption Presets Structure#
CE.SDK’s caption presets are organized in a specific folder structure:
assets/v3/ly.img.captionPresets/├── content.json # Master index of all presets├── presets/ # Folder containing preset files│ ├── my-custom-preset.blocks # Serialized caption block with styling│ └── …└── thumbnails/ # Folder containing preview images ├── my-custom-preset.png # Preview image for preset └── …The main content.json file acts as an index that lists all available presets with their metadata. Instead of individual folders for each preset, all preset files are organized in two main folders:
presets/: Contains all the serialized caption block files (.blocksfiles)thumbnails/: Contains all the preview images for the presets (.pngfiles)
When CE.SDK loads the caption presets, it reads the content.json file to discover all available presets and their locations. This follows the same pattern as other asset sources in CE.SDK, but with this specific folder organization.
Creating Custom Caption Presets#
Before updating the content.json file, you’ll need to create your custom preset styles. The easiest way to create a custom preset is to design it within CE.SDK itself:
- Create a text element in your project. Style and animate it as desired (using a text element as the basis is best since it supports all the styling properties needed for captions)
- Use the engine’s serialization API to export the text block:
// Assuming 'textBlock' is the ID of your styled text elementconst serializedBlock = await engine.block.saveToString([textBlock]);- Save this serialized data as a
.blocksfile (e.g.,my-custom-preset.blocks) - Create a thumbnail image that visually represents your preset style
Important: Using a text element as the basis for your caption preset is highly recommended. Text elements support all the necessary styling properties (colors, fonts, backgrounds, shadows, etc.) and ensure compatibility with the caption system. For more details on text properties, see the text styling documentation.
Adding Customizable Properties#
One of the key advantages of the caption presets system is that it allows users to customize specific properties of a preset. To enable this, you need to define which properties should be customizable in the payload.properties array in the content.json file.
For each customizable color property, you should define:
- The property type (must be “Color”)
- The property path (e.g., “fill/solid/color”, “backgroundColor/color”, “dropShadow/color”)
- The default value (RGBA color object)
- The current value (initially the same as the default)
Example of customizable color properties:
"payload": { "properties": [ { "type": "Color", "property": "fill/solid/color", "value": { "r": 1, "g": 1, "b": 1, "a": 1 }, "defaultValue": { "r": 1, "g": 1, "b": 1, "a": 1 } }, { "type": "Color", "property": "backgroundColor/color", "value": { "r": 0, "g": 0, "b": 0, "a": 0.5 }, "defaultValue": { "r": 0, "g": 0, "b": 0, "a": 0.5 } } ]}This allows users to modify specific color aspects of a preset without changing the entire style.
Updating the Content.json File#
Once you have your custom preset files, follow these steps to update the content.json file:
- Download or create a base
content.jsonfile if you don’t already have one - Open the file in a text editor or JSON editor
- Add new entries to the
assetsarray for each of your custom presets - Save the updated file
Here’s an example of what the content.json file should look like:
{ "version": "3.0.0", "id": "ly.img.captionPresets", "assets": [ { "id": "//ly.img.captionPresets/background", "label": { "en": "Background" }, "meta": { "uri": "{{base_url}}/ly.img.captionPresets/presets/background.preset", "thumbUri": "{{base_url}}/ly.img.captionPresets/thumbnails/background.png", "mimeType": "application/ubq-blocks-string" }, "payload": { "properties": [ { "type": "Color", "property": "fill/solid/color", "value": { "r": 1, "g": 1, "b": 1, "a": 1 }, "defaultValue": { "r": 1, "g": 1, "b": 1, "a": 1 } }, { "type": "Color", "property": "backgroundColor/color", "value": { "r": 0, "g": 0, "b": 0, "a": 0.5 }, "defaultValue": { "r": 0, "g": 0, "b": 0, "a": 0.5 } } ] } }, { "id": "//ly.img.captionPresets/outline", "label": { "en": "Outline" }, "meta": { "uri": "{{base_url}}/ly.img.captionPresets/presets/outline.preset", "thumbUri": "{{base_url}}/ly.img.captionPresets/thumbnails/outline.png", "mimeType": "application/ubq-blocks-string" }, "payload": { "properties": [ { "type": "Color", "property": "fill/solid/color", "value": { "r": 1, "g": 1, "b": 1, "a": 1 }, "defaultValue": { "r": 1, "g": 1, "b": 1, "a": 1 } }, { "type": "Color", "property": "dropShadow/color", "value": { "r": 0, "g": 0, "b": 0, "a": 1 }, "defaultValue": { "r": 0, "g": 0, "b": 0, "a": 1 } } ] } } ]}To add your custom preset, add a new entry to the assets array with these required fields:
{ "id": "//ly.img.captionPresets/my-custom-preset", // A unique identifier with proper namespace "label": { "en": "My Custom Preset" // The name that will appear in the UI }, "meta": { "uri": "{{base_url}}/ly.img.captionPresets/presets/my-custom-preset.preset", "thumbUri": "{{base_url}}/ly.img.captionPresets/thumbnails/my-custom-preset.png", "mimeType": "application/ubq-blocks-string" // Important: Include this mime type }, "payload": { "properties": [ { "type": "Color", "property": "fill/solid/color", "value": { "r": 1, "g": 1, "b": 1, "a": 1 }, "defaultValue": { "r": 1, "g": 1, "b": 1, "a": 1 } }, // Add other properties that can be customized { "type": "Color", "property": "dropShadow/color", "value": { "r": 0, "g": 0, "b": 0, "a": 0.8 }, "defaultValue": { "r": 0, "g": 0, "b": 0, "a": 0.8 } } ] }}Hosting and Serving Custom Presets#
After updating the content.json file, you need to host the files on your server. Follow these steps:
-
Create the proper folder structure on your server that matches the standard caption presets organization:
/assets/v3/ly.img.captionPresets/├── content.json├── presets/│ ├── background.preset│ ├── outline.preset│ ├── my-custom-preset.preset│ └── ...└── thumbnails/├── background.png├── outline.png├── my-custom-preset.png└── ... -
Upload all files to your server, maintaining this exact folder structure:
- Your updated content.json file should go in the root folder
- All .preset files should go in the presets/ folder
- All thumbnail images should go in the thumbnails/ folder
-
Make sure the files are accessible via HTTP/HTTPS and properly configured with CORS headers if needed
-
Test that you can access each file directly via its URL in a browser
For more information on hosting assets, see the asset hosting documentation.
Loading Custom Presets into CE.SDK#
To load your custom caption presets into CE.SDK, you need to tell the engine where to find your updated content.json file. Since CE.SDK already includes a caption presets asset source with the ID “ly.img.captionPresets”, we’ll update this existing source rather than creating a new one.
For that you only have to configure the base URL to the one pointing at the location your assets are being available from:
const config = { baseURL: 'https://yourdomain.com/assets', // Your base assets path};
CreativeEngine.init(config).then(async engine => { // ...});Your custom presets will seamlessly integrate with any built-in presets and automatically appear in the caption presets panel in the UI.
Related Documentation#
- Asset Source Concepts - For understanding how asset sources work in CE.SDK
- Remote Asset Sources - For more details on hosting and serving assets remotely
- Asset Library Customization - For customizing how assets appear in the UI
- Text Styling - For understanding the styling properties available for text elements