Metrics, monitoring and improved playlist support

[defagos]

This release mostly focuses on metrics and monitoring. It makes it possible to inspect and monitor playback performance, both locally and remotely.

It also improves features associated with playlists, adding looping playback as well as a simpler way to manage items in a playlist at the user interface level.

Metrics

• Provide several key metrics during playback (bitrates, stalls, data requests, frame drops, etc.). Current metrics can be queries from PlayerProperties at any time, or obtained periodically using periodicMetricsPublisher(forInterval:queue:limit:).
• Receive important events during playback (metadata and asset loading, errors, stalls, etc.) by subscribing to the metricEventsPublisher publisher.
• The MetricsCollector observable object lets you easily create metrics visualizations, e.g. using SwiftUI or Swift Charts.

Monitoring

• Add PillarboxMonitoring package, offering seamless integration with Pillarbox monitoring platform.
• Provide MetricsTracker to automatically collect and send metrics data to Pillarbox monitoring platform.

Tracking

• Make trackers easier to implement with reliable access to properties when a tracker is disabled.
• Add metrics protocol method to PlayerItemTracker.
• Add optional and mandatory behaviors to tracker adapters, letting you control how isTrackingEnabled affects them.
• Add support for optional session identifiers, letting you associate an identifier with a tracker, useful to relate data remotely collected by a tracker with an associated local session.

Playlist support

• The items of a Player can be simply displayed as a Playlist supporting usual actions (reorder, delete).
• A source can be associated to items, making it possible to display any kind of relevant data in a playlist user interface.
• Repeated playback of a single item or of an entire playlist can be enabled with the new repeatMode player property.

Miscellaneous improvements

• Add date support for streams embedding timestamps. A seek method accepting a date as parameter has been enabled and a date() method has been added to retrieve the current date.
• Make smart navigation interval configurable.
• Improve server support in CoreBusiness by adding support for custom server URLs and query parameters.
• Add Audio Description information to Commanders Act analytics labels.
• Add date interval measurement operator to the Core package.
• Add stopwatch to the Core package.
• Remove Timelane.

Breaking changes

• Update PlayerItemTracker protocol method signatures. Implementations can also be made simpler using properties now provided when a tracker is disabled.
• PlayerConfiguration navigation mode is now set through a navigationMode property instead of a simple Boolean flag.
• Commanders Act and comScore events captured do not require a leading dot anymore.
• The player current item is set using currentItem. The index-based currentIndex and setCurrentIndex(_:) APIs have been removed accordingly.
• The current time was retrieved from a time property which, for consistency, has been replaced with a time() function.

Fixes

• Make User Agent reliable in Commanders Act events.

Demo improvements

• Make tvOS Playback HUD, displaying various streaming key metrics, also available on iOS. The HUD can be enabled and customized under the demo Settings tab.
• Add metrics debugging view to the main custom player layout, accessible from its settings menu.
• Provide more entry options for custom URL and URN entry (token, DRM, server).
• Make the custom player slider accessible with VoiceOver.
• Add basic keyboard shortcut support.
• Add BBC and Mux test streams.
• Display metrics session identifier when a failure is encountered while playing SRG SSR content. This makes it possible to relate a playback session to data visualized remotely.
• Improve automatic keyboard dismissal.

What's changed

