Handling Autoplay in Scrollable Containers

When FwPlayerDeckView is placed inside a scrollable parent (e.g., NestedScrollView, Compose Column with verticalScroll, or LazyColumn), it cannot automatically detect that the outer container is scrolling. This page explains the problem, provides two approaches to solve it, and documents known limitations in Jetpack Compose.

---

Table of Contents

1. Background

2. Approach 1: Manual Viewport Notification

   • Demo 1A: Traditional View (Fragment + NestedScrollView)

   • Demo 1B: Compose (Activity + Scrollable Column)

3. Approach 2: Automatic Visibility Tracking

   • Demo 2A: Traditional View (Fragment + NestedScrollView)

   • Demo 2B: Compose (Activity + Scrollable Column)

4. How Automatic Tracking Works Internally

5. Known Limitations of Automatic Tracking in Compose

6. Recommendation Summary

---

Background

FwPlayerDeckView has built-in lifecycle callbacks that handle window-level visibility:

• onAttachedToWindow() / onDetachedFromWindow() — fires when the view is added to or removed from the window.

• onWindowFocusChanged() — fires when the hosting window gains or loses focus.

These callbacks work correctly for basic scenarios (e.g., the Activity goes to the background). However, they do not fire when a parent scrollable container clips the view out of the visible area. When the user scrolls the FwPlayerDeckView off-screen inside a NestedScrollView or Compose scrollable Column, the view remains attached to the window and the window retains focus. As a result, autoplay continues even though the PlayerDeck is no longer visible to the user.

We provide two approaches to solve this problem.

---

Approach 1: Manual Viewport Notification

The host code detects scrolling itself and calls onViewPortEntered() / onViewPortLeft() on the FwPlayerDeckView when it crosses a visibility threshold (e.g., 50%).

Pros:

• Full control over visibility detection logic.

• Works reliably in all environments (traditional Views and Compose).

• Compatible with any scrollable container, including LazyColumn.

Cons:

• Requires manual scroll tracking and visibility calculation.

• More boilerplate code in the host.

---

Demo 1A: Traditional View (Fragment + NestedScrollView)

Layout XML (fragment_player_deck_scrollable.xml):

<?xml version="1.0" encoding="utf-8"?>
<androidx.core.widget.NestedScrollView
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/scrollView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:fillViewport="true">

    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="vertical">

        <!-- Content above the PlayerDeck -->
        <TextView
            android:layout_width="match_parent"
            android:layout_height="300dp"
            android:gravity="center"
            android:text="Scroll down to see PlayerDeckView" />

        <!-- FwPlayerDeckView -->
        <com.firework.videofeed.FwPlayerDeckView
            android:id="@+id/playerDeck"
            android:layout_width="match_parent"
            android:layout_height="200dp" />

        <!-- Content below the PlayerDeck -->
        <TextView
            android:layout_width="match_parent"
            android:layout_height="800dp"
            android:gravity="center"
            android:text="Bottom content" />

    </LinearLayout>
</androidx.core.widget.NestedScrollView>

Fragment (PlayerDeckScrollableFragment.kt):

import android.graphics.Rect
import android.os.Bundle
import android.util.Log
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.view.ViewTreeObserver
import androidx.fragment.app.Fragment
import com.firework.common.feed.FeedResource
import com.firework.videofeed.FwPlayerDeckView
import com.firework.viewoptions.BaseOption
import com.firework.viewoptions.PlayerOption
import com.firework.viewoptions.ViewOptions
import kotlin.math.max
import kotlin.math.min

