asciinema player

asciinema player is a web player for terminal session recordings and live streams.

Unlike typical web video players, which play heavyweight video files (.mp4, .mov), asciinema player plays lightweight terminal session recordings in the text-based asciicast format (.cast), such as those produced by the asciinema recorder.

The player is built from the ground up with JavaScript and Rust (WASM), and is available as npm package and a standalone JS bundle.

You can use it on any HTML page - in a project documentation, on a blog, or in a conference talk presentation.

It's as easy as adding a single line of Javascript code to your web page:

AsciinemaPlayer.create('demo.cast', document.getElementById('demo'));

Check out the quick start guide for basic setup overview.

You can see the player in action in asciinema documentation.

Notable features:

• ability to copy-paste terminal content - it's just text after all!
• smooth, timing-accurate playback,
• reproduction of terminal size changes recorded during the session,
• live terminal streaming with adaptive buffering and automatic reconnection,
• audio playback, synchronized with recordings, with live audio support for streams,
• idle time optimization to skip periods of inactivity,
• posters,
• markers for navigation or auto-pause,
• configurable font families and line height,
• automatic terminal scaling to fit into container element in most efficient way,
• full-screen mode,
• keystroke overlay showing keys typed during the recording,
• built-in and custom color themes, automatic use of recorded terminal colors, and support for 256 colors and 24-bit true color (ISO-8613-3),
• adjustable playback speed,
• frame-by-frame stepping, backward and forward,
• looped playback, infinite or finite,
• starting playback at specific time,
• API for programmatic control,
• keyboard shortcuts,
• support for other recording formats like ttyrec, typescript.

Building

To build the player, first download the source code:

git clone https://github.com/asciinema/asciinema-player
cd asciinema-player

The recommended way to get the toolchain is the Nix dev shell, which provides Node.js, Rust and the wasm32-unknown-unknown target, and just works:

nix develop

If you don't use Nix, you need Node.js with npm, and the Rust toolchain (1.86 or later) with the wasm32-unknown-unknown target (added with rustup target add wasm32-unknown-unknown).

Then build the player with:

npm install
npm run build

This produces following output files:

• dist/index.js - monolithic ES module, to be import-ed in your JS bundle
• dist/bundle/asciinema-player.js - standalone monolithic player script (IIFE), to be linked directly from a website
• dist/bundle/asciinema-player.min.js - minimized version of the above
• dist/bundle/asciinema-player.css - stylesheet, to be linked directly from a website or included in a CSS bundle

The monolithic version of the player covers majority of use cases, and it's all you need to use the player.

In addition, the split version of the player is built with npm run build, producing the following files:

• dist/ui.js - UI ES module, to be import-ed in your JS bundle
• dist/bundle/asciinema-player-ui.js - standalone UI script (IIFE), to be linked directly from a website
• dist/bundle/asciinema-player-ui.min.js - minimized version of the above
• dist/bundle/asciinema-player-worker.js - standalone web worker script (IIFE), to be linked directly from a website
• dist/bundle/asciinema-player-worker.min.js - minimized version of the above

The split version runs the UI and data crunching (parsing, terminal emulation) in separate OS threads, which improves UI's responsiveness during playback. In this setup the UI code runs in the window context, while the processing code runs in a WebWorker. The benefit of this configuration is typically observed only for high frame-rate / high bandwidth recordings. For typical demos/sessions it's not worth the setup hassle.

Development

For toolchain setup and build instructions, see Building. Running the test suite additionally requires Playwright browsers, which the Nix dev shell provides.

Common tasks are defined in the justfile: just build, just test, just format.

If you'd like to propose or submit any changes, please read the contribution guidelines first.

Donations

Sustainability of asciinema development relies on donations and sponsorships.

Please help the software project you use and love. Become a supporter or a corporate sponsor.

asciinema is sponsored by:

• Brightbox

Consulting

If you're interested in integration or customization of asciinema player to suit your needs, check asciinema consulting services.

License

© 2011 Marcin Kulik.

All code is licensed under the Apache License, Version 2.0. See LICENSE file for details.