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

1. Go to Settings > Developer Settings > Personal access tokens.
2. Click on Generate new token.
3. Provide a note for the token, and change the expiration (if needed).
4. Make sure that at least the read:packages scope is selected.
5. Click on Generate token.
6. if you are in SRG SSR, click on Configure SSO, then Authorize the token.
7. Copy your Personal access token.
8. 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 SRG SSR Maven repository

Pillarbox is also deployed to the SRG SSR Maven repository. If you don't want to use the GitHub Packages repository, add the following to your Gradle configuration:

[!NOTE] You only need to add either the GitHub Packages repository or the SRG SSR repository, not both.

// 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()
        }
    }
}

The necessary credentials can be found in the SRG SSR Bitwarden.

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 handle SRG SSR Cast receiver with SRG SSR content
implementation("ch.srgssr.pillarbox:pillarbox-core-business-cast:<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
}

kotlin {
    compilerOptions {
        jvmTarget = JvmTarget.JVM_17
    }
}

Integrate Pillarbox

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

• pillarbox-analytics
• pillarbox-cast
• pillarbox-cast-receiver
• pillarbox-core-business
• pillarbox-core-business-cast
• pillarbox-player
• pillarbox-ui

Release process

Pillarbox is released via the CI pipeline hosted in GitHub Actions. A release is triggered by pushing a tag in the format X.Y.Z (e.g. 2.1.0).

Pushing such a tag runs the Release Pillarbox workflow, which:

1. Runs pre-release checks
2. Publishes packages
3. Uploads the demo app to Firebase App Distribution
4. Creates a GitHub Release
5. Publishes the documentation

Once the workflow completes, the Pillarbox team reviews the generated release notes and finalizes them.

Past releases are available in the release history.

Contributing

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

License

See the LICENSE file for more information.