Hi,
We implemented the suggestion from How to render WebView UI controls on top of KeplerVideoSurfaceView on Vega OS? - #7 by amen and built a minimal reproduction, but the overlay still disappears the moment the native video surface becomes active. Details below.
SDK Version: v0.24 (0.24.12112) React Native Version: RN0.83 (@amazon-devices/react-native-kepler 4.0.1)
Environment where this reproduces
Device: Fire TV Stick (AFTCA002)
OS: Vega OS 2.0 (TV Ship, build 515)
Display: 3840 x 2160 (4K)
Vega SDK: 0.24.12112
RN for Vega: 0.83 / @amazon-devices/react-native-kepler 4.0.1
@amazon-devices/react-native-w3cmedia 2.3.2
@amazon-devices/webview 4.0.2
Build type: Release
Our sample matches your code snippets:
Metro assetExts — added ‘html’ with the exact .includes(‘html’) ? … : […] guard.
Asset load — Image.resolveAssetSource(require(‘./assets/player-overlay.html’)).uri.
Layout — KeplerVideoView + a transparent WebView container as siblings inside one parent View; WebView wired with onMessage, onLoadStart → setIsWebViewReady(false), onLoad → setIsWebViewReady(true).
Styles — container {flex:1}, overlayWebView {flex:1, transparent}, modalContainer {transparent, position:‘absolute’, top:0, left:0}.
TV input — useTVEventHandler from @amazon-devices/react-native-kepler forwarding keys via injectJavaScript.
Bidirectional comms — overlay → RN via window.ReactNativeWebView.postMessage(…) handled by onMessage; RN → overlay via webRef.current.injectJavaScript(…).
Readiness gating — all injectJavaScript calls gated behind an isWebViewReady flag (true in onLoad, false in onLoadStart).
HTML overlay — background: transparent on both html and body; only the control elements have visible styling.
Components — @amazon-devices/webview for the WebView, @amazon-devices/react-native-kepler for useTVEventHandler, KeplerVideoView (from @amazon-devices/react-native-w3cmedia) for the video, with a UI-thread VideoPlayer.
Result
Before playback: the overlay renders correctly and is fully interactive (play/pause, scrub, remote input all work).
The instant the native video surface activates (KeplerVideoView: onSurfaceViewCreated / W3CMEDIA: setVideoSurface), the overlay disappears. Only the video is visible afterward.
In the device log this lines up exactly with setVideoSurface:
[OverlaySpike] overlay → RN message: {“type”:“OVERLAY_READY”} # overlay visible & interactive
VwContents::SetSize width: 1920 height 1080 # WebView laid out
KeplerVideoView: onSurfaceViewCreated 1
VideoPlayer: setSurfaceHandle: 1
W3CMEDIA: setVideoSurface: surface = SurfaceRef:0x… # ← overlay disappears here
During the transition the WebView shows as Window role: Overlay and the app/video as Window role: Full screen, which appears to composite above the overlay. We also tried a headless KeplerVideoSurfaceView and an explicit zIndex on the overlay — same result in both cases, so this does not look like a JS-side styling or z-order issue.
the full source is inline below.
OverlaySpike.tsx
// @ts-nocheck
import React, {useRef, useState, useCallback} from 'react';
import {View, StyleSheet, Image} from 'react-native';
import {useTVEventHandler} from '@amazon-devices/react-native-kepler';
import {VideoPlayer, KeplerVideoView} from '@amazon-devices/react-native-w3cmedia';
import {WebView} from '@amazon-devices/webview';
// Public clear MP4 (URL mode — no MSE/DRM needed to show the compositing issue).
const VIDEO_URL = 'https://media.w3.org/2010/05/sintel/trailer.mp4';
// Per recipe: load the overlay HTML as a bundled asset.
const overlaySource = {
uri: Image.resolveAssetSource(require('./assets/player-overlay.html')).uri,
};
export const OverlaySpike = () => {
const video = useRef<VideoPlayer | null>(null);
const webRef = useRef(null);
const [videoReady, setVideoReady] = useState(false);
const [isWebViewReady, setIsWebViewReady] = useState(false);
if (video.current === null) {
if (global.navigator === undefined) { global.navigator = {}; }
if (global.window === undefined) { global.window = global; }
video.current = new VideoPlayer();
}
const started = useRef(false);
if (!started.current) {
started.current = true;
(async () => {
try {
const vp = video.current;
await vp.initialize();
setVideoReady(true);
// Short delay so the overlay is visibly on screen BEFORE video starts.
await new Promise(r => setTimeout(r, 5000));
vp.src = VIDEO_URL;
vp.autoplay = true;
vp.load();
vp.play();
} catch (e) {
console.error('\[OverlaySpike\] init failed', e);
}
})();
}
const handleTransportMessage = useCallback((event: any) => {
try {
const data = JSON.parse(event.nativeEvent.data);
console.log('\[OverlaySpike\] overlay -> RN message:', JSON.stringify(data));
} catch (\_) {}
}, [ ]);
const tvEventHandler = useCallback((evt: any) => {
if (!evt || !isWebViewReady || !webRef.current) { return; }
const js = `(function(){ if (window.onTvKey) window.onTvKey(${JSON.stringify(evt.eventType)}); })();true;`;
try { webRef.current.injectJavaScript(js); } catch (\_) {}
}, \[isWebViewReady\]);
useTVEventHandler(tvEventHandler);
return (
{/\* Native video base (rendered first). */}
{videoReady ? (
) : null}
{/* Transparent overlay (sibling on top). \*/}
<WebView
ref={webRef}
source={overlaySource}
style={styles.overlayWebView}
javaScriptEnabled={true}
domStorageEnabled={true}
allowSystemKeyEvents={true}
allowFileAccess={true}
onMessage={handleTransportMessage}
onLoadStart={() => setIsWebViewReady(false)}
onLoad={() => setIsWebViewReady(true)}
/>
);
};
const styles = StyleSheet.create({
container: {flex: 1},
// absoluteFill covers the full 4K panel (literal 1920x1080 would cover only
// the top-left quadrant on this device). Does not affect the disappearance.
backgroundVideo: {...StyleSheet.absoluteFillObject},
overlayWebView: {flex: 1, backgroundColor: 'rgba(0,0,0,0)'},
modalContainer: {...StyleSheet.absoluteFillObject, backgroundColor: 'rgba(0,0,0,0)'},
});
player-overlay.html
<!doctype html>
<html>
<head>
<meta name="viewport" content="width=device-width,initial-scale=1" />
<style>
/* Per recipe: transparent on both html and body; only controls are visible. */
html, body {
margin: 0; height: 100vh; width: 100vw;
background: transparent !important;
overflow: hidden; font-family: sans-serif; color: #fff;
}
.top { position: absolute; top: 0; left: 0; right: 0; padding: 48px 64px;
background: linear-gradient(to bottom, rgba(0,0,0,0.75), rgba(0,0,0,0)); }
.title { font-size: 52px; font-weight: 700; }
.controls { position: absolute; left: 0; right: 0; bottom: 0; padding: 48px 64px 64px;
background: linear-gradient(to top, rgba(0,0,0,0.85), rgba(0,0,0,0)); }
.track { position: relative; height: 10px; border-radius: 6px; background: rgba(255,255,255,0.3); }
.fill { position: absolute; top: 0; left: 0; height: 10px; border-radius: 6px; width: 35%; background: #00a0ff; }
.btns { display: flex; justify-content: center; align-items: center; gap: 72px; margin-top: 36px; }
.play { width: 104px; height: 104px; border-radius: 50%; background: rgba(255,255,255,0.18);
border: 3px solid #fff; display: flex; align-items: center; justify-content: center; font-size: 52px; }
</style>
</head>
<body>
<div class="top"><div class="title">Overlay controls</div></div>
<div class="controls">
<div class="track"><div class="fill" id="fill"></div></div>
<div class="btns"><div class="play" id="play">❙❙</div></div>
</div>
<script>
var playing = true;
window.onTvKey = function (key) {
if (key === 'select' || key === 'playpause') {
playing = !playing;
document.getElementById('play').innerHTML = playing ? '❙❙' : '▶';
}
postToNative({ type: 'TRANSPORT', key: key });
};
function postToNative(msg) {
try {
if (window.ReactNativeWebView && window.ReactNativeWebView.postMessage) {
window.ReactNativeWebView.postMessage(JSON.stringify(msg));
}
} catch (e) {}
}
postToNative({ type: 'OVERLAY_READY' });
</script>
</body>
</html>
metro.config.js
const {getDefaultConfig, mergeConfig} = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(\__dirname);
const config = {
resolver: {
assetExts: defaultConfig.resolver.assetExts.includes('html')
? defaultConfig.resolver.assetExts
: \[...defaultConfig.resolver.assetExts, 'html'\],
},
};
module.exports = mergeConfig(defaultConfig, config);
App.tsx
import React from 'react';
import {OverlaySpike} from './OverlaySpike';
export const App = () => {
return ;
};
Questions
- What in your validated setup keeps the transparent WebView above the active video surface? Is there a required prop/call we’re missing? (KeplerVideoView exposes only showControls, showCaptions, videoPlayer, scalingmode.)
- Is this OS-build- or resolution-dependent? Which OS build and resolution was the recipe validated on? (We’re on OS 2.0 build 515 at 4K.)
Thanks,
Hari