API sync QoS

[defagos]

• [x] Discuss ideas from review feedbacks: https://github.com/SRGSSR/pillarbox-documentation/issues/86
• [x] In particular: Maybe the stream type could be useful so that the player time position can be interpreted correctly (distance from the live edge for DVR).
• [x] bitrate: Currently in bytes, but name is misleading. Shouldn't we send bitrates / bandwidths in bps and keep these key names?
• [x] How do we convert between mega / kilo / bytes / bits for local display purposes? (1024? 1000?)
• [x] What type should log be provided in? String? Dictionary?
• [x] Should we add the stall dictionary when we have no stalls?
• [x] Shouldn't we send, provided this can be reliably determined, which network connection type the user is on? (wifi, 4G)
• [x] What about experience_timings and service_timings?
• [x] The version number should likely not be a semantic versioning since this has little value (only breaking changes matter). Can we simply use an integer?
• [x] AirPlay: Shouldn't we send an event when enabling / disabling AirPlay since playback is moving from one device to another?
• [x] Picture in Picture: Same question. Could be interesting to identify in a playback session.
• [x] We should likely add player_position to the start event. We might namely enable tracking later and in this case this value might be interesting.
• [x] Does it really make sense to send heartbeats while paused? This has no real benefit IMHO.
• [x] In which events should we send the stream type?
• [x] In which events should we send the VPN info?
• [x] Is the VPN info optional?
• [x] Shouldn't we send a heartbeat event right at the beginning to have initial values?
• [x] Should we revisit our event model and drop the start event, providing static info (e.g. origin) in all events?
• [x] Should we use a use case to justify the addition of a new field, to make sure that it's really necessary data for a QoS/QoE tool?
• [x] AirPlay flag: Sending events when enabling or disabling AirPlay does not suffice since we are lacking the initial state. We could send a fake event after the start but maybe it is just easier to add a flag to event payloads. With heartbeats we will have a precision of 30 seconds which should be enough.
• [x] Which event names do we want to support with this first iteration of our implementation?
• [x] Shouldn't we send the selected audio / subtitle tracks in status events?
• [x] Are QoS timings really our responsibilty?
• [x] String constants have various formats (e.g. "Tablet", "Pillarbox", "on-demand"). Should we align these values to have something readable and consistent?
• [x] New session when retrying after failure?
• [x] Could we have SESSION, START, HEARTBEAT, HEARTBEAT, etc. as event sequence?
• [x] Since heartbeats are sent also when paused, shouldn't we send some playback status (maybe simple, playing vs. paused) in status events?
• [x] When player throw a fatal error, should we send a STOP event ? Because we could have a none fatal error.
• [x] Developers custom events

Other topics

• [x] Deliver metadata with errors?

[defagos]

• We will add a stream type field with live / on-demand values.
• player_position will contain:
  • The position relative to 0 for on-demand content.
  • The Unix timestamp corresponding to the player playhead position for a livestream.
• Bitrate / bandwidth: In bits per second.
• 1024 between byte units _(@jboix See IEC 80000-13 you can also use KiB, MiB, abbreviation to detonated that the conversion is done with 1024 instead of 1000 to a avoid confusion)_
• log format: Any. Will be used for technical inspection and can be extracted from Grafana (or similar), not really used to plot things.
• stall: Present if the player is able to count stalls, with both fields set to 0 if no stall.
• wifi / mobile / wired: Not added. Bandwidth should suffice.
• Additional idea: VPN flag if possible to detect client-side (without additional external service).
• qoe and qos seem easier to understand (and shorter).
• Version number: Number, only major for breaking changes.
• AirPlay status events.
• No events for Picture in Picture.
• player_position: No real use case yet to justify having it in start event.
• Heartbeat while paused: Kept, can be used to keep a session alive.

[defagos]

• Time information: Sent in status events (stop, hb, etc.) and error events, not in start:
  • duration: Stream duration available from the player.
  • position: Raw position available from the player, relative to the stream window origin. Negative values admitted.
  • position_timestamp: Raw date available from the player (read from the playlist), corresponding to the current player position. If not available from the playlist, not calculated client-side. We have all the info server-side for an estimate (duration and position, as well as event timestamp).
• We send an initial heartbeat event right after the start, thus providing current time / bandwidth information immediately.
• The stream type (live / on-demand) is sent in status events, not start or error events. Field is stream_type.
• VPN information sent in status events, not start or error events. Field is vpn and is optional if the platform is not able to retrieve it.
• We don't revisit our model and keep start, error and status events separated.
• Yes, we should ask ourselves about use cases before adding fields unnecessarily.
• AirPlay: No events changed when toggled, only a flag in status events, not start or error events. Field is airplay and is only provided with values true / false on platforms supporting AirPlay.
• Events supported in this first implementation: start, error, stop, heartbeat.
• Tracks: Not added yet. Will wait until there is a real need.
• QoS / QoE: Keep.
• On-demand / Live.
• New session id created when restarting after failure.
• SESSION, START, etc. sequence is not a good idea since we would need a specific payload for the start to send timings. So would make things more complex.
• Playback state not useful.
• Fatal error is not followed by a stop.
• We wont' endorse custom event creation, though our model makes it possible. Those events will be received by our dispatcher but ignored when stored in our custom data store anyway.

[defagos]

Metadata with errors:

• Possible for Apple platforms. Required if we want to provide a start date in case of a blocking reason.
• Web: Already possible.
• Android: Requires a PoC.

[defagos]

Monitoring pecifications have been updated accordingly. Closed.