### Create Pillarbox Player
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business/docs/README.md
Instantiate and prepare the PillarboxExoPlayer to be ready for playback. The player will automatically start playback when a MediaItem is available.
```kotlin
val player = PillarboxExoPlayer(context)
// Make the player ready to play content
player.prepare()
// Will start playback when a MediaItem is ready to play
player.play()
```
--------------------------------
### Display a Player with PlayerSurface
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-ui/docs/README.md
Demonstrates how to display a Player using the PlayerSurface composable. This is the basic setup for rendering video content.
```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.media3.common.Player
import ch.srgssr.pillarbox.ui.widget.player.PlayerSurface
@Composable
fun SimplePlayer(
player: Player,
modifier: Modifier = Modifier,
) {
PlayerSurface(
player = player,
modifier = modifier,
)
}
```
--------------------------------
### Build PillarboxMediaController
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
Illustrates how to build and obtain a PillarboxMediaController instance, which is used to interact with the media session from an activity or other components. This example shows building it for a specific MediaLibraryService.
```kotlin
coroutineScope.launch {
val mediaController: PillarboxPlayer = PillarboxMediaController.Builder(context, DemoMediaLibraryService::class.java).build()
doSomethingWith(mediaController)
}
```
--------------------------------
### Implement Custom AssetLoader
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Provides an example of creating a custom AssetLoader to handle non-standard media sources, such as local resource IDs or custom URIs. It defines how to load and prepare these assets for playback.
```kotlin
class CustomAssetLoader(context: Context) : AssetLoader(DefaultMediaSourceFactory(context)) {
override fun canLoadAsset(mediaItem: MediaItem): Boolean {
return mediaItem.localConfigruation?.uri?.scheme == "custom"
}
override suspend fun loadAsset(mediaItem: MediaItem): Asset {
val data = service.fetchData(mediaItem.localConfigruation!!.uri)
val trackerData = MutableMediaItemTrackerData()
trackerData[KEY] = FactoryData(CustomMediaItemTracker.Factory(), CustomTrackerData("CustomData"))
val mediaMetadata = MediaMetadata.Builder()
.setTitle(data.title)
.setArtworkUri(data.imageUri)
.setChapters(data.chapters)
.setCredits(data.credits)
.build()
val mediaSource = mediaSourceFactory.createMediaSource(MediaItem.fromUri(data.url))
return Asset(
mediaSource = mediaSource,
trackersData = trackerData.toMediaItemTrackerData(),
mediaMetadata = mediaMetadata,
blockedTimeRanges = emptyList(),
)
}
}
```
--------------------------------
### Initialize PillarboxCastPlayer
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business-cast/docs/README.md
Example of how to initialize the PillarboxCastPlayer, which is used to connect to SRG SSR receivers.
```kotlin
val player = PillarboxCastPlayer(context)
```
--------------------------------
### Implement AssetLoader with Tracking
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaItemTracking.md
Provides an example of an AssetLoader that loads an Asset with custom tracking data. It overrides `canLoadAsset` and `loadAsset` to include the DemoMediaItemTracker.
```kotlin
class DemoAssetLoader(context: Context) : AssetLoader(DefaultMediaSourceFactory(context)) {
override fun canLoadAsset(mediaItem: MediaItem): Boolean {
return true
}
override suspend fun loadAsset(mediaItem: MediaItem): Asset {
val trackerData = MutableMediaItemTrackerData()
trackerData[key] = FactoryData(DemoMediaItemTracker.Factory(), DemoTrackerData("Data1"))
return Asset(
mediaSource = mediaSourceFactory.createMediaSource(mediaItem),
trackersData = trackerData.toMediaItemTrackerData(),
)
}
}
```
--------------------------------
### Create and Prepare PillarboxExoPlayer
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Demonstrates the basic creation of a PillarboxExoPlayer instance and prepares it for media playback.
```kotlin
val player = PillarboxExoPlayer(context, Default)
// Make the player ready to play content
player.prepare()
// Will start playback when a MediaItem is ready to play
player.play()
```
--------------------------------
### ExoPlayer Documentation Links
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Provides links to official ExoPlayer documentation for various features, which are also applicable to Pillarbox.
```html
Getting started with ExoPlayer
Player events
Media items
Playlists
Track selection
```
--------------------------------
### Pillarbox Android Concepts Documentation Links
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Links to specific documentation pages for Pillarbox Android concepts, such as media item tracking and media sessions.
```html
Media item tracking
Media session
```
--------------------------------
### Pillarbox Android API References
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Provides links to API documentation for various classes and interfaces within the Pillarbox Android project.
```html
android.view.View
androidx.media3.common.MediaItem
androidx.media3.exoplayer.ExoPlayer
androidx.media3.exoplayer.source.MediaSource
androidx.media3.ui.PlayerView
ch.srgssr.pillarbox.player.PillarboxExoPlayer
ch.srgssr.pillarbox.player.PillarboxPlayer
ch.srgssr.pillarbox.player.asset.AssetLoader
ch.srgssr.pillarbox.player.asset.timeRange.Chapter
ch.srgssr.pillarbox.player.asset.timeRange.Credit
media-items-documentation
media3-ui-documentation
pillarbox-ui
exo-player-documentation
```
--------------------------------
### Integrating Custom MediaCompositionService with PillarboxExoPlayer
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business/docs/README.md
Demonstrates how to initialize PillarboxExoPlayer with a custom CachedMediaCompositionService. This allows the player to utilize the caching mechanism for media compositions.
```kotlin
val player = PillarboxExoPlayer(context) {
srgAssetLoader(context) {
mediaCompositionService(CachedMediaCompositionService())
}
}
```
--------------------------------
### Create and Observe Credits
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Illustrates how to create Opening and Closing Credit objects and how to use the PillarboxPlayer to listen for credit changes. It also covers retrieving current and time-specific credits.
```kotlin
val openingCredits = Credit.Opening(start = 5_000L, end = 10_000L)
val closingCredits = Credit.Closing(start = 20_000L, end = 30_000L)
val player = PillarboxExoPlayer(context, Default)
player.addListener(object : Listener {
override fun onCreditChanged(credit: Credit?) {
when (credit) {
is Credit.Opening -> Unit // Show "Skip intro" button
is Credit.Closing -> Unit // Show "Skip credits" button
else -> Unot // Hide button
}
}
})
val credits = player.getCurrentCredits()
val currentCredit = player.getCreditAtPosition()
val creditAtPosition = player.getCreditAtPosition(5_000L)
```
--------------------------------
### Build PillarboxMediaSession
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
Demonstrates how to create and build an instance of PillarboxMediaSession, which is an enhanced version of Media3's MediaSession. This is typically used to manage media playback and integrate with system services.
```kotlin
val mediaSession = PillarboxMediaSession.Builder(context, player).build()
```
--------------------------------
### Create and Observe Chapters
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Demonstrates how to create a Chapter object and how to add a listener to the PillarboxPlayer to observe chapter changes. It also shows how to retrieve the current chapters and the chapter at a specific position.
```kotlin
val chapter = Chapter(
id = "1",
start = 0L,
end = 12_000L,
mediaMetadata = MediaMetadata.Builder().setTitle("Chapter 1").build()
)
val player = PillarboxExoPlayer(context, Default)
player.addListener(object : Listener {
override fun onChapterChanged(chapter: Chapter?) {
if (chapter == null) {
// Hide chapter information
} else {
// Display chapter information
}
}
})
val chapters = player.getCurrentChapters()
val currentChapter = player.getChapterAtPosition()
val chapterAtPosition = player.getChapterAtPosition(10_000L)
```
--------------------------------
### Create and Set MediaItem
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Illustrates how to create a MediaItem from a URI and set it to the PillarboxExoPlayer for playback.
```kotlin
val mediaUri = "https://example.com/media.mp4"
val mediaItem = MediaItem.fromUri(mediaUri)
player.setMediaItem(mediaItem)
```
--------------------------------
### Observe Player States with Compose
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-ui/docs/README.md
Demonstrates how to use extension functions from the `ch.srgssr.pillarbox.ui.extension` package to observe a `Player`'s state (current position, duration, playing status) as Compose `State` instances.
```kotlin
import androidx.compose.runtime.Composable
import androidx.media3.common.Player
import ch.srgssr.pillarbox.ui.extension.currentPositionAsState
import ch.srgssr.pillarbox.ui.extension.durationAsState
import ch.srgssr.pillarbox.ui.extension.isPlayingAsState
@Composable
fun MyPlayer(player: Player) {
val currentPosition: Long by player.currentPositionAsState()
val duration: Long by player.durationAsState()
val isPlaying: Boolean by player.isPlayingAsState()
}
```
--------------------------------
### Add GitHub Packages Repository to Gradle
Source: https://github.com/srgssr/pillarbox-android/blob/main/docs/README.md
Configures your Gradle project to use the GitHub Packages repository for Pillarbox Android. This involves adding the repository to your `settings.gradle(.kts)` or root `build.gradle(.kts)` file and providing authentication credentials.
```kotlin
repositories {
maven("https://maven.pkg.github.com/SRGSSR/pillarbox-android") {
credentials {
username = providers.gradleProperty("gpr.user").get()
password = providers.gradleProperty("gpr.key").get()
}
}
}
```
```kotlin
repositories {
maven("https://maven.pkg.github.com/SRGSSR/pillarbox-android") {
credentials {
username = project.findProperty("gpr.user")?.toString()
password = project.findProperty("gpr.key")?.toString()
}
}
}
```
--------------------------------
### Build and Use PillarboxMediaBrowser
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
This Kotlin code demonstrates how to build a PillarboxMediaBrowser instance using PillarboxMediaBrowser.Builder and then use it for media playback. It requires a CoroutineScope to launch the asynchronous operation.
```kotlin
coroutineScope.launch {
val mediaBrowser: PillarboxPlayer = PillarboxMediaBrowser.Builder(context, DemoMediaLibraryService::class.java).build()
doSomethingWith(mediaBrowser)
}
```
--------------------------------
### Use Custom AssetLoader with PillarboxExoPlayer
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Demonstrates how to integrate a custom AssetLoader with PillarboxExoPlayer by passing it during player creation, enabling playback of custom media sources.
```kotlin
val player = PillarboxExoPlayer(context, Default) {
+CustomAssetLoader(context)
}
player.prepare()
player.setMediaItem(MediaItem.fromUri("custom://video:1234"))
player.play()
```
--------------------------------
### Add Pillarbox Dependencies
Source: https://github.com/srgssr/pillarbox-android/blob/main/docs/README.md
Includes the necessary Pillarbox libraries as dependencies in your module's `build.gradle` or `build.gradle.kts` file. Different modules are available for player features, Cast integration, SRG SSR content handling, and UI elements. Replace `` with the desired version.
```kotlin
// Player specific features
implementation("ch.srgssr.pillarbox:pillarbox-player:")
// Library to handle Cast integration
implementation("ch.srgssr.pillarbox:pillarbox-cast:")
// Library to handle SRG SSR content through media URNs
implementation("ch.srgssr.pillarbox:pillarbox-core-business:")
// Library to handle SRG SSR Cast receiver with SRG SSR content
implementation("ch.srgssr.pillarbox:pillarbox-core-business-cast:")
// Library to display the video surface
implementation("ch.srgssr.pillarbox:pillarbox-ui:")
```
--------------------------------
### Player with Controls and Subtitles
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-ui/docs/README.md
Shows how to create a complete player UI by combining PlayerSurface with ExoPlayerControlView for playback controls and ExoPlayerSubtitleView for displaying subtitles. It uses a Box layout to layer these components.
```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.*
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.media3.common.Player
import ch.srgssr.pillarbox.ui.exoplayer.ExoPlayerControlView
import ch.srgssr.pillarbox.ui.exoplayer.ExoPlayerSubtitleView
import ch.srgssr.pillarbox.ui.widget.player.PlayerSurface
@Composable
fun MyPlayer(
player: Player,
modifier: Modifier = Modifier,
) {
Box(
modifier = modifier
.fillMaxWidth()
.wrapContentHeight()
.background(color = Color.Black),
contentAlignment = Alignment.Center,
) {
PlayerSurface(
player = player,
defaultAspectRatio = 1f,
)
ExoPlayerControlView(
player = player,
modifier = Modifier.matchParentSize(),
)
ExoPlayerSubtitleView(
player = player,
modifier = Modifier.matchParentSize(),
)
}
}
```
--------------------------------
### Add Pillarbox Player Dependency
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Integrates the Pillarbox Player module into your Android project by adding the necessary dependency to your build.gradle or build.gradle.kts file.
```kotlin
implementation("ch.srgssr.pillarbox:pillarbox-player:")
```
--------------------------------
### Configure GitHub Credentials in gradle.properties
Source: https://github.com/srgssr/pillarbox-android/blob/main/docs/README.md
Sets up your GitHub username and personal access token in the `gradle.properties` file for authenticating with GitHub Packages. Ensure your token has the `read:packages` scope.
```properties
gpr.user=
gpr.key=
```
--------------------------------
### Initialize SRGAnalytics with AnalyticsConfig
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-analytics/docs/README.md
Initialize SRGAnalytics in your Application's onCreate() method using either initSRGAnalytics() or SRGAnalytics.init(), providing an AnalyticsConfig instance.
```kotlin
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
val config = AnalyticsConfig(
vendor = AnalyticsConfig.Vendor.SRG,
appSiteName = "Your AppSiteName here",
sourceKey = SourceKey.DEVELOPMENT,
nonLocalizedApplicationName = "Your non-localized AppSiteName here",
)
initSRGAnalytics(config)
// or
SRGAnalytics.init(this, config)
}
}
```
--------------------------------
### Create MediaItem with URN
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business/docs/README.md
Create a MediaItem using the SRGMediaItem constructor with a media URN. Optionally, customize the MediaItem with host and vector settings.
```kotlin
val urn = "urn:rts:video:12345"
// MediaItem created on Prod with Vector.MOBILE
val mediaItem: MediaItem = SRGMediaItem(urn)
// Optionally customize the MediaItem
val customMediaItem: MediaItem = SRGMediaItem(urn) {
setHost(IlHost.Stage)
setVector(Vector.TV)
setVector(context.getVector())
}
// Give the MediaItem to the player so it can be played
player.setMediaItem(mediaItem)
```
--------------------------------
### Enable Java 17 Support in Gradle
Source: https://github.com/srgssr/pillarbox-android/blob/main/docs/README.md
Configures the Android project to use Java 17 for both source and target compatibility. This is essential for projects utilizing Pillarbox and should be added to the `android` section of your `build.gradle` or `build.gradle.kts` files.
```kotlin
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
kotlin {
compilerOptions {
jvmTarget = JvmTarget.JVM_17
}
}
```
--------------------------------
### Configure PillarboxExoPlayer Monitoring
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Shows how to configure monitoring behavior for PillarboxExoPlayer, including disabling it, outputting to Logcat, or sending to a remote server.
```kotlin
val player = PillarboxExoPlayer(context, Default) {
// Disable monitoring recording (default behavior)
disableMonitoring()
// Output each monitoring event to Logcat
monitoring(Logcat)
// Send each monitoring event to a remote server
monitoring(Remote) {
config(endpointUrl = "https://example.com/monitoring")
}
}
```
--------------------------------
### Configure Asset with MediaItemTracker
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaItemTracking.md
Shows how to set up an Asset with tracking data using a MutableMediaItemTrackerData. The FactoryData links the tracker factory and its initial data to a specific key.
```kotlin
val trackerData = MutableMediaItemTrackerData()
trackerData[KEY] = FactoryData(DemoMediaItemTracker.Factory(), MyTrackingData("Data1"))
val asset = Asset(
trackerData = trackerData,
// ...
)
```
--------------------------------
### Release PillarboxExoPlayer
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Properly releases the PillarboxExoPlayer instance to free up resources when it's no longer needed. Note that the player cannot be used after release.
```kotlin
player.release()
```
--------------------------------
### Add Chapters to MediaItem
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Shows how to associate a list of Chapter objects with a MediaItem by setting them in the MediaMetadata.
```kotlin
val chapter = Chapter(
id = "1",
start = 0L,
end = 12_000L,
mediaMetadata = MediaMetadata.Builder().setTitle("Chapter 1").build()
)
val mediaMetadata = MediaMetadata.Builder()
.setChapters(listOf(chapter))
.build()
val mediaItem = MediaItem.Builder()
.setMediaMetadata(mediaMetadata)
.build()
```
--------------------------------
### Add Dependency
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business/docs/README.md
Add the pillarbox-core-business dependency to your project's build.gradle or build.gradle.kts file to integrate the module.
```kotlin
implementation("ch.srgssr.pillarbox:pillarbox-core-business:")
```
--------------------------------
### Add Media3 UI Dependency
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Includes the necessary dependency for AndroidX Media3 UI components, such as PlayerView, in your project.
```kotlin
implementation("androidx.media3:media3-ui:")
```
--------------------------------
### GitHub Actions Secrets for Demo Deliveries
Source: https://github.com/srgssr/pillarbox-android/blob/main/docs/CONTINUOUS_INTEGRATION.md
These are the required GitHub Actions secrets to be set up for building and publishing the Demo application. They include credentials for signing, Firebase project IDs, and tester group associations.
```bash
# Required GitHub Actions secrets:
# DEMO_KEY_ALIAS: The key alias for the Gradle signature config.
# DEMO_KEY_PASSWORD: The key password for the Gradle signature config.
# FIREBASE_CREDENTIAL_FILE_CONTENT: The Firebase CLI credential file content.
# NIGHTLY_APP_ID: The Firebase project ID to publish the nightly.
# NIGHTLY_GROUPS: The Firebase testers group associated to the nightly demo.
# RELEASE_APP_ID: The Firebase project ID to publish the release.
# RELEASE_GROUPS: The Firebase testers group associated to the release demo.
```
--------------------------------
### Custom MediaCompositionService Implementation
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business/docs/README.md
Provides a custom implementation of MediaCompositionService that caches MediaComposition objects to improve performance. It fetches compositions from a backend and stores them in a mutable map.
```kotlin
class CachedMediaCompositionService : MediaCompositionService {
private val mediaCompositionCache = mutableMapOf()
override suspend fun fetchMediaComposition(uri: Uri): Result {
if (uri in mediaCompositionCache) {
return Result.success(mediaCompositionCache.getValue(uri))
}
val mediaComposition = fetchMediaCompositionFromBackend(uri)
if (mediaComposition != null) {
mediaCompositionCache[uri] = mediaComposition
return Result.success(mediaComposition)
} else {
return Result.failure(IOException("$uri not found"))
}
}
}
```
--------------------------------
### Link Player to PlayerView
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Connects a PillarboxExoPlayer instance to an AndroidX Media3 PlayerView for displaying video playback.
```kotlin
@Override
fun onCreate(savedInstanceState: Bundle) {
super.onCreate(savedInstanceState)
val player = PillarboxExoPlayer(context, Default)
val playerView: PlayerView = findViewById(R.id.player_view)
// A player can only be attached to one View!
playerView.player = player
}
```
--------------------------------
### Create PillarboxCastPlayer with SessionAvailabilityListener
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-cast/docs/README.md
Instantiate PillarboxCastPlayer and set a SessionAvailabilityListener to handle cast session availability changes. This allows you to manage media playback and preparation when a cast session becomes available or unavailable.
```kotlin
val player = PillarboxCastPlayer(context, Default)
player.setSessionAvailabilityListener(object : SessionAvailabilityListener {
override fun onCastSessionAvailable() {
// The cast session is connected.
player.setMediaItems(mediaItems)
player.play()
player.prepare()
}
override fun onCastSessionUnavailable() {
// The cast session has been disconnected.
}
})
// When the player is not needed anymore.
player.release()
```
--------------------------------
### Create a Custom MediaItemTracker
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaItemTracking.md
Demonstrates how to define a custom MediaItemTracker with specific tracking data and a factory for its creation. This involves creating a data class for tracking information and implementing the MediaItemTracker interface.
```kotlin
data class MyTrackingData(val data: String)
class DemoMediaItemTracker : MediaItemTracker {
override fun start(player: ExoPlayer, initialData: MyTrackingData) {
// ....
}
override fun stop(player: ExoPlayer) {
// ....
}
class Factory : MediaItemTracker.Factory() {
override fun create(): DemoMediaItemTracker {
return DemoMediaItemTracker()
}
}
}
```
--------------------------------
### GitHub Actions Workflow for Quality Checks
Source: https://github.com/srgssr/pillarbox-android/blob/main/docs/CONTINUOUS_INTEGRATION.md
This workflow is triggered on Pull Requests and pushes to the main branch. It performs build checks across platforms, runs linters, checks dependencies, and executes tests. Results are reported directly in the Pull Request.
```yaml
name: Quality
on:
push:
branches: [ main ]
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up JDK 11
uses: actions/setup-java@v3
with:
java-version: '11'
distribution: 'temurin'
cache: gradle
- name: Grant execute permission for gradlew
run: chmod +x gradlew
- name: Build with Gradle
run: ./gradlew build --stacktrace
- name: Run linters
run: ./gradlew lint --stacktrace
- name: Check dependencies
run: ./gradlew dependencyCheckAnalyze --stacktrace
- name: Run tests
run: ./gradlew test --stacktrace
```
--------------------------------
### Add Credits to MediaItem
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/README.md
Explains how to attach a list of Credit objects to a MediaItem by including them in the MediaMetadata.
```kotlin
val openingCredits = Credit.Opening(start = 5_000L, end = 10_000L)
val closingCredits = Credit.Closing(start = 20_000L, end = 30_000L)
val mediaMetadata = MediaMetadata.Builder()
.setCredits(listOf(openingCredits, closingCredits))
.build()
val mediaItem = MediaItem.Builder()
.setMediaMetadata(mediaMetadata)
.build()
```
--------------------------------
### Add Pillarbox Core Business Cast Dependency
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business-cast/docs/README.md
Add this dependency to your module's build.gradle or build.gradle.kts file to include the pillarbox-core-business-cast module.
```kotlin
implementation("ch.srgssr.pillarbox:pillarbox-core-business-cast:")
```
--------------------------------
### Create PillarboxCastPlayer with Lambda Listener
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-cast/docs/README.md
An alternative way to create PillarboxCastPlayer using a lambda for the SessionAvailabilityListener, providing a more concise syntax for handling session events.
```kotlin
val player = PillarboxCastPlayer(context, Default) {
onCastSessionAvailable {
// The cast session is connected.
setMediaItems(mediaItems)
play()
prepare()
}
onCastSessionUnavailable {
// The cast session has been disconnected.
}
}
```
--------------------------------
### Pillarbox UI Components and States
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-ui/docs/README.md
References to various UI components and state management classes within the Pillarbox Android library, including player surfaces, control views, subtitle views, and scale modes.
```APIDOC
UI Components:
- ExoPlayerControlView: Controls for the ExoPlayer.
- ExoPlayerSubtitleView: Displays subtitles for the ExoPlayer.
- PlayerSurface: A generic surface for displaying video content.
Surface Types:
- SurfaceType.Spherical: For spherical video playback.
- SurfaceType.Surface: For standard SurfaceView playback.
- SurfaceType.Texture: For TextureView playback.
State Management:
- ProgressTrackerState: Tracks playback progress.
Scale Modes:
- ScaleMode.Crop: Scales the video to fill the container, cropping if necessary.
- ScaleMode.Fill: Scales the video to fill the container, maintaining aspect ratio.
- ScaleMode.Fit: Scales the video to fit within the container, maintaining aspect ratio.
```
--------------------------------
### PlayerSurface Scale Mode Customization
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-ui/docs/README.md
Illustrates how to customize the scaling behavior of the video content within PlayerSurface using the `scaleMode` argument. Different scale modes affect how the video fits its container.
```kotlin
import androidx.media3.common.Player
import ch.srgssr.pillarbox.ui.widget.player.PlayerSurface
import ch.srgssr.pillarbox.ui.ScaleMode
// Example usage with ScaleMode.Fit
PlayerSurface(
player = player,
scaleMode = ScaleMode.Fit,
)
// ScaleMode.Fit: Resizes the player to fit within its parent while maintaining its aspect ratio.
// ScaleMode.Fill: Stretches the player to fill its parent, ignoring the defined aspect ratio.
// ScaleMode.Crop: Trims the player to fill its parent while maintaining its aspect ratio.
```
--------------------------------
### Handle Player Errors
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-core-business/docs/README.md
Implement the Player.Listener to catch and handle playback errors. Specific exceptions like BlockReasonException and ResourceNotFoundException can be identified and managed.
```kotlin
player.addListener(object : Player.Listener {
override fun onPlayerError(error: PlaybackException) {
when (val cause = error.cause) {
is BlockReasonException.StartDate -> Log.d("Pillarbox", "Content is blocked until ${cause.instant}")
is BlockReasonException -> Log.d("Pillarbox", "Content is blocked", cause)
is ResourceNotFoundException -> Log.d("Pillarbox", "No resources found in the chapter")
else -> Log.d("Pillarbox", "An error occurred", cause)
}
}
})
```
--------------------------------
### Configure User Consent during Initialization
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-analytics/docs/README.md
Configure user consent by providing a UserConsent object when initializing analytics. This sets consent for ComScore and Commanders Act services.
```kotlin
val userConsent = UserConsent(
comScore = ComScoreUserConsent.UNKNOWN,
commandersActConsentServices = emptyList(),
)
val config = AnalyticsConfig(
vendor = AnalyticsConfig.Vendor.SRG,
appSiteName = "Your AppSiteName here",
sourceKey = SourceKey.DEVELOPMENT,
nonLocalizedApplicationName = "Your non-localized AppSiteName here",
userConsent = userConsent,
)
initSRGAnalytics(config)
```
--------------------------------
### Local to Remote Playback Switching
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-cast/docs/README.md
Demonstrates how to manage playback between a local player (PillarboxExoPlayer) and a remote player (PillarboxCastPlayer) based on cast session availability. It shows how to set the current player and update the UI accordingly.
```kotlin
val localPlayer = PillarboxExoPlayer(context, Default)
val remotePlayer = PillarboxCastPlayer(context, Default)
var currentPlayer: PillarboxPlayer = if (remotePlayer.isCastSessionAvailable()) remotePlayer else localPlayer
player.setSessionAvailabilityListener(object : SessionAvailabilityListener {
override fun onCastSessionAvailable() {
setCurrentPlayer(remotePlayer)
}
override fun onCastSessionUnavailable() {
setCurrentPlayer(localPlayer)
}
})
PlayerView(currentPlayer)
```
--------------------------------
### PlayerSurface Surface Type Customization
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-ui/docs/README.md
Demonstrates how to specify the type of surface used for rendering video in PlayerSurface via the `surfaceType` argument. This allows choosing between SurfaceView, TextureView, or SphericalGLSurfaceView.
```kotlin
import androidx.media3.common.Player
import ch.srgssr.pillarbox.ui.widget.player.PlayerSurface
import ch.srgssr.pillarbox.ui.widget.player.SurfaceType
// Example usage with SurfaceType.Surface
PlayerSurface(
player = player,
surfaceType = SurfaceType.Surface,
)
// SurfaceType.Surface (default): Uses SurfaceView, optimized for all content including DRM.
// SurfaceType.Texture: Uses TextureView, suitable for animations, but not DRM content.
// SurfaceType.Spherical: Uses SphericalGLSurfaceView for 360° video content, not DRM compatible.
```
--------------------------------
### Add SRG SSR Maven Repository to Gradle
Source: https://github.com/srgssr/pillarbox-android/blob/main/docs/README.md
Configures the Gradle build to use the SRG SSR Maven repository. This involves adding the repository URL and providing credentials, which can be done in either the `settings.gradle(.kts)` or root `build.gradle(.kts)` file. The credentials should be fetched from Gradle properties.
```kotlin
// If you declare your repositories in the `settings.gradle(.kts)` file
repositories {
maven("https://nxrm.rts.ch/repository/maven-srgssr/") {
credentials {
username = providers.gradleProperty("srg_maven_user").get()
password = providers.gradleProperty("srg_maven_password").get()
}
}
}
// If you declare your repositories in the root `build.gradle(.kts)` file
repositories {
maven("https://nxrm.rts.ch/repository/maven-srgssr/") {
credentials {
username = project.findProperty("srg_maven_user")?.toString()
password = project.findProperty("srg_maven_password")?.toString()
}
}
}
```
--------------------------------
### Add AssetLoader to PillarboxPlayer
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaItemTracking.md
Illustrates how to integrate a custom AssetLoader into the PillarboxPlayer during its initialization. This allows the player to use the custom loader for media assets.
```kotlin
val player = PillarboxExoPlayer(context) {
+DemoAssetLoader(context)
}
```
--------------------------------
### Enable Foreground Service Permissions
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
Details the required permissions in AndroidManifest.xml to enable foreground services, specifically for media playback. This is essential for background playback functionality on modern Android versions.
```xml
```
--------------------------------
### Automotive App Description for Media
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
This XML file, automotive_app_desc.xml, specifies that the application uses media capabilities for Android Auto.
```xml
```
--------------------------------
### Declare PillarboxMediaSessionService in AndroidManifest
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
Provides the necessary XML configuration for the AndroidManifest.xml file to declare a custom service that extends PillarboxMediaSessionService. This enables background playback and integration with media controls.
```xml
```
--------------------------------
### Add Analytics Dependency
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-analytics/docs/README.md
Add the pillarbox-analytics dependency to your module's build.gradle or build.gradle.kts file to integrate the analytics module.
```kotlin
implementation("ch.srgssr.pillarbox:pillarbox-analytics:")
```
--------------------------------
### Release PillarboxMediaSession
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
Shows the correct way to release the PillarboxMediaSession instance when it's no longer needed, which is crucial for resource management and preventing memory leaks. It's often called when the associated player is released.
```kotlin
mediaSession.release()
```
--------------------------------
### Add Pillarbox Cast Dependency
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-cast/docs/README.md
Add the Pillarbox Cast module dependency to your build.gradle or build.gradle.kts file to integrate Cast functionality into your Android application.
```kotlin
implementation("ch.srgssr.pillarbox:pillarbox-cast:")
```
--------------------------------
### Declare PillarboxMediaLibraryService in Manifest
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
This XML snippet shows how to declare the DemoMediaLibraryService in the Android manifest. It includes necessary intent filters for MediaLibraryService and MediaBrowserService, and specifies foreground service type.
```xml
```
--------------------------------
### Enable Foreground Service Permission
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
This XML snippet adds the necessary permission to the manifest to enable foreground services, which is required for media playback services.
```xml
```
--------------------------------
### Configure MediaItemConverter
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-cast/docs/README.md
Configure the MediaItemConverter for PillarboxCastPlayer. By default, it uses DefaultMediaItemConverter, but you can provide a custom implementation if needed.
```kotlin
val player = PillarboxCastPlayer(context, Default) {
mediaItemConverter(DefaultMediaItemConverter()) // By default
}
```
--------------------------------
### Declare Android Auto Application
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaSession.md
This XML snippet declares the application as an Android Auto application by referencing an automotive app description resource.
```xml
```
--------------------------------
### Send Commanders Act Event
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-analytics/docs/README.md
Send a custom event for Commanders Act using SRGAnalytics.sendEvent(). Events are used to track application-specific occurrences like clicks or user choices.
```kotlin
val commandersActEvent = CommandersActEvent(name = "event")
SRGAnalytics.sendEvent(commandersActEvent)
```
--------------------------------
### Toggle Media Item Tracking
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-player/docs/MediaItemTracking.md
Explains how to enable or disable media item tracking globally for the PillarboxPlayer using the `trackingEnabled` property. Setting this to `false` will stop all active trackers.
```kotlin
player.trackingEnabled = false
```
--------------------------------
### Send Commanders Act Page View
Source: https://github.com/srgssr/pillarbox-android/blob/main/pillarbox-analytics/docs/README.md
Send a page view event specifically for Commanders Act using SRGAnalytics.sendPageView(). This method sends the event only to Commanders Act.
```kotlin
val commandersActPageView = CommandersActPageView(
name = "page_name",
type = "page_type",
levels = listOf("level1", "level2"),
)
SRGAnalytics.sendPageView(
commandersAct = commandersActPageView
)
```