Vega Media Controls Issues - Amazon Vega Docs

Use this page to diagnose problems with Vega Media Controls in your media app, such as:

Fast-forward and rewind buttons on the remote don’t respond.
Alexa voice commands are ignored or call a different handler than you expect.
The seek bar doesn’t match the playback position.
Media controls work only some of the time.

Quick triage: platform or app issue

Before you investigate your app code, answer the following questions.

Question	Platform issue indicator
Does the problem only occur on specific Fire TV device models?	Yes
Do some input methods work while others don’t (for example, the D-pad works but the media buttons don’t)?	Yes
Did the issue appear after a Fire TV OS update?	Yes

If you answered yes to two or more questions, you likely have a platform issue. Contact your Amazon representative or follow the triage guidelines to report it. Otherwise, continue with the common issues on this page.

Fast-forward and rewind buttons don’t respond

Symptoms

The fast-forward and rewind buttons on the remote don’t respond.
D-pad left and right still seek.
Play and pause work normally.

Cause Your app isn’t registered with Vega Media Controls, usually because the W3C Media integration isn’t set up. Solution

Make sure the primary interactive component in your manifest.toml file has the media category and is identified as the interface provider. For the full manifest, see Get started with Vega Media Controls.
[[components.interactive]] id = "com.yourapp.main" categories = ["com.amazon.category.kepler.media"] [[extras]] key = "interface.provider" component-id = "com.yourapp.main"
Make sure your manifest lists the commands and features that your app supports. Your app doesn’t receive SkipForward and SkipBackward unless they appear in command_options, and it doesn’t receive FastForward and Rewind unless VariableSpeed appears in features.

Call setMediaControlFocus on your player before you start playback, as described in W3C Media integration with Vega Media Controls.

const componentInstance = useComponentInstance();
const player = new W3CMediaPlayer();

// Call this before playing content.
player.setMediaControlFocus(componentInstance);

Confirm that your app is registered by running the registration check.

Media controls work only some of the time

Symptoms

Fast-forward and rewind work sometimes but not always.
Controls start working after you restart the app.

Cause The app calls setMediaControlFocus too late, for example after playback has already started, or before the component instance is available. Solution Call setMediaControlFocus once the component instance is available and before playback starts.

export const App = () => {
  const componentInstance = useComponentInstance();
  const [player, setPlayer] = useState<W3CMediaPlayer | null>(null);

  useEffect(() => {
    if (componentInstance) {
      const mediaPlayer = new W3CMediaPlayer();
      mediaPlayer.setMediaControlFocus(componentInstance);
      setPlayer(mediaPlayer);
    }
  }, [componentInstance]);

  // Start playback only after media control focus is set.
  const startPlayback = () => {
    player?.play();
  };

  // ...
};

Don’t set focus inside the function that starts playback.

// Incorrect: focus is set after playback has started.
const startVideo = () => {
  player.play();
  player.setMediaControlFocus(componentInstance);
};

Seek bar doesn’t match the playback position

Symptoms

Fast-forward and rewind work, but the seek bar doesn’t move.
The displayed position drifts from the actual playback position.

Cause Your app handles media control commands itself but doesn’t publish the new state to Vega Media Controls after it changes the playback position. Solution After every change to playback position or status, update your session state and call updateMediaSessionStates. The following example extends the MediaPlayerState pattern from Get started with Vega Media Controls.

async handleSkipForward(delta: ITimeValue, sessionId?: IMediaSessionId): Promise<void> {
  const newPosition = this.player.currentTime + delta.seconds + delta.nanoseconds / 1e9;
  this.player.currentTime = newPosition;

  const nowMs = Date.now();
  this.mediaPlayerState.currentPosition = {
    seconds: Math.floor(newPosition),
    nanoseconds: Math.floor((newPosition % 1) * 1e9),
  };
  this.mediaPlayerState.playbackPosition = {
    updatedAtTime: {seconds: Math.floor(nowMs / 1000), nanoseconds: (nowMs % 1000) * 1e6},
    position: this.mediaPlayerState.currentPosition,
  };

  // Publish the new state so the seek bar and Alexa stay in sync.
  this.mediaControlServer.updateMediaSessionStates([this.mediaPlayerState.getServerState()]);
}

Apply the same pattern anywhere your app changes position outside a handler, such as a seek from your own UI.

