HTML compositions
Import timed HTML pages as projects, and export projects back to HTML.
Coming in the next release
@miraiclip/html-composition is built and tested, and ships in the next SDK release.
An HTML composition is a plain HTML page whose elements carry their own timing in data- attributes. @miraiclip/html-composition turns one into a Miraiclip document you can edit, undo and export, and turns a document back into one.
import { createProject } from "@miraiclip/core";
import { exportHtmlComposition, importHtmlComposition } from "@miraiclip/html-composition";
const { doc, warnings } = importHtmlComposition(html);
const project = createProject(doc);
const { html: back } = exportHtmlComposition(project.getState().doc);Both functions return warnings that list anything that didn't carry over. Nothing fails silently.
The format
<div data-composition-id="launch" data-width="1920" data-height="1080" data-duration="8"
style="background:#0b1020">
<style>.title { font: 800 120px sans-serif; color: #fff }</style>
<video id="demo" src="media/demo.mp4" data-start="0" data-duration="6" data-track-index="0" muted></video>
<audio src="media/music.mp3" data-start="0" data-duration="8" data-volume="0.6"></audio>
<h1 id="title" class="title" data-start="demo - 1" data-duration="3" data-track-index="1">Ship faster</h1>
</div>| Attribute | On | Meaning |
|---|---|---|
data-composition-id | root | Marks the root. Becomes the project name |
data-width, data-height | root | Canvas size (default 1920 × 1080) |
data-fps | root | Frame rate (default 30) |
data-duration | root | Composition length in seconds |
data-start | timed element | Seconds, or <id>, <id> + 2, <id> - 0.5: relative to the end of the element with that id |
data-duration | timed element | Length in seconds |
data-track-index | timed element | Layer. 0 is the bottom |
data-media-start | <video>, <audio> | Where in the file to start (the trim) |
data-volume | <video>, <audio> | Volume |
Import
| Element | Becomes |
|---|---|
<video> | A video asset and clip. muted sets volume to 0 |
<audio> | An audio asset and clip on an audio track |
<img> without styling | An image clip |
Anything else, including styled <img> | An HTML clip with the element's markup and the page's <style>, rendered at the composition size, so the CSS layout carries over |
| The root's own background and untimed children | One HTML clip on a background track below everything |
- Only the outermost timed element counts. A timed element inside another belongs to its parent's markup.
- CSS
@keyframescarry over: those clips are markedanimated. - Scripts don't run on import. GSAP, anime.js and Lottie timelines are reported in
warnings. To animate with scripts after import, use scripted templates. - An element without a length gets the rest of the composition, or 5 seconds with a warning.
- A
<video>'s own CSS layout isn't kept: it is fitted to the frame, with a warning. - Nested compositions (
data-composition-src) aren't imported. Import each one separately.
| Option | Default | Meaning |
|---|---|---|
fps | data-fps, else 30 | Frame rate of the new document |
resolveSrc(src) | unchanged | Rewrite media src values, for example to absolute URLs |
mediaDurationsUs | none | Known media lengths in µs, keyed by src, for elements without data-duration |
Export
exportHtmlComposition(doc, options?) writes the same format back. Video, audio and image clips become <video>, <audio> and <img>; HTML clips become their markup with params filled in; text clips become styled <div>s. Track order becomes data-track-index and z-index.
| Not exported | Warning |
|---|---|
| Keyframes, effects and playback speed | Per clip |
| Transitions | Exported as hard cuts |
| Caption clips and custom clip kinds | Left out |
| Hidden tracks | Their clips are left out |
| Option | Default | Meaning |
|---|---|---|
compositionId | the project name, else "main" | data-composition-id of the root |
assetUrl(asset) | the asset's src | The URL the page should load for an asset |