doc/clock.md

   1 # Clock Architecture
   2
   3 ## Introduction
   4
   5 This document presents the new clock archictecture for **VLC**, starting from
   6 VLC 4.0.
   7
   8 The clock is the element that manages the synchronisation of all [ES][ES],
   9 notably audio and video (+subtitles) synchronization.
  10
  11 While it can seem simple, at first glance, this part is not trivial, because
  12 one must take care of numerous clocks in parallel, and they can be out-of-sync:
  13 for example, your audio clock and your system clock are not necessary in-sync.
  14 This is the same issue between your streamer's clock and your player's clock.
  15 And most clocks drift.
  16
  17 [PCR]: #f  "Program Clock Reference"
  18 [PTS]: #f  "Presentation TimeStamp"
  19 [DTS]: #f  "Decoding TimeStamp"
  20 [ES]: #f "Elementary streams, aka Tracks"
  21
  22 ### Old clock system
  23
  24 The old clock from VLC was mainly an "*input clock*", based on the [input
  25 PCR][PCR] (from the file), inherited from the time where VLC was mostly a
  26 **MPEG-2/TS** player on the network. This is the correct clock for streaming,
  27 and notably when your input format carries a [PCR][] or something similar.
  28
  29 This old clock is quite nice, but has quite a few shortcomings, notably it
  30 requires resampling of your audio output, even for local files or simple audio
  31 files.
  32
  33 It also rebases all the timings on the main input [PCR][], and it loses all the
  34 original [PTS][] (because it was adding the current computer date). This is
  35 notably an issue for transcoding (where it loses the original timestamps), for
  36 pausing (we need to keep rewriting the timestamps) and for frame-accuracy
  37 (because you know accurately only the input timings).
  38
  39 It also depends too much on having a valid input, which are very rare,
  40 unfortunately. And it does not work well with very large delays.
  41
  42 Finally, the UI seekbar advances only when the [PCR][] is updated, which makes
  43 big jumps in the seekbar, and is not smooth for the end-user. This notably
  44 happens with large-audio samples and is related to the file format.
  45
  46 ## New clock system
  47
  48 The idea of the new clock system is to have multiple pluggable clocks, one of
  49 which being the master clock, that could be selected depending on the
  50 situation.
  51
  52 For example, you could have an **audio master clock** *(local files)*, an
  53 **input PCR master clock** *(streaming)*, a **video master clock** *(V-Sync)*
  54 or a future **external clock** *(SDI, netsync...)*.  In the *audio master
  55 clock* mode, VLC would not resample the audio anymore.
  56
  57 As previously, there is one clock per input-program.  This **main clock** is
  58 therefore mostly at the es_out level and manages mostly the [PTS][] of all the
  59 Elementary Streams.
  60
  61 ### Different clocks: main, slave and master
  62
  63 Every output *(audio, video, stream)* has a clock, managed in the core. One of
  64 those clock is master, the other are slaves.
  65
  66 The main clock is the part managing the selection of the clocks and it will
  67 derivate the main timings from the system clock *(the monotonic clock)* and
  68 will provide those timings to the rest of VLC, including outputs, modules and
  69 interfaces.
  70
  71 It is currently an affine function based on the system clock, where the affine
  72 coefficients are the moving average of the coefficient computed from the master
  73 clock (In the future, it could be a different function).
  74
  75 The main clock holds a reference to all the output clocks, whether they are the
  76 master or one of the slaves. Please refer to the ***src/clock/clock.c*** for
  77 details about those structures
  78
  79 The master clock de facto defines the slope of the affine function.
  80
  81 The main clock will rebase the timestamps according to the master clock.  The
  82 slaves ask the main clock, what is the system time corresponding to their
  83 [PTS][].
  84
  85 If you want to see it differently, the master clock is a setter and the slave
  86 clocks are the getters.
  87
  88 ### Core outputs
  89
  90 The audio will be the master clock, in the nominal case.
  91
  92 ## Delays
  93
  94 One important feature is the delaying/hastening of [elementary streams][ES]
  95 with regards to other ES, also known as "Track Synchronization".
  96
  97 It's very hard to hasten ES, because most hardware decoders will not like that,
  98 and because often your decoder is already fully loaded (taking a lot of CPU).
  99
 100 Instead, we delay all the other [ES][] that are not in advance, by (sort of)
 101 **pausing** them. That means not displaying any new image for video outputs, or
 102 playing silence for audio outputs.
 103
 104 However, if we are in the case where the master output is the one that is in
 105 advance, pausing this output will break the main clock, and it will
 106 artificially drift.
 107
 108 The main clock needs therefore to be reset when you find the synchro again, aka
 109 when the output is "un-paused".