Hello World: Your First Video App

This walkthrough builds the smallest possible video app for Vega OS: a single screen that loads one progressive MP4 file and plays it. It uses URL playback mode, so you don’t need Shaka Player, DASH, HLS, or DRM to get a picture on screen. When you finish, you’ll have a working app you can extend into an adaptive streaming app. For background on how the playback stack fits together, see W3C Media API in React Native for Vega.

Prerequisites

A Vega app created from a template. For instructions, see Build Your App.
The W3C Media Player dependency, Babel configuration, and manifest permissions in place. For instructions, see Media Player Setup.
A Fire TV device or emulator that you can deploy to.

Build the app

Confirm your dependency

Your package.json file must include the W3C Media package:

"@amazon-devices/react-native-w3cmedia": "~2.1.80"

Then install it:

npm install

Create the player screen

Create a file named src/HelloWorldPlayer.tsx with the following content. This is the whole app: a VideoPlayer instance that owns playback state, and a KeplerVideoView that renders the video surface.

import React, {useEffect, useRef, useState} from 'react';
import {StyleSheet, Text, View} from 'react-native';
import {
  VideoPlayer,
  KeplerVideoView,
} from '@amazon-devices/react-native-w3cmedia';

// Any progressive MP4, MP3, MKV, FLV, OGG, or FLAC URL works in URL mode.
const VIDEO_URL = 'https://example.com/media/hello-world.mp4';

export const HelloWorldPlayer = () => {
  const player = useRef<VideoPlayer | null>(null);
  const [status, setStatus] = useState('Initializing player...');

  useEffect(() => {
    const video = new VideoPlayer();
    player.current = video;

    // Standard HTMLMediaElement events are available.
    video.addEventListener('loadedmetadata', () => setStatus('Loaded'));
    video.addEventListener('playing', () => setStatus('Playing'));
    video.addEventListener('ended', () => setStatus('Ended'));
    video.addEventListener('error', () => setStatus('Playback error'));

    // Vega requires an explicit initialize() before you set src or call play().
    video
      .initialize()
      .then(() => {
        video.src = VIDEO_URL;
        return video.play();
      })
      .catch((error: unknown) => {
        setStatus(`Failed to start: ${String(error)}`);
      });

    return () => {
      // Always release the native player when the screen unmounts.
      video.pause();
      video.finalize?.();
      player.current = null;
    };
  }, []);

  return (
    <View style={styles.container}>
      {player.current ? (
        <KeplerVideoView
          style={styles.video}
          videoPlayer={player.current as VideoPlayer}
        />
      ) : null}
      <Text style={styles.status}>{status}</Text>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {flex: 1, backgroundColor: 'black'},
  video: {flex: 1},
  status: {color: 'white', padding: 16, fontSize: 20},
});

Render the screen from your app entry point

Point your app root at the new screen.

import React from 'react';
import {HelloWorldPlayer} from './src/HelloWorldPlayer';

export const App = () => <HelloWorldPlayer />;

Replace the video URL

Set VIDEO_URL to a media file your device can reach. URL mode supports MP4, MP3, MKV, FLV, OGG, and FLAC. If you point it at an HLS (.m3u8) or DASH (.mpd) manifest, playback fails — those require MSE mode and a JavaScript player. See Selecting Playback Mode.

Build, install, and run

Build your app and deploy it to your device or emulator. For the full command set, see Build Your App.The video plays full screen, and the status text under it updates as the player moves from Loaded to Playing.

Add play and pause

The VideoPlayer object exposes the standard HTMLMediaElement surface, so simple controls are a few lines. Wire this to a focusable button or a D-pad key handler:

const togglePlayback = () => {
  const video = player.current;
  if (!video) {
    return;
  }
  if (video.paused) {
    video.play();
  } else {
    video.pause();
  }
};

You can also read currentTime, duration, and volume, and listen for timeupdate to drive a progress bar.

Troubleshooting

Symptom	Likely cause
`ReferenceError: Property 'React' doesn't exist`	babel.config.js isn’t updated. See Media Player Setup.
Audio plays, but the screen is black	`KeplerVideoView` isn’t in the render tree, or its parent has no height. Give the container `flex: 1`.
`initialize()` rejects	Missing `wants` entries in manifest.toml.
Nothing plays and you get an `error` event	The URL is an HLS or DASH manifest, or the codec isn’t supported. Check Media Player Requirements.

Next steps

Selecting Playback Mode — choose between URL mode and MSE mode
Shaka Player Integration — add adaptive streaming
W3C Media integration with Vega Media Controls — connect to system playback controls

​Prerequisites

​Build the app

​Add play and pause

​Troubleshooting

​Next steps

​Related topics

Prerequisites

Build the app

Add play and pause

Troubleshooting

Next steps

Related topics