asciinema player

Web player for terminal session recordings ⏩
Under Apache License 2.0
By asciinema

terminal video unix player video-playback tty asciicast

Note: This is README for development branch. See the version for latest stable release.

asciinema player

Web player for terminal session recordings (as produced
by asciinema recorder) that you can
use on your website by simply adding <asciinema-player> tag.


asciinema player is an open-source terminal session player written in
ClojureScript. Contrary to other video players asciinema player doesn't play
heavy-weight video files (.mp4, .webm etc) but instead it plays light-weight
terminal session files called

Asciicast is a capture of terminal's raw output, which has to be interpreted
during the playback, so the player comes with its own interpreter based on Paul
Williams' parser for ANSI-compatible video
terminals. Its output is fully compatible
with most widely used terminal emulators like xterm, Gnome Terminal, iTerm etc.

You can see the player in action on

If you don't want to depend on and you prefer to host the player
and the recordings yourself then read on, it's very simple.


Self-hosting quick start

The following example shows how to use asciinema player on your own website,
without depending on

It assumes you have obtained terminal session recording file by either:

Download the player

Download latest version of the player from
releases page. You
only need asciinema-player.js and asciinema-player.css files.

Use the player in your HTML page

First, add asciinema-player.js, asciinema-player.cssand the .cast file
with your recording to your site's assets.

Then add necessary includes to your HTML document:







<asciinema-player> element attributes

Number of columns of player's terminal.

When not set it defaults to 80 (until asciicast gets loaded) and to terminal
width saved in the asciicast file (after it gets loaded).

It's recommended to set it to the same value as in asciicast file to prevent
player to resize itself from 80x24 to the actual dimensions of the asciicast
when it gets loaded.


Number of lines of player's terminal.

When not set it defaults to 24 (until asciicast gets loaded) and to terminal
height saved in the asciicast file (after it gets loaded).

Same recommendation as for cols applies here.


Set this attribute to any value if playback should start automatically. Defaults
to no autoplay.


Set this attribute to any value if the recording should be preloaded on player's
initialization. Defaults to no preload.


Set this attribute to any value if playback should be looped. Defaults to no


Start playback at given time.

Supported formats:

Defaults to 0.


Playback speed. Defaults to 1 (normal speed). 2 means 2x faster.


Limit terminal inactivity to given number of seconds.

For example, when set to 2 any inactivity longer than 2 seconds will be
"compressed" to 2 seconds.

Defaults to:


Poster (preview) to display before playback start.

The following poster specifications are supported:

The easiest way of specifying a poster is to use npt:2:34 format. This will
preload the recording and display terminal contents from the recording at 2 min
34 s.


<asciinema-player src="..." poster="npt:2:34"></asciinema-player>

Alternatively, a poster value of data:text/plain,This will be printed as
poster\n\rThis in second line
will display arbitrary text. All ANSI escape
codes can be used to add color
and move the cursor around to produce good looking poster.

Example of using text poster with cursor positioning:

<asciinema-player src="..." poster="data:text/plain,I'm regular \x1b[1;32mI'm bold green\x1b[3BI'm 3 lines down"></asciinema-player>

Defaults to screen contents at start-at (or blank terminal when start-at is


Size of the terminal font.

Possible values:

Defaults to small.


Terminal color theme.

One of:

Defaults to asciinema.

You can also use a custom theme.


Title of the asciicast, displayed in the titlebar in fullscreen mode.


Author of the asciicast, displayed in the titlebar in fullscreen mode.


URL of the author's homepage/profile. Author name (author above) is linked to
this URL.


URL of the author's image, displayed in the titlebar in fullscreen mode.

Example usage with options

<asciinema-player src="/demo.cast" speed="2" theme="solarized-dark" loop="loop" poster="data:text/plain,\e[5;5HAwesome \e[1;33mdemo!"></asciinema-player>

Controlling the player programmatically

The player's DOM element provides several properties, methods and events
allowing for programmatical control over the player.


duration property gives the length of the recording in seconds, or zero if no
recording data is available (for ex. before loadedmetadata event is

document.getElementById('player').duration; // 123.45


currentTime property gives the current playback time in seconds. Setting this
value seeks the recording to the new time.

document.getElementById('player').currentTime; // 1.23
document.getElementById('player').currentTime = 33;


play method attempts to begin playback of the recording. If the recording
hasn't been preloaded then it tries to load it, and then starts the playback.


NOTE: If you want to synchronize asciinema player's playback with other elements
on the page (for example <audio> element) then you should wait for the play
event to occur, which signifies actual start of the playback.


pause method pauses playback.


loadedmetadata, loadeddata, canplay, canplaythrough

The loadedmetadata, loadeddata, canplay and canplaythrough events are
fired (all of them, in this order) when the recording has been loaded and is
ready to play. The recordings are always fully fetched (you can't partially load
resource with XHR) so there's no difference in the amount of metadata/data
available between these 4 events - when either event occurs the player already
has all the information for smooth playback. In other words, it's enough to
listen to only one of them, e.g. canplaythrough (all 4 are supported to make
it more in line with HTMLVideoElement).

document.getElementById('player').addEventListener('loadedmetadata', function(e) {
console.log("duration is", this.duration);

document.getElementById('player').addEventListener('canplaythrough', function(e) {
console.log("all ready to play");

NOTE: The player starts fetching the recording either when preload attribute
is set (in this case these events may not be immediately followed by play
event), or when user starts the playback (in this case these events are
immediately followed by play event).


The play event is fired when playback has begun.

document.getElementById('player').addEventListener('play', function(e) {
console.log("it's playing");
console.log("we're at", this.currentTime);


The pause event is fired when playback has been paused.

document.getElementById('player').addEventListener('pause', function(e) {
console.log("it's paused");

Keyboard shortcuts

The following keyboard shortcuts are currently available (when the player
element is focused):


The project uses leiningen for development and build
related tasks so make sure you have it installed (as well as Java 7 or 8).

Clone this repository:

git clone
cd asciinema-player

Make sure git submodules are fetched and up to date:

git submodule update --init --recursive

Start local web server with auto-compilation and live code reloading in the browser:

lein figwheel dev

Start auto-compilation of .less files:

lein less auto

Once the above tasks are running, open localhost:3449
in the browser to load the player with sample asciicast. Any changes made to
.cljs or .less files will be automatically pushed to the browser, preserving
player's state.

Run tests with:

lein doo phantom test

Building from source

To build stand-alone .js and .css files clone repository, initialize git
submodules (as shown above), then run:

lein cljsbuild once release
lein less once

This produces resources/public/js/asciinema-player.js and resources/public/css/asciinema-player.css.


If you want to contribute to this project check out
Contributing page.


Developed with passion by Marcin Kulik and great open
source contributors.


Copyright © 2011-2018 Marcin Kulik.

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