Embed an animation in a web page

<oxframe-player> plays an oxframe scene on any website: a blog post, a course, docs, a landing page. The scene itself runs in the browser, compiled to WebAssembly, so there is no video file to host, and every frame is drawn at the size it is shown, sharp on any screen.

Quick start

Open a scene in the playground, press Embed and paste what it copies into your page:

<script type="module" src="https://oxframe.dev/player.js"></script>
<oxframe-player build="a2e41d72bdf182b4502dbf61219fcfc9" controls loop></oxframe-player>

build names one compiled build of the scene on compile.oxframe.dev. A build never changes, so an embed keeps playing exactly what you published, even after the code in the playground moves on. The player is a 5 kB script (gzip) plus the scene's own wasm; nothing loads until the player scrolls near the screen.

Attributes

Attribute	What it does
`build`	The build to play, from the playground's Embed button.
`example`	Plays one of the playground examples by name, such as `intro`, in its newest build.
`js`, `wasm`	A build you host yourself (see below).
`controls`	Shows play/pause, the time bar and the time.
`autoplay`	Starts playing when the player is on screen. Not for visitors who ask their system for reduced motion.
`loop`	Starts again at the end.
`at`	Opens at this time, in seconds (`at="2.5"`).
`compile`	Another compile service, for `build` and `example`. The default is `https://compile.oxframe.dev`.

The player takes the width of its container and the shape of the scene. Set a width or height with CSS as for an image; style the inside with ::part(canvas), ::part(controls) and ::part(message). Clicking the picture or pressing Space on the focused player plays and pauses. A player that scrolls off screen pauses, and goes on when it comes back.

From JavaScript

The element works like a <video> for the basics:

const player = document.querySelector('oxframe-player');
player.addEventListener('ready', () => console.log(player.duration, 's'));
player.addEventListener('ended', () => console.log('done'));
player.currentTime = 2; // seconds
player.play();
player.pause();
player.paused; // true or false

Events: ready (the scene is loaded and duration is known), play, pause, timeupdate, ended, and error with the reason in event.detail.message. Changing build, example, js or wasm loads the new scene.

Hosting the build yourself

The playground builds one file. A project with several files or its own assets can be built to WebAssembly with wasm-bindgen and served from your own site. Add a library target that registers the project:

# Cargo.toml
[lib]
crate-type = ["cdylib"]

[dependencies]
oxframe = { version = "0.23", default-features = false, features = ["wasm", "gpu"] }
wasm-bindgen = "0.2"

// src/lib.rs
use wasm_bindgen::prelude::*;

#[wasm_bindgen(start)]
pub fn start() {
    oxframe::wasm::register(crate::project); // your pub fn project() -> Project
}

cargo build --release --lib --target wasm32-unknown-unknown
wasm-bindgen --target web --out-dir public/scene --out-name bundle --no-typescript \
  target/wasm32-unknown-unknown/release/my_video.wasm

The wasm-bindgen command must be the same version as the wasm-bindgen crate in your Cargo.lock (cargo install wasm-bindgen-cli --version …). Running wasm-opt -Os from Binaryen on the .wasm afterwards makes it several times smaller.

Then point the player at the two files:

<oxframe-player js="/scene/bundle.js" wasm="/scene/bundle_bg.wasm" controls></oxframe-player>

The player runs the scene in a Web Worker, so a slow scene never freezes the page. With WebGPU it draws on the GPU, otherwise on the CPU. A page with a strict Content Security Policy needs 'wasm-unsafe-eval' in script-src, and worker-src blob: when the player comes from another site.

When a video file is better

Where scripts cannot run (email, social networks, a slide deck), render a file with oxframe render (Rendering video), or share a link to a video with oxframe publish.

Edit this page on GitHub