@buoy-gg/tv-remote
Record remote events received by a React Native TV app and inspect them in Buoy Desktop. Desktop can send supported host-side input and replay recorded sequences. The device package observes events; it does not inject hardware presses itself.
Install
npm install @buoy-gg/core @buoy-gg/external-sync @buoy-gg/tv-remote
Account setup
Start in a development build. You need a Free or Pro Buoy account. Sign in from your app's folder:
npx --package=@buoy-gg/core buoy login
Your browser opens buoy.gg. Click Allow. The CLI then writes a dev token. It works in dev builds for 30 days.
On Expo, the token goes in .env.development.local. Buoy reads it by itself in dev builds. You can also pass it in yourself:
import { Buoy } from "@buoy-gg/core";
Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });
On React Native CLI, the token goes in .env.local as BUOY_KEY. React Native does not load that file by itself. Pass the token in with your app's own env setup. Keep the menu inside the providers used by your app. Restart the development server after installing packages. See the Quick Start for the complete root component.
Connect a TV app
Use a compatible react-native-tvos app and follow the TV installation guide. Mount the core integration after account initialization:
import { FloatingDevTools } from "@buoy-gg/core";
<FloatingDevTools headless />;
Keep the TV app headless so a focusable developer overlay does not interfere with its navigation. Open Desktop, sign in, select the device, and open the tool's panel. A phone build is not a substitute for testing TV behavior.
Capture and replay
Arm recording in Desktop, press a short sequence on the physical or simulated remote, and compare the received events with the app's behavior. Disarm when done. Menu capture on tvOS is opt-in and is released on disarm.
| Target | Host input support |
|---|---|
| Android TV emulator or authorized device | adb input key events; the host must be able to reach the target. |
| Apple TV simulator | idb arrows, select, and menu; play/pause is unsupported in this path. |
| Physical Apple TV | Record received events; host replay is unsupported. |
The Apple TV simulator lane requires idb separately from Xcode. Follow Desktop diagnostics and the TV guide for host setup. Capture depends on supported TV event APIs and account access; it does not guarantee every OS-level remote event reaches JavaScript.
For custom integrations, exports include arm, disarm, clear, setMenuCapture, getEventsSince, getState, subscribe, and tvRemoteSyncAdapter. Check getState().supported before treating a platform as available.
Desktop and MCP
React Native connections require @buoy-gg/external-sync. Follow the Desktop connection guide, sign in to Desktop separately, and confirm the selected device. MCP uses the sign-in from buoy login on your computer. Free has the basic MCP. Reading this tool from the MCP needs Pro.
Device data can travel over your LAN to the configured broker. Account validation makes network requests. See Telemetry for data-flow details.
Web support (unreleased)
Browser capture observes keyboard events without consuming them. It does not reproduce a TV’s native focus behavior. The browser build is available in this checkout and has not been published yet. See the web setup guide for registration, dependencies, and browser boundaries.