3.0.0

[MGaetan89]

New features

Playback monitoring

Pillarbox records various metrics related to playback performance (bitrate, stalls, playback duration, ...).
You can retrieve these values by using the following:

val player = PillarboxExoPlayer(context)
player.getCurrentMetrics() // Get the current PlaybackMetrics
player.currentMetricsAsFlow() // Get PlaybackMetrics as a Flow
player.getPeriodicallyCurrentMetricsAsState() // Get PlaybackMetrics as a Compose State

By default, these metrics are sent to a Pillarbox monitoring service when using PillarboxExoPlayer from pillarbox-core-business, or discarded when using PillarboxExoPlayer from pillarbox-player. You can customize this by doing:

val player = PillarboxExoPlayer(context) {
    // Disable monitoring handling
    disableMonitoring()
    // Output metrics to Logcat
    monitoring(Logcat)
    // Send metrics to a remote server
    monitoring(Remote) {
        config(endpointUrl = "...")
    }
}

Improved block reason support

The BlockReasonException is now a sealed class, possibly containing more information about a specific error.

val error = player.playerError
when (error) {
    is BlockReasonException.GeoBlock -> TODO("This chapter is geo-blocked")
    is BlockReasonException.StartDate -> TODO("This chapter will be available on ${error.instant}")
    is BlockReasonException.EndDate -> TODO("This chapter is no longer available since ${error.instant}")
    // Handle other types...
}

Customize the surface type used by the player

When using PlayerSurface from pillarbox-ui, you can now specify the type of surface you want to use:

PlayerSurface(
    player = player,
    surfaceType = SurfaceType.Surface, // Or `Texture` or `Spherical`
)

See SurfaceType for more information.

Other features

• Pillarbox API documentation is now available online.
• Chapters are available in the media item metadata. You can get them using MediaItem.mediaMetadata.chapters.
• Credits are available in the media item metadata. You can get them using MediaItem.mediaMetadata.credits.
• MediaItem.tag is no longer reserved for Pillarbox usage.
• Introduce PillarboxPreloadManager helper for Media3 PreloadManager. Note that these APIs are incubating on Media3 side and will change in future versions.

Breaking changes

Introduce a DSL to create a player

The PillarboxExoPlayer constructor and the DefaultPillarbox have been removed.
Instead, you can use the PillarboxExoPlayer builder function, which comes in two variants:

• PillarboxExoPlayer from pillarbox-player: closely matches a default ExoPlayer, with Pillarbox monitoring disabled.
• PillarboxExoPlayer from pillarbox-core-business: suited for the SRG SSR needs, i.e. it can play URN and sends playback metrics to Pillarbox monitoring.

val player = PillarboxExoPlayer(context, Default) // from pillarbox-player
val srgPlayer = PillarboxExoPlayer(context) // from pillarbox-core-business

You can customize the player during creation:

val player = PillarboxExoPlayer(context) {
    addAssetLoader(CustomAssetLoader())
    seekBackwardIncrement(5.seconds)
    seekForwardIncrement(10.seconds)
}

Removal of deprecated symbols

Symbol	Replacement	Comment
MediaItemUrn	SRGMediaItemBuilder
Player.disableTextTrack()	Player.disableTextTrack()	Use the extension from ch.srgssr.pillarbox.player.tracks instead
Player.setDefaultTextTrack()	Player.setAutoTextTrack()
Player.disableAudioTrack()	Player.disableAudioTrack()	Use the extension from ch.srgssr.pillarbox.player.tracks instead
Player.setDefaultAudioTrack()	Player.setAutoAudioTrack()
Tracks.text	Tracks.textTracks
Tracks.audio	Tracks.audioTracks
Tracks.video	Tracks.videoTracks

Others breaking changes

• Remove DefaultHttpClient. Use PillarboxHttpClient instead.

What's Changed

