Debugging SurfaceView Issues in Jetpack Compose: Lessons Learned from Android TV Development

If you’ve worked with Jetpack Compose and SurfaceView on Android TV, you may have encountered a puzzling issue: video playback shows a white screen, but audio works fine. This exact issue surfaced during my recent project using Media3 Player, and while I eventually found a solution, it required diving deep into how Jetpack Compose works.

This post outlines the problem, the debugging journey, and how I resolved it — hopefully saving you time if you face a similar situation.

The Problem

I was implementing video playback using SurfaceView with Media3 Player in Jetpack Compose. Everything seemed to work:

• Audio played fine.

• The UI rendered correctly.

But the video screen was white.

Interestingly, setting SurfaceView.setZOrderOnTop(true) fixed it — but at the cost of breaking UI layering (not ideal for overlays like media controls).

The Discovery: Surface Composable and CompositingStrategy.Offscreen

After days of debugging, I realized the issue wasn’t with SurfaceView or the Media3 Player. It was caused by Compose’s Surface composable in the layout hierarchy.

The Surface composable internally uses graphicsLayer with CompositingStrategy.Offscreen. According to the documentation:

“Rendering content is always done into an offscreen buffer first, then drawn to the destination. This is useful for blending or masking content.”

This offscreen rendering conflicts with SurfaceView, which relies on direct rendering. As a result, SurfaceView fails to display its content correctly when layered under or near a composable using CompositingStrategy.Offscreen.

The Fix: Replace Surface with Box

Replacing Surface with a Box composable in the hierarchy fixed the issue entirely. Unlike Surface, Box doesn’t enforce offscreen rendering, which allowed SurfaceView to render properly.

Here’s what the fix looked like:

Box(modifier = Modifier.fillMaxSize()) {
    AndroidView(
        factory = { context ->
            SurfaceView(context).apply {
                // Initialize the Media3 Player
            }
        },
        modifier = Modifier.matchParentSize()
    )

    // Add your media controls overlay here
    MediaControls()
}

What About TextureView?

For those wondering, TextureView works fine even with CompositingStrategy.Offscreen. This is because TextureView uses a different rendering pipeline that integrates seamlessly with Compose’s compositing system.

Final Thoughts

This issue highlighted the importance of understanding how Jetpack Compose integrates with traditional Android views. While Compose is powerful, there are still quirks when combining it with components like SurfaceView.

If you’ve encountered similar challenges or have tips for working with SurfaceView and Compose, I’d love to hear from you. Let’s discuss in the comments!

#AndroidTV #JetpackCompose #Media3 #SurfaceView #Kotlin #AndroidDevelopment