[GH-ISSUE #224] asciicast v2: file extension and media type

kerem commented

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

Owner

Originally created by @ku1ik on GitHub (Sep 4, 2017).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/224

We used .json for v1 asciicasts, but I wouldn't use it with v2 as json-lines/ndjson is not JSON.parse-able. Each line is json-parsable, the whole thing is not, so using .json would send false message to users and/or tools.

From what I understand json-lines spec and ndjson spec allow each to be any JSON value, which means our format of first header line (object) + subsequent event lines (arrays) conforms to them. So I'd rather go with .jsonl or .ndjson rather than just .json.

I'd consider going even further with this: use new media type (content-type), something like application/vnd.asciicast.v2, and a file extension like .cast. The reasoning behind using custom media-type/extension is: if you see file with .jsonl ext, how do you know it's asciicast and not Hadoop/Spark dataset or other thing? Any json-lines supporting tool (like jq) can read and process .jsonl files with the assumption that each line represents distinct and equal entry ({...} object in 99% of cases). We use { ... } only in the first line, and [...] in all subsequent lines, and processing such file with generic .jsonl tools would probably not work (easily) anyway. So using custom extension would give it domain-specific meaning, saying "this is asciicast v2", and the v2 spec would say "it's encoded as json-lines, with the following meaning of lines: ...".

Originally created by @ku1ik on GitHub (Sep 4, 2017). Original GitHub issue: https://github.com/asciinema/asciinema/issues/224 We used `.json` for v1 asciicasts, but I wouldn't use it with v2 as json-lines/ndjson is not `JSON.parse`-able. Each line is json-parsable, the whole thing is not, so using `.json` would send false message to users and/or tools. From what I understand [json-lines spec](http://jsonlines.org/) and [ndjson spec](https://github.com/ndjson/ndjson-spec) allow each to be any JSON value, which means our format of first header line (object) + subsequent event lines (arrays) conforms to them. So I'd rather go with `.jsonl` or `.ndjson` rather than just `.json`. I'd consider going even further with this: use new media type (content-type), something like `application/vnd.asciicast.v2`, and a file extension like `.cast`. The reasoning behind using custom media-type/extension is: if you see file with `.jsonl` ext, how do you know it's asciicast and not Hadoop/Spark dataset or other thing? Any json-lines supporting tool (like [jq](https://stedolan.github.io/jq/)) can read and process `.jsonl` files with the assumption that each line represents distinct and equal entry (`{...}` object in 99% of cases). We use `{ ... }` only in the first line, and `[...]` in all subsequent lines, and processing such file with generic `.jsonl` tools would probably not work (easily) anyway. So using custom extension would give it domain-specific meaning, saying "this is asciicast v2", and the v2 spec would say "it's encoded as json-lines, with the following meaning of lines: ...".

kerem closed this issue

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

kerem commented

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

Author

Owner

@dhobsd commented on GitHub (Sep 4, 2017):

I agree with the idea of introducing a new MIME type. Perhaps ".tcast" for the extension and "vnd.termcast" for the type? I know the thing is called asciicast right now, but it actually isn't ascii.

@dhobsd commented on GitHub (Sep 4, 2017): I agree with the idea of introducing a new MIME type. Perhaps ".tcast" for the extension and "vnd.termcast" for the type? I know the thing is called asciicast right now, but it actually isn't ascii.

kerem commented

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

Author

Owner

@ku1ik commented on GitHub (Sep 4, 2017):

@dhobsd not sure I see your point about it not being ascii. Of course it's not 7-bit ascii but utf-8 encoded stdout stream, so in that regard I agree. But "ascii" may be a synonym for text in geek circles, and it definitely sends the "this is text, not some pixels" message imho.

As for the name "asciicast", I like it, but due to the tool name "asciinema" and the hosted recording URLs like "asciinema.org/a/12345" many people call the recordings "asciinemas" ¯_(ツ)_/¯
So it even crossed my mind to officially call them asciinemas to make things simpler. But not quite convinced if that's a good idea :)

For "termcast" name, there's termcast.org, which is a telnet, tty-based (if I understand correctly) streaming server - I'm not comfortable with hijacking existing names (is this a popular site?). I do like the name though, and the term "termcasting" feels more to the point than "asciicasting" for sure.

@ku1ik commented on GitHub (Sep 4, 2017): @dhobsd not sure I see your point about it not being ascii. Of course it's not 7-bit ascii but utf-8 encoded stdout stream, so in that regard I agree. But "ascii" may be a synonym for text in geek circles, and it definitely sends the "this is text, not some pixels" message imho. As for the name "asciicast", I like it, but due to the tool name "asciinema" and the hosted recording URLs like "asciinema.org/a/12345" many people call the recordings "asciinemas" ¯\_(ツ)_/¯ So it even crossed my mind to officially call them asciinemas to make things simpler. But not quite convinced if that's a good idea :) For "termcast" name, there's termcast.org, which is a telnet, tty-based (if I understand correctly) streaming server - I'm not comfortable with hijacking existing names (is this a popular site?). I do like the name though, and the term "termcasting" feels more to the point than "asciicasting" for sure.