class PlayerDeckScrollableFragment : Fragment(),
    ViewTreeObserver.OnScrollChangedListener {

    private var playerDeckView: FwPlayerDeckView? = null
    private var scrollView: View? = null

    // Track whether the PlayerDeck was visible in the last check
    private var wasPlayerDeckVisible = false

    // Throttle scroll checks to avoid excessive computation
    private var lastScrollTime = 0L
    private val scrollThrottleMs = 100L

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?,
    ): View {
        val root = inflater.inflate(
            R.layout.fragment_player_deck_scrollable, container, false
        )
        playerDeckView = root.findViewById(R.id.playerDeck)
        scrollView = root.findViewById(R.id.scrollView)
        return root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        val viewOptions = ViewOptions.Builder()
            .baseOption(
                BaseOption.Builder()
                    .feedResource(FeedResource.Channel("your_channel_id"))
                    .build()
            )
            .playerOption(
                PlayerOption.Builder()
                    .autoplay(true)
                    .build()
            )
            .build()

        playerDeckView?.setOnErrorListener { error ->
            Log.e(TAG, "Error: $error")
        }

        playerDeckView?.init(viewOptions, childFragmentManager)
    }

    override fun onStart() {
        super.onStart()
        // Register scroll listener on the parent NestedScrollView
        scrollView?.viewTreeObserver?.addOnScrollChangedListener(this)
    }

    override fun onStop() {
        // Unregister when the fragment is no longer visible
        scrollView?.viewTreeObserver?.removeOnScrollChangedListener(this)
        super.onStop()
    }

    override fun onScrollChanged() {
        // Throttle: skip if called too frequently
        val now = System.currentTimeMillis()
        if (now - lastScrollTime < scrollThrottleMs) return
        lastScrollTime = now

        val deck = playerDeckView ?: return
        val isHalfVisible = deck.visibleRatio() >= 0.5f

        when {
            wasPlayerDeckVisible && !isHalfVisible -> {
                // Was visible, now scrolled out — pause playback
                deck.onViewPortLeft()
                Log.d(TAG, "PlayerDeck left viewport")
            }
            !wasPlayerDeckVisible && isHalfVisible -> {
                // Was hidden, now scrolled in — resume playback
                deck.onViewPortEntered()
                Log.d(TAG, "PlayerDeck entered viewport")
            }
        }
        wasPlayerDeckVisible = isHalfVisible
    }

    /**
     * Calculates the fraction of the view that is currently visible on screen.
     * Returns a value between 0.0 (fully hidden) and 1.0 (fully visible).
     */
    private fun View.visibleRatio(): Float {
        if (!isShown || height == 0) return 0f
        val rect = Rect()
        return if (getGlobalVisibleRect(rect)) {
            min(1f, max(0f, rect.height().toFloat() / height.toFloat()))
        } else {
            0f
        }
    }

    override fun onDestroyView() {
        try {
            scrollView?.viewTreeObserver?.removeOnScrollChangedListener(this)
        } catch (e: Exception) {
            Log.w(TAG, "Cleanup error", e)
        }
        playerDeckView?.destroy()
        playerDeckView = null
        scrollView = null
        super.onDestroyView()
    }

    companion object {
        private const val TAG = "PlayerDeckScrollable"
    }
}

How it works:

1. An OnScrollChangedListener is registered on the NestedScrollView's ViewTreeObserver.

2. On each scroll event (throttled to every 100ms), getGlobalVisibleRect() computes how much of the FwPlayerDeckView is on screen.

3. When the visible ratio drops below 50%, onViewPortLeft() pauses playback.

4. When the visible ratio reaches 50% or above, onViewPortEntered() resumes playback.

---

Demo 1B: Compose (Activity + Scrollable Column)

This example shows manual viewport notification in a Compose-based UI, using rememberScrollState() and the update block of AndroidView to track visibility.

import android.content.Context
import android.graphics.Rect
import android.os.Bundle
import android.util.Log
import android.view.ViewGroup
import androidx.activity.compose.setContent
import androidx.appcompat.app.AppCompatActivity
import androidx.compose.foundation.ScrollState
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import androidx.fragment.app.FragmentActivity
import com.firework.common.feed.FeedResource
import com.firework.videofeed.FwPlayerDeckView
import com.firework.viewoptions.BaseOption
import com.firework.viewoptions.PlayerOption
import com.firework.viewoptions.ViewOptions
import kotlin.math.max
import kotlin.math.min

class ManualScrollComposeActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                val scrollState = rememberScrollState()
                Column(
                    modifier = Modifier
                        .fillMaxSize()
                        .verticalScroll(scrollState),
                ) {
                    // Top spacer to push PlayerDeck below the fold
                    Spacer(modifier = Modifier.fillMaxWidth().height(800.dp))

                    // PlayerDeck with manual scroll tracking
                    ScrollablePlayerDeckItem(
                        modifier = Modifier.fillMaxWidth().height(200.dp),
                        scrollState = scrollState,
                    )

                    // Bottom spacer
                    Spacer(modifier = Modifier.fillMaxWidth().height(800.dp))
                }
            }
        }
    }
}

@Composable
private fun ScrollablePlayerDeckItem(
    modifier: Modifier = Modifier,
    scrollState: ScrollState,
) {
    val context = LocalContext.current

    val viewOptions = remember {
        ViewOptions.Builder()
            .baseOption(
                BaseOption.Builder()
                    .feedResource(FeedResource.Channel("your_channel_id"))
                    .build()
            )
            .playerOption(
                PlayerOption.Builder()
                    .autoplay(true)
                    .build()
            )
            .build()
    }

    // Track the last known visibility state to avoid redundant calls
    var lastVisibilityState by remember { mutableStateOf(false) }

    // Read scrollState.value so that recomposition (and thus the update block)
    // is triggered whenever the scroll position changes.
    val currentScrollValue = scrollState.value

    AndroidView(
        modifier = modifier,
        factory = { androidContext ->
            FwPlayerDeckView(androidContext).apply {
                layoutParams = ViewGroup.LayoutParams(
                    ViewGroup.LayoutParams.MATCH_PARENT,
                    ViewGroup.LayoutParams.MATCH_PARENT,
                )

                setOnErrorListener { error ->
                    Log.e("ManualScrollCompose", "Error: $error")
                }

                // Initialize the view
                val fragmentManager =
                    (context as FragmentActivity).supportFragmentManager
                init(viewOptions, fragmentManager)
            }
        },
        update = { view ->
            // IMPORTANT: Reference currentScrollValue here so the Compose compiler
            // sees this lambda captures a value that changes on every scroll.
            // Without this, strong-skipping mode treats the lambda as unchanged
            // (its only other capture, lastVisibilityState, is a stable State object)
            // and skips calling update entirely.
            @Suppress("UNUSED_EXPRESSION")
            currentScrollValue

            // Compute visibility using getGlobalVisibleRect (consistent with Demo 1A and the SDK internals).
            val rect = Rect()
            val isHalfVisible = if (view.getGlobalVisibleRect(rect) && view.height > 0) {
                min(1f, max(0f, rect.height().toFloat() / view.height.toFloat())) >= 0.5f
            } else {
                false
            }

            // Only notify the PlayerDeck when visibility state actually changes
            if (isHalfVisible != lastVisibilityState) {
                if (isHalfVisible) {
                    view.onViewPortEntered()
                } else {
                    view.onViewPortLeft()
                }
                lastVisibilityState = isHalfVisible
            }
        },
        onRelease = { view ->
            view.destroy()
        },
    )
}

How it works:

1. rememberScrollState() tracks the scroll position of the Column. Reading scrollState.value in the composable body triggers recomposition whenever the scroll position changes.

2. Critical: currentScrollValue is referenced inside the update lambda. This is required because Compose's strong-skipping mode (enabled by default since Compose compiler 1.5.4+) remembers lambdas based on their captured values. Without this reference, the lambda only captures lastVisibilityState (a MutableState object whose reference never changes), so Compose considers the lambda unchanged and skips calling update entirely — even though the parent composable recomposed.

