FastPix Video Data SDK for AndroidX Media3 - monitor playback performance and QoE

Use the FastPix Video Data SDK for Media3 to monitor streaming quality, playback performance, and user interactions in your Android app. It is the official FastPix Video Data SDK for AndroidX Media3 - wrap your Media3 player with FastPixBaseMedia3Player and it automatically tracks startup time, rebuffering, bitrate changes, playback errors, and viewer engagement, then streams them as real-time quality-of-experience (QoE) analytics to the FastPix dashboard. It builds on FastPix's Android Data Core SDK.

It is not a video player - it is a drop-in analytics layer for the Media3 player you already use. Under the hood it hooks into Media3's AnalyticsListener, so there is no manual event wiring.

Works with: AndroidX Media3 on Android 7.0 (API 24) and above, HLS and MP4 sources, Kotlin and Java. Powered by FastPix, the video API platform.

FastPix docs · Video Data overview · Create a free account

---

Start here

New to the SDK? Follow these in order and you will have Media3 analytics flowing to your dashboard:

1. Why FastPix for Media3?
2. What you can track
3. How it works
4. Who it's for
5. Requirements
6. Before you start
7. Add the GitHub Packages repositories
8. Add the SDK dependency
9. Add the required permissions
10. Attach the SDK to your Media3 player
11. Run the sample app
12. Verify events in your dashboard
13. Which FastPix data SDK do I need?
14. FAQ
15. Troubleshooting

---

Why FastPix for Media3?

Media3's AnalyticsListener and PlaybackStatsListener give you raw playback events, but turning them into startup-time, rebuffering, and error dashboards is work you have to build and maintain. FastPix does that for you: wrap your Media3 player, pass your workspace key, and every session shows up on the dashboard with QoE metrics you can slice by device, app version, video, and custom dimensions.

• No new player required. Keep the Media3 player you already ship. The SDK observes it; it does not replace it.
• Real-time QoE analytics. Startup time, rebuffering, bitrate/resolution changes, and playback failures, collected as the video plays.
• Viewer engagement. See what people actually watch, and where they drop off.
• Built on Media3's own hooks. It attaches through AnalyticsListener, so it stays accurate across Media3 versions.
• Custom and beacon domains. Attach up to ten custom dimensions and send analytics to a custom tracking domain.

What you can track

• User engagement - how viewers interact with your video in real time.
• Playback quality - buffering, resolution changes, and network-aware context.
• Device and app diagnostics - spot playback issues specific to a device, OS, or app version.
• Errors - automatic capture of fatal and handled playback errors.
• Custom metadata - domain-specific dimensions you can filter the dashboard by.

How it works

Your app plays a video with AndroidX Media3. You wrap that player with FastPixBaseMedia3Player, which attaches to its AnalyticsListener and turns playback signals (startup, bitrate, rebuffering, errors, engagement) into beacons sent to FastPix, keyed to your workspace. A few minutes later the session appears in your FastPix dashboard as QoE and engagement analytics.

Who it's for

Any Android team that streams video with Media3 and needs to see how playback actually performs:

• OTT and streaming apps - track startup time and rebuffering across phones, tablets, and Android TV.
• E-learning and course apps - see which lessons stall or get abandoned.
• Live events and sports - catch stream-quality problems while they are happening.
• Short-form and UGC platforms - measure engagement and playback failures at scale.

Requirements

• Android Studio: Ladybug | 2024.2.1 or later
• Minimum SDK: 24 (Android 7.0)
• Target SDK: 35 (Android 15)
• Compile SDK: 36
• Kotlin: 2.2.10+
• Java: 11
• Gradle: 8.9+

Before you start

You will need:

• A FastPix account and workspace key. Create a free account, then copy the Workspace Key from your FastPix dashboard. See Set up a workspace. This is the only value the SDK strictly requires.
• A Media3 player that already plays a video. The SDK wraps your Media3 player, so it must already be playing before you add analytics.
• A GitHub Personal Access Token (PAT) with the read:packages scope. The SDK and its core dependency are published to GitHub Packages, which requires authentication even for public packages. Create a token.

---

Add the GitHub Packages repositories

The SDK (io.fastpix.data:media3) and its required core dependency (io.fastpix.data:core) live in two GitHub Packages repositories. Add both, or the core dependency will fail to resolve.

GitHub Packages requires authentication, so provide your GitHub username and a PAT (read:packages). Put them in local.properties (which is git-ignored, so your token is never committed):

