Vega 0.24 / VVD: Media Controls client discovery fails with Active Clusters status 126

Vega Open Beta Bug Reports
1

1. Summary

A separate third-party app cannot discover another app’s media endpoints using the documented Media Controls client API. The public wrapper throws a TypeError; the native response reports Active Clusters status 126.

App: TV Helper POC, package com.tvhelper.controller (unpublished; no Appstore link).
Severity: Blocks current development.

The intended use case is a TV assistance app that reads a separate video app’s media session and resumes paused playback, without modifying that video app or using developer-shell commands.

2. Steps to reproduce

  1. On VVD 0.24.12044, install the official AmazonAppDev/vega-video-sample (version 3.24.0, commit ef8e4da89b22ef7973d0d41beedfa2b42f7bb272, package com.amazondeveloper.keplervideoapp).
  2. Start its HLS sample (Cosmos Laundromat, catalog item 169327). Video frames play successfully. We added no custom control integration to the provider’s application code.
  3. In a separate React Native client app with no embedded player, call:
import { MediaControlComponentAsync } from '@amazon-devices/kepler-media-controls';

const locator = MediaControlComponentAsync.makeMediaControlEndpointLocator();
const endpoints = await locator.getMediaControlEndpoints();
  1. Repeat the call in the client foreground and from a diagnostic background timer. Both fail.

3. Observed behavior / error

The public API throws TypeError: undefined is not a function in the SDK KeplerMediaControlsTM bundle. Diagnostic inspection of the underlying native getMediaControlEndpoints() response returned an error object rather than an endpoint array:

{
  "isSuccess": false,
  "errorCode": 1,
  "errorTypes": "",
  "errorMessage": "Active Clusters query transaction 2 failed with status: 126"
}

Endpoint discovery fails before we can call getSessionState or play. This is not a report of video decoding failure or a confirmed failure of the play command itself.

4. Expected behavior

A list of supported provider endpoints, or a documented actionable error. The Media Controls overview describes cross-app client methods as available to developers. The getting-started guide says its manifest prerequisites apply to providers, not client methods.

Workarounds tried / possible cause

Adding wants.service declarations for com.amazon.audio.control, com.amazon.audio.system and com.amazon.lcm.app.session.notifier.service, rebuilding and reinstalling, did not resolve the failure.

The installed VVD policy appears to require the platform signer for:

  • com.amazon.privilege.cluster-client.access
  • com.amazon.kcp.privilege.query.access
  • com.amazon.kcp.privilege.media-controls.access

We have not modified that policy or established that these checks are the exact cause of status 126. No workaround is confirmed.

5. Environment

  • Host: macOS arm64
  • Vega SDK / VVD package: 0.24.12044
  • Vega CLI: 1.3.4
  • React Native: 0.83.0
  • @amazon-devices/kepler-media-controls: 1.0.25
  • Client state: foreground and background
  • Physical retail device: not tested

6. Questions for the Vega team

  1. Are client discovery, getSessionState and play supported for ordinary third-party apps on retail Vega devices? What exact manifest declarations, user consent or registration are required?
  2. What does Active Clusters status 126 mean? Is this a known VVD limitation or SDK bug? Is there a working client sample or fixed version?
  3. If these operations require platform signing or partner access, what is the application process and which team owns it?

Related product-integration question: the helper must be invoked while an unrelated video app is foreground. useTVEventHandler receives Menu in our helper’s foreground but not while the video app is foreground (three presses; the same helper instance remains alive and its background timer executes). We understand an in-app listener is not necessarily a global launch mechanism. Is there a supported remote-button, Alexa or accessibility entry point for this workflow, followed by return to the existing media session? If this should be a separate Q&A topic, please let us know.

We can provide a minimal standalone client and sanitized reproduction results. Thank you.

5

Hi @Roman_PotapovRoman_Potapov

Welcome to Amazon Developer Community!!

I have been able to reproduce the issue you are facing and we are working on it internally to help you.

In the meantime, please do share the minimal standalone client - it’ll speed up verification.

Warm Regards,
Ivy