3. In the update block, getGlobalVisibleRect() computes the visible portion of the AndroidView on screen (consistent with Demo 1A and the SDK's internal tracker).

4. The lastVisibilityState guard prevents redundant onViewPortEntered() / onViewPortLeft() calls — only actual state transitions trigger notification.

5. onViewPortEntered() / onViewPortLeft() are called when the visible ratio crosses the 50% threshold.

---

Approach 2: Automatic Visibility Tracking

Call setVisibilityTrackingEnabled(true) before or after init(). The SDK will internally track visibility and pause/resume playback automatically. No manual scroll-tracking code is needed.

Pros:

• Zero manual scroll tracking code required.

• Single line of configuration.

Cons:

• May not work in certain Compose scenarios (see Known Limitations below).

---

Demo 2A: Traditional View (Fragment + NestedScrollView)

Use the same XML layout as Demo 1A. The Fragment is much simpler because no scroll listener is needed:

import android.os.Bundle
import android.util.Log
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import androidx.fragment.app.Fragment
import com.firework.common.feed.FeedResource
import com.firework.videofeed.FwPlayerDeckView
import com.firework.viewoptions.BaseOption
import com.firework.viewoptions.PlayerOption
import com.firework.viewoptions.ViewOptions

class PlayerDeckScrollableFragmentAuto : Fragment() {

    private var playerDeckView: FwPlayerDeckView? = null

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?,
    ): View {
        val root = inflater.inflate(
            R.layout.fragment_player_deck_scrollable, container, false
        )
        playerDeckView = root.findViewById(R.id.playerDeck)
        return root
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        val viewOptions = ViewOptions.Builder()
            .baseOption(
                BaseOption.Builder()
                    .feedResource(FeedResource.Channel("your_channel_id"))
                    .build()
            )
            .playerOption(
                PlayerOption.Builder()
                    .autoplay(true)
                    .build()
            )
            .build()

        playerDeckView?.setOnErrorListener { error ->
            Log.e("PlayerDeckAuto", "Error: $error")
        }

        // Enable automatic visibility tracking — this is the only extra line needed
        playerDeckView?.setVisibilityTrackingEnabled(true)

        playerDeckView?.init(viewOptions, childFragmentManager)
    }

    override fun onDestroyView() {
        playerDeckView?.destroy()
        playerDeckView = null
        super.onDestroyView()
    }
}

Compared to Demo 1A, the only addition is:

playerDeckView?.setVisibilityTrackingEnabled(true)

No OnScrollChangedListener, no visibleRatio() calculation, no manual onViewPortEntered()/onViewPortLeft() calls.

---

Demo 2B: Compose (Activity + Scrollable Column)

import android.os.Bundle
import android.util.Log
import android.view.ViewGroup
import androidx.activity.compose.setContent
import androidx.appcompat.app.AppCompatActivity
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material3.MaterialTheme
import androidx.compose.runtime.Composable
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import androidx.fragment.app.FragmentActivity
import com.firework.common.feed.FeedResource
import com.firework.videofeed.FwPlayerDeckView
import com.firework.viewoptions.BaseOption
import com.firework.viewoptions.PlayerOption
import com.firework.viewoptions.ViewOptions

class AutoTrackingComposeActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MaterialTheme {
                val scrollState = rememberScrollState()
                // Use a regular scrollable Column (NOT LazyColumn — see limitations below)
                Column(
                    modifier = Modifier
                        .fillMaxSize()
                        .verticalScroll(scrollState),
                ) {
                    Spacer(modifier = Modifier.fillMaxWidth().height(800.dp))
                    PlayerDeckAutoSection()
                    Spacer(modifier = Modifier.fillMaxWidth().height(800.dp))
                }
            }
        }
    }
}

@Composable
private fun PlayerDeckAutoSection() {
    val context = LocalContext.current

    val viewOptions = remember {
        ViewOptions.Builder()
            .baseOption(
                BaseOption.Builder()
                    .feedResource(FeedResource.Channel("your_channel_id"))
                    .build()
            )
            .playerOption(
                PlayerOption.Builder()
                    .autoplay(true)
                    .build()
            )
            .build()
    }

    AndroidView(
        modifier = Modifier
            .fillMaxWidth()
            .height(200.dp),
        factory = { androidContext ->
            FwPlayerDeckView(androidContext).apply {
                layoutParams = ViewGroup.LayoutParams(
                    ViewGroup.LayoutParams.MATCH_PARENT,
                    ViewGroup.LayoutParams.MATCH_PARENT,
                )

                setOnErrorListener { error ->
                    Log.e("AutoTrackingCompose", "Error: $error")
                }

                // Enable automatic visibility tracking
                setVisibilityTrackingEnabled(true)

                // Initialize the view
                val fragmentManager =
                    (context as FragmentActivity).supportFragmentManager
                init(viewOptions, fragmentManager)
            }
        },
        onRelease = { view ->
            view.destroy()
        },
    )
}

Key point: setVisibilityTrackingEnabled(true) can be called before or after init(). In the example above it is called before init() inside the factory block so the tracker starts as soon as the view is initialized.

Important: Use a regular scrollable Column (with Modifier.verticalScroll()), not LazyColumn. See the limitations section below.

---

How Automatic Tracking Works Internally

When setVisibilityTrackingEnabled(true) is called, the SDK creates a ViewVisibilityTracker that monitors the view using the Android View system:

1. Listeners registered: OnGlobalLayoutListener and OnScrollChangedListener on the view's ViewTreeObserver. An OnAttachStateChangeListener handles window attach/detach events.

2. Visibility computation: On each scroll or layout event (throttled to every 50ms to avoid excessive computation), the tracker calls getGlobalVisibleRect() on the view and computes:

   visibleFraction = (visibleRect.width * visibleRect.height) / (view.width * view.height)

3. Threshold: If visibleFraction >= 0.5 (50%), the view is considered visible. If it drops below 50%, the view is considered hidden.

4. Callback: When the visibility state changes, the tracker notifies the FwPlayerDeckView, which calls playerManager.pauseTemporarily() or playerManager.resumeFromTemporaryPause() accordingly.

5. Cleanup: The tracker is automatically stopped when destroy() is called.

---

Known Limitations of Automatic Tracking in Compose

The automatic visibility tracking (setVisibilityTrackingEnabled) relies on Android View system mechanisms (ViewTreeObserver, getGlobalVisibleRect). In certain Jetpack Compose scenarios, these mechanisms do not work correctly.

1. LazyColumn / LazyRow / LazyVerticalGrid

LazyColumn and similar lazy composables dispose the AndroidView entirely when items scroll out of the visible area. The view is destroyed (removed from the composition tree) rather than merely scrolled off-screen.

Impact:

• The ViewVisibilityTracker never gets a chance to detect "scrolled out" — the view is simply gone.

• Autoplay does stop (because the view is detached from the window), but re-entering the viewport creates a brand new view instance, losing all internal state.

• The onRelease callback fires on every scroll-out, calling destroy(), and factory fires on every scroll-in, calling init() again.

2. Deeply Nested Compose Layout Nodes with Clipping

If the AndroidView is nested inside multiple Compose containers that apply Modifier.clip() or custom clipping, getGlobalVisibleRect() may not accurately reflect Compose-level clipping.

Impact:

• The Android View system and Compose layout system track clipping independently.

• The visible rect may report the view as "visible" when Compose has actually clipped it, causing autoplay to continue when the view is not visible to the user.

3. Compose Scroll Containers That Do Not Trigger OnScrollChangedListener

While Modifier.verticalScroll() typically propagates scroll events through the underlying AndroidComposeView, there are edge cases where offset changes are handled purely in Compose's layout system and never dispatched as traditional scroll events to ViewTreeObserver:

• Modifier.offset with animated values — the offset is applied at the Compose layout level.

• Custom NestedScrollConnection — scroll deltas may be consumed before reaching the View layer.

• HorizontalPager / VerticalPager — page transitions use Compose-internal animation.

Impact:

• The OnScrollChangedListener never fires, so the tracker cannot detect visibility changes.

• Autoplay continues even though the view has been scrolled off-screen.

---

Recommendation Summary

Scenario	Recommended Approach
NestedScrollView (traditional View)	Approach 2 (automatic) — simplest setup
Compose Column with verticalScroll	Approach 2 (automatic) — generally works
LazyColumn / LazyRow	Approach 1 (manual) — required because views are disposed
HorizontalPager / VerticalPager	Approach 1 (manual) — scroll events may not propagate
Complex nested Compose layouts with clipping	Approach 1 (manual) — getGlobalVisibleRect may be inaccurate

General rule of thumb:

• For simple layouts, prefer Approach 2 for its simplicity.

• For LazyColumn/LazyRow scenarios, always use Approach 1 or avoid LazyColumn entirely by using a regular scrollable Column.

• When in doubt, Approach 1 is the safest choice since it gives you full control over the visibility detection logic.