README.md

samsung-tv-remote

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

---

Features

✅ Support Samsung SmartTV from 2016+
✅ Wake TV from sleep mode thanks to Wake-on-LAN (WoL)
✅ Send one or multiple keys at once to the TV
✅ 241 known keys already predefined

Installation

npm install samsung-tv-remote --save

yarn add samsung-tv-remote

Usage

Example

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

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

const main = async () => {
    const remote = new SamsungTvRemote({
        ip: '192.168.1.111',
        mac: 'fc:03:9f:0d:72:37'
    });
    await remote.wakeTV();
    await remote.sendKey(Keys.KEY_DOWN);
    await remote.sendKeys([Keys.KEY_POWER]);
};
main().catch(console.error);

Options

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

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

    /**
     * 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.
     * It could be: 55000 (legacy), 8001 (2016+) or 8002 (2018+).
     *
     * @default 8002
     */
    port?: number,

    /**
     * Milliseconds before the connection to the TV times out.
     *
     * @default 1000
     */
    timeout?: number;

    /**
     * Enables more detailed output.
     *
     * @default false
     */
    debug?: boolean;
}

Apis

class SamsungTvRemote {
    /**
     * Turn 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>;

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

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

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.