kerem commented

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

Author

Owner

@XANi commented on GitHub (Sep 5, 2017):

Well term "asciicast" already googles main page of ascinema. And it is shorter and easier to say ;)

Also you "cast" "ascii" on "cinema" screen. IMO asciicast fits very well

@dhobsd arguably it should ANSICast as those are control codes making terms pretty. But asciinema/asciicast is name unique enough that it googles well so I doubt changing it have any useful benefits

@XANi commented on GitHub (Sep 5, 2017): Well term "asciicast" already googles main page of ascinema. And it is shorter and easier to say ;) Also you "cast" "ascii" on "cinema" screen. IMO asciicast fits very well @dhobsd arguably it should ANSICast as those are control codes making terms pretty. But asciinema/asciicast is name unique enough that it googles well so I doubt changing it have any useful benefits

kerem commented

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

Author

Owner

@josegonzalez commented on GitHub (Sep 20, 2017):

I like asciicast. In my head, asciinema is the name of the website that shows asciicasts. If anything, the recorder should be renamed asciicorder or something :P

@josegonzalez commented on GitHub (Sep 20, 2017): I like `asciicast`. In my head, asciinema is the name of the website that shows `asciicasts`. If anything, the recorder should be renamed `asciicorder` or something :P

kerem commented

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

Author

Owner

@pdfkungfoo commented on GitHub (Nov 1, 2017):

Question for @sickill :

Would you re-consider my previous feature request #117 for asciicast v2 ?

(In #117 I had been asking for a way to put comments into the file. I wanted to make it easier to navigate the file while editing it with a text editor.)

@pdfkungfoo commented on GitHub (Nov 1, 2017): Question for @sickill : Would you re-consider my previous feature request #117 for asciicast v2 ? (In #117 I had been asking for a way to put comments into the file. I wanted to make it easier to navigate the file while editing it with a text editor.)

kerem commented

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

Author

Owner

@ku1ik commented on GitHub (Nov 1, 2017):

@KurtPfeifle I see the point, however this doesn't seem like an essential feature for most of the users, and it would add extra complexity across the whole stack (recorder and cli player, web player, server). Maybe you could just create wrapper scripts/aliases like asciinema-play, asciinema-upload, which would filter out comments, and then pass the result to actual asciinema play/upload?

@ku1ik commented on GitHub (Nov 1, 2017): @KurtPfeifle I see the point, however this doesn't seem like an essential feature for most of the users, and it would add extra complexity across the whole stack (recorder and cli player, web player, server). Maybe you could just create wrapper scripts/aliases like `asciinema-play`, `asciinema-upload`, which would filter out comments, and then pass the result to actual `asciinema play/upload`?

kerem commented

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

Author

Owner

@XANi commented on GitHub (Nov 2, 2017):

#117 really seems like an ugly workaround, the more useful way to do it IMO would be just having an app or option to generate map of file (time:line) which is pretty trivial with new format.

Or player to have option to return "current line played". Once you have line you could even have "open editor at point" command which just does $EDITOR +$lineNo $filename, altho that's probably a bit of feature creep for a player

@XANi commented on GitHub (Nov 2, 2017): #117 really seems like an ugly workaround, the more useful way to do it IMO would be just having an app or option to generate map of file (time:line) which is pretty trivial with new format. Or player to have option to return "current line played". Once you have line you could even have "open editor at point" command which just does `$EDITOR +$lineNo $filename`, altho that's probably a bit of feature creep for a player

kerem commented

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

Author

Owner

@perlun commented on GitHub (Feb 20, 2021):

Late to the party, but I do agree with @KurtPfeifle that filtering out comments in asciinema-player would be slightly useful. If this feature ever would get implemented, I would suggest using standard // Javascript-style comments for this.

(I know comments are not valid JSON, but they are valid jsonc. 😉)

@perlun commented on GitHub (Feb 20, 2021): Late to the party, but I do agree with @KurtPfeifle that filtering out comments in `asciinema-player` would be slightly useful. If this feature ever would get implemented, I would suggest using standard `//` Javascript-style comments for this. (I know comments are not valid JSON, but they are valid `jsonc`. :wink:)

kerem referenced this issue

2026-03-15 10:08:41 +03:00

[GH-ISSUE #165] poor fish shell support/documentation #740

Rows
Columns

[GH-ISSUE #224] asciicast v2: file extension and media type #165