starred/asciinema

Fork 0

mirror of https://github.com/asciinema/asciinema.git synced 2026-04-25 07:55:51 +03:00

[GH-ISSUE #636] Proposals to `--append` recording mode improvements #330

New issue

Closed

opened 2026-02-25 20:33:21 +03:00 by kerem · 4 comments

kerem commented

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

Owner

Originally created by @anton-sergeev on GitHub (Jun 2, 2024).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/636

Hi all!

Used asciinema cli version: v2.4.0.

I recently discovered the --append recording flag and noticed following points/peculiarities in the places of gluing:

Sometime during playback, the first line of the second part appears at the end of last line of the first part. This occurs when the first part completes abnormally, i.e. without "newline" at last command written.
To solve this issue, I manually press Enter to inject "newline" into the recording file at the beginning of recording in --append mode.
If the size of the terminal changed while recording the two parts, it "fitted" incorrectly when played back.
To solve this issue, I manually resize the terminal at the beginning of recording in --append mode, which injects a "r" command into the recording file.

My proposal here is to automatically inject "newline" and "r" command into the recording file when running --append mode.

Another thing, is the timestamps in the recording file. No matter how much actual time has passed between two parts, the first commands of the second part timed as they were right after the end of the first part. Here is example (not real):

...
[71.662464, "o", "\u001b[1;34muser\u001b[0;31m@\u001b[1;34mhostname\u001b[m\u001b[0;32m/somewhere\u001b[0;31m$ \u001b[m"]
[73.126504, "o", "exit\r\n"]
// here is a gluing of sub-parts, see time-stamping here with minimal gap
[73.147615, "o", "\u001b[1;34muser\u001b[0;31m@\u001b[1;34mhostname\u001b[m\u001b[0;32m/somewhere\u001b[0;31m$ \u001b[m"]
[74.909581, "o", "\r\n"]
[74.909697, "o", "\u001b[1;34muser\u001b[0;31m@\u001b[1;34mhostname\u001b[m\u001b[0;32m/somewhere\u001b[0;31m$ \u001b[m"]
[75.586918, "r", "132x28"]
...

Finally, a quick search didn't get an answer on conceptual limitation of --append mode: should it support changing theme, title or other things from here? Or better to use separate recording in this cases?

Originally created by @anton-sergeev on GitHub (Jun 2, 2024). Original GitHub issue: https://github.com/asciinema/asciinema/issues/636 Hi all! Used **asciinema cli** version: **v2.4.0**. I recently discovered the `--append` recording flag and noticed following points/peculiarities in the places of gluing: * Sometime during playback, the first line of the second part appears at the end of last line of the first part. This occurs when the first part completes abnormally, i.e. without _"newline"_ at last command written. To solve this issue, I manually press `Enter` to inject _"newline"_ into the recording file at the beginning of recording in `--append` mode. * If the size of the terminal changed while recording the two parts, it _"fitted"_ incorrectly when played back. To solve this issue, I manually resize the terminal at the beginning of recording in `--append` mode, which injects a `"r"` command into the recording file. My proposal here is to automatically inject _"newline"_ and `"r"` command into the recording file when running `--append` mode. Another thing, is the timestamps in the recording file. No matter how much actual time has passed between two parts, the first commands of the second part timed as they were right after the end of the first part. Here is example (not real): ```jsonl ... [71.662464, "o", "\u001b[1;34muser\u001b[0;31m@\u001b[1;34mhostname\u001b[m\u001b[0;32m/somewhere\u001b[0;31m$ \u001b[m"] [73.126504, "o", "exit\r\n"] // here is a gluing of sub-parts, see time-stamping here with minimal gap [73.147615, "o", "\u001b[1;34muser\u001b[0;31m@\u001b[1;34mhostname\u001b[m\u001b[0;32m/somewhere\u001b[0;31m$ \u001b[m"] [74.909581, "o", "\r\n"] [74.909697, "o", "\u001b[1;34muser\u001b[0;31m@\u001b[1;34mhostname\u001b[m\u001b[0;32m/somewhere\u001b[0;31m$ \u001b[m"] [75.586918, "r", "132x28"] ... ``` Finally, a quick search didn't get an answer on conceptual limitation of `--append` mode: should it support changing _theme_, _title_ or other things [from here](https://docs.asciinema.org/manual/asciicast/v2/#optional-header-attributes)? Or better to use separate recording in this cases?

kerem closed this issue

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

kerem commented

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

Author

Owner

@ku1ik commented on GitHub (Jul 3, 2024):

Hey 👋

Sometime during playback, the first line of the second part appears at the end of last line of the first part. This occurs when the first part completes abnormally, i.e. without "newline" at last command written.
To solve this issue, I manually press Enter to inject "newline" into the recording file at the beginning of recording in --append mode.

While injecting a newline may seem like a solution it's not going to solve the problem for many situations where recording is stopped abruptly.

For example, when recording stops while there's a "full screen" program such as vim running, the terminal is left in a state which is far from the default, normal state a shell would expect - the active screen buffer could be set to alternate instead of primary (which doesn't have scrollback), the cursor may be hidden, the control sequence parser may be in some intermediate state expecting more parameters, etc etc. Just adding a newline won't revert those changes to the internal terminal state, and this will likely result in the initial output of the appended recording to produce garbage or other types of inaccurate positioning of printed text. In other words, adding a newline can help in some cases (e.g. when there were no full screen programs recorded), but will not solve it comprehensively.

