Skip to content

Loading a recording

While the easiest way of loading a recording into the player is by using asciicast file URL, it's also easy to customize the loading procedure or even replace it completely.

Preloading

By default the player doesn't fetch a recording upon initialization, postponing the loading until user starts the playback. Given how small (in terms of filesize) terminal recordings are this usually is perfectly fine. However, if you wish so you can force the player to preload the recording upon its initialization using preload option:

AsciinemaPlayer.create(src, containerElement, { preload: true });

Custom fetch options

If you'd like to fetch a recording from a URL, but you need to tweak how HTTP request is performed (e.g. configure credentials, change HTTP method), you can do so by using { url: "...", fetchOpts: { ... } } object as the source argument. fetchOpts object is then passed to fetch (as its 2nd argument).

For example:

AsciinemaPlayer.create(
  { url: url, fetchOpts: { method: 'POST' } },
  containerElement
);

Inlining with Data URL

If a recording file is small and you'd rather avoid additional HTTP request, you can inline the recording by using Data URL:

AsciinemaPlayer.create(
  'data:text/plain;base64,' + base64encodedAsciicast,
  containerElement
);

For example:

AsciinemaPlayer.create(
  'data:text/plain;base64,eyJ2ZXJzaW9uIjogMiwgIndpZHRoIjogODAsICJoZWlnaHQiOiAyNH0KWzAuMSwgIm8iLCAiaGVsbCJdClswLjUsICJvIiwgIm8gIl0KWzIuNSwgIm8iLCAid29ybGQhXG5cciJdCg==',
  document.getElementById('demo')
);

This approach is useful e.g. when you're dynamically generating HTML on the server-side, embedding player initialization code in HTML of the page.

Dynamic loading

If you prefer to provide a recording to the player manually at runtime you can use the following variant of the src argument with the create function:

AsciinemaPlayer.create({ data: data }, containerElement);

The value of data can be:

  • a string containing asciicast in v2 or v1 format
  • an array representing asciicast in v2 format
  • an object representing asciicast in v1 format
  • a function which returns one of the above (may be async)

Provided data is parsed with built-in asciicast format parser by default (also see Playing other recording formats below).

Examples of supported data specifications:

// string representing asciicast in v2 format (ndjson)
'{"version": 2, "width": 80, "height": 24}\n[1.0, "o", "hello "]\n[2.0, "o", "world!"]';

// string representing asciicast in v1 format (json)
'{"version": 1, "width": 80, "height": 24, "stdout": [[1.0, "hello "], [1.0, "world!"]]}';

// array representing asciicast in v2 format
[
  {version: 2, width: 80, height: 24},
  [1.0, "o", "hello "],
  [2.0, "o", "world!"]
]

// object representing asciicast in v1 format
{version: 1, width: 80, height: 24, stdout: [[1.0, "hello "], [1.0, "world!"]]};

// function returning a string representing asciicast in v2 format (ndjson)
() => '{"version": 2, "width": 80, "height": 24}\n[1.0, "o", "hello "]\n[2.0, "o", "world!"]';

Passing asciicast v2 as a string looks like this:

AsciinemaPlayer.create(
  { data: '{"version": 2, "width": 80, "height": 24}\n[1.0, "o", "hello "]\n[2.0, "o", "world!"]' },
  document.getElementById('demo')
);

Similarly to inlining with Data URL this is useful for server-side generation use-cases.

If data is a function, then the player invokes it when playback is started by a user. If preload option is used, the function is invoked during player initialization (mounting in DOM).

Say you'd like to embed asciicast contents in a (hidden) HTML tag on your page, following data source can be used to extract it and pass it to the player:

AsciinemaPlayer.create(
  { data: () => document.getElementById('asciicast').textContent.trim() },
  document.getElementById('demo')
);

Finally, you can call fetch yourself and transform the result:

AsciinemaPlayer.create(
  { data: () => fetch(url, { method: 'POST' }).then(...) },
  containerElement
);

This is handy e.g. when you need to extract an asciicast from a nested JSON structure produced by HTTP API.

Note

You can fetch the recording first and only then initialize the player with { data: '...' }, like this:

fetch('/demo.cast').then(resp => {
  AsciinemaPlayer.create({ data: resp }, document.getElementById('demo'));
});

However this has a downside: the player is not added to the page until the data is loaded, resulting in the player poping up on the page out of nowhere a moment after the page load.

By using { data: () => ... } (function variant) you can mount the player on the page immediately.

Playing other recording formats

By default, recordings are parsed with a built-in asciicast format parser.

If you have a recording produced by other terminal session recording tool (e.g. script, termrec, ttyrec) you can use one of built-in file format parsers, or implement a custom parser function.

Recording format parser can be specified in the source argument to AsciinemaPlayer.create as a string (built-in) or a function (custom):

AsciinemaPlayer.create({ url: url, parser: parser }, containerElement);

See Parsers for information on available built-in parsers and how to implement a custom one.