[Proposal] Add getWallClockOffset API

[peaBerberian]

I was lately working on an application relying on the RxPlayer at Canal+, and trying to see how our upcoming thumbnail API ( #1496 ) could be integrated in their projects.

I found out that this application relied only on getWallClockTime for storing the current playback position.
The value returned by this method is basically the current position offseted so it corresponds to the unix timestamp at which the corresponding media data was intended to be broadcasted.

In other words, doing new Date(wallClockTime * 1000) will translate that position into the corresponding date, whereas our getPosition API, returns a more arbitrary timestamp without special meaning, that we will call here the "media position" (it is the actual position advertised by the HTML video element in the page).

Applications like to use the wallClockTime for live contents as this allows to display a seeking bar with the date in an e.g. hours:minutes:seconds format which is much more useful to a final user than a timestamp without any special meaning.
We even also rely on wallClockTime ourselves on the demo page.

However, most other RxPlayer API rely on the media position instead. For example, getAvailablePeriods, getMinimumPosition, getLiveEdge and future thumbnail API all will provide timestamp in the "meaningless" media position format.

---

Converting from the wallClockTime to the "media position" and vice-versa was awkward before, you basically had to re-call player.getWallClockTime() - player.getPosition() to obtain the difference and thus to convert the wallClockTime you're using in your application into a media position you can use more easily with the RxPlayer API.

Instead, I propose here to add the player.getWallClockOffset() API, which returns that difference in a more explicit way.

You can then do something like:

function compareWithMaximumPosition(wallClockTime) {
  const wallClockOffset = rxPlayer.getWallClockOffset();
  const currentPosition = wallClockTime - wallClockOffset;

  const maximumPosition = rxPlayer.getMaximumPosition();
  const deltaFromMax = maximumPosition - currentPosition;
  console.log(
    `We are ${deltaFromMax} seconds behind the maximum seekable position`,
  );
}

Which makes more sense and seems feels more stable than randomly re-obtaining the same offset by doing:

const wallClockOffset = player.getWallClockTime() - player.getPosition();

Note that we could have added a rxPlayer.toMediaPosition(wallClockTime) method instead, which may be even more easily discoverable, but I found getWallClockOffset more useful and still approachable.

[github-actions]

Automated performance checks have been performed on commit 6f029dc1f30fe02be018efc61cd6d4ba3ae5ce7c with the base branch dev.

Tests results

✅ Tests have passed.

Performance tests 1st run output

No significative change in performance for tests:

Name	Mean	Median
loading	19.47ms -> 19.46ms (0.013ms, z: 0.55837)	27.00ms -> 27.00ms
seeking	11.37ms -> 14.73ms (-3.361ms, z: 0.64321)	11.40ms -> 11.40ms
audio-track-reload	26.13ms -> 26.16ms (-0.029ms, z: 0.07877)	38.40ms -> 38.40ms
cold loading multithread	48.75ms -> 47.21ms (1.538ms, z: 11.17500)	70.35ms -> 69.30ms
seeking multithread	11.98ms -> 13.30ms (-1.314ms, z: 0.42041)	10.65ms -> 10.50ms
audio-track-reload multithread	26.12ms -> 25.93ms (0.189ms, z: 3.28502)	38.55ms -> 38.25ms
hot loading multithread	15.43ms -> 15.41ms (0.021ms, z: 1.23150)	22.50ms -> 22.35ms

If you want to skip performance checks for latter commits, add the skip-performance-checks label to this Pull Request.