• Add Swift Package Index documentation links by @defagos in Add Swift Package Index documentation links #889
• Update SwiftLint to version 0.55.1 by @defagos in Update SwiftLint to version 0.55.1 #890
• Improve server support in Core Business by @defagos in Improve server support in Core Business #891
• Add playback HUD support by @defagos in Add playback HUD support #893
• Immediately dismiss the keyboard when scrolling by @defagos in Immediately dismiss the keyboard when scrolling #895
• Update Xcode to version 15.4 by @defagos in Update Xcode to version 15.4 #896
• Make smart navigation interval configurable by @defagos in Make smart navigation interval configurable #902
• Provide audio description information in analytics labels by @defagos in Provide audio description information in analytics labels #894
• Add basic keyboard shortcut support by @defagos in Add basic keyboard shortcut support #898
• Add support for token-protected and DRM-encrypted URLs to the demo by @defagos in Add support for token-protected and DRM-encrypted URLs to the demo #907
• Add useful testing information for stream encoding and packaging teams by @defagos in Add useful testing information for stream encoding and packaging teams #910
• Gather player metrics by @defagos in Gather player metrics #912
• Simplify the gathering of player metrics by @waliid in Simplify the gathering of player metrics #915
• Update issue templates by @defagos in Update issue templates #914
• Add metrics collector by @defagos in Add metrics collector #916
• Add SRG SSR environment support to URN entry by @defagos in Add SRG SSR environment support to URN entry #919
• Use built-in player metadata image retrieval by @defagos in Use built-in player metadata image retrieval #921
• Measure startup times by @waliid in Measure startup times #920
• Make metric event API more ergonomic by @defagos in Make metric event API more ergonomic #922
• Improve behavior for streams providing no metrics by @defagos in Improve behavior for streams providing no metrics #923
• Document PillarboxPlayer APIs as supported on the main thread only by @defagos in Document PillarboxPlayer APIs as supported on the main thread only #932
• Localize MB unit by @defagos in Localize MB unit #933
• Fix incorrectly rounded displayed data volume by @defagos in Fix incorrectly rounded displayed data volume #934
• Provide metric events for fatal errors by @defagos in Provide metric events for fatal errors #937
• Capture stalls in QoS metrics by @defagos in Capture stalls in QoS metrics #938
• Provide warnings in QoS metric events by @defagos in Provide warnings in QoS metric events #939
• Display event log in metrics debugging view by @defagos in Display event log in metrics debugging view #942
• Add BBC and Mux test streams to the demo by @defagos in Add BBC and Mux test streams to the demo #949
• Revisit player item tracking by @waliid in Revisit player item tracking #950
• Reuse comScore session when pausing at item end by @defagos in Reuse comScore session when pausing at item end #952
• Create basic QoS tracker by @waliid in Create basic QoS tracker #953
• Send QoS tracker payload data to a specific endpoint by @waliid in Send QoS tracker payload data to a specific endpoint #962
• Update 3rd party dependencies by @defagos in Update 3rd party dependencies #965
• Wait until the User Agent is retrieved by Commanders Act by @defagos in Wait until the User Agent is retrieved by Commanders Act #964
• Update metrics tracker to most recent specifications by @defagos in Update metrics tracker to most recent specifications #967
• Display monitoring session identifier in metrics debugging view by @defagos in Display monitoring session identifier in metrics debugging view #968
• Fix incorrect y-axis data volume scale by @defagos in Fix incorrect y-axis data volume scale #969
• Extract settings menu by @defagos in Extract settings menu #972
• Add mandatory tracker support by @defagos in Add mandatory tracker support #971
• Update metrics tracker to most recent specifications by @defagos in Update metrics tracker to most recent specifications  #974
• Fix incorrect negative metrics when toggling AirPlay by @defagos in Fix incorrect negative metrics when toggling AirPlay #976
• Remove Timelane by @defagos in Remove Timelane #978
• Update metrics tracker to most recent specifications by @defagos in Update metrics tracker to most recent specifications #977
• Document monitoring and metrics support by @defagos in Document monitoring and metrics support #979
• Update SwiftLint to version 0.56.1 by @defagos in Update SwiftLint to version 0.56.1 #980
• Improve metric event name consistency by @defagos in Improve metric event name consistency #983
• Avoid returning metrics for reserved items by @defagos in Avoid returning metrics for reserved items #982
• Fix missing comScore labels when replaying content by @defagos in Fix missing comScore labels when replaying content #985
• Improve playlist user interface integration by @defagos in Improve playlist user interface integration #986
• Fix incorrect metadata timings after recovering from failure by @defagos in Fix incorrect metadata timings after recovering from failure #990
• Update SwiftLint to version 0.56.2 by @defagos in Update SwiftLint to version 0.56.2 #991
• Fix incorrect QoE timing after recovering from failure by @defagos in Fix incorrect QoE timing after recovering from failure #992
• Support repeat modes by @waliid in Support repeat modes #993
• Add date support by @defagos in Add date support #994
• Make the player custom slider accessible via VoiceOver by @defagos in Make the player custom slider accessible via VoiceOver #995

Full Changelog: 2.0.0...3.0.0

---

This discussion was created from the release Metrics, monitoring and improved playlist support.