<asciinema-player> HTML5 element Published on 02 Oct 2016 by Marcin Kulik

We have just released asciinema web player v2.3.0. Since v2.0.0 there were two smaller releases bringing lots of improvements (see the CHANGELOG), but this one definitely deserves a post of its own.

This new version makes self-hosting of the player even simpler. Let’s see an example.


<div id="player-container"></div>
  asciinema.player.js.CreatePlayer('player-container', '/demo.json');


<asciinema-player src="/demo.json"></asciinema-player>

Awesome, right?

This is possible thanks to HTML5 Custom Elements, which allow web developers to define new types of HTML elements. New asciinema-player.js includes definition of new AsciinemaPlayer element type and its associated <asciinema-player> tag. The .js bundle also provides Custom Element polyfill which makes the new element working in browsers which don’t support this feature yet.

The element supports several attributes known from <video> element like loop, autoplay, preload, as well as asciinema-specific ones like speed, theme, font-size.

See README for a quick “getting started with self-hosting” guide and a description of all supported attributes.



1.3 aka "And Now for Something Completely Different" Published on 13 Jul 2016 by Marcin Kulik

I’m very happy to announce the release of asciinema 1.3, which is kind of a special release. It brings several bug fixes and improvements for end users, and at the same time it makes life of asciinema developers (mostly me) and package maintainers (many people!) way easier.

See CHANGELOG for a detailed list of changes, continue reading for motivation on transitioning back to Python.

Wait, what? Back to Python? Yes, asciinema 1.3 brings back the original Python implementation of asciinema. It’s based on 0.9.8 codebase and adds all features and bug fixes that have been implemented in asciinema’s Go version between 0.9.8 and 1.2.0. We’ll keep the Go implementation in golang branch, it won’t be maintained though.

While Go definitely has its strengths (easy concurrency, runtime speed, startup speed, stand-alone binary), this project didn’t really benefit from any of these (and suffered from Go’s pain points). Here is a (not exhaustive) list of things that contributed to the decision of dropping Go for Python:

asciinema recorder codebase (and feature set) is relatively small (under 900 LOC currently) so it wasn’t a big effort to port all newer features on top of the old Python implementation.

Note, that the above list applies specifically to asciinema recorder. There are great use cases for Go (like IPFS) and if I was to build system-level software, protocol implementation or any kind of network daemon (proxy for example) I’d definitely consider Go. Also, asciinema is a cli app distributed to end users. If you’re building in-house software that has to run only on single platform then many of the above points may become non-issue for you.

Anyway, it feels good to be back on Python!

2016-07-14 update: Many people raised a question: why was it ported from Python to Go in the first place? There were several reasons. First, Go’s static binaries nicely solve the packaging problem (we didn’t have that many native packages then and pip install asciinema wasn’t always reliable due to the fact that it supported both Python 2 and 3). It later appeared that majority of people prefer native packages so distributing precompiled binaries wasn’t a big win for this type of project in the end. Second, Go was initially advertised as a “systems language”, and if your program does system stuff like select/signal/ioctl then Go should be perfect, right? Well, it appears that Go excels (and was built for) slightly different things (multi-core concurrency, networking, distributed systems). It is no longer advertised as a “systems language” by its authors. Third, Go’s static type system with type inference and functions as first class citizens felt like a nice bonus. In reality, the lack of generics forces you to write lots of boilerplate and repetitive code. 20 lines of boilerplate, imperative code is not simpler and easier to understand (like some Go defendants claim) than 2 lines of higher level code because it adds noise to the essence of algorithm. When reading code you don’t need that level of granularity in most cases. Well, at least I don’t need it :) Fourth, it was interesting to apply my knowledge of this domain to a language with different qualities. I would lie if I said having fun wasn’t part of the thing.


Self-hosting Published on 06 Jan 2016 by Marcin Kulik

I’m very happy to announce version 2.0 of the asciinema web player. There are several exciting aspects of this release so let’s get straight to the point.

