Date support

[defagos]

As a developer integrating Pillarbox I want to be able to seek to a specific date, provided such information is returned in a stream.

Acceptance criteria

• Seeking to a date is possible for streams delivering date information.
• Progress information can be obtained as a date for streams delivering date information.
• The demo displays dates for livestreams when available (similar to the system UI).

Hints

• Dates can appear in-on demand streams and livestreams.

Tasks

• Provide current date and seek to date APIs (no need to provide tolerances or smooth seeking, just bridge with AVPlayer APIs).
• Provide date information on ProgressTracker.
• Display date position for livestreams that provide date information.
• Make time / date APIs more consistent (usually func but we sometimes use var).
• Ensure same consistency for metrics retrieval (also document metrics retrieval at any time in corresponding article).
• Check that we can start playback at some date (make dedicated API available if needed).

[defagos]

Some findings:

• Our on-demand sports streams contains date information.
• The system UX displays date information only for livestreams, even if available in an on-demand stream (different on tvOS where display can always be toggled between both).
• Date information is available from AVPlayerItem, not from AVPlayer. Since discontinuities might arise we probably need to use stream date and time information to store a mapping between player time and date, updated when appropriate. This mapping can then be used as reference for calculations since we need to use our seek to time APIs, as seek to date APIs are more limited (tolerances e.g.) and do not support smooth seeking.
• Seeking to a date before the available range seeks to its beginning. Seeking to a date after the available range does nothing.
• Calling the seek to date APIs (which we will not directly do in the end, but can be inspiring for our API design) on a stream without date support does nothing.

Some ideas:

• We can associate Date and TimeRange to a content. Currently CMTimeRange but maybe we should store .time or .date and build ranges accordingly. This is similar to what we did in SRG Media Player but with better API design with the help of labeled enums.
• We need to update our ProgressTracker API for date handling support as well.

Unlike what we did with SRG Media Player, though, we should not hack date support if the stream does not support it.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs during the next 14 days or if the stale label is not removed.

[defagos]

Seek to date API

We will expose the simple AVPlayer seek to date API. This API does not support tolerances (according to the documentation the seek is always approximate).

Implementing tolerances would require using a fixed date vs. time reference, with no guarantee it remains valid in time, and would introduce a lot of complexity (e.g. time ranges should be expressible with either dates or positions, like we did in SRG Media Player).

This complexity does not seem justified yet. In general, if one wants to seek to some date, it is always as a result of having some external date information available to perform a single seek. Other seeks (e.g. to implement a progress bar or skip buttons) are probably always time-based anyway.

If AVPlayer implements tolerance support in the future we will of course support it as well.

Blocked time range and smooth seeking support

Since we do not call our seek API but rather AVPlayer seek to date API directly, blocked time ranges will not be skipped immediately (but after 1/10th second while playing). Smooth seeking will not supported as well but, as said above, date-based seeking is not appropriate for progress bar implementation.

This means we could theoretically start playback in a on-demand or livestream in a paused state while seeing a forbidden image, but this is really a corner case which, to be addressed correctly, would require a lot of work.

Playback start

To be able to start playback at a specific date we would need to update PlayerItemConfiguration to support a StartLocation, either position(Position) or date(Date), but in the date case we cannot deal with blocked time ranges correctly unless we implement full equivalence between date and time, as outlined above.

For this reason we decided not to support playback start at a specific date for the moment. This keeps things simple until this feature is really requested, at which point we might decide what to do.

Date calculations

Unlike Letterbox which was able to calculate date estimeates for livestreams based on wall-clock playback, Pillarbox only delivers date values and supports seeking to a date when a stream contains timestamps.

Moreover, Letterbox was correcting fluctuations near the live edge by storing a time vs. date reference. This is actually not needed and was an artifact of time truncation to the seekable time range, a behavior also implemented by Pillarbox but that we now have removed. No