Timestamps guide

Author: Noarkhh

guides/useful_concepts/timestamps.md

@@ -0,0 +1,44 @@
+# Timestamps - the stamps in time
+
+In a nutshell, timestamps determine when a given event occurred in time. For
+example when you take a photo with your phone, the exact time and date the photo
+is taken is recorded - it's a timestamp. When dealing with media we also need a
+way to tell when different things need to happen. In Membrane we use two most
+common types of timestamps:
+
+* PTS (Presentation Time Stamp) - determines when the media should be
+  displayed.
+* DTS (Decoding Time Stamp) - information for the decoder when the media should
+  be decoded.
+
+## Time in Membrane
+
+We know that timestamps represent the time of occurrence of an event, but these
+concepts are pretty abstract. We need to somehow represent them in the context
+of our framework. To represent time - durations, latencies, timestamps, - we
+use terms of type `t:Membrane.Time.t/0`:
+
+* To create a term representing some amount of time, we use
+  `Membrane.Time.<unit>/0` and `Membrane.Time.<unit>s/1` functions. For example 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)`
+
+## Carriers of timestamps
+
+We now have a way to represent timestamps, but to be useful they have to refer
+to something, an event of some sort. As you probably know, media streams in
+Membrane are sent between elements packaged in
+[Buffers](`t:Membrane.Buffer.t/0`). As we can see in the specification, a buffer
+is a struct with 4 fields:
+
+* `:payload` - data contained in the buffer
+* `:pts` and `:dts` - timestamps assigned to the buffer
+* `:metadata` - metadata describing the contents of the buffer
+
+Buffers often correspond to some units which the stream is composed of, for
+example video frames in raw video streams or RTP packets in RTP streams.
+These units are the perfect fits to have timestamps assigned to them - and in
+most cases they do. For example, a PTS assigned to a buffer containing a
+raw video frame determines then the frame should be displayed.

mix.lock

@@ -1,7 +1,7 @@
 %{
   "bunch": {:hex, :bunch, "1.6.1", "5393d827a64d5f846092703441ea50e65bc09f37fd8e320878f13e63d410aec7", [:mix], [], "hexpm", "286cc3add551628b30605efbe2fca4e38cc1bea89bcd0a1a7226920b3364fe4a"},
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
-  "coerce": {:hex, :coerce, "1.0.1", "211c27386315dc2894ac11bc1f413a0e38505d808153367bd5c6e75a4003d096", [:mix], [], "hexpm", "b44a691700f7a1a15b4b7e2ff1fa30bebd669929ac8aa43cffe9e2f8bf051cf1"},
+  "coerce": {:hex, :coerce, "1.0.2", "5ef791040c92baaa5dd344887563faaeac6e6742573a167493294f8af3672bbe", [:mix], [], "hexpm", "0b3451c729571234fdac478636c298e71d1f2ce1243abed5fa43fa3181b980eb"},
   "credo": {:hex, :credo, "1.7.10", "6e64fe59be8da5e30a1b96273b247b5cf1cc9e336b5fd66302a64b25749ad44d", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "71fbc9a6b8be21d993deca85bf151df023a3097b01e09a2809d460348561d8cd"},
   "dialyxir": {:hex, :dialyxir, "1.4.5", "ca1571ac18e0f88d4ab245f0b60fa31ff1b12cbae2b11bd25d207f865e8ae78a", [:mix], [{:erlex, ">= 0.2.7", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "b0fb08bb8107c750db5c0b324fa2df5ceaa0f9307690ee3c1f6ba5b9eb5d35c3"},
   "earmark_parser": {:hex, :earmark_parser, "1.4.44", "f20830dd6b5c77afe2b063777ddbbff09f9759396500cdbe7523efd58d7a339c", [:mix], [], "hexpm", "4778ac752b4701a5599215f7030989c989ffdc4f6df457c5f36938cc2d2a2750"},