Android quick start

OGPlayer for Android is built on Media3/ExoPlayer with a Jetpack Compose player UI, distributed as AAR artifacts.

Requirements: Android 8.0+ (minSdk 26) · Kotlin 2.1+ · a Compose-enabled app for the UI module (ogplayer-core alone works from any Android app).

1 · Add the repository and the dependencies

Android artifacts are served from the OGPlayer Maven repository. Add it to dependencyResolutionManagement in your settings file, after google() and mavenCentral() — the content filter keeps Gradle from asking it for anything outside the tv.ogplayer group:

Kotlin DSL

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://maven.ogplayer.tv") { content { includeGroup("tv.ogplayer") } }
    }
}

Groovy DSL

settings.gradle

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://maven.ogplayer.tv"
            content { includeGroup "tv.ogplayer" }
        }
    }
}

Projects that still declare repositories per module (allprojects { repositories { … } } in the root build.gradle) add the same maven(…) line there instead.

Then the modules, in your app module:

Kotlin DSL

app/build.gradle.kts

dependencies {
    implementation("tv.ogplayer:ogplayer-core:<version>")
    implementation("tv.ogplayer:ogplayer-ui:<version>")
    // optional capabilities:
    implementation("tv.ogplayer:ogplayer-ads-ima:<version>")
    implementation("tv.ogplayer:ogplayer-cast:<version>")
}

Groovy DSL

app/build.gradle

dependencies {
    implementation "tv.ogplayer:ogplayer-core:<version>"
    implementation "tv.ogplayer:ogplayer-ui:<version>"
    // optional capabilities:
    implementation "tv.ogplayer:ogplayer-ads-ima:<version>"
    implementation "tv.ogplayer:ogplayer-cast:<version>"
}

Replace <version> with the current Android SDK version — 1.6.0 at the time of writing; the release notes always list the latest per platform. All tv.ogplayer modules in your app must share one version.

Media3 (which the SDK builds on) requires core-library desugaring in your app module:

android {
    compileOptions {
        isCoreLibraryDesugaringEnabled = true
    }
}
dependencies {
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
}

R8 / ProGuard: nothing to configure

The AARs ship their own consumer rules — when your app builds with minifyEnabled true, R8 picks them up automatically and keeps exactly the SDK surface your code calls. No -keep rules to copy, no proguard documentation to maintain. (The SDK itself ships pre-minified.)

Offline downloads add a foreground-service permission

ogplayer-core ships the download service, so manifest merging adds FOREGROUND_SERVICE + FOREGROUND_SERVICE_DATA_SYNC to your app. Two consequences:

• Play Console asks you to declare the foreground-service use — select data sync and describe media downloads for offline playback.
• On Android 15+ the platform caps dataSync services at ~6 hours per day; very large download queues past that point continue only while the app is foregrounded.

If your app doesn’t offer downloads and you’d rather not declare anything, remove the permission in your manifest:

<uses-permission
    android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC"
    tools:node="remove" />

2 · Build a player and load media

val player = OGPlayer.Builder(context)
    .setLicenseKey("OGP2…")                     // omit → watermarked trial mode
    .setAdsProvider(ImaAdsProvider(context))    // optional
    .setCastConnector(OGCastConnector(context)) // optional
    .build()

player.load(
    OGMediaItem.Builder("https://example.com/stream.m3u8")
        .setStreamType(StreamType.VOD)
        .setTitle("My video")
        .setDrm(
            DrmConfig.Builder("https://license.example.com/widevine")
                .setTokenProvider("X-DRM-Token") { tokenService.freshToken() }
                .build(),
        )
        .setThumbnailTrack("https://example.com/storyboard.vtt")
        .build(),
)

DRM tokens are fetched on every license request — never frozen at load time — so sessions survive long pauses and license expiry transparently (PlaybackListener.onDrmSessionRenewed).

3 · Show the player

OGPlayerView(
    player = player,
    uiConfig = OGUiConfig.Builder().build(),
    fullscreenHandler = ActivityFullscreenHandler(activity),
    overlays = mapOf(OverlaySlot.TOP_END to { MyWatermark() }),
)

Release the player with player.release() when the screen goes away.

4 · Listen

player.addListener(object : PlaybackListener {
    override fun onStateChanged(state: PlaybackState) { /* IDLE/BUFFERING/READY/ENDED */ }
    override fun onError(error: OGPlayerError) { /* stable codes, see Error codes */ }
})
player.addAnalyticsListener { event -> analytics.track(event.toString()) }

Complete examples

Every guide in these docs has a matching screen in the open-source Android demo app — clone it and lift code from there.