👋 Introduction

@kud/androidtv-remote is a modern TypeScript/ESM implementation of the Android TV Remote v2 protocol. Pair with a device over TLS, then send keys, launch apps, and inject text straight from Node — with a typed event API and lean dependencies.

🔐 The pairing-then-reconnect model

The protocol is certificate-based, and that shapes the whole API:

• First run — start() runs the TLS pairing flow; the TV shows a PIN, you submit it with sendCode(), and on ready you call getCertificate() to keep the credentials.
• Every run after — construct with the saved cert and you reconnect silently, no PIN. Subscribe to typed events (powered, volume, current_app, unpaired) to track device state.

Internal logging stays silent unless you pass debug: true, so it sits cleanly inside a larger app.

📦 Install

npm install @kud/androidtv-remote

🚀 Quick start

Pair a new device, then persist the certificate for next time:

import { createAndroidRemote } from "@kud/androidtv-remote";

const remote = createAndroidRemote("192.168.1.42");

remote.on("secret", () => remote.sendCode("123456")); // PIN shown on the TV
remote.on("ready", () => remote.sendPower());

await remote.start();

const cert = remote.getCertificate(); // save key + cert to reconnect without pairing

Reconnect later by passing the saved certificate:

const remote = createAndroidRemote("192.168.1.42", {
  cert: { key: savedKey, cert: savedCert },
});