[GH-ISSUE #257] RFC asciicast v2: On-screen annotations #181

New issue

Closed

opened 2026-02-25 20:32:59 +03:00 by kerem · 2 comments

kerem commented

2026-02-25 20:32:59 +03:00

Owner

Originally created by @pfalcon on GitHub (Jan 16, 2018).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/257

Why: Oftentimes, the purpose of screencast are teaching/tutorials. Just showing typed stuff and output is not enough.

Usecases:

Give a "title"/generic description of what happens on the screen. This is essentially a closed caption.
Pinpoint/explain a particular element on the screen.

While these are different usecases, they could be addressed by the same player UI element (though ideally CC-style annotations would be rendered in a way to note obscure screen content).

Proposed format:

{
  "duration": 10.0,
...
  "version": 1,
  "height": 24,
  "width": 80,
  "annotations": [
    {at:0.5, dur: 1, relx: 0.1, rely: 0.1, text: "annotation asciinema/asciinema-server#1"},
    {at:3.0, dur: 3, relx: 0.8, rely: 0.8, text: "annotation\n#2"}
  ],
  "stdout": [
...

As can be seen, annotations blend well with v1 too.

An alternative format would be:

  "annotations": [
    [0.5, 1, 0.1, 0.1, "annotation asciinema/asciinema-server#1", props: {}],
  ],

It's mandatory to support arbitrary annotation properties for extension and alternative players. relx/rely specify relative position of left top annotation corner, taking 1.0 as full terminal width/height.

FAQ:

Q: How are annotations shown at ascii terminal playback?
A: Generally, in no way. It's webcast feature. But interested parties may develop alternative players if they wish.

Q: How annotations being authored?
A: Manually. Though asciinema.org could offer an UI for that: during pause at needed place, press "Add ann" button, draw a rectangle over playback window, fill in text, set duration of annotation.

Simple reference implementation was posted as https://github.com/dhobsd/castty/pull/30

Originally created by @pfalcon on GitHub (Jan 16, 2018). Original GitHub issue: https://github.com/asciinema/asciinema/issues/257 Why: Oftentimes, the purpose of screencast are teaching/tutorials. Just showing typed stuff and output is not enough. Usecases: 1. Give a "title"/generic description of what happens on the screen. This is essentially a closed caption. 2. Pinpoint/explain a particular element on the screen. While these are different usecases, they could be addressed by the same player UI element (though ideally CC-style annotations would be rendered in a way to note obscure screen content). Proposed format: ~~~ { "duration": 10.0, ... "version": 1, "height": 24, "width": 80, "annotations": [ {at:0.5, dur: 1, relx: 0.1, rely: 0.1, text: "annotation asciinema/asciinema-server#1"}, {at:3.0, dur: 3, relx: 0.8, rely: 0.8, text: "annotation\n#2"} ], "stdout": [ ... ~~~ As can be seen, annotations blend well with v1 too. An alternative format would be: ~~~ "annotations": [ [0.5, 1, 0.1, 0.1, "annotation asciinema/asciinema-server#1", props: {}], ], ~~~ It's mandatory to support arbitrary annotation properties for extension and alternative players. `relx`/`rely` specify relative position of left top annotation corner, taking 1.0 as full terminal width/height. FAQ: Q: How are annotations shown at ascii terminal playback? A: Generally, in no way. It's webcast feature. But interested parties may develop alternative players if they wish. Q: How annotations being authored? A: Manually. Though asciinema.org could offer an UI for that: during pause at needed place, press "Add ann" button, draw a rectangle over playback window, fill in text, set duration of annotation. Simple reference implementation was posted as https://github.com/dhobsd/castty/pull/30

kerem closed this issue

2026-02-25 20:32:59 +03:00

kerem commented

2026-02-25 20:32:59 +03:00

Author

Owner

@beekhof commented on GitHub (Feb 19, 2019):

Sad to see this closed without comment, its exactly what I'm looking for

@beekhof commented on GitHub (Feb 19, 2019): Sad to see this closed without comment, its exactly what I'm looking for

kerem commented

2026-02-25 20:32:59 +03:00

Author

Owner

@jpellman commented on GitHub (Jun 24, 2019):

See asciinema/asciinema-server#256 for the reason for why this was closed. While the feature requests are legitimate, the OP was communicating with the project leads in an excessively condescending and adversarial tone for a product that he was paying absolutely nothing for. Additionally, this request is a possible duplicate of https://github.com/asciinema/discussions/issues/189.

@jpellman commented on GitHub (Jun 24, 2019): See asciinema/asciinema-server#256 for the reason for why this was closed. While the feature requests are legitimate, the OP was communicating with the project leads in an excessively condescending and adversarial tone for a product that he was paying absolutely nothing for. Additionally, this request is a possible duplicate of https://github.com/asciinema/discussions/issues/189.

kerem referenced this issue

2026-02-25 20:33:37 +03:00

[PR #181] [MERGED] respect PEP8 coding style #401

kerem referenced this issue

2026-02-25 20:33:37 +03:00

[PR #182] [MERGED] pep8: inlude modules on top of a file #402

kerem referenced this issue

2026-03-15 11:13:51 +03:00

[PR #182] [MERGED] pep8: inlude modules on top of a file #1012

kerem referenced this issue

2026-03-15 11:13:51 +03:00

[PR #181] [MERGED] respect PEP8 coding style #1015