On this page

Beta

The Cavalry Web Player and API is currently in beta and so subject to change.

## Intro

The **Cavalry Web Player** is a WebAssembly-based runtime for rendering and playing Cavalry animations (`.cv` files) in web browsers.

Create bespoke, fully customisable animations that can be viewed and exported from modern web browsers. With native support for Cavalry’s extensive features, designers and animators can now work unshackled by the limits of formats like Lottie meaning non-technical teams can create and deliver design systems to their clients in a light-weight, easy to use format.

The [Web Player API](/content/docs/web-player/api/index.html) can be used to update Layer attributes from a Scene embedded in the Web Player.

Algo case study

Check out this fantastic [project](https://algo.tv/cavalry) by the amazing team at [Algo](https://algo.tv/) in collaboration with various artists on [scenery.io](https://scenery.io/) using the **Web Player** to get a flavour of the kinds of things that are possible.

The example below is a custom integration that uses the Web Player and the API to load a `.cv` file along with a custom UI which can be used to update the Scene based on Attributes added to the [Control Centre](/content/docs/user-interface/menus/window-menu/control-centre/index.html).

## Quick Start

[Download the Cavalry Web Player↓ Download](https://beta-player.scenegroup.co/cavalry-web-player.zip)

1. Download the Cavalry Web Player package.
2. Unzip.
3. Start the included server:

```bash
# macOS

cd /path/to/cavalry-web-player

# Windows

cd \path\to\cavalry-web-player

python3 serve.py
```

This will open a browser window and load [localhost:8000](http://localhost:8000/). Try the 'Minimal Player' example, load a `.cv` scene file and use the playback controls.

## Integration

### Integration Example

```javascript
// Import the Cavalry module

const wasm = await import("/CavalryWasm.js");

// Initialise the module

const Module = await wasm.default({

locateFile: (path) => `/wasm-lib/${path}`

});

// Load a scene file

Module.FS.writeFile("scene.cv", sceneData);

const player = Module.Cavalry.MakeWithPath("scene.cv");

// Set up rendering surface

const canvas = document.getElementById("canvas");

const surface = Module.makeWebGLSurfaceFromElement(canvas, 800, 600);

// Render current frame

player.render(surface);

// Start playback

player.play();

// Animation loop using requestAnimationFrame (for display sync and power efficient playback)

let animationFrameId = null;
function runPlaybackLoop() {

const tick = (timestamp) => {

if (!player.isPlaying()) {

return;

}

// tick() advances the frame based on elapsed time and renders

const status = player.tick(surface, timestamp);

// Optionally update UI when a frame changes

if (status.frameChanged) {

console.log(`Frame: ${status.currentFrame}`);

}

animationFrameId = requestAnimationFrame(tick);

};

animationFrameId = requestAnimationFrame(tick);
}

runPlaybackLoop();

// To stop playback:

// player.stop();
// cancelAnimationFrame(animationFrameId);
```

### Server Requirements

For production deployment, ensure the server:

1. Sets proper MIME types:
   - `Content-Type: application/wasm` for `.wasm` files
   - `Content-Type: application/javascript` for `.js` files
2. Serves over HTTPS.

### File Size Optimisation

The Cavalry Web Player files are relatively large due to the comprehensive feature set. We intend to work on reducing the size in the future, however for now, if file size is an issue, try to:

- **Pre-compress** the `.wasm` file with gzip.
- **Set** `Content-Encoding: gzip` header.
- **Use a CDN** for better distribution.
- Most servers automatically compress these files.

### Browser Compatibility

**Requirements:**

- WebAssembly support
- WebGL 2.0
- Modern JavaScript (ES6 modules)

### Multiple Players

Multiple Cavalry Web Players can be used on the same page, simply add more than one player instance to the page. The [demos](/content/docs/web-player/demos/index.html) contain lots of examples of making player modules.

### Shadow Dom

The Web Player supports usage inside the Shadow DOM, where the canvas element is hidden from the public DOM. This can be configured via `shadowHost` and Shadow DOM settings in the HTML. See [demos](/content/docs/web-player/demos/index.html).

### Video Assets

Video Playback

The Web Player supports video assets, but it's not considered a video player. It's recommended to use the [video element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video) for straight up video playback.

A video example is included which demonstrates playing back video with the Web Player. Please see the `webcodec-helper.js` file as a starting point if further features are required. See [demos](/content/docs/web-player/demos/index.html).

## Notes

Scene files (.cv) should be saved to a minimum of file version `1.0.55` which is supported from Cavalry 2.5.0.

Unsupported features:

- Audio (audio support is in progress)

Unsupported Layers:

- [Image Smart Folder](/content/docs/user-interface/menus/window-menu/assets-window/image-smart-folder/index.html)
- [Audio Smart Folder](/content/docs/user-interface/menus/window-menu/assets-window/audio-smart-folder/index.html)
- [JavaScript Layers](/content/docs/nodes/general/javascript-layers/index.html)
- [Jsmath](/content/docs/nodes/utilities/js-math/index.html)

## FAQs

### Are all of the Cavalry features supported?

99% of features are supported. Those that are still being worked on can be seen in the **Notes** section.

### Is it possible to add interaction for animations?

Yes, in part. Attributes can be adjusted in real-time via a UI or cursor position. See the [demo page](https://beta-player.scenegroup.co/) for examples. Note that the Web Player does not incorporate any sort of state machine.

### What is the file size of the Web Player runtime?

The payload is currently ~3MB when compressed (see **File Size Optimisation**). This relatively large file size is due to the focus on comprehensive feature support but keep in mind this file will be cached by browsers and so pre-loaded on subsequent visits to a web page. We intend to work on decreasing the size of the player later for future betas.