[GH-ISSUE #117] [Feature request] Allow some sort of "commenting" inside the asciinema JSON

kerem commented

2026-03-15 08:56:36 +03:00

Owner

Originally created by @pdfkungfoo on GitHub (Jun 30, 2015).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/117

ASCiinema's popularity will improve the more, the better the contents of screencasts are. However, to produce _really good_ ASCiinema playback material, there is a need to _edit_ the original recordings.

While editing recordings isn't a problem per se, to do so with a file that plays longer than 1 minute is quite a stretch, because it is difficult to navigate its structure. If we could insert comments (which should be ignored when playing the file), that task would get more easy.

I am aware that "pure" JSON does not allow comments.

However, for asciinema it would be a nice feature if I could insert lines like

# this is a comment; we are @ playtime 1:03 right now; this is line 2345 of recording

This would help immensely when editing a recorded file.

Originally created by @pdfkungfoo on GitHub (Jun 30, 2015). Original GitHub issue: https://github.com/asciinema/asciinema/issues/117 ASCiinema's popularity will improve the more, the better the contents of screencasts are. However, to produce **_really good**_ ASCiinema playback material, there is a need to **_edit**_ the original recordings. While editing recordings isn't a problem per se, to do so with a file that plays longer than 1 minute is quite a stretch, because it is difficult to navigate its structure. If we could insert comments (which should be ignored when playing the file), that task would get more easy. I am aware that "pure" JSON does not allow comments. However, for `asciinema` it would be a nice feature if I could insert lines like ``` # this is a comment; we are @ playtime 1:03 right now; this is line 2345 of recording ``` This would help immensely when editing a recorded file.

kerem

2026-03-15 08:56:36 +03:00

closed this issue
added the
feature request
label

kerem commented

2026-03-15 08:56:53 +03:00

Author

Owner

@ku1ik commented on GitHub (Jun 30, 2015):

I see your point. However we cannot make the JSON file "special" because it is also meant to be read by web browsers and other external tools. By using unsupported syntax in JSON we would break all of them (except the asciinema recorder/player).

@ku1ik commented on GitHub (Jun 30, 2015): I see your point. However we cannot make the JSON file "special" because it is also meant to be read by web browsers and other external tools. By using unsupported syntax in JSON we would break all of them (except the `asciinema` recorder/player).

kerem commented

2026-03-15 08:56:58 +03:00

Author

Owner

@pdfkungfoo commented on GitHub (Jun 30, 2015):

I was not aware that web browsers read (and process) the JSON directly.

Which ones would that be? On what occasions?

Also, which "other external tools" are you aware of that can replay asciinema JSON files?

@pdfkungfoo commented on GitHub (Jun 30, 2015): I was not aware that web browsers read (and process) the JSON directly. Which ones would that be? On what occasions? Also, which _"other external tools"_ are you aware of that can replay `asciinema` JSON files?

kerem commented

2026-03-15 08:57:03 +03:00

Author

Owner

@ku1ik commented on GitHub (Jul 1, 2015):

The asciinema player will soon be able to play asciicast directly from JSON file produced by the recorder, allowing for easy self hosting (asciinema.js + your-recording.json). It's not yet there but will be soon. One of the reasons for choosing JSON for asciicast file format is it's good, native support by web browsers.

I'm not aware of any other players, but I can see some editing/optimizing tools coming and I want to make it easier for people by allowing to use standard, often built-in JSON parsers.

Also, see this: https://gist.github.com/sickill/1c44512cac222c8afea7

@ku1ik commented on GitHub (Jul 1, 2015): The asciinema player will soon be able to play asciicast directly from JSON file produced by the recorder, allowing for easy self hosting (asciinema.js + your-recording.json). It's not yet there but will be soon. One of the reasons for choosing JSON for [asciicast file format](http://blog.asciinema.org/post/one-point-o/) is it's good, native support by web browsers. I'm not aware of any other players, but I can see some editing/optimizing tools coming and I want to make it easier for people by allowing to use standard, often built-in JSON parsers. Also, see this: https://gist.github.com/sickill/1c44512cac222c8afea7

kerem commented

2026-03-15 08:57:08 +03:00

Author

Owner

@noisy commented on GitHub (Jul 21, 2015):

@KurtPfeifle @sickill maybe the solution would be to write a (maybe 3rd party) visual editor for screencasts. I think it should be possible to add ascii-callouts in specified places on the screen, which will be displayed on screencast for specified time.

@noisy commented on GitHub (Jul 21, 2015): @KurtPfeifle @sickill maybe the solution would be to write a (maybe 3rd party) visual editor for screencasts. I think it should be possible to add ascii-callouts in specified places on the screen, which will be displayed on screencast for specified time.

kerem commented

2026-03-15 08:57:13 +03:00

Author

Owner

@ku1ik commented on GitHub (Jul 21, 2015):

@noisy I think @KurtPfeifle is talking about different thing. If I'm getting this correctly what you described is "subtitle" support, with the data coming directly from the asciicast file (as an additional "overlay text track"). @KurtPfeifle wanted to put comments into the asciicast JSON file so he can navigate throughout the file easier, but these comments should be ignored during playback.

@ku1ik commented on GitHub (Jul 21, 2015): @noisy I think @KurtPfeifle is talking about different thing. If I'm getting this correctly what you described is "subtitle" support, with the data coming directly from the asciicast file (as an additional "overlay text track"). @KurtPfeifle wanted to put comments into the asciicast JSON file so he can navigate throughout the file easier, but these comments should be ignored during playback.

kerem commented

2026-03-15 08:57:18 +03:00

Author

Owner

@ku1ik commented on GitHub (Mar 26, 2016):

One option I see here to make editing easier is to use absolute time instead of relative one - would make finding the right spot much easier. We can discuss this in a separate issue though. As for adding comments to JSON, it's not going to happen.

@ku1ik commented on GitHub (Mar 26, 2016): One option I see here to make editing easier is to use absolute time instead of relative one - would make finding the right spot much easier. We can discuss this in a separate issue though. As for adding comments to JSON, it's not going to happen.

kerem commented

2026-03-15 08:57:23 +03:00

Author

Owner

@pdfkungfoo commented on GitHub (Mar 26, 2016):

I would not like absolute time, because some of my editing modifications also spans changing the timings.

To get this "right" would be much more difficult with absolute times. (Currently, I can speed up or slow down individual lines by just overwriting one digit at the right spot...)

@pdfkungfoo commented on GitHub (Mar 26, 2016): I would not like absolute time, because some of my editing modifications also spans changing the timings. To get this "right" would be much more difficult with absolute times. (Currently, I can speed up or slow down individual lines by just overwriting one digit at the right spot...)

kerem commented

2026-03-15 08:57:29 +03:00

Author

Owner

@pdfkungfoo commented on GitHub (Mar 26, 2016):

So, it is too difficult to make the asciinema playback tolerant of sprinkled in comment lines? (These could also be automatically removed upon publication.)

@pdfkungfoo commented on GitHub (Mar 26, 2016): So, it is too difficult to make the asciinema playback tolerant of sprinkled in comment lines? (These could also be automatically removed upon publication.)

kerem commented

2026-03-15 08:57:34 +03:00

Author

Owner

@ku1ik commented on GitHub (Mar 26, 2016):

JSON doesn't support comments and we use default JSON parsers for loading the recording - Go's stdlib JSON parser (when you asciinema play file.json in terminal), and web browsers' own JSON parsers when playing in the web player.

Alternative could be to support additional file format, for example edn, which is human readable and supports commenting.

@ku1ik commented on GitHub (Mar 26, 2016): JSON doesn't support comments and we use default JSON parsers for loading the recording - Go's stdlib JSON parser (when you `asciinema play file.json` in terminal), and web browsers' own JSON parsers when playing in the web player. Alternative could be to support additional file format, for example [edn](https://github.com/edn-format/edn), which is human readable and supports commenting.

kerem commented

2026-03-15 08:57:39 +03:00

Author

Owner

@pdfkungfoo commented on GitHub (Mar 26, 2016):

It would be "good enough" to make asciinema play file.json tolerant for commented lines.

Couldn't it be implemented by a two-stage approach:

filtering out comments from the non-standard JSON (using a simple grep -v-alike routine) before
handing over the filtered standard JSON to the currently used JSON parser

?

Sorry if this sound dumb -- I'm not a programmer.

@pdfkungfoo commented on GitHub (Mar 26, 2016): It would be "good enough" to make `asciinema play file.json` tolerant for commented lines. Couldn't it be implemented by a two-stage approach: 1. filtering out comments from the non-standard JSON (using a simple `grep -v`-alike routine) before 2. handing over the filtered standard JSON to the currently used JSON parser ? Sorry if this sound dumb -- I'm not a programmer.

kerem commented

2026-03-15 08:57:44 +03:00

Author

Owner

@ku1ik commented on GitHub (Mar 26, 2016):

You can do it now like this:

grep -v "..." file.json | asciinema play -
grep -v "..." file.json | asciinema upload -

@ku1ik commented on GitHub (Mar 26, 2016): You can do it now like this: ``` grep -v "..." file.json | asciinema play - grep -v "..." file.json | asciinema upload - ```

kerem commented

2026-03-15 08:57:49 +03:00

Author

Owner

@pdfkungfoo commented on GitHub (Mar 26, 2016):

Ouuuhhhh....

Thanks a lot. That's probably good enough for me. ;-)

I'll give it a workout soon.

(I had not been aware that asciinema could work with input...)

@pdfkungfoo commented on GitHub (Mar 26, 2016): Ouuuhhhh.... Thanks a lot. That's probably good enough for me. ;-) I'll give it a workout soon. (I had not been aware that `asciinema` could work with <stdin> input...)

kerem referenced this issue

2026-03-15 11:23:53 +03:00

[PR #703] [MERGED] Bump tempfile from 3.20.0 to 3.23.0 #1197

Rows
Columns

[GH-ISSUE #117] [Feature request] Allow some sort of "commenting" inside the asciinema JSON #703