[GH-ISSUE #70] Decouple terminal recording from asciinema.org #665

New issue

Closed

opened 2026-03-15 07:25:32 +03:00 by kerem · 0 comments

kerem commented

2026-03-15 07:25:32 +03:00

Owner

Originally created by @ku1ik on GitHub (Aug 11, 2014).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/70

Recording should not be tied to asciinema.org.

You should be able to:

record to a local file with asciinema rec <filename>,
replay locally (in a terminal) from files with asciinema play <filename>,
replay locally (in a terminal) from URLs with asciinema play <url>,
instruct player on asciinema.org to play from external URL?

This is a prerequisite for #49, it is in fact a simpler version of it.

Saving/sharing/replaying from a local file means we have to decide on the data format.

Requirements for data format:

should include raw stdout data with frame timing + (initial) width/height of the terminal window
should be easy to parse and process for asciinema and external tools
should allow live streaming
should be easy to read/parse by js player itself (so you can point js player directly to URL containing recording in this format)
the format should be versioned

Option 1: use current format used by asciinema.org

zip file with custom extension (like .asciicast for ex), including 3 files:

meta.json - with metadata like width/height of terminal, title, etc
stdout - raw stdout bytes,
stdout.timing - timing information.

Current implementation uses these 3 files when uploading the recording to asciinema.org.
This however isn't really compatible with live streaming idea and doesn't address all the requirements above.

Option 2: new JSON based format

With frames inlined, to be used when persisted:

{
  version: 1,
  width: 80,
  height: 24,
  frames: [<frame>, <frame>, <frame>...]
}

With frames delegated to an URL, to be used when streaming:

{
  version: 1,
  width: 80,
  height: 24,
  frames_url: "https://....." or "ws://....."
}

frames_url is a URL to streaming endpoint, either http or websocket.

Format of the single frame:

JSON isn't suited to store arbitrary binary data in strings and raw stdout output contains lots of non-printable bytes so we should encode them. Base64 or encoding each byte in hex or utf would do.

[1.234, "bHMgLWxhIC8="]

{ delay: 1.234, data: "bHMgLWxhIC8=" }

Streaming endpoint(s) could be implemented to spit out each new frame in a separate line.

Originally created by @ku1ik on GitHub (Aug 11, 2014). Original GitHub issue: https://github.com/asciinema/asciinema/issues/70 Recording should not be tied to asciinema.org. You should be able to: - record to a local file with `asciinema rec <filename>`, - replay locally (in a terminal) from files with `asciinema play <filename>`, - replay locally (in a terminal) from URLs with `asciinema play <url>`, - instruct player on asciinema.org to play from external URL? This is a prerequisite for #49, it is in fact a simpler version of it. Saving/sharing/replaying from a local file means we have to decide on the data format. **Requirements for data format:** - should include raw stdout data with frame timing + (initial) width/height of the terminal window - should be easy to parse and process for `asciinema` and external tools - should allow live streaming - should be easy to read/parse by js player itself (so you can point js player directly to URL containing recording in this format) - the format should be versioned **Option 1: use current format used by asciinema.org** zip file with custom extension (like `.asciicast` for ex), including 3 files: - `meta.json` - with metadata like width/height of terminal, title, etc - `stdout` - raw stdout bytes, - `stdout.timing` - timing information. Current implementation uses these 3 files when uploading the recording to asciinema.org. This however isn't really compatible with live streaming idea and doesn't address all the requirements above. **Option 2: new JSON based format** With frames inlined, to be used when persisted: ``` { version: 1, width: 80, height: 24, frames: [<frame>, <frame>, <frame>...] } ``` With frames delegated to an URL, to be used when streaming: ``` { version: 1, width: 80, height: 24, frames_url: "https://....." or "ws://....." } ``` `frames_url` is a URL to streaming endpoint, either http or websocket. Format of the single frame: JSON isn't suited to store arbitrary binary data in strings and raw stdout output contains lots of non-printable bytes so we should encode them. Base64 or encoding each byte in hex or utf would do. ``` [1.234, "bHMgLWxhIC8="] ``` or ``` { delay: 1.234, data: "bHMgLWxhIC8=" } ``` Streaming endpoint(s) could be implemented to spit out each new frame in a separate line.