Title: Black screen issue with video playback on Amazon Vega React Native app

Vega Open Beta Q&A
1

Title: Black screen issue with video playback on Amazon Vega React Native app

Hi everyone,

We are developing a digital signage player app for Amazon Vega using React Native.

We are having a persistent black screen issue during media playback. We tested multiple approaches, but none of them worked reliably so far:

  • React Native video playback

  • Shaka Player

  • WebView with HTML5 video player

  • Native video surface approach

Our media URLs are valid and accessible directly in the browser. The JSON content is also loaded dynamically from our backend, and the player receives the correct media path and type.

Example media URL:

Example JSON structure:

{
  "playlists": [
    {
      "media": [
        {
          "path": "uploads/6a3d24e074cea.mp4",
          "type": "video",
          "duration": 20,
          "zone": 1
        }
      ]
    }
  ]
}

The app screen opens correctly, but when media playback starts, the video area stays black. We also experienced the same issue with image/video switching in the player.

Could you please advise what the recommended and officially supported approach is for video playback on Amazon Vega with React Native?

Specifically:

  1. Should we use @amazon-devices/react-native-w3cmedia and KeplerVideoSurfaceView?

  2. Is there a working sample for full-screen video playback in React Native on Vega?

  3. Are there codec, container, resolution, or server header requirements for MP4 playback?

  4. Are WebView-based HTML5 video players supported or discouraged on Vega?

  5. What is the correct lifecycle flow for initializing VideoPlayer, attaching the surface, setting the source URL, and calling play()?

Any guidance or sample code would be greatly appreciated.

Thank you.
Before you continue

4

Hi @murat_tansu,

Welcome to the Amazon Developer Community!

For playing MP4 files from a URL in a React Native app, the recommended approach is URL Mode using @amazon-devices/react-native-w3cmedia with VideoPlayer and KeplerVideoSurfaceView.

To answer your specific questions:

  1. Yes - use @amazon-devices/react-native-w3cmedia with VideoPlayer and KeplerVideoSurfaceView.

  2. See the Selecting the Playback Mode ( Selecting the Playback Mode | Design and Develop Vega Apps ) documentation - it includes a full working example for URL Mode playback.

  3. URL Mode supports flat files: .mp4, .mkv, .mp3, .flv, .ogg, .flac. For MP4, use H.264 video + AAC audio. No special server headers are required - the URL just needs to be directly accessible.

  4. WebView-based HTML5 video is supported on Vega (see Vega Web Apps ( Overview of Vega Web Apps | Design and Develop Vega Apps )), but for a React Native app, using react-native-w3cmedia directly is recommended for better performance and platform integration.

  5. The correct lifecycle flow is:

    1. Create new VideoPlayer()
    2. Call await videoPlayer.initialize()
    3. Receive surface handle from onSurfaceViewCreated callback
    4. Call videoPlayer.setSurfaceHandle(handle)
    5. Set videoPlayer.src = ‘your-url.mp4’
    6. Call videoPlayer.play() (or set autoplay = true before setting src)

Important: Ensure initialize() has resolved before calling setSurfaceHandle, and make sure your
manifest.toml includes the required media services.

Resources:

If you’re still seeing a black screen after following the above, please share your SDK version and any
device error logs so we can investigate further.

Warm regards,
Aishwarya

5

Hi Aishwarya,

Thank you very much for your detailed response and for providing the documentation links.

We really appreciate your guidance. We will carefully review the recommended implementation steps and verify our application against the documentation you shared.

If we continue to experience the black screen issue after completing these checks, we will collect the SDK version, device information, and application logs, and share them with you for further investigation.

Thank you again for your support and assistance.

Best regards,

Murat Tansu ÖZYOL
SignOS Digital Signage