First, the new player directly supports asciicast v1 format. In other words, there is no need to pre-process the recording upfront, before passing it to the player. This is possible thanks to built-in 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 all about (input is handled by your terminal+shell at the time of recording anyway). Handling of escape sequences is fully compatible with most modern terminal emulators like xterm, Gnome Terminal, iTerm, mosh etc.

This is cool in itself, but the best part of it is that it enables self-hosting of the recordings on your own website, without depending on asciinema.org. If you’re not comfortable keeping your recordings on asciinema.org (“in the cloud” == “other people’s computers”), or you simply prefer to own and fully control your content, this release solves this problem for you. Just place player’s .js + .css files together with .json file of your recording in your web assets directory, and insert short <script> tag in your HTML. Take a look at README for quick start.

It’s also worth mentioning that this version of the player (including terminal emulator part) has been implemented in ClojureScript. If you were sceptical about performance of compile-to-javascript languages and/or performance of immutable data structures then this will hopefully convince you that there’s no need to worry about it. ClojureScript compiler does a wonderful job of converting high level Clojure code into highly optimized, fast JavaScript code. If it’s possible to build a performant player like this one in ClojureScript then you can build anything in ClojureScript. Look at the source if you’re curious how it looks like.

Check asciinema/asciinema-player on Github for API documentation and usage examples.



Private asciicasts Published on 11 May 2015 by Marcin Kulik

The core idea behind asciinema.org is to allow anyone to share the recording of their terminal session by simply sharing a link to your asciicast page. Since the inception of asciinema all recordings has been public. We wanted to encourage you to share your knowledge, show off your tricks, and allow others to learn from it.

It appears though that the nature of the asciicasts is often semi-private. Many of you would like to record something and share it with a selected group of people only, your team-mates for example. There were requests for private asciicasts. There were some ideas to workaround the fact that everything on asciinema.org was public. asciinema would be way more useful if it allowed you to decide if and with whom you share the recordings, wouldn’t it?

The good news is as of today all new recorded asciicasts are private by default. They get unique, secret URLs (like Github’s gists) which means you can share them with selected people as easy as before. Whoever gets the secret link can view the asciicast. Private asciicasts are not listed on the Browse page or anywhere else on the site.

Public asciicasts are still a thing though, and you can publish any of your recordings by clicking “Make public” in gear dropdown menu on an asciicast page. If you’d rather have all your new recordings public by default you can change the visibility policy on your asciinema.org account settings page.

It’s possible that next version of asciinema recorder will have -p and -P switches for asciinema rec and asciinema upload commands, which will force private (-p) or public (-P) visibility for a single asciicast, overriding the default account policy.



New ways of asciicast embedding Published on 31 Mar 2015 by Marcin Kulik

Support for embedding asciicasts just got way more awesome. See embedding docs for details, read on for examples.

Embedding on your site

In addition to the existing support for embedding full player widget on your page, you can now use image link to display a screenshot linking to your recording on asciinema.org. This is useful in places where script tags are not allowed, for example in Github README files.

You can get the embed snippets for a specific asciicast by clicking on “Embed” link on asciicast page.

Here’s an example of how the image link looks like:

Embedding on Slack, Twitter and Facebook

asciinema.org supports oEmbed, Open Graph and Twitter Card protocols now. When you share an asciicast on Twitter, Slack, Facebook, Google+ or any other site which supports one of these APIs, the asciicast is presented in a rich form (usually with a title, author, description and a thumbnail image), linking to your recording on asciinema.org.

Here’s how it looks on Slack:

And here’s my tweet including a link to the same asciicast:


1.0 Published on 13 Mar 2015 by Marcin Kulik

I’m very happy to announce the release of asciinema 1.0, which brings many long-awaited features and settles the ground for even more awesome features and improvements coming in the future.

See CHANGELOG for a detailed list of changes, continue reading for highlights of this important release.

Idle time optimization

Did you ever wish you had more powerful machine because this software compilation you’re recording takes long time? Or maybe you wanted to pause the recording process, plan your next steps, and then resume recording? If you said “yes!” to any of the above then you may like asciinema’s new option.