Given the above I think it's not worth it to implement such workaround. If in your setup the probability of abrupt ending of a recording session is high then my suggestion is to not use --append and always recording to individual files.

If the size of the terminal changed while recording the two parts, it "fitted" incorrectly when played back.
To solve this issue, I manually resize the terminal at the beginning of recording in --append mode, which injects a "r" command into the recording file.

I think this is something we could add, it seems like a nice, low effort improvement. It would be ideal to insert the resize event only if window size is different than in the original recording. Also, actually, given the original recording might have resize events, to know if the window size changed we would need to use the last known window size instead of just the initial one in order to reliably check if the insertion of the new resize event is necessary. Either way, this sounds good 👍

Another thing, is the timestamps in the recording file. No matter how much actual time has passed between two parts, the first commands of the second part timed as they were right after the end of the first part.

This is by design. The idea for this behavior is that you can stop recording, prepare for another round, and resume recording, and the replayed session should look as if there wasn't any pause. In your example the difference between last event of the original recording (73.126504) and the first event of the appended recording (73.147615), which is ~0.02s is a time between the start of the 2nd recording session and the first output event. The appended events are just shifted by the last event time from the original recording (73.126504), i.e. 73.126504 is added to every new event time.

I guess we could introduce a new option which would allow specifying additional delay between the sessions, that would shift the new events farther 🤔