# local.properties
gpr.user=YOUR_GITHUB_USERNAME
gpr.key=YOUR_PERSONAL_ACCESS_TOKEN

Then read those values in settings.gradle.kts and apply them to both repositories:

import java.util.Properties

val credsProps = Properties().apply {
    val f = file("${rootDir}/local.properties")
    if (f.exists()) f.inputStream().use { load(it) }
}
val githubUser = credsProps.getProperty("gpr.user") ?: System.getenv("GITHUB_ACTOR")
val githubToken = credsProps.getProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri("https://maven.pkg.github.com/FastPix/android-data-androidXmedia3")
            credentials {
                username = githubUser
                password = githubToken
            }
        }
        maven {
            url = uri("https://maven.pkg.github.com/FastPix/android-core-data-sdk")
            credentials {
                username = githubUser
                password = githubToken
            }
        }
    }
}

Never commit your PAT. Keep gpr.user / gpr.key in local.properties (git-ignored) or in the GITHUB_ACTOR / GITHUB_TOKEN environment variables for CI - never inline in a tracked file.

Add the SDK dependency

In your app module's build.gradle:

dependencies {
    implementation 'io.fastpix.data:media3:1.2.7'
}

This pulls in io.fastpix.data:core transitively, which is why the core repository above is required.

Add the required permissions

The SDK sends analytics over the network, so your app's AndroidManifest.xml needs both:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Attach the SDK to your Media3 player

Set up your Media3 player as usual, then create a FastPixBaseMedia3Player with your player view, the player instance, and your workspace key. The video, player, and custom metadata objects are optional but make the dashboard easier to slice. Release the SDK alongside the player.

class VideoPlayerActivity : AppCompatActivity() {
    private lateinit var binding: ActivityVideoPlayerBinding
    private lateinit var exoPlayer: ExoPlayer
    private lateinit var fastPixDataSDK: FastPixBaseMedia3Player

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityVideoPlayerBinding.inflate(layoutInflater)
        setContentView(binding.root)

        setupPlayer()
        setupAnalytics()
    }

    private fun setupPlayer() {
        exoPlayer = ExoPlayer.Builder(this).build()
        binding.playerView.player = exoPlayer
        
        val mediaItem = MediaItem.fromUri("YOUR_VIDEO_URL")
        exoPlayer.setMediaItem(mediaItem)
        exoPlayer.prepare()
    }

    private fun setupAnalytics() {
        // Optional
        val videoDataDetails = VideoDataDetails(
            videoId = UUID.randomUUID().toString(),
            videoTitle = "My Video"
        ).apply {
            videoSeries = "Demo Series"
            videoProducer = "Demo Producer"
            videoContentType = "VOD"
            // ..etc
        }
        // Optional
        val playerDataDetails = PlayerDataDetails(
            playerName = "media3",
            playerVersion = "latest-version"
        )
        // Optional
        val customDataDetails = CustomDataDetails().apply {
            customField1 = "Custom Value 1"
            customField2 = "Custom Value 2"
            // ..etc
        }

        fastPixDataSDK = FastPixBaseMedia3Player(
            context = this,
            playerView = binding.playerView,
            exoPlayer = exoPlayer,
            workSpaceId = "workspace-key",
            playerDataDetails = playerDataDetails,
            videoDataDetails = videoDataDetails,
            customDataDetails = customDataDetails
        )
    }

    override fun onDestroy() {
        super.onDestroy()
        exoPlayer.release()
        fastPixDataSDK.release()
    }
}

Replace workspace-key with your real Workspace Key and YOUR_VIDEO_URL with your stream. For the full list of metadata fields, see Use custom dimensions.

Run the sample app

This repo includes a runnable sample in the app/ module that plays FastPix sample streams with the SDK attached. To build and run it:

1. Clone the repository and open it in Android Studio:

   git clone https://github.com/FastPix/android-data-androidXmedia3.git
   cd android-data-androidXmedia3

2. Add your GitHub credentials to local.properties so Gradle can download the SDK (see Add the GitHub Packages repositories):

   gpr.user=YOUR_GITHUB_USERNAME
   gpr.key=YOUR_PERSONAL_ACCESS_TOKEN

3. To send analytics to your own workspace, open app/src/main/java/io/fastpix/exo/VideoPlayerActivity.kt and replace the workSpaceId = "your-workspace-key" placeholder with the Workspace Key from your FastPix dashboard. The bundled reel feed (ReelActivity) plays ready-made FastPix streams, so you can run it as-is without changing the video URLs.

