The html asset is deprecated and has been replaced by the html5 asset. If you are still using html, this guide covers what to change and the two differences that catch people out during migration.
Why migrate
The deprecated html asset renders static markup through a limited renderer. The html5 asset runs your page in a real browser, with a JavaScript runtime and preloaded animation libraries.
1. Change the asset type
Update "type": "html" to "type": "html5".
2. Move width and height to the clip
On the deprecated asset, width and height sat inside the asset object. On html5 they are clip-level properties. Leaving them inside the asset returns an unknown_property validation error.
Before:
{
"asset": {
"type": "html",
"html": "<div class=\"bar\">Hello</div>",
"css": "...",
"width": 560,
"height": 120
},
"start": 0,
"length": 5
}
After:
{
"asset": {
"type": "html5",
"html": "<div class=\"bar\">Hello</div>",
"css": "..."
},
"start": 0,
"length": 5,
"width": 560,
"height": 120
}
3. Inline any custom fonts
Important: This step fails silently. If you skip it, your render will still succeed, but your text will quietly fall back to a default font. For burnt-in captions or overlays, that can ship unnoticed.
Custom fonts that worked on the deprecated asset will stop resolving on html5, for two reasons:
• The timeline.fonts array does not apply to html5 assets. It loads fonts for the rich-text and rich-caption assets only.
• The render sandbox runs under a strict Content-Security-Policy, which blocks remote @font-face URLs.
To keep a custom font, base64-encode it and embed it directly in your CSS as a data: URI. WOFF2 is preferred for size:
@font-face {
font-family: 'Brand';
src: url('data:font/woff2;base64,<encoded font>') format('woff2');
}
.title { font-family: 'Brand', sans-serif; }
Alternatively, use a system family such as system-ui, Arial, or Georgia, which resolves without loading a font file.
If you only need a single styled line of text, the rich-text asset is simpler than embedding a font, and it does use timeline.fonts.
4. Check your sizing CSS
While migrating, it is worth correcting your page sizing to match the documented rules. These matter more on html5, because capture happens at the page's natural size rather than in a viewport.
• Pin html, body to the clip dimensions, with margin: 0; padding: 0; overflow: hidden.
• Use fixed pixel values on the root, not %, vw, or vh.
• Size the clip to your content, not to the whole canvas, then place it with offset.
html, body {
margin: 0;
padding: 0;
width: 560px;
height: 120px;
overflow: hidden;
background: transparent;
}
A common issue is setting height: 100% on your root element without pinning html, body to a fixed height. The percentage then has no determinate height to resolve against, and your content can sit in an unexpected position.
Other things to know
The html5 asset also brings capabilities the legacy asset did not have. GSAP, anime.js, D3, and Lottie are preloaded and available, so you can animate your overlays. Note that the renderer captures frames by seeking to a timestamp rather than playing in real time, so animations must be seekable, avoid setTimeout, setInterval, and Date.now().
The sandbox also blocks remote images and network requests, so embed images as data: URIs and bundle any data as a literal in your js.