• Check device capabilities to display picture in picture button by @StaehliJ in Check device capabilities to display picture in picture button #663
• Bump gradle/actions from 3 to 4 in the actions group by @dependabot in Bump gradle/actions from 3 to 4 in the actions group #668
• Fix PillarboxSlider min/max values by @MGaetan89 in Fix PillarboxSlider min/max values #671
• Bump android-gradle-plugin from 8.5.1 to 8.5.2 by @dependabot in Bump android-gradle-plugin from 8.5.1 to 8.5.2 #675
• Bump kotlin from 2.0.0 to 2.0.10 by @dependabot in Bump kotlin from 2.0.0 to 2.0.10 #674
• Bump the androidx group with 4 updates by @dependabot in Bump the androidx group with 4 updates #673
• Update Gradle to 8.10 by @MGaetan89 in Update Gradle to 8.10 #679
• Bump the androidx group with 2 updates by @dependabot in Bump the androidx group with 2 updates #681
• Move Chapters and Credits into MediaMetadata by @StaehliJ in Move Chapters and Credits into MediaMetadata #687
• Bump madrapps/jacoco-report from 1.6.1 to 1.7.0 in the actions group by @dependabot in Bump madrapps/jacoco-report from 1.6.1 to 1.7.0 in the actions group #689
• Bump kotlin from 2.0.10 to 2.0.20 by @dependabot in Bump kotlin from 2.0.10 to 2.0.20 #686
• Bump kotlinx-serialization from 1.7.1 to 1.7.2 by @dependabot in Bump kotlinx-serialization from 1.7.1 to 1.7.2 #692
• Bump android-gradle-plugin from 8.5.2 to 8.6.0 by @dependabot in Bump android-gradle-plugin from 8.5.2 to 8.6.0 #691
• Bump the androidx group across 1 directory with 12 updates by @dependabot in Bump the androidx group across 1 directory with 12 updates #693
• Bump com.autonomousapps.dependency-analysis from 1.33.0 to 2.0.1 by @dependabot in Bump com.autonomousapps.dependency-analysis from 1.33.0 to 2.0.1 #690
• Bump the androidx group across 1 directory with 8 updates by @dependabot in Bump the androidx group across 1 directory with 8 updates #700
• Update AndroidX Compose by @MGaetan89 in Update AndroidX Compose #698
• Bump detekt from 1.23.6 to 1.23.7 by @dependabot in Bump detekt from 1.23.6 to 1.23.7 #696
• Qos by @StaehliJ in Qos #694
• Extract Detekt config in a dedicated plugin and simplify config by @MGaetan89 in Extract Detekt config in a dedicated plugin and simplify config #703
• Update to AndroidX Navigation 2.8.0 by @MGaetan89 in Update to AndroidX Navigation 2.8.0 #701
• Bump com.autonomousapps.dependency-analysis from 2.0.1 to 2.0.2 by @dependabot in Bump com.autonomousapps.dependency-analysis from 2.0.1 to 2.0.2 #707
• Bump kotlinx-coroutines from 1.8.1 to 1.9.0 by @dependabot in Bump kotlinx-coroutines from 1.8.1 to 1.9.0 #706
• Fix ComScoreTrackerIntegrationTest flakiness by @MGaetan89 in Fix ComScoreTrackerIntegrationTest flakiness #711
• Store pillarbox data into current tracks by @StaehliJ in Store pillarbox data into current tracks #704
• Fix MonitoringTest by using PillarboxExoPlayer directly by @MGaetan89 in Fix MonitoringTest by using PillarboxExoPlayer directly #714
• Remove ModalNavigationDrawer positioning hack in PlaybackSettingsDrawer by @MGaetan89 in Remove ModalNavigationDrawer positioning hack in PlaybackSettingsDrawer #712
• 708 revisit timerange trackers by @StaehliJ in 708 revisit timerange trackers #713
• Bump madrapps/jacoco-report from 1.7.0 to 1.7.1 in the actions group by @dependabot in Bump madrapps/jacoco-report from 1.7.0 to 1.7.1 in the actions group #721
• 716 update monitoring data format by @StaehliJ in 716 update monitoring data format #724
• Add missing Detekt rules by @MGaetan89 in Add missing Detekt rules #725
• Bump the androidx group with 5 updates by @dependabot in Bump the androidx group with 5 updates #718
• Bump android-gradle-plugin from 8.6.0 to 8.6.1 by @dependabot in Bump android-gradle-plugin from 8.6.0 to 8.6.1 #719
• Bump kotlinx-serialization from 1.7.2 to 1.7.3 by @dependabot in Bump kotlinx-serialization from 1.7.2 to 1.7.3 #720
• Fix monitoring by @StaehliJ in Fix monitoring #727
• Revisit media item tracker by @StaehliJ in Revisit media item tracker #717
• Remove deprecated symbols by @MGaetan89 in Remove deprecated symbols #723
• Bump com.autonomousapps.dependency-analysis from 2.0.2 to 2.1.1 by @dependabot in Bump com.autonomousapps.dependency-analysis from 2.0.2 to 2.1.1 #730
• Make the slider interactive again by @MGaetan89 in Make the slider interactive again #733
• Bump com.autonomousapps.dependency-analysis from 2.1.1 to 2.1.4 by @dependabot in Bump com.autonomousapps.dependency-analysis from 2.1.1 to 2.1.4 #741
• Bump android-gradle-plugin from 8.6.1 to 8.7.0 by @dependabot in Bump android-gradle-plugin from 8.6.1 to 8.7.0 #740
• Add surface type to PlayerSurface by @StaehliJ in Add surface type to PlayerSurface #742
• Bump the androidx group with 5 updates by @dependabot in Bump the androidx group with 5 updates #739
• Move Monitoring configuration to pillarbox-core-business by @MGaetan89 in Move Monitoring configuration to pillarbox-core-business #743
• Update to Gradle 8.10.2 by @MGaetan89 in Update to Gradle 8.10.2 #735
• 729 dont destroy playbacksession on error to allow retrieve session id on error by @StaehliJ in 729 dont destroy playbacksession on error to allow retrieve session id on error #734
• Bump mockk from 1.13.12 to 1.13.13 by @dependabot in Bump mockk from 1.13.12 to 1.13.13 #746
• Bump the srgssr group with 3 updates by @dependabot in Bump the srgssr group with 3 updates #744
• Bump ktor from 2.3.12 to 3.0.0 by @dependabot in Bump ktor from 2.3.12 to 3.0.0 #745
• Add SAM endpoints and CH/WW locations by @MGaetan89 in Add SAM endpoints and CH/WW locations #736
• Introduce PillarboxPreloadManager by @MGaetan89 in Introduce PillarboxPreloadManager #726
• Update monitoring URL by @MGaetan89 in Update monitoring URL #753
• Bump kotlin from 2.0.20 to 2.0.21 by @dependabot in Bump kotlin from 2.0.20 to 2.0.21 #751
• Add server picker in "Examples" by @MGaetan89 in Add server picker in "Examples" #752
• Revisit BlockReasonException by @StaehliJ in Revisit BlockReasonException #754
• Add User Story template by @MGaetan89 in Add User Story template #755
• Remove severity from monitoring error by @MGaetan89 in Remove severity from monitoring error #757
• Bump app.cash.turbine:turbine from 1.1.0 to 1.2.0 by @dependabot in Bump app.cash.turbine:turbine from 1.1.0 to 1.2.0 #759
• Bump com.autonomousapps.dependency-analysis from 2.1.4 to 2.2.0 by @dependabot in Bump com.autonomousapps.dependency-analysis from 2.1.4 to 2.2.0 #758
• 748 simplify player creation by @StaehliJ in 748 simplify player creation #760
• Remove deprecated DefaultHttpClient by @MGaetan89 in Remove deprecated DefaultHttpClient #761
• Rename to PillarboxExoPlayer by @StaehliJ in Rename to PillarboxExoPlayer #765
• Network stack okhttp by @StaehliJ in Network stack okhttp #766
• 571 update pillarbox documentation by @StaehliJ in 571 update pillarbox documentation #763
• Bump com.autonomousapps.dependency-analysis from 2.2.0 to 2.3.0 by @dependabot in Bump com.autonomousapps.dependency-analysis from 2.2.0 to 2.3.0 #769
• Let the user input any value for the media URL/URN by @MGaetan89 in Let the user input any value for the media URL/URN #773
• Update dependencies by @MGaetan89 in Update dependencies #771
• Update to Dokka 2.0.0-Beta by @MGaetan89 in Update to Dokka 2.0.0-Beta #767
• Create a workflow to deploy the Dokka documentation by @MGaetan89 in Create a workflow to deploy the Dokka documentation #775
• Update documentation for pillarbox-analytics by @MGaetan89 in Update documentation for pillarbox-analytics #770
• Update documentation for pillarbox-cast by @MGaetan89 in Update documentation for pillarbox-cast #774
• Bump com.autonomousapps.dependency-analysis from 2.3.0 to 2.4.2 by @dependabot in Bump com.autonomousapps.dependency-analysis from 2.3.0 to 2.4.2 #778
• Bump ktor from 3.0.0 to 3.0.1 by @dependabot in Bump ktor from 3.0.0 to 3.0.1 #779
• Add Google's Maven repository to Dependabot config by @MGaetan89 in Add Google's Maven repository to Dependabot config #780
• Bump android-gradle-plugin from 8.7.1 to 8.7.2 by @dependabot in Bump android-gradle-plugin from 8.7.1 to 8.7.2 #782
• Bump the androidx group with 8 updates by @dependabot in Bump the androidx group with 8 updates #781
• Update to AndroidX Core 1.15.0 by @MGaetan89 in Update to AndroidX Core 1.15.0 #783
• Update documentation in pillarbox-core-business by @MGaetan89 in Update documentation in pillarbox-core-business #776
• Update documentation in pillarbox-ui by @MGaetan89 in Update documentation in pillarbox-ui #787
• Bump robolectric from 4.13 to 4.14 by @dependabot in Bump robolectric from 4.13 to 4.14 #798
• Fix Dokka jar generation for release by @MGaetan89 in Fix Dokka jar generation for release #793
• Create an enum for IL location by @MGaetan89 in Create an enum for IL location #791
• Migrate Vector to be an enum by @MGaetan89 in Migrate Vector to be an enum #790

Full Changelog: 2.3.0...3.0.0

---

This discussion was created from the release 3.0.0.