Skip to content

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

36 Commits

Folders and files

Repository files navigation

@cldmv/node-android-tv-remote

@cldmv/node-android-tv-remote is a modern, event-driven Node.js module for controlling Android TV devices via ADB. It supports sending keycodes, comprehensive keyboard input (71 characters with smart shift detection), remote control commands, screenshots and device management. It is designed for compatibility with a wide range of Android TV devices, including Fire TV, Chromecast with Google TV, Nvidia Shield and more.

Every remote is an event source: operations report through structured log events and failures through structured error events instead of writing to the console, so the library slots into an application's own logging and error handling.

Drive any Android TV from Node.js β€” keys, text, screenshots and power β€” over ADB.

npm version npm downloads GitHub downloads Last commit npm last update coverage

Contributors Sponsor shinrai


✨ What's New

Latest: v2.2.1 (November 2026)

  • engines.node is now >=22.12.0 (#89) β€” v2.2.0 declared >=22.22.0, the floor of the development toolchain rather than of the package. The runtime floor is now the one @devicefarmer/adbkit 4 and commander 15 declare; require() needs Node.js 22.13.0 or later. The 22.22.0 toolchain floor moves to devEngines, so it only applies when working on this repository. The exported API and behavior are unchanged.
  • View full v2.2.1 Changelog

Recent Releases

  • v2.2.0 (November 2026) β€” library layout with a tsup build into dist/, @devicefarmer/adbkit 4, waitBootComplete(timeout) rejects at its timeout, and screencap() reports the file saved only once written; declared Node.js >=22.22.0 (Changelog)
  • v2.1.9 (October 2026) β€” brace-expansion security fix in the dev toolchain and dev-tooling bumps; no runtime change (Changelog)
  • v2.1.8 (October 2026) β€” independent event emitters per remote, an unheard error no longer crashes the process, npm run setup-device works again, relicensed under Apache-2.0 (Changelog)
  • v2.1.7 (October 2026) β€” CommonJS entry loads the ESM build directly, fails clearly without require(esm), and exports createAndroidTVRemote (Changelog)

Note: v2.1.1 through v2.1.6 were released on GitHub but never published to npm; npm went from v2.1.0 straight to v2.1.7. See the changelogs for what changed in between, including the Node.js 20.9.0 floor from v2.1.1.

πŸ“š For complete version history and detailed release notes, see the docs/changelog/ folder.


πŸš€ Key Features

  • 🎯 Event-driven architecture - Comprehensive event system with structured data
  • ⌨️ Comprehensive keyboard input - 71 characters with smart shift detection and special symbols
  • πŸ”„ ESM & CommonJS support - Works with both import and require
  • πŸ›‘οΈ Error resilience - Errors are reported as events instead of crashing your app; an error listener is optional (see Event-Driven Usage)
  • πŸ”— Method chaining - Fluent API for event listener management
  • πŸ“Š Structured logging - Timestamped, categorized log events with source tracking
  • πŸš€ Promise-based - Modern async/await support with callback compatibility
  • πŸ“Έ Advanced screencap - High-performance PNG screenshots with resizing and thumbnails
  • ⚑ Performance optimized - Direct PNG streaming with 20x speed improvements
  • πŸ”„ Device management - Reboot, wake, settings configuration with event tracking
  • πŸ“± Universal compatibility - Works with Fire TV, Chromecast, Shield, and more

πŸ“¦ Installation

Requirements

  • Node.js >=22.12.0 (the package's engines floor; adbkit 4 and its commander 15 dependency need it). require() loads the ESM build through Node's require(esm), so require() needs Node.js >=22.13.0, where require(esm) runs without warnings.
  • Developing this package needs Node.js 22.22.0 or later (devEngines).
  • The Android Debug Bridge (ADB) binary installed and available in your system PATH (see below). A postinstall check prints install instructions when adb is missing.
  • sharp installs a platform-specific prebuilt binary; the install environment must be able to fetch it.

Install

npm install @cldmv/node-android-tv-remote

Install ADB

Windows

  1. Download the SDK Platform Tools for Windows.
  2. Extract the ZIP file.
  3. Add the extracted folder to your system PATH (so you can run adb from any terminal).
  4. Test by running adb version in Command Prompt.

macOS

  1. Download the SDK Platform Tools for Mac.
  2. Extract the ZIP file.
  3. Move the extracted folder to a location like /usr/local/bin or add it to your PATH.
  4. Test by running adb version in Terminal.

Linux

  1. Download the SDK Platform Tools for Linux.
  2. Extract the ZIP file.
  3. Move the extracted folder to /usr/local/bin or add it to your PATH.
  4. You may also install via your package manager:
    • Ubuntu/Debian: sudo apt-get install android-tools-adb
    • Fedora/Red Hat: sudo dnf install android-tools
    • CentOS/yum: sudo yum install android-tools
  5. Test by running adb version in your shell.

Note: You must accept the ADB authorization prompt on your Android TV device the first time you connect.


πŸš€ Quick Start

// ESM (Node.js with type: "module" in package.json)
import createRemote from "@cldmv/node-android-tv-remote";

// CommonJS
const createRemote = require("@cldmv/node-android-tv-remote");

// Create remote (async function)
const remote = await createRemote({ ip: "192.168.1.100" });

// Use with async/await (recommended)
await remote.press.home();
await remote.press.up();
await remote.press.ok();

// Or chain promises
createRemote({ ip: "192.168.1.100" }).then(async (remote) => {
	await remote.press.home();
	await remote.press.up();
	await remote.press.ok();
});

createAndroidTVRemote(config) is an alias of createRemote(config), exported by name from both entries:

import { createAndroidTVRemote } from "@cldmv/node-android-tv-remote";
// or: const { createAndroidTVRemote } = require("@cldmv/node-android-tv-remote");

const remote = await createAndroidTVRemote({ ip: "192.168.1.100" });

🎯 Usage

Event-Driven Usage (Recommended)

This module uses an event-driven architecture instead of console logging. All operations emit structured events that you can listen to. The remote is a Node.js event emitter, but an error event is only emitted when a listener is attached, so an error listener is optional. Without one, the error is emitted as a log event with level: 'error' and written to NODE_DEBUG=android-tv-remote. Register an error listener to handle failures yourself:

import createRemote from "@cldmv/node-android-tv-remote";

const remote = await createRemote({ ip: "192.168.1.100" });

// Listen for log events (info, warn, error, debug)
remote.on("log", (data) => {
	console.log(`[${data.level}] ${data.source}: ${data.message}`);
});

// Listen for error events
remote.on("error", (data) => {
	console.error(`ERROR from ${data.source}:`, data.error.message);

	// Handle specific error types
	if (data.error.message.includes("device unauthorized")) {
		console.log("Please authorize ADB on your Android TV device");
	}
});

// Listen for screenshot events
remote.on("screencap-complete", (data) => {
	console.log(`Screenshot completed in ${data.timing.total}ms`);
});

// Use the remote
await remote.press.home();
await remote.screencap({ filepath: "./screenshot.png" });

Async Initialization

The createRemote function is async and returns a Promise:

import createRemote from "@cldmv/node-android-tv-remote";

// Async initialization with await
const remote = await createRemote({ ip: "192.168.1.100" });
remote.on("log", console.log);
await remote.press.play();

// Or use .then()
createRemote({ ip: "192.168.1.100" }).then((remote) => {
	remote.on("log", console.log);
	return remote.press.play();
});

Screenshot Functionality

Advanced screencap with resizing, thumbnails, and file saving:

import createRemote from "@cldmv/node-android-tv-remote";

const remote = await createRemote({ ip: "192.168.1.100" });

// Basic screenshot (returns PNG stream)
const stream = await remote.screencap();

// Screenshot with resizing
const resizedStream = await remote.screencap({ width: 1280, height: 720 });

// Save screenshot to file (non-blocking)
await remote.screencap({ filepath: "./screenshot.png" });

// Resized screenshot saved to file
await remote.screencap({
	width: 640,
	height: 360,
	filepath: "./thumbnail.png"
});

// Quick thumbnail (default 240px width)
const thumbStream = await remote.thumbnail();

// Custom thumbnail dimensions
const customThumb = await remote.thumbnail({
	width: 320,
	height: 180,
	filepath: "./thumb.png"
});

// Access last screenshot data
console.log("Last screenshot available:", !!remote.lastScreencapData);

// Listen for screenshot events
remote.on("screencap-complete", (data) => {
	console.log(`Screenshot completed in ${data.timing.total}ms`);
});

Device Management

Comprehensive device control with event tracking:

import createRemote from "@cldmv/node-android-tv-remote";

const remote = await createRemote({ ip: "192.168.1.100" });

// Reboot the device
await remote.reboot();

// Ensure device is awake and responsive
const isAwake = await remote.ensureAwake();

// Configure optimal settings for remote control
await remote.setSettings(); // Set optimal settings
await remote.setSettings("get"); // Get current settings

// Wait for device to finish booting (after reboot)
await remote.waitBootComplete(60000); // 60 second timeout

// Connection management
await remote.connect();
console.log("Connected:", remote.isConnected);
await remote.disconnect();

// Listen for device management events
remote.on("log", (data) => {
	if (data.source === "reboot") {
		console.log(`Reboot: ${data.message}`);
	}
	if (data.source === "ensureAwake") {
		console.log(`Wake: ${data.message}`);
	}
});

Keyboard Input

Comprehensive text input with individual key support and smart shift detection:

import createRemote from "@cldmv/node-android-tv-remote";

const remote = await createRemote({ ip: "192.168.1.100" });

// Text input (recommended for typing sentences)
await remote.keyboard.text("Hello World!");
await remote.keyboard.text("user@example.com");

// Individual character input
await remote.keyboard.key.h(); // Types "h"
await remote.keyboard.key.e(); // Types "e"
await remote.keyboard.key.l(); // Types "l"
await remote.keyboard.key.l(); // Types "l"
await remote.keyboard.key.o(); // Types "o"

// Shifted characters (only available for keys that change when shifted)
await remote.keyboard.key.shift.h(); // Types "H"
await remote.keyboard.key.shift.one(); // Types "!"
await remote.keyboard.key.shift.semicolon(); // Types ":"

// Special characters and symbols
await remote.keyboard.key.space(); // Types " "
await remote.keyboard.key.exclamation(); // Types "!"
await remote.keyboard.key.at(); // Types "@"
await remote.keyboard.key.hash(); // Types "#"
await remote.keyboard.key.dollar(); // Types "$"

// Control keys
await remote.keyboard.key.tab(); // Tab character
await remote.keyboard.key.enter(); // Enter/Return
await remote.keyboard.key.backspace(); // Backspace

// Using keycode fallback (when available for regular keys)
await remote.keyboard.key.a.keycode(); // Sends keycode instead of character

// Note: Shift variants are only available for keys that actually change
// when shifted (letters, numbers, and some symbols). Special characters
// like @, #, !, etc. don't have shift variants since they're already
// the shifted form. Shift keys only support text input, not keycodes,
// since Android ADB doesn't support sending multiple keycodes simultaneously.

Event Data Structure

Log Events:

{
  level: 'info' | 'warn' | 'error' | 'debug',
  message: 'Human readable message',
  source: 'connect' | 'disconnect' | 'screencap' | 'reboot' | 'ensureAwake' | etc,
  timestamp: '2025-10-15T18:37:44.854Z',
  data?: any // Optional additional data
}

Error Events:

{
  error: Error, // The actual error object
  source: 'connect' | 'adb' | 'screencap' | 'reboot' | etc,
  message: 'Human readable error message',
  timestamp: '2025-10-15T18:37:44.854Z'
}

Screenshot Events:

// screencap-complete event
{
  timestamp: '2025-10-15T18:37:44.854Z',
  filepath?: './screenshot.png', // If saved to file
  processed: true, // Whether Sharp processing was used
  width?: 1280,
  height?: 720,
  timing: {
    capture: 25.4, // ADB capture time in ms
    sharpProcess?: 1.2, // Sharp processing time in ms
    total: 26.6 // Total operation time in ms
  }
}

πŸ”§ API

Main Methods

  • connect() / disconnect() - Device connection management
  • press.<key>() / press.long.<key>() - Remote control buttons
  • keyboard.text(text) - Text input
  • keyboard.key.<key>() / keyboard.key.<key>.keycode() - Individual keys (71 available)
  • keyboard.key.shift.<key>() - Shifted keys (47 available, text input only)
  • inputKeycode(code) - Raw Android keycodes
  • reboot() - Reboot the Android TV device
  • ensureAwake() - Ensure device is awake and responsive
  • setSettings(mode) - Configure optimal Android TV settings
  • waitBootComplete(timeout) - Wait for device boot completion
  • screencap(options) - Take PNG screenshots with optional resizing and file saving
  • thumbnail(options) - Take thumbnail screenshots (default 240px width)

Event Methods

  • on(event, listener) - Add event listener (returns remote for chaining)
  • off(event, listener) - Remove event listener (returns remote for chaining)
  • once(event, listener) - Add one-time event listener (returns remote for chaining)
  • emit(event, ...args) - Emit custom events

Events

  • log - Emitted for all operations (info, warn, error, debug levels)
  • error - Emitted when errors occur (structured error data). Each remote has its own listeners. With no error listener attached, the error is emitted as a log event with level: 'error' (the Error is in data.error) instead of throwing. The failing call still reports it: commands reject, and connect() / disconnect() resolve with the Error as before
  • screencap-start - Emitted when screenshot capture begins
  • screencap-captured - Emitted when raw screenshot is captured
  • screencap-processing - Emitted when image processing begins
  • screencap-ready - Emitted when processed stream is ready
  • screencap-saved - Emitted when screenshot is saved to file
  • screencap-complete - Emitted when entire screenshot operation completes

Properties

  • isConnected - Boolean indicating connection status
  • initPromise - Promise that resolves when initialization completes
  • lastScreencapData - Buffer/Stream containing the last captured screenshot data

See JSDoc comments in source code for full API documentation.


πŸ“Ί Supported Devices

Device Supported Native Remote Buttons
Fire TV Stick Yes Home, Back, Menu, D-Pad, Play/Pause, Volume
Chromecast w/ Google TV Yes Home, Back, Assistant, D-Pad, Volume, Input
Nvidia Shield Yes Home, Back, D-Pad, Play/Pause, Volume
Roku (Android TV) Partial Home, Back, D-Pad, Play/Pause
Xiaomi Mi Box Yes Home, Back, D-Pad, Volume
Sony Bravia (Android TV) Yes Home, Back, D-Pad, Volume, Input

See Keyboard Keys and Keycodes for full lists.


πŸ“š Documentation

  • Keyboard Keys β€” every keyboard.key character and its shifted variant
  • Keycodes β€” the Android keycodes behind press.<key>() and inputKeycode()
  • Changelog β€” release notes for every version

CodeFactor OpenSSF Scorecard npms.io score npm unpacked size Repo size


🀝 Contributing

Contributions are welcome β€” open an issue or a pull request on GitHub.

npm test          # Vitest against src/, then build and run the CommonJS entry tests against dist/
npm run build     # tsup: src/index.mjs β†’ dist/index.mjs, src/index.cjs copied to dist/index.cjs
npm run lint      # ESLint
npm run format    # Prettier

The published package ships only the built dist/. In a checkout, the package name resolves to dist/ by default (run npm run build first) and to src/ with the node-android-tv-remote-dev export condition:

node --conditions=node-android-tv-remote-dev app.mjs
# or once per shell
export NODE_OPTIONS=--conditions=node-android-tv-remote-dev

The test suite sets the condition itself, so npm test always runs against src/.

Contributors Sponsor shinrai


πŸ”— Links


πŸ“„ License

npm license

Apache-2.0 Β© Shinrai / CLDMV. See LICENSE for the full text.

About

No description, website, or topics provided.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages