samsung-tv-remote

📺 NodeJS module to remotely control Samsung SmartTV starting from 2016.

---

Features

✅ Support Samsung SmartTV from 2016+
✅ Detect any Samsung TVs awake on the network
✅ Wake a TV from sleep mode - thanks to Wake-on-LAN (WoL)
✅ Send one or multiple keys at once to a TV
✅ 241 known keys already predefined
✅ Works as a library and as a CLI tool
✅ Dual build support (CJS/ESM)

Command line tool

The CLI utility provides an interactive way to control your TV remotely.

npx samsung-tv-remote

As a package

Installation

npm install samsung-tv-remote --save

yarn add samsung-tv-remote

Example

/** CommonJS */
// const { getAwakeSamsungDevices, Keys, SamsungTvRemote, getLastConnectedDevice } = require('samsung-tv-remote');

/** ESM / Typescript */
import { getAwakeSamsungDevices, getLastConnectedDevice, Keys, SamsungTvRemote } from 'samsung-tv-remote';

(async () => {
    let device = getLastConnectedDevice();
    if (!device) {
        const devices = await getAwakeSamsungDevices();
        if (devices.length) {
            device = devices[0];
        }
    }
    if (device) {
        try {
            const remote = new SamsungTvRemote({ device });
            await remote.wakeTV();
            await remote.sendKey(Keys.KEY_DOWN);
            await remote.sendKeys([Keys.KEY_POWER])
            remote.disconnect();
        } catch (error) {
            console.error(error);
        }
    }
})();

Options

export interface SamsungTvRemoteOptions {
    /**
     * IP address of the TV to connect to.
     */
    ip: string;

    /**
     * MAC address of the TV to connect to.
     *
     * Required only when using the 'wakeTV()' api.
     *
     * @default 00:00:00:00:00:00
     */
    mac?: string;

    /**
     * A Samsung device to connect to.
     *
     * To be used in replacement of `ip` and `mac` options.
     */
    device?: SamsungDevice;

    /**
     * Name under which the TV will recognize your program.
     *
     * - It will be displayed on TV, the first time you run your program, as a 'device' trying to connect.
     * - It will also be used by this library to persist a token on the operating system running your program,
     *   so that no further consent are asked by the TV after the first run.
     *
     * @default SamsungTvRemote
     */
    name?: string;

    /**
     * Port address used for remote control emulation protocol.
     *
     * Different ports are used in different TV models.
     * @example 55000 (legacy), 8001 (2016+) or 8002 (2018+).
     *
     * @default 8002
     */
    port?: number;

    /**
     * Delay in milliseconds before the connection to the TV times out.
     *
     * @default 5000
     */
    timeout?: number;

    /**
     * Delay in milliseconds between sending key commands.
     *
     * Some TV models or applications may drop key events if they are sent too quickly.
     * Introducing a delay helps ensure reliable key interactions.
     *
     * @default 60
     */
    keysDelay?: number;
}

Apis

class SamsungTvRemote {
    /**
     * Turns the TV on or awaken it from sleep mode (also called WoL - Wake-on-LAN).
     *
     * The mac address option is required in this case.
     */
    wakeTV(): Promise<void>;

    /**
     * Sends a key to the TV.
     */
    sendKey(key: keyof typeof Keys): Promise<void>;

    /**
     * Sends multiple keys to the TV.
     */
    sendKeys(key: (keyof typeof Keys)[]): Promise<void>;

    /**
     * Closes the connection to the TV.
     *
     * It doesn't shut down the TV - it only closes the connection to it.
     */
    disconnect(): void;
}

Helpers

/**
 * Searches for last connected device, if any.
 */
getLastConnectedDevice(): SamsungDevice | undefined;

/**
 * Retrieves a list of Samsung devices that are currently awake and reachable on the network.
 */
getAwakeSamsungDevices(timeout = 500): Promise<SamsungDevice[]>;

Debug

You can enable verbose mode to help debug your program.

Set the LOG_LEVEL environment variable to one of the supported values: none, debug, info, warn, error.

Example

# Run your program in debug mode
LOG_LEVEL=debug npm run yourprogram

FAQ

I'm getting a TypeError: bufferUtil.mask is not a function

Under the hood, this library is using ws package and also bufferutil to enhance ws' performances.

Since bufferutil is a binary addon, it may or may not be installed correctly on your current platform due to potential incompatibilities.

In such cases, using the environment variable WS_NO_BUFFER_UTIL=1 will be necessary to resolve the issue.

You can read more here.

Development

See the developer docs.

Contributing

> Want to Help ?

Want to file a bug, contribute some code or improve documentation ? Excellent!

But please read up first on the guidelines for contributing, and learn about submission process, coding rules and more.

> Code of Conduct

Please read and follow the Code of Conduct and help me keep this project open and inclusive.