Overview

Pillarbox is the modern SRG SSR multimedia player ecosystem, built on top of AndroidX Media3. Pillarbox has been designed with robustness, flexibility, and efficiency in mind, with full customization of:

Metadata and asset URL retrieval.
Asset resource loading, including support for Widevine and PlayReady.
Analytics integration.
User interface layout, in either Compose or XML Views. Helpers are available in the pillarbox-ui module.

Its robust player provides all essential playback features you might expect:

Audio and video (including 360° videos) playback.
Support for on-demand and live streams, with and without DVR.
Integration with the system playback user experience.
Integration with Android's MediaSession and Android Auto.
Playlist management (navigation to previous/next item, shuffle, repeat, ...).
Support for alternative audio tracks, audio description, subtitles, ...
Multiple instances support.
Picture-in-picture support.
Playback speed controls.

In addition, Pillarbox provides support for SRG SSR content by including the pillarbox-core-business module (see "Getting started" below).

[!TIP] Pillarbox is also available on Apple platforms and the Web.

Demo

You can easily get your hands on Pillarbox by running one of the demo applications available in this project: pillarbox-demo for phone/tablet, or pillarbox-demo-tv for TV.

Each application allows you to:

Try Pillarbox with various media types and sources.
See how Pillarbox answers various use cases (pillarbox-demo only).
Access a wide range of SRG SSR content.
Search for specific SRG SSR content.

Getting started

Add the GitHub Packages repository

Pillarbox is deployed to GitHub Packages. So you need to add the following repository in your Gradle configuration:

// If you declare your repositories in the `settings.gradle(.kts)` file
repositories {
    maven("https://maven.pkg.github.com/SRGSSR/pillarbox-android") {
        credentials {
            username = providers.gradleProperty("gpr.user").get()
            password = providers.gradleProperty("gpr.key").get()
        }
    }
}

// If you declare your repositories in the root `build.gradle(.kts)` file
repositories {
    maven("https://maven.pkg.github.com/SRGSSR/pillarbox-android") {
        credentials {
            username = project.findProperty("gpr.user")?.toString()
            password = project.findProperty("gpr.key")?.toString()
        }
    }
}

Create a Personal access token

Go to Settings > Developer Settings > Personal access tokens.
Click on Generate new token.
Provide a note for the token, and change the expiration (if needed).
Make sure that at least the read:packages scope is selected.
Click on Generate token.
Copy your Personal access token.
In your ~/.gradle/gradle.properties file (create it if needed), add the following properties:
```
gpr.user=<your_GitHub_username>
gpr.key=<your_GitHub_personal_access_token>
```

[!TIP] You can check the GitHub documentation for more information.

Add the Pillarbox dependencies

In your module's build.gradle/build.gradle.kts file, add the following dependencies, based on your needs:

// Player specific features
implementation("ch.srgssr.pillarbox:pillarbox-player:<pillarbox_version>")

// Library to handle Cast integration
implementation("ch.srgssr.pillarbox:pillarbox-cast:<pillarbox_version>")

// Library to handle SRG SSR content through media URNs
implementation("ch.srgssr.pillarbox:pillarbox-core-business:<pillarbox_version>")

// Library to display the video surface
implementation("ch.srgssr.pillarbox:pillarbox-ui:<pillarbox_version>")

The latest stable version is

Enable Java 17

If not already enabled, you also need to turn on Java 17 support in every build.gradle/build.gradle.kts files using Pillarbox. To do so, add/update the following to/in the android section:

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

kotlinOptions {
    jvmTarget = "17"
}

Support Android API < 24

A change in AndroidX Media3 1.3.0 requires applications to use library desugaring, as described in the corresponding Android documentation:

compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
    isCoreLibraryDesugaringEnabled = true
}

dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.4")
}

[!IMPORTANT] This should be done even if your min SDK version is 24+.

Integrate Pillarbox

To start using Pillarbox in your project, you can check each module's documentation:

Contributing

If you want to contribute to the project have a look at our contributing guide.

License

See the LICENSE file for more information.

SRGSSR / pillarbox-android

readme