@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 with a Free or Pro Buoy account key. From the app directory:

npx --package=@buoy-gg/core buoy login

For Expo, initialize Buoy with the key written to .env.local:

import { Buoy } from "@buoy-gg/core";

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

For React Native CLI, pass the key through your app's environment configuration; .env.local is not loaded automatically. 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.

Full TV Remote guide

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 also needs a process account and Pro access.

Device data can travel over your LAN to the configured broker. Account validation makes network requests. See Telemetry for data-flow details.