Note: This README applies to development branch. See the version for the latest stable release here.
Web player for terminal session recordings (as produced by asciinema recorder) that you can use on your own website.
asciinema player is an open-source terminal session player written in
Javascript and Rust/WASM. Unlike other video players asciinema player doesn't play
heavy-weight video files (.mp4, .webm etc) and instead plays light-weight
terminal session files called
asciicasts.
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 asciinema.org.
If you don't want to depend on asciinema.org and you prefer to host the player and the recordings yourself then read on, it's very simple.
- ability to copy-paste terminal content - it's just a text after all!,
- ultra smooth, timing-accurate playback,
- automatic font scaling to fit into container element in most efficient way,
- idle time optimization to skip longer periods of inactivity,
- predefined and custom font sizes,
- NPT-based or custom text poster,
- adjustable playback speed,
- looped playback, infinite or finite,
- starting playback at specific time,
- keyboard shortcuts,
- multiple color schemes for standard 16 colors,
- full support for 256 color palette and 24-bit true color (ISO-8613-3),
- full-screen mode.
The following examples show how to use asciinema player on your own website, without depending on asciinema.org.
It assumes you have obtained terminal session recording file by either:
- recording terminal session to a local file with
asciinema rec demo.cast(more details on recording), - downloading an existing recording from asciinema.org by appending
.castto the asciicast page URL (for example: https://asciinema.org/a/28307.cast).
Download latest version of the player bundle from
releases page. You
only need asciinema-player.min.js and asciinema-player.css files.
First, add asciinema-player.min.js, asciinema-player.cssand the .cast file of
your recording to your site's assets. The HTML snippet below assumes they're in
the web server's root directory.
Then add necessary includes to your HTML document and initialize the player
inside an empty <div> element:
<html>
<head>
...
<link rel="stylesheet" type="text/css" href="/asciinema-player.css" />
...
</head>
<body>
...
<div id="demo"></div>
...
<script src="/asciinema-player.min.js"></script>
<script>
AsciinemaPlayer.create('/demo.cast', document.getElementById('demo'));
</script>
</body>
</html>Add asciinema-player to your devDependencies:
npm install --save-dev asciinema-player@3.0.0-rc.2Add empty <div id="demo"></div> element to your page to contain the player.
Import and use create function from asciinema-player module:
import * as AsciinemaPlayer from 'asciinema-player';
AsciinemaPlayer.create('/demo.cast', document.getElementById('demo'));Finally, include player's CSS file - found in the npm package at
dist/bundle/asciinema-player.css - in your CSS bundle.
To mount the player in your page call the create function exported by the
asciinema-player ES module with 2 arguments: the URL (or path) to the
asciicast file and the container DOM element to mount the player in.
const player = AsciinemaPlayer.create(url, containerElement);The returned object contains the following attributes:
el- DOM element of the playerdispose- a function to dispose the player, i.e. to remove it from the page
You can tweak file fetching by passing { url: "...", fetchOpts: { ... } } as
the 1st argument to create. fetchOpts object is then passed to
fetch (as its 2nd
argument). This can be used to change HTTP method, configure credentials, etc.
If you'd like to inline the recording contents you can do so with Data URLs. For example:
const player = AsciinemaPlayer.create(
'data:text/plain;base64,eyJ2ZXJzaW9uIjogMiwgIndpZHRoIjogODAsICJoZWlnaHQiOiAyNH0KWzAuMSwgIm8iLCAiaGVsbCJdClswLjUsICJvIiwgIm8gIl0KWzIuNSwgIm8iLCAid29ybGQhXG5cciJdCg==',
containerElement
);To pass additional options when mounting the player use 3 argument variant:
const player = AsciinemaPlayer.create(url, containerElement, opts);For example, to enable looping and select Solarized Dark theme:
AsciinemaPlayer.create('/demo.cast', document.getElementById('demo'), {
loop: true,
theme: 'solarized-dark'
});See below for a full list of available options.
Type: number
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.
Type: number
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.
Type: boolean
Set this option to true if playback should start automatically.
Defaults to false - no auto play.
Type: boolean
Set this option to true if the recording should be preloaded on player's
initialization.
Defaults to false - no preload.
Type: boolean or number
Set this option to either true or a number if playback should be looped. When
set to a number (e.g. 3) then the recording will be re-played given number of
times and stopped after that.
Defaults to false - no looping.
Type: number or string
Start playback at a given time.
Supported formats:
123(number of seconds)"2:03"("mm:ss")"1:02:03"("hh:mm:ss")
Defaults to 0.
Type: number
Playback speed. The value of 2 means 2x faster.
Defaults to 1 - normal speed.
Type: number
Limit terminal inactivity to a given number of seconds.
For example, when set to 2 any inactivity longer than 2 seconds will be
"compressed" to 2 seconds.
Defaults to:
idle_time_limitfrom asciicast header (saved when passing-i <sec>toasciinema rec),- no limit, when it was not specified at the time of recording.
Type: string
Terminal color theme.
One of:
"asciinema""monokai""tango""solarized-dark""solarized-light"
Defaults to "asciinema".
You can also use a custom theme.
Type: string
Poster (a preview frame) to display until the playback is started.
The following poster specifications are supported:
npt:1:23- display recording "frame" at given time using NPT ("Normal Play Time") notationdata:text/plain,Poster text- print given text
The easiest way of specifying a poster is to use NPT format. For example,
npt:1:23 will preload the recording and display terminal contents at 1 min 23
sec.
Example:
AsciinemaPlayer.create('/demo.cast', document.getElementById('demo'), {
poster: 'npt:1:23'
});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 custom text poster with control sequences (aka escape codes):
AsciinemaPlayer.create('/demo.cast', document.getElementById('demo'), {
poster: "data:text/plain,I'm regular \x1b[1;32mI'm bold green\x1b[3BI'm 3 lines down"
});Defaults to blank terminal or, when startAt is specified, to screen contents
at time specified by startAt.
Type: string
Controls the player's fitting (sizing) behaviour inside its container element.
Possible values:
"width"- scale to full width of the container"height"- scale to full height of the container (requires the container element to have fixed height)"both"- scale to either full width or height, maximizing usage of available space (requires the container element to have fixed height)false/"none"- don't scale, use fixed size font (also seefontSizeoption below)
Defaults to "width".
Version 2.x of the player supported only the behaviour represented by the
falsevalue. If you're upgrading from v2 to v3 and want to preserve the sizing behaviour then includefit: falseoption.
Type: string
Size of the terminal font.
Possible values:
"small""medium""big"- any valid CSS
font-sizevalue, e.g."15px"
Defaults to "small".
This option is effective only when
fit: falseoption is specified as well (see above).
Type: string
Terminal font-family override.
Use any valid CSS font-family value, e.g "'JetBrains Mono', Consolas, Menlo, 'Bitstream Vera Sans Mono', monospace".
Type: number
Terminal line height override.
The value is relative to the font size (like em unit in CSS). For example a
value of 1 makes the line height equal to the font size, leaving no space
between lines. A value of 2 makes it double the font size, etc.
Defaults to 1.33333333.
The following keyboard shortcuts are currently available (when the player element is focused):
- space - play / pause
- f - toggle fullscreen mode
- ← / → - rewind by 5 seconds / fast-forward by 5 seconds
- Shift + ← / Shift + → - rewind by 10% / fast-forward by 10%
- 0, 1, 2 ... 9 - jump to 0%, 10%, 20% ... 90%
The project requires Node.js, npm and Rust for development and build related tasks so make sure you have the latest versions installed.
To build the project:
git clone https://github.com/asciinema/asciinema-player
cd asciinema-player
git submodule update --init
npm install
npm run build
npm run bundle
This produces:
dist/index.js- ES module, to beimport-ed in your JS bundledist/bundle/asciinema-player.js- standalone player script, to be linked directly from a websitedist/bundle/asciinema-player.min.js- minimized version of the abovedist/bundle/asciinema-player.css- stylesheet, to be linked directly from a website or included in a CSS bundle
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-2021 Marcin Kulik.
All code is licensed under the Apache License, Version 2.0. See LICENSE file for details.