Alexa voice commands call a different handler than expected

Symptoms

Saying “Alexa, stop” pauses playback instead of calling handleStop.
“Alexa, fast forward” seeks instead of calling handleFastForward.

Cause Alexa translates some transport control utterances to a different Vega Media Controls command than the utterance name suggests. Solution Implement the handlers in the following table. They are the ones Alexa actually calls.

Alexa command	Handler called	Notes
Pause	`handlePause`
Stop	`handlePause`	Alexa doesn’t call `handleStop`.
Rewind	`handleSeek`	Seeks back 10 seconds by default. If the user says a duration, such as “rewind 20 seconds,” the seek uses that duration.
Fast forward	`handleSeek`	Seeks forward 10 seconds by default.
Next	`handleNext`
Previous	`handlePrevious`
Start over	`handleSeek`

Diagnostic tools

These checks use the Vega Media Controls client API to see your app the way the system does. Run them from a test build of your app. For more about the client API, see For media control client apps.

Check that your app is registered

The endpoint locator returns a ranked list of media apps. The first entry is typically the app that currently has focus.

import {MediaControlComponentAsync} from '@amazon-devices/kepler-media-controls';

const checkRegistration = async () => {
  const locator = MediaControlComponentAsync.makeMediaControlEndpointLocator();
  const endpoints = await locator.getMediaControlEndpoints();

  console.log(`Registered media apps: ${endpoints.length}`);
  endpoints.forEach((endpoint, index) => {
    console.log(`App ${index}: ${endpoint.getEndpointPackageId().id}`);
  });

  // Release the clients when you're done.
  endpoints.forEach((endpoint) => endpoint.destroy());
};

If your app’s package ID isn’t in the list, check your manifest and your setMediaControlFocus call.

Test command routing

Send commands to the focused app and confirm that your handlers receive them.

import {MediaControlComponentAsync} from '@amazon-devices/kepler-media-controls';

const testMediaControls = async () => {
  const locator = MediaControlComponentAsync.makeMediaControlEndpointLocator();
  const endpoints = await locator.getMediaControlEndpoints();

  if (endpoints.length === 0) {
    console.error('No media apps registered');
    return;
  }

  const focusedApp = endpoints[0];
  const tenSeconds = {seconds: 10, nanoseconds: 0};

  const tests = [
    {name: 'Play', action: () => focusedApp.play()},
    {name: 'Pause', action: () => focusedApp.pause()},
    {name: 'Skip forward', action: () => focusedApp.skipForward(tenSeconds)},
    {name: 'Skip backward', action: () => focusedApp.skipBackward(tenSeconds)},
  ];

  for (const test of tests) {
    try {
      await test.action();
      console.log(`${test.name}: sent`);
    } catch (error) {
      console.error(`${test.name} failed:`, error);
    }
  }

  endpoints.forEach((endpoint) => endpoint.destroy());
};

Minimal working implementation

The following example is the smallest W3C Media integration that receives remote and Alexa media commands.

import {useComponentInstance} from '@amazon-devices/react-native-kepler';
import {W3CMediaPlayer} from '@amazon-devices/react-native-w3cmedia';
import {useEffect} from 'react';

export const App = () => {
  const componentInstance = useComponentInstance();

  useEffect(() => {
    if (componentInstance) {
      const player = new W3CMediaPlayer();
      player.setMediaControlFocus(componentInstance);
    }
  }, [componentInstance]);

  return <YourVideoPlayerUI />;
};

Your package.json file must include the following dependencies.

{
  "@amazon-devices/kepler-media-controls": "~1.0.0",
  "@amazon-devices/react-native-w3cmedia": "~1.0.0"
}

​Quick triage: platform or app issue

​Fast-forward and rewind buttons don’t respond

​Media controls work only some of the time

​Seek bar doesn’t match the playback position

​Alexa voice commands call a different handler than expected

​Diagnostic tools

​Check that your app is registered

​Test command routing

​Minimal working implementation

​Related topics

Quick triage: platform or app issue

Fast-forward and rewind buttons don’t respond

Media controls work only some of the time

Seek bar doesn’t match the playback position

Alexa voice commands call a different handler than expected

Diagnostic tools

Check that your app is registered

Test command routing

Minimal working implementation

Related topics