asciinema rec command learned new option: --max-wait. It allows limiting idle time, by replacing long pauses (terminal inactivity) with shorter ones.

You use it like this:

asciinema rec --max-wait=2

This starts recording session in which all pauses longer than 2 seconds are replaced with exactly 2 second ones.

An asciicast is worth a thousand words, so let’s compare recording with and without --max-wait. First, let’s look at the result of recording with plain asciinema rec:

Now, let’s look at the result of recording the same thing, this time with asciinema rec --max-wait=2:

Using this new option will make you look like you always know what to do next, you’re confident, and last but not least - you own a super computer that can compile the biggest project in a matter of seconds. How cool is that?

Local workflow

Another improvement to asciinema rec is its ability to save the recording to a local file.

asciinema rec demo.json

This saves the session to demo.json file. Now, you can replay it directly in your terminal:

asciinema play demo.json

Finally, if you’re happy about it and you want to share it on asciinema.org just run:

asciinema upload demo.json

Let’s see it in action:

If you don’t need to keep your recording local and just want to record and upload in one step, you can still asciinema rec without a filename.

New, simple asciicast format

Due to the fact that previous versions of asciinema recorder didn’t allow saving recordings locally, there was no stable and documented “asciicast format”.

This changes with 1.0. The file produced with asciinema rec <filename> is a simple JSON file with a strict set of attributes. The format is versioned to allow future extensions while preserving backwards compatibility. See asciicast file format version 1.

If you know how to deal with ansi escape sequences you can manually edit your recordings with a text editor, or build a tool that can post-process them.

Configuration file

There are several new options that can be set in ~/.asciinema/config file. See README for a description of all of them.

Here’s an example of setting --max-wait permanently, so you don’t need to pass it manually on each invocation of asciinema rec:

maxwait = 2


All available installation methods can be found on installation page.

Note: not all native packages may be updated yet. If you want to make sure you’re getting the latest version of asciinema download a binary for you platform here.

The future

The changes introduced in this release, in addition to being valuable by themselves, enable even more awesomeness in the future. For example, the upcoming ability to self host (yes!) your recordings (without depending on asciinema.org) wouldn’t be possible without having a way to record to a file with a well defined format.

I hope you’ll enjoy the future. Meanwhile, enjoy asciinema 1.0!


asciinema switching to Mozilla Persona for login Published on 24 Oct 2013 by Marcin Kulik

So far you could log in to asciinema using your Github or Twitter account via OAuth. The idea behind this was twofold:

Passwords are insecure, inconvenient and annoying. Inconvenience of passwords was nicely summed up by Xavier in his tweet saying “password reset is the new login”. So the OAuth flow, being very simple for the user (given he/she is already logged in at the provider), helped achieving the initial goals.

And while OAuth based login worked totally fine it made asciinema dependent on commercial vendors for no good reason. OAuth was designed for API authorization between applications, not for user authentication. asciinema doesn’t need access to user’s Github repositories nor user’s tweets. It just needs the ability to authenticate a user. Also, the assumption that everyone has either Github or Twitter account is simply wrong.

The assumption that everyone has an email address is a correct one though. E-mail is ubiquitous and everyone remembers his/her own address. Can’t we just use it as an ID on the web? Mozilla believes we can and we should. Mozilla Persona, a reference implementation of BrowserID protocol, puts the email address at the center of authentication and gives us simple, privacy-sensitive single sign-in solution.

asciinema team believes in Mozilla’s mission for promoting openness and innovation on the web, and thus we switch to Persona based authentication, replacing the existing OAuth based flow. If you have an existing asciinema account then fear not, you won’t lose access to it. When signing in just use the same email address that you assigned to your account. If you don’t remember which one you have used (or you haven’t set the email address at all) then sign in (with your preferred email address) and you’ll be given an option to locate your existing account by doing the OAuth dance for one last time.

Let us know what you think about this change. Enjoy!