@ku1ik commented on GitHub (Jul 3, 2024): Hey :wave: > Sometime during playback, the first line of the second part appears at the end of last line of the first part. This occurs when the first part completes abnormally, i.e. without "newline" at last command written. To solve this issue, I manually press Enter to inject "newline" into the recording file at the beginning of recording in --append mode. While injecting a newline may seem like a solution it's not going to solve the problem for many situations where recording is stopped abruptly. For example, when recording stops while there's a "full screen" program such as vim running, the terminal is left in a state which is far from the default, normal state a shell would expect - the active screen buffer could be set to alternate instead of primary (which doesn't have scrollback), the cursor may be hidden, the control sequence parser may be in some intermediate state expecting more parameters, etc etc. Just adding a newline won't revert those changes to the internal terminal state, and this will likely result in the initial output of the appended recording to produce garbage or other types of inaccurate positioning of printed text. In other words, adding a newline can help in some cases (e.g. when there were no full screen programs recorded), but will not solve it comprehensively. Given the above I think it's not worth it to implement such workaround. If in your setup the probability of abrupt ending of a recording session is high then my suggestion is to not use `--append` and always recording to individual files. > If the size of the terminal changed while recording the two parts, it "fitted" incorrectly when played back. To solve this issue, I manually resize the terminal at the beginning of recording in --append mode, which injects a "r" command into the recording file. I think this is something we could add, it seems like a nice, low effort improvement. It would be ideal to insert the resize event only if window size is different than in the original recording. Also, actually, given the original recording might have resize events, to know if the window size changed we would need to use the last known window size instead of just the initial one in order to reliably check if the insertion of the new resize event is necessary. Either way, this sounds good :+1: > Another thing, is the timestamps in the recording file. No matter how much actual time has passed between two parts, the first commands of the second part timed as they were right after the end of the first part. This is by design. The idea for this behavior is that you can stop recording, prepare for another round, and resume recording, and the replayed session should look as if there wasn't any pause. In your example the difference between last event of the original recording (`73.126504`) and the first event of the appended recording (`73.147615`), which is ~0.02s is a time between the start of the 2nd recording session and the first output event. The appended events are just shifted by the last event time from the original recording (`73.126504`), i.e. `73.126504` is added to every new event time. I guess we could introduce a new option which would allow specifying additional delay between the sessions, that would shift the new events farther :thinking:

kerem commented

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

Author

Owner

@anton-sergeev commented on GitHub (Jul 3, 2024):

Another thing, is the timestamps in the recording file. No matter how much actual time has passed between two parts, the first commands of the second part timed as they were right after the end of the first part.

This is by design. The idea for this behavior is that you can stop recording, prepare for another round, and resume recording, and the replayed session should look as if there wasn't any pause. In your example the difference between last event of the original recording (73.126504) and the first event of the appended recording (73.147615), which is ~0.02s is a time between the start of the 2nd recording session and the first output event. The appended events are just shifted by the last event time from the original recording (73.126504), i.e. 73.126504 is added to every new event time.

In my use cases, it is very useful to be able to restore the absolute time for saved entries/records in record file.
So, actually my point here not a "little gap" but loss of the ability to reconstruct absolute timestamps.

For fixing big intervals between glued parts there is a idle-time-limit playback option (which I always use).

@anton-sergeev commented on GitHub (Jul 3, 2024): > > Another thing, is the timestamps in the recording file. No matter how much actual time has passed between two parts, the first commands of the second part timed as they were right after the end of the first part. > > This is by design. The idea for this behavior is that you can stop recording, prepare for another round, and resume recording, and the replayed session should look as if there wasn't any pause. In your example the difference between last event of the original recording (73.126504) and the first event of the appended recording (73.147615), which is ~0.02s is a time between the start of the 2nd recording session and the first output event. The appended events are just shifted by the last event time from the original recording (73.126504), i.e. 73.126504 is added to every new event time. In my use cases, it is very useful to be able to restore the absolute time for saved entries/records in record file. So, actually my point here not a "little gap" but loss of the ability to reconstruct absolute timestamps. For fixing big intervals between glued parts there is a `idle-time-limit` playback option (which I always use).

kerem commented

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

Author

Owner

@ku1ik commented on GitHub (Sep 11, 2025):

Quick update about recent improvements in the discussed areas:

The new asciicast v3 file format uses relative/delta time. This makes time adjustments way easier - for example, if you need to increase the delay between first and second concatenated recording you can change the time interval of the first event in the second recording before concatenating them. This is manual, so not ideal, but still an option (can be scripted though). I guess we could have a flag to enable concatenation mode where the subsequent recording base time uses offset from the header timestamp. I guess that's what you expected in the first place, right?

Regarding the terminal resizing - I modified how concat and --append work - they now inject "r" event automatically at join points between recordings.

@ku1ik commented on GitHub (Sep 11, 2025): Quick update about recent improvements in the discussed areas: The new [asciicast v3](https://docs.asciinema.org/manual/asciicast/v3/) file format uses relative/delta time. This makes time adjustments way easier - for example, if you need to increase the delay between first and second concatenated recording you can change the time interval of the first event in the second recording before concatenating them. This is manual, so not ideal, but still an option (can be scripted though). I guess we could have a flag to enable concatenation mode where the subsequent recording base time uses offset from the header timestamp. I guess that's what you expected in the first place, right? Regarding the terminal resizing - I modified how concat and `--append` work - they now inject `"r"` event automatically at join points between recordings.

kerem commented

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

Author

Owner

@anton-sergeev commented on GitHub (Sep 12, 2025):

Regarding the terminal resizing - I modified how concat and --append work - they now inject "r" event automatically at join points between recordings.

Super!

... I guess we could have a flag to enable concatenation mode where the subsequent recording base time uses offset from the header timestamp. I guess that's what you expected in the first place, right?

Yes, an extra flag for this behavior is ideal.

Off-topic:

The new asciicast v3 file format uses relative/delta time.

One of my use cases is for shell logging history (mentioned in the previous message). Sometimes I need to know when some commands were run, so I manually look for timestamps in the asciicast file. With the v3 delta times, this adds an extra step - calculating all time values from the beginning of the file.
And players, I suppose, should do the same when playback jumps to a random position.
Also, floating point calculations add errors, so the error will increase with the number of lines-records in the asciicast v3 file. This is not a big problem, just a pedantic note :)

Is there a public discussion somewhere about the new version of the file format?

@anton-sergeev commented on GitHub (Sep 12, 2025): > Regarding the terminal resizing - I modified how concat and --append work - they now inject "r" event automatically at join points between recordings. Super! > ... I guess we could have a flag to enable concatenation mode where the subsequent recording base time uses offset from the header timestamp. I guess that's what you expected in the first place, right? Yes, an extra flag for this behavior is ideal. --- Off-topic: > The new [asciicast v3](https://docs.asciinema.org/manual/asciicast/v3/) file format uses relative/delta time. One of my use cases is for shell logging history (mentioned in the [previous message](/asciinema/asciinema/issues/636#issuecomment-2205582826)). Sometimes I need to know when some commands were run, so I manually look for timestamps in the asciicast file. With the v3 delta times, this adds an extra step - calculating all time values from the beginning of the file. And players, I suppose, should do the same when playback jumps to a random position. Also, floating point calculations add errors, so the error will increase with the number of lines-records in the asciicast v3 file. This is not a big problem, just a pedantic note :) Is there a public discussion somewhere about the new version of the file format?

kerem referenced this issue

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

[PR #330] [MERGED] Change "how to stop recording" info message #434

kerem referenced this issue

2026-03-15 11:15:44 +03:00

[PR #330] [MERGED] Change "how to stop recording" info message #1046