Web player for terminal session recordings (as produced by asciinema recorder) that you can use on your website.
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
asciicasts.
Asciicast is a capture of terminal's raw output and thus the player comes with its own terminal emulator based on Paul Williams' parser for ANSI-compatible video terminals. It covers only the display part of the emulation as this is what the player is about (input is handled by your terminal+shell at the time of recording anyway) and its handling of escape sequences is fully compatible with most modern terminal emulators like xterm, Gnome Terminal, iTerm, mosh etc.
Features:
- copy-paste of terminal content (it's just a text after all!),
- predefined and custom font sizes,
- custom playback speeds,
- looped playback,
- starting playback at specific time,
- keyboard shortcuts,
- multiple color schemes,
- full-screen mode.
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.
The following example assumes you have obtained terminal session recording file by either:
- recording terminal session to a local file with
asciinema rec demo.json(more details on recording), - downloading an existing recording from asciinema.org by appending
.jsonto the asciicast page URL (for example: https://asciinema.org/a/28307.json).
Download latest version of the player from
releases page. You
only need asciinema-player.js and asciinema-player.css files.
First, add player files (asciinema-player.js and asciinema-player.css)
together with the recording demo.json file to your site assets.
Then add necessary includes to your document's <head>:
<link rel="stylesheet" type="text/css" href="/asciinema-player.css" />
<script src="/asciinema-player.js"></script>Now, add empty <div> element in your markup where you want the player to show
up, assigning it id attribute. Then initialize the player with this id and the
URL of the .json file containing the recording:
<div id="player-container"></div>
<script>
asciinema_player.core.CreatePlayer('player-container', '/demo.json');
</script>Complete example:
<html>
<head>
<link rel="stylesheet" type="text/css" href="/asciinema-player.css" />
<script src="/asciinema-player.js"></script>
</head>
<body>
<div id="player-container"></div>
<script>
asciinema_player.core.CreatePlayer('player-container', '/demo.json');
</script>
</body>
</html>Create the player widget with the following JavaScript code:
asciinema_player.core.CreatePlayer(parent, asciicastURL, options)where:
parent- DOM element into which the player should be inserted (as the only child),asciicastURL- URL of the asciicast JSON file to play,options- (optional) object with any of the following properties:width- width of the player (number of terminal columns),height- height of the player (number of terminal lines),autoPlay- set to true if playback should start automatically, default:false,loop- set to true if playback should be looped, default:false,startAt- start playback at given time (123, "2:03", "1:02:03"), default: 0,speed- playback speed, default: 1,poster- poster (preview) to display before playback start, default: blank terminal,fontSize- size of terminal font:'small','medium','big'or any CSSfont-sizevalue (e.g.15px); default:'small',theme- terminal theme, one of'asciinema','tango','solarized-dark','solarized-light','monokai'; default:'asciinema',title- title of the asciicast, displayed in the titlebar in fullscreen mode,author- author of the asciicast, displayed in the titlebar in fullscreen mode,authorURL- URL of the author's homepage/profile,authorImgURL- URL of the author's image, displayed in the titlebar in fullscreen mode
For example:
<div id="player-container"></div>
<script>
asciinema_player.core.CreatePlayer('player-container', '/demo.json', { speed: 2, theme: 'solarized-dark' });
</script>CreatePlayer doesn't return anything useful yet (that's why we're not storing
its result in a variable). In the future it will return a "control object" for
programmatic control of the playback.
Here are some jQuery workarounds for controlling the player pending development of a formal API. Due to the same-origin policy, these work only with a player hosted in your web page.
| Action | Coding |
|---|---|
| Start or stop the player | $(".playback-button").trigger("click") |
| Determine if player is playing | 2 == $(".playback-button")[0].getElementsByTagName("path").length |
| Fetch elapsed time | $(".time-elapsed").text() |
| Fetch remaining time | $(".time-remaining").text() |
The following keyboard shortcuts are currently available (when the player element is focused):
space- play / pausef- toggle fullscreen mode←/→- rewind 5 seconds / fast-forward 5 seconds0, 1, 2 ... 9- jump to 0%, 10%, 20% ... 90%</>- decrease / increase playback speed
The project uses leiningen for development and build related tasks so make sure you have it installed (as well as Java 7 or 8).
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
To build stand-alone .js and .css files run:
lein cljsbuild once release
lein less once
This produces resources/public/js/release.js and resources/public/css/main.css.
- make
CreatePlayerreturn "control object" - add hooks (start/pause/resume/finish)
- figure out if GPL is compatible with Clojure(Script)'s EPL
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-2016 Marcin Kulik.
All code is licensed under the GPL, v3 or later. See LICENSE file for details.