starred/asciinema

Fork 0

mirror of https://github.com/asciinema/asciinema.git synced 2026-04-26 00:15:56 +03:00

[GH-ISSUE #712] Cumulative rounding error in v3 format inter-event time-deltas #972

New issue

Closed

opened 2026-03-15 11:10:55 +03:00 by kerem · 4 comments

kerem commented

2026-03-15 11:10:55 +03:00

Owner

Originally created by @finite-state-machine on GitHub (Oct 27, 2025).
Original GitHub issue: https://github.com/asciinema/asciinema/issues/712

Pre-submission checks

I have searched existing issues and this bug has not been reported yet
This is a bug report for asciinema CLI (not player or server)

Bug Description

My quick read of the code suggests the current implementation suffers from accumulating rounding errors in event timestamps. In any case this is a very easy mistake to make when implementing the v3 format, and should be documented in the format description.

Assume timestamps are stored with millisecond precision (seconds with three decimal places; currently the default). If a recurring event happens every ~10.4 ms (e.g., "processing item 12345/99999"), the rounded interval between these events will consistently be ~0.4ms less than the actual value. Over time, these errors add up: after an hour, this difference of 4% would cause the recording to end more than two minutes early.

That probably doesn't matter very much for a single session in isolation, but would make it very difficult to "line up" two or more recordings of simultaneously running, interacting processes, or a terminal capture and a log file.

I suggest the following changes:

prevent accumulating rounding errors as follows:
- keep a sum of the rounded time-deltas as written
- compute inter-event time-delta as clock_time - recording_start_time - sum_of_previously_written_deltas, rather than clock_time - last_event_clock_time
document this easy-to-make mistake in the v3 format description

Steps to Reproduce

Note: I'm happy to prepare a script that reproduces this issue on request. As there are no relevant references to "rounding" in any of asciinema's github repos/issues/etc., I'm not sure a repro would add any value to this report.

Expected Behavior

The sum of inter-event time-deltas should equal the actual duration of the recording, ±1 count (least significant figure).

Operating System

N/A

asciinema CLI Version

(Code inspection on 2025-10-27)

Installation Method

Other

Terminal Information

N/A

Additional Context

No response

Originally created by @finite-state-machine on GitHub (Oct 27, 2025). Original GitHub issue: https://github.com/asciinema/asciinema/issues/712 ### Pre-submission checks - [x] I have searched existing issues and this bug has not been reported yet - [x] This is a bug report for asciinema CLI (not player or server) ### Bug Description My quick read of the code suggests the current implementation suffers from accumulating rounding errors in event timestamps. In any case this is a very easy mistake to make when implementing the v3 format, and should be documented in the format description. Assume timestamps are stored with millisecond precision (seconds with three decimal places; currently the default). If a recurring event happens every ~10.4 ms (e.g., "processing item 12345/99999"), the rounded interval between these events will consistently be ~0.4ms less than the actual value. Over time, these errors add up: after an hour, this difference of 4% would cause the recording to end more than two minutes early. That probably doesn't matter very much for a single session in isolation, but would make it very difficult to "line up" two or more recordings of simultaneously running, interacting processes, or a terminal capture and a log file. I suggest the following changes: - prevent accumulating rounding errors as follows: - keep a sum of the _rounded_ time-deltas _as written_ - compute inter-event time-delta as `clock_time - recording_start_time - sum_of_previously_written_deltas`, rather than `clock_time - last_event_clock_time` - document this easy-to-make mistake in the v3 format description ### Steps to Reproduce _**Note:** I'm happy to prepare a script that reproduces this issue on request. As there are no relevant references to "rounding" in any of asciinema's github repos/issues/etc., I'm not sure a repro would add any value to this report._ ### Expected Behavior The sum of inter-event time-deltas should equal the actual duration of the recording, ±1 count (least significant figure). ### Operating System N/A ### asciinema CLI Version (Code inspection on 2025-10-27) ### Installation Method Other ### Terminal Information N/A ### Additional Context _No response_

kerem closed this issue

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

kerem commented

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

Author

Owner

@ku1ik commented on GitHub (Oct 27, 2025):

Looks like you haven't read the source code too closely :) And if you actually tried to create a repro you would find that your assumption is wrong.

The time delta is calculated between Duration objects, which have nanosecond precision. Then the delta is quantized to milliseconds using error diffusion algorithm ("carry-over the quantization error").

See here:

@ku1ik commented on GitHub (Oct 27, 2025): Looks like you haven't read the source code too closely :) And if you actually tried to create a repro you would find that your assumption is wrong. The time delta is calculated between `Duration` objects, which have nanosecond precision. Then the delta is quantized to milliseconds using error diffusion algorithm ("carry-over the quantization error"). See here: - https://github.com/asciinema/asciinema/blob/43584efc154648cd46d6e5b2960499bd7e0b8925/src/asciicast/v3.rs#L227-L229 - https://github.com/asciinema/asciinema/blob/43584efc154648cd46d6e5b2960499bd7e0b8925/src/util.rs#L96-L179

kerem commented

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

Author

Owner

@finite-state-machine commented on GitHub (Oct 27, 2025):

Looks like you haven't read the source code too closely :) And if you actually tried to create a repro you would find that your assumption is wrong.

The time delta is calculated between Duration objects, which have nanosecond precision. Then the delta is quantized to milliseconds using error diffusion algorithm ("carry-over the quantization error").

Thanks for this! I'm impressed; I suspect many developers would have overlooked this. (It was a very quick read of the code, and I don't actually speak Rust.)

Is it worth documenting this on the format description page? And, perhaps, mentioning "rounding" as ~synonym for "quantization" at least once in the code, to facilitate searching?

@finite-state-machine commented on GitHub (Oct 27, 2025): > Looks like you haven't read the source code too closely :) And if you actually tried to create a repro you would find that your assumption is wrong. > > The time delta is calculated between `Duration` objects, which have nanosecond precision. Then the delta is quantized to milliseconds using error diffusion algorithm ("carry-over the quantization error"). Thanks for this! I'm impressed; I suspect many developers would have overlooked this. (It was a _very_ quick read of the code, and I don't actually speak Rust.) Is it worth documenting this on the format description page? And, perhaps, mentioning "rounding" as ~synonym for "quantization" at least once in the code, to facilitate searching?

kerem commented

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

Author

Owner

@finite-state-machine commented on GitHub (Oct 27, 2025):

(To be honest: I figured this project's devs would know, without looking, whether this was an issue or not. Given that, preparing a repro didn't seem like a good use of time.)

I'd also like to thank you @ku1ik and the rest of the asciinema team for all the hard work that's gone into this very helpful tool. It's appreciated! 🥰

@finite-state-machine commented on GitHub (Oct 27, 2025): (To be honest: I figured this project's devs would know, without looking, whether this was an issue or not. Given that, preparing a repro didn't seem like a good use of time.) I'd also like to thank you @ku1ik and the rest of the asciinema team for all the hard work that's gone into this very helpful tool. It's appreciated! 🥰

kerem commented

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

Author

Owner

@ku1ik commented on GitHub (Oct 27, 2025):

Is it worth documenting this on the format description page?

Yeah, good suggestion. I'll make a note about this.

I'd also like to thank you @ku1ik and the rest of the asciinema team for all the hard work that's gone into this very helpful tool. It's appreciated! 🥰

My pleasure :)

@ku1ik commented on GitHub (Oct 27, 2025): > Is it worth documenting this on the format description page? Yeah, good suggestion. I'll make a note about this. > I'd also like to thank you @ku1ik and the rest of the asciinema team for all the hard work that's gone into this very helpful tool. It's appreciated! 🥰 My pleasure :)