Timestamps guide #1033
Open
Timestamps guide #1033
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Noarkhh
added
the
no-changelog
Noarkhh
force-pushed
the
dynamic-pads-guide
branch
from
7548f9e to
b8872bf
Compare
Noarkhh
force-pushed
the
timestamps-guide
branch
from
304ef61 to
0bd2ef7
Compare
Noarkhh
force-pushed
the
dynamic-pads-guide
branch
from
b8872bf to
3262a1e
Compare
Noarkhh
force-pushed
the
dynamic-pads-guide
branch
2 times, most recently
from
9841fae to
b4539b0
Compare
Noarkhh
force-pushed
the
timestamps-guide
branch
from
0bd2ef7 to
a62cba5
Compare
mat-hek
reviewed
Jan 7, 2026
Member
mat-hek
left a comment
mat-hek
left a comment
There was a problem hiding this comment.
Sounds great. I'm missing some summary/guidelines, that would emphasise that:
- DTS should always be monotonic, while PTS for video with B-frames can be non-monotonic
- Filters should always forward timestamps
- If a filter doesn't use timestamps, it should forward them, but not rely on them being set
- Sources should attach timestamps to buffers whenever they're known
- Whenever possible, elements should rely on timestamps instead of framerate or audio duration calculated from the stream
- If an element queues buffers in its state (or uses a library that does so), it should make sure that the timestamps for the output buffers are the same as for the corresponding input buffers
- You should make sure that calculations on timestamps don't introduce an accumulating error. Prefer using rationals (Ratio library) to floats.
- Elements should generate deterministic output timestamps for better testability
- If an element transforms N input buffers into M output buffers, each of the output buffers should have either:
- the timestamp of the first of the input buffers (even if only a part of it was used to construct the output buffers)
- more precise timestamps, if it's possible to calculate them
- Timestamps are harder than they seem and are the source of many bugs, including:
- Audio/video desynchronization
- Stream hanging (due to waiting indefinitely to process/play a buffer because of a wrong timestamp)
- Stream stalls (e.g. due to processing a real-time stream slightly faster than real time)
- Memory leaks (e.g. due to processing a real-time stream slightly slower than real time and indefinite buffering)
- Video flickering (due to incorrect handling of B-frames)
- Audio cracking
Therefore, the operations on timestamps should be given a lot of care and be well-tested
guides/useful_concepts/timestamps.md
Outdated
| @@ -0,0 +1,100 @@ | |||
| # Timestamps | |||
|
|
|||
| In a nutshell, timestamps determine when a given event occurred in time. For | |||
Member
There was a problem hiding this comment.
Suggested change
| In a nutshell, timestamps determine when a given event occurred in time. For | |
| In a nutshell, timestamps determine when a given event occurred (or should occur) in time. For |
guides/useful_concepts/timestamps.md
Outdated
| send them over as fast as possible, which is not something we want. We want the receiver | ||
| to get the stream in realtime, so that they can display it as it comes. | ||
|
|
||
| ## Decoding Time Stamps |
Member
There was a problem hiding this comment.
Suggested change
| ## Decoding Time Stamps | |
| ## Decode Time Stamps (DTS) |
FelonEkonom
approved these changes
Jan 8, 2026
| [Realtimer](https://hexdocs.pm/membrane_realtimer_plugin/Membrane.Realtimer.html) | ||
| is an element from | ||
| [membrane_realtimer_plugin](https://hex.pm/packages/membrane_realtimer_plugin). | ||
| It takes in a stream and limits its flow according to its PTSs. For example, if |
Member
There was a problem hiding this comment.
Not really, it will take dts || pts
| should make sure that the timestamps for the output buffers are the same as for | ||
| the corresponding input buffers. | ||
| * You should ensure that calculations on timestamps don't introduce an | ||
| accumulating error. Prefer using rationals (Ratio library) to floats. |
| to create a term representing three seconds, we call `Membrane.Time.seconds(3)`. | ||
| * To read the amount of time represented, we can use `Membrane.Time.as_<unit>/2` | ||
| functions. For example, to get an amount of milliseconds represented by a time, | ||
| we call `Membrane.Time.as_milliseconds(some_time)` |
Member
There was a problem hiding this comment.
Membrane.Time.as_milliseconds/1? It would generate a link to as_milliseconds docs, I guess
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.