4. Select a device or emulator running Android 7.0 (API 24) or higher.

5. Run the app from Android Studio, or from the command line:

   ./gradlew :app:installDebug

The app opens the reel feed and starts playing. As the video plays, the SDK sends QoE beacons (startup, buffering, bitrate changes, engagement) to FastPix; confirm them in Verify events in your dashboard.

If the build fails with "android.useAndroidX property is not enabled", add android.useAndroidX=true to the project's gradle.properties, then rebuild.

Verify events in your dashboard

1. Run the app and play a video for at least 10 seconds. Pause, resume, and seek so the SDK captures a few events.
2. Open the FastPix dashboard and go to Video Data.
3. A few minutes after playback, your session appears with views, startup time, rebuffering, and any errors.

If nothing shows up, see Troubleshooting.

---

Which FastPix data SDK do I need?

Pick the data SDK that matches the player you ship. All of them report to the same FastPix Video Data dashboard.

You are using	Use this SDK
AndroidX Media3	This repo (android-data-androidXmedia3)
The legacy standalone com.google.android.exoplayer2 library	android-data-exoplayer-sdk
Android native MediaPlayer	android-media-player-data
AVPlayer (iOS)	iOS-data-avplayer-sdk
React Native (Android + iOS)	react-native-video-data
An HTML5 web player (Video.js, Shaka, HLS.js)	web-video-data-core-sdk

Related building block: android-core-data-sdk - the foundational data layer this SDK wraps.

FAQ

How do I monitor Media3 playback performance in Android? Wrap your Media3 player with FastPixBaseMedia3Player and pass your workspace key (see Attach the SDK to your Media3 player). From then on, streaming quality, startup time, rebuffering, playback errors, and engagement appear in the FastPix dashboard - no manual AnalyticsListener wiring.

How do I track video analytics in an Android app? If your app uses AndroidX Media3, add this SDK, wrap your Media3 player, and pass your workspace key. It builds on Media3's AnalyticsListener and sends the data to the FastPix dashboard. Start at Add the GitHub Packages repositories.

Is this an alternative to Mux Data for Media3? Yes. Like Mux Data for Android, FastPix provides a native tracking wrapper for AndroidX Media3 that monitors startup time, rebuffering, bitrate, playback errors, and engagement, and reports them to the FastPix dashboard.

Does it work with the old standalone player library? This repo is for AndroidX Media3 (the current Android media library). For the legacy standalone com.google.android.exoplayer2 library, use android-data-exoplayer-sdk. Both report to the same FastPix dashboard.

What metrics does it track? Startup time, rebuffering, bitrate and resolution changes, playback errors, and viewer engagement - the signals that make up a quality-of-experience (QoE) score - plus device, OS, and app diagnostics.

What is the minimum Android version? Android 7.0 (API level 24).

Why do I need a GitHub Personal Access Token to install it? The SDK and its core dependency are hosted on GitHub Packages, which requires authentication (a PAT with read:packages) even for public packages. This is a GitHub requirement.

Why does Gradle say it can't find io.fastpix.data:core? Because you only added the media3 repository. The SDK depends on the core artifact in a separate GitHub Packages repo. Add both repositories from Add the GitHub Packages repositories.

Where do I get my workspace key? From the FastPix dashboard. Create a free account and copy the Workspace Key. See Set up a workspace.

Troubleshooting

• No data in the dashboard. Confirm the INTERNET permission is present (Add the required permissions), that the workspace key is your real key, and that the video actually played. Data can take a few minutes to appear.
• Build fails resolving io.fastpix.data:core. Add the core GitHub Packages repository (Add the GitHub Packages repositories).
• 401 / 403 from GitHub Packages. Your PAT is missing or lacks the read:packages scope. Regenerate it and re-run the build.

License

Copyright © 2025 FastPix. All rights reserved. This project is proprietary software; the FastPix SDK components require appropriate licensing. See LICENSE.

Support

For questions, issues, or feature requests:

• Email: support@fastpix.com
• Documentation: Monitor AndroidX Media3
• Issues: GitHub Issues

Related documentation

• Monitor AndroidX Media3
• FastPix Video Data overview
• Use custom dimensions
• AndroidX Media3 Documentation
• AndroidX Media3 player developer guide