asciinema-player: Playing .cast Terminal Recordings on the Web

What asciinema-player solves that a video tag does not

A screen recording of a terminal is mostly text, but an MP4 of it is not. asciinema-player exists because the recording format and the playback format can both be text. It plays asciicast files, the `.cast` format produced by the asciinema recorder, and the README states the player is built from the ground up with JavaScript and Rust compiled to WASM. The visible consequence is that terminal content inside the player can be selected and copied. A video player cannot do that, and a GIF certainly cannot.

The audience is narrow and specific: people who write project documentation, blog posts or conference talk slides and want a terminal session embedded in an HTML page. The README lists those three cases directly. If you are publishing a tutorial where the reader needs to reproduce commands, copy-pasteable output matters more than pixel fidelity, and that is the argument for this tool over a screencast.

It is not a recorder. The README points at the asciinema CLI for producing `.cast` files, and the player only consumes them. That split is worth understanding before you install anything.

How the player processes a .cast file

The build produces two configurations, and the difference is architectural rather than cosmetic. The monolithic build, `dist/index.js`, runs everything in one place. The split build adds `dist/ui.js` plus `dist/bundle/asciinema-player-worker.js`, and the README explains that this runs the UI in the window context while parsing and terminal emulation happen in a WebWorker on a separate OS thread. The stated benefit is UI responsiveness during playback, and the README is unusually candid about when that matters: the gain is typically observed only for high frame-rate or high bandwidth recordings, and for typical demos it is not worth the setup hassle.

That is a real design trade-off stated plainly. The parsing and emulation work is the expensive part, and moving it off the main thread costs you an extra script to load and a worker to configure. The player is a renderer over an event stream with timestamps, which is why idle time optimization exists as an option: periods of inactivity in the recording can be skipped rather than played out in real time.

The Rust component is the terminal emulator, which is what makes 256-color and 24-bit true color output render correctly. The README lists ISO-8613-3 among the supported color capabilities, along with configurable font families and line height.

Installing asciinema-player and embedding a first recording

The README gives the one-line embed as the primary usage example. You need a `.cast` file, a container element and the player script. The standalone bundle is the path for a plain HTML page:

npm install asciinema-player

That installs the npm package. For a page that does not go through a bundler, the release page publishes `dist/bundle/asciinema-player.min.js` and `dist/bundle/asciinema-player.css` as standalone files to link directly. Once the script is loaded, the README's example is a single call:

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

The first argument is the recording URL and the second is the DOM element to mount into. After that call the player should appear in the container and begin according to its default settings. If you are building from source instead of installing, the README's sequence is a clone, then `nix develop` for the toolchain, then `npm install` and `npm run build`. The Nix shell provides Node.js, Rust and the `wasm32-unknown-unknown` target; without Nix you need Rust 1.85 or later and must add that target yourself with `rustup target add wasm32-unknown-unknown`.

The build output is worth knowing before you pick a file. `dist/index.js` is the monolithic ES module for importing into a JS bundle, `dist/bundle/asciinema-player.js` and its `.min.js` counterpart are the standalone scripts, and `dist/bundle/asciinema-player.css` is the stylesheet. The README states the monolithic version covers the majority of use cases.

Where the player is the wrong tool

The format choice is the limitation. A `.cast` file is not a video, so anywhere a video is required, the player does not help. If your publishing target takes an MP4 or a GIF, you need a conversion step outside this project, and the README and repository layout here do not describe one. The player renders in a browser, so it has no role in a pipeline that produces a downloadable media file.

The second constraint is the split build's cost. The README says the separate-thread configuration is typically only worth it for high frame-rate or high bandwidth recordings. That means the responsiveness problem the split build solves is real but narrow, and adopting the worker setup for an ordinary demo adds scripts and configuration for no stated benefit.

The toolchain is another practical boundary. Building from source requires Node.js, npm, and Rust 1.85 or later with the WASM target, or the Nix dev shell. If your environment cannot provide that, you are limited to the published bundles and the npm package, which is fine for embedding but not for modifying the player. The README does not document rollback or downgrade paths between releases, so pinning a version is your own responsibility.

asciinema-player compared with a terminal-to-GIF or terminal-to-video tool

The nearest alternative is not another web player, it is a recorder-to-image pipeline. Tools that convert a terminal session into an animated GIF or a video file solve the opposite problem: they produce a self-contained asset that works in places where you cannot run JavaScript, such as a README on a code host, a slide deck exported to PDF, or a chat message.

The difference in approach is total. A GIF or video is a fixed raster: it plays the same everywhere, it cannot be restyled to match your site's font, and its text cannot be selected. asciinema-player keeps the recording as text and re-renders it live, which is why the README can advertise copy-paste of terminal content, configurable font families, multiple color themes and adjustable playback speed. Those are properties a rendered image simply does not have.

The cost is a JavaScript dependency and a browser. If your audience reads your documentation as a rendered page, the player wins on fidelity and interactivity. If your audience needs a file they can attach or paste anywhere, the image pipeline wins, and asciinema-player is the wrong side of that decision.

Maintenance, releases and what the Apache-2.0 licence means here

The repository is not archived, and the last push was on 2026-09-13, which is recent. Releases are frequent: v3.17.0 on 2026-06-30, v3.16.0 on 2026-06-19 and v3.15.1 on 2026-02-27. The version in `package.json` is 3.17.0, matching the most recent release, so the published package and the repository are in step. The default branch is `develop`, not `main`, which is worth knowing if you track the source rather than the npm package.

Upgrade cost is mostly the version pin. The package declares `solid-js` as its only runtime dependency, so the surface you inherit is small, and the `exports` map in `package.json` fixes the public entry points: `.`, `./ui.js`, and the bundle files for the player, UI and worker. Those paths are the contract. If you link `dist/bundle/asciinema-player.min.js` directly, a release that changes the bundle layout would affect you, and the `exports` map is the place to check.

Licensing is Apache-2.0, stated in both the README and `package.json`, with copyright attributed to Marcin Kulik. Apache-2.0 includes an explicit patent grant and requires that you preserve notices when redistributing. That is a summary of the licence identifier, not legal advice; read the `LICENSE` file for the terms that apply to you. The README also notes that asciinema development relies on donations and sponsorships, and points to separate consulting services for integration or customization work, which is a signal that commercial support exists outside the repository.

Editorial conclusion

Adopt asciinema-player if you publish terminal walkthroughs on the web and want real, copy-pasteable text rather than a video file. Skip it if you need an MP4 or GIF export, or if your recordings are high frame-rate enough to need the split UI/worker build. Before committing, verify that your .cast files are asciicast v3 and check the index.d.ts type definitions for the options you plan to set, since the README only links out to the options documentation.

Frequently asked questions

Official sources

1. asciinema/asciinema-player on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases