Headless media playback player client/service destruction on dismount

Vega Open Beta Q&A
1

We are trying to implement headless playback, and have it loading and playing fine, but when we go to back out of our player into the menu we cannot figure out how to destroy/remove/stop the playback. We keep hearing the playback playing in the background even after we have backed out of the video player. - even after we call playerClient.destroy();

We have combed through the sample app provided here - but don’t see the video player being destroyed, only backgrounded, and when the video stream changes - repurposed.

Also, we never see onSurfaceViewDestroyed being called from the KeplerVideoSurfaceView when we dismount the video player component.

Are we supposed to be destroying the headless client and/or server or storing them globally to reuse?

I feel we have a fundamental disconnect/misunderstanding of how the headless media playback lifecycle is supposed to work. Can someone be so kind as to explain how we are supposed to be using it, and point to any documentation that we may have missed?

3

Hi @Jon_Page ,

Please check if these Best Practices help you with the background playback.

If you still have issues, please fill in the below details for further investigation:

Steps to Reproduce

  1. [List the steps for reproducing the bug]
  2. [Any specific component or method call in React Native triggering the issue]
  3. …

Observed Behavior

Explain what actually happened, noting any discrepancies or malfunctions.

<!-- Answer here -->

Expected Behavior

Describe what you expected the SDK to do under normal operation.

<!-- Answer here -->

Possible Root Cause & Temporary Workaround

Fill out anything you have tried. If you don’t know, N/A is acceptable

<!-- Answer here -->

Logs or crash report

(Please make sure to provide relevant logs as attachment and share VPKG file with your Amazon contact)

For crash issues, please refer this guide for faster troubleshooting: https://developer.amazon.com/docs/kepler-tv/detect-crash.html.

 ~/.vscode/extensions/amazon.kepler-extension-<version>/ExtensionLogs
 ~/.vscode/extensions/amazon.kepler-ui-extension-<version>/ExtensionLogs

Environment

Please fill out the fields related to your bug below:

  • SDK Version: Output of kepler --version
  • App State: [Foreground/Background]
  • OS Information
    Please ssh into the device via kepler exec vda shelland copy the output from cat /etc/os-releaseinto the answer section below. Note, if you don’t have a simulator running or device attached kepler exec vda shell will respond with vda: no devices/emulators found
<!-- Answer here if applicable -->
  • Player SDK: [Bitmovin, Shaka, ...]
  • Player SDK Version: [e.g. 1.23]
    • Audio Codecs: [AAC, ...]
    • Video Codecs: [h.264, mp4]
    • Manifest Types: [m3u8, dash, etc ..]

Thanks,
Rohit

4

I understand how to background the service when the app gets backgrounded, but what about the lifecycle when leaving the video player but remaining in the app?

as in Video Player > menu > select new video > Video Player

Do I unloadSync in that scenario?

Video Player > {unloadSync?} menu > select new video > {?} Video Player

How does the headless playback lifecycle work in that situation?

5

I’m also facing a similar issue. When backing out of the player screen, we are calling `playerClient.destroy()` but that results in the app getting back to the device’s Home screen, which I guess it’s a crash but no logs are shown.

6

Hi @Jon_Page , @adheus ,

I have already reported this to our internal team.

Please share the information requested above for us to better understand the issue and root cause it.

Thanks,
Rohit

7

Steps to Reproduce

  1. Install and setup headless playback according to the demo app
  2. Navigate to the video player, play video
  3. Back out of the video player to the app’s menu

Observed Behavior

Explain what actually happened, noting any discrepancies or malfunctions.

The media keeps playing in the background after the video player is unmounted

Expected Behavior

Describe what you expected the SDK to do under normal operation.

The Video should stop playing after the Video Player component is unmounted

Possible Root Cause & Temporary Workaround

Fill out anything you have tried. If you don’t know, N/A is acceptable

We are unsure of what the lifecycle of the headless playback should be and if/how we should destroy the playback session

Environment

Please fill out the fields related to your bug below:

  • SDK Version: 0.20.3719
  • App State: Foreground
  • OS Information
NAME="OS"
OE_VERSION="4.0.0"
OS_MAJOR_VERSION="1"
OS_MINOR_VERSION="1"
RELEASE_ID="2"
OS_VERSION="1.1"
BRANCH_CODE="VegaMainlineTvIntegration"
BUILD_DESC="OS 1.1 (VegaMainlineTvIntegration/4418)"
BUILD_FINGERPRINT="4.0.155683.0(3072cab629675a74)/4418N:user-external/release-keys"
BUILD_VARIANT="user-external"
BUILD_TAGS="release-keys"
BUILD_DATE="Wed Sep 03 05:40:19 UTC 2025"
BUILD_TIMESTAMP="1756878019"
VERSION_NUMBER="201010441850"
  • Player SDK: Headless / Shaka
  • Player SDK Version: [e.g. 1.23]
    • Video Codecs: h.264
    • Manifest Types: m3u8 HLS