[Proposal] Solution 1: PlaybackObserver is moved in src

Root issue
----------

While working on code refactoring for better taking into account the new
potentially multithread nature of the RxPlayer code (with some files
only running in a WebWorker environment and others only running in a
main thread environment), we recently refactored our file hierarchy
(#1365) to better reflect that new situation. The idea is to make
RxPlayer developpers more aware of what code is intended to run where.

In that work, we had a remaining issue concerning the
`PlaybackObserver`.
This is the part of the code that is monitoring and advertising playback
conditions to the rest of the RxPlayer code. Most core RxPlayer modules
rely on it, in both main thread and WebWorker environments.

The root issue is that the `PlaybackObserver` is a class and thus cannot
be easily transmitted in-between environments (as the main thread and
WebWorker only exchanges between one another through `postMessage`
calls, which follows some rules preventing from doing that).

As such, and only on a multithreaded scenario, the RxPlayer is
serializing in some way the constructed source PlaybackObserver in the
main thread to reconstruct one (the `WorkerPlaybackObserver`) on the
worker.

Because a whole complex PlaybackObserver-compatible structure has to
both be constructed in the main thread and in the worker (yet only the
main thread can act as the "true" source one, because the media element
can only be accessed in main thread), we were asking ourselves where
should we put the common utils (required by both the main thread and
worker) needed to construct one (like the `ObservationPosition` class
and the `generateReadOnlyObserver` util).

Solution 1
----------

This is a first solution proposal, which moves the `PlaybackObserver`
directory outside of the `main_thread` and `core` directories. Instead,
its code is now directly in `src/playback_observer`.

This solution takes inspiration from the `src/mse` directory, which also
exports both:

  1. files intended to be imported when MSE API are present in the
     current environment (when in main thread or when in a WebWorker
     with the MSE-in-worker feature) and

  2. files intended to be imported in environments without MSE.

For example the `src/mse/main_media_source_interface.ts` should __ONLY__
be imported in environments with MSE capabilities. If you do not, you
should import `src/mse/worker_media_source_interface.ts`.

Likewise, I here added a
`src/playback_observer/media_element_playback_observer.ts` file exporting
a `MediaElementPlaybackObserver` structure (new name of the
`PlaybackObserver`) which can only be imported in environements where the
media element is available (so, only on main thread) and a
`src/playback_observer/worker_playback_observer.ts` file which should only
be imported in other environments.

Doing this allows to easily share common utils, in a
`src/playback_observer/utils` directory, without involving the rest of
the RxPlayer code.

Result
------

I'm quite happy with the result, though I get it may seem weird to have
a complex core frequently-running logic part directly in `src` (and not
in `main_thread` or `core` as was the norm) - though it is also the case
of directories like `mse` or `transports`.

RxPlayer code very rarely imported files inside other directories (which
it does here with paths like
`../playback_observer/media_element_playback_observer`) as a way to
push better modularization. Though here it may seem like a feature
because its unusual-ness forces the developper to double check if this
is the right file that is imported.

src/core/adaptive/adaptive_representation_selector.ts

@@ -16,17 +16,17 @@
 
 import config from "../../config";
 import log from "../../log";
-import type {
-  IObservationPosition,
-  IReadOnlyPlaybackObserver,
-} from "../../main_thread/types";
 import type {
   IAdaptation,
   IManifest,
   IPeriod,
   IRepresentation,
   ISegment,
 } from "../../manifest";
+import type {
+  ObservationPosition,
+  IReadOnlyPlaybackObserver,
+} from "../../playback_observer";
 import isNullOrUndefined from "../../utils/is_null_or_undefined";
 import noop from "../../utils/noop";
 import type { IRange } from "../../utils/ranges";
@@ -604,7 +604,7 @@ export interface IRepresentationEstimatorPlaybackObservation {
    * Information on the current media position in seconds at the time of a
    * Playback Observation.
    */
-  position : IObservationPosition;
+  position : ObservationPosition;
   /**
    * Last "playback rate" set by the user. This is the ideal "playback rate" at
    * which the media should play.

src/core/main/common/DecipherabilityFreezeDetector.ts

@@ -15,7 +15,7 @@
  */
 
 import log from "../../../log";
-import type { IFreezingStatus, IRebufferingStatus } from "../../../main_thread/types";
+import type { IFreezingStatus, IRebufferingStatus } from "../../../playback_observer";
 import getMonotonicTimeStamp from "../../../utils/monotonic_timestamp";
 import type SegmentSinksStore from "../../segment_sinks";
 

src/core/main/common/content_time_boundaries_observer.ts

@@ -19,13 +19,13 @@ import type {
   IBufferType,
 } from "../../../core/types";
 import { MediaError } from "../../../errors";
-import type { IReadOnlyPlaybackObserver } from "../../../main_thread/types";
 import type {
   IManifest,
   IAdaptation,
   IRepresentationIndex,
   IPeriod,
 } from "../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../playback_observer";
 import type { IPlayerError } from "../../../public_types";
 import EventEmitter from "../../../utils/event_emitter";
 import isNullOrUndefined from "../../../utils/is_null_or_undefined";

src/core/main/common/create_content_time_boundaries_observer.ts

@@ -3,12 +3,12 @@ import type {
   IStreamOrchestratorPlaybackObservation,
 } from "../../../core/types";
 import log from "../../../log";
-import type { IReadOnlyPlaybackObserver } from "../../../main_thread/types";
 import type {
   IManifest,
   IPeriod,
 } from "../../../manifest";
 import type { IMediaSourceInterface } from "../../../mse";
+import type { IReadOnlyPlaybackObserver } from "../../../playback_observer";
 import type { IPlayerError } from "../../../public_types";
 import type { CancellationSignal } from "../../../utils/task_canceller";
 import ContentTimeBoundariesObserver from "./content_time_boundaries_observer";

src/core/main/worker/worker_main.ts

@@ -5,8 +5,6 @@ import {
 } from "../../../errors";
 import features from "../../../features";
 import log from "../../../log";
-// XXX TODO
-import { ObservationPosition } from "../../../main_thread/api/playback_observer";
 import Manifest, {
   Adaptation,
   Period,
@@ -24,6 +22,11 @@ import {
   WorkerMessageType,
 } from "../../../multithread_types";
 import DashWasmParser from "../../../parsers/manifest/dash/wasm-parser";
+import { ObservationPosition } from "../../../playback_observer";
+import type {
+  IWorkerPlaybackObservation,
+} from "../../../playback_observer/worker_playback_observer";
+import WorkerPlaybackObserver from "../../../playback_observer/worker_playback_observer";
 import type { IPlayerError, ITrackType } from "../../../public_types";
 import createDashPipelines from "../../../transports/dash";
 import arrayFind from "../../../utils/array_find";
@@ -60,10 +63,6 @@ import {
 import sendMessage, {
   formatErrorForSender,
 } from "./send_message";
-import type {
-  ICorePlaybackObservation,
-} from "./worker_playback_observer";
-import WorkerPlaybackObserver from "./worker_playback_observer";
 
 export default function initializeWorkerMain() {
   /**
@@ -97,7 +96,7 @@ export default function initializeWorkerMain() {
   /**
    * When set, emit playback observation made on the main thread.
    */
-  let playbackObservationRef : SharedReference<ICorePlaybackObservation> | null = null;
+  let playbackObservationRef : SharedReference<IWorkerPlaybackObservation> | null = null;
 
   onmessage = function (e: MessageEvent<IMainThreadMessage>) {
     log.debug("Worker: received message", e.data.type);
@@ -161,7 +160,7 @@ export default function initializeWorkerMain() {
 
         const currentCanceller = new TaskCanceller();
         const currentContentObservationRef = new SharedReference<
-          ICorePlaybackObservation
+          IWorkerPlaybackObservation
         >(objectAssign(msg.value.initialObservation, {
           position: new ObservationPosition(...msg.value.initialObservation.position),
         }));
@@ -475,7 +474,7 @@ interface IBufferingInitializationInformation {
 function loadOrReloadPreparedContent(
   val : IBufferingInitializationInformation,
   contentPreparer : ContentPreparer,
-  playbackObservationRef : IReadOnlySharedReference<ICorePlaybackObservation>,
+  playbackObservationRef : IReadOnlySharedReference<IWorkerPlaybackObservation>,
   parentCancelSignal : CancellationSignal
 ) {
   const currentLoadCanceller = new TaskCanceller();
@@ -544,6 +543,7 @@ function loadOrReloadPreparedContent(
 
   const playbackObserver = new WorkerPlaybackObserver(playbackObservationRef,
                                                       contentId,
+                                                      sendMessage,
                                                       currentLoadCanceller.signal);
 
   const contentTimeBoundariesObserver = createContentTimeBoundariesObserver(

src/core/segment_sinks/garbage_collector.ts

@@ -15,7 +15,7 @@
  */
 
 import log from "../../log";
-import type { IReadOnlyPlaybackObserver } from "../../main_thread/types";
+import type { IReadOnlyPlaybackObserver } from "../../playback_observer";
 import isNullOrUndefined from "../../utils/is_null_or_undefined";
 import type { IRange } from "../../utils/ranges";
 import { getInnerAndOuterRanges } from "../../utils/ranges";

src/core/stream/adaptation/get_representations_switch_strategy.ts

@@ -15,11 +15,8 @@
  */
 
 import config from "../../../config";
-import type { IReadOnlyPlaybackObserver } from "../../../main_thread/types";
-import type {
-  IAdaptation,
-  IPeriod,
-} from "../../../manifest";
+import type { IAdaptation, IPeriod } from "../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../playback_observer";
 import arrayIncludes from "../../../utils/array_includes";
 import type {
   IRange } from "../../../utils/ranges";

src/core/stream/adaptation/types.ts

@@ -1,10 +1,10 @@
-import type { IReadOnlyPlaybackObserver } from "../../../main_thread/types";
 import type {
   IManifest,
   IAdaptation,
   IPeriod,
   IRepresentation,
 } from "../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../playback_observer";
 import type {
   IAudioTrackSwitchingMode,
   IVideoTrackSwitchingMode,

src/core/stream/orchestrator/stream_orchestrator.ts

@@ -17,12 +17,12 @@
 import config from "../../../config";
 import { MediaError } from "../../../errors";
 import log from "../../../log";
-import type { IReadOnlyPlaybackObserver } from "../../../main_thread/types";
 import type {
   IManifest,
   IDecipherabilityUpdateElement,
   IPeriod,
 } from "../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../playback_observer";
 import isNullOrUndefined from "../../../utils/is_null_or_undefined";
 import queueMicrotask from "../../../utils/queue_microtask";
 import type {

src/core/stream/period/period_stream.ts

@@ -20,13 +20,9 @@ import {
   MediaError,
 } from "../../../errors";
 import log from "../../../log";
-import type { IReadOnlyPlaybackObserver } from "../../../main_thread/types";
-import type {
-  IAdaptation,
-  IPeriod } from "../../../manifest";
-import {
-  toTaggedTrack,
-} from "../../../manifest";
+import type { IAdaptation, IPeriod } from "../../../manifest";
+import { toTaggedTrack } from "../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../playback_observer";
 import type { ITrackType } from "../../../public_types";
 import arrayFind from "../../../utils/array_find";
 import objectAssign from "../../../utils/object_assign";

src/core/stream/period/types.ts

@@ -1,12 +1,12 @@
-import type {
-  IObservationPosition,
-  IReadOnlyPlaybackObserver,
-} from "../../../main_thread/types";
 import type {
   IManifest,
   IAdaptation,
   IPeriod,
 } from "../../../manifest";
+import type {
+  ObservationPosition,
+  IReadOnlyPlaybackObserver,
+} from "../../../playback_observer";
 import type { ITrackType } from "../../../public_types";
 import type { IRange } from "../../../utils/ranges";
 import type {
@@ -94,7 +94,7 @@ export interface IPeriodStreamPlaybackObservation {
    * Information on the current media position in seconds at the time of the
    * Observation.
    */
-  position : IObservationPosition;
+  position : ObservationPosition;
   /** `duration` property of the HTMLMediaElement. */
   duration : number;
   /** `readyState` property of the HTMLMediaElement. */

src/core/stream/period/utils/get_adaptation_switch_strategy.ts

@@ -15,8 +15,8 @@
  */
 
 import config from "../../../../config";
-import type { IReadOnlyPlaybackObserver } from "../../../../main_thread/types";
 import type { IAdaptation, IPeriod } from "../../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../../playback_observer";
 import areCodecsCompatible from "../../../../utils/are_codecs_compatible";
 import type { IRange } from "../../../../utils/ranges";
 import {

src/core/stream/representation/types.ts

@@ -1,8 +1,4 @@
-import type {
-  IContentProtection,
-  IObservationPosition,
-  IReadOnlyPlaybackObserver,
-} from "../../../main_thread/types";
+import type { IContentProtection } from "../../../main_thread/types";
 import type {
   IManifest,
   IAdaptation,
@@ -11,6 +7,10 @@ import type {
   IRepresentation,
 } from "../../../manifest";
 import type { IEMSG } from "../../../parsers/containers/isobmff";
+import type {
+  ObservationPosition,
+  IReadOnlyPlaybackObserver,
+} from "../../../playback_observer";
 import type {
   IAudioRepresentationsSwitchingMode,
   IPlayerError,
@@ -185,7 +185,7 @@ export interface IRepresentationStreamPlaybackObservation {
    * Information on the current media position in seconds at the time of a
    * Playback Observation.
    */
-  position : IObservationPosition;
+  position : ObservationPosition;
   /**
    * Information on whether the media element was paused at the time of the
    * Observation.

src/core/stream/representation/utils/append_segment_to_buffer.ts

@@ -23,8 +23,8 @@ import {
   SourceBufferError,
 } from "../../../../errors";
 import log from "../../../../log";
-import type { IReadOnlyPlaybackObserver } from "../../../../main_thread/types";
 import { toTaggedTrack } from "../../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../../playback_observer";
 import type { IRange } from "../../../../utils/ranges";
 import type { IReadOnlySharedReference } from "../../../../utils/reference";
 import sleep from "../../../../utils/sleep";

src/core/stream/representation/utils/get_buffer_status.ts

@@ -15,13 +15,13 @@
  */
 
 import config from "../../../../config";
-import type { IReadOnlyPlaybackObserver } from "../../../../main_thread/types";
 import type {
   IManifest,
   IAdaptation,
   IPeriod,
   IRepresentation,
 } from "../../../../manifest";
+import type { IReadOnlyPlaybackObserver } from "../../../../playback_observer";
 import isNullOrUndefined from "../../../../utils/is_null_or_undefined";
 import type {
   IBufferedChunk,