Skip to main content
HomeWeb Player

Getting Started

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 can be used to update Layer attributes from a Scene embedded in the Web Player.

Algo case study

Check out this fantastic project by the amazing team at Algo in collaboration with various artists on 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.

Loading Cavalry Player…
Use the controls to update the animation.

Quick Start​

Download the Cavalry Web Player↓ Download
  1. Download the Cavalry Web Player package.
  2. Unzip.
  3. Start the included server: 
    # 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. Try the 'Minimal Player' example, load a .cv scene file and use the playback controls.

Integration​

Integration Example​

// 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 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.

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 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.

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:

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 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