LG TV IP Control

This is a JS library that implements TCP network control for LG TVs manufactured since 2018. It utilizes encryption rules based on a guide found on the internet. A non-encrypted mode is provided for older models, but hasn't been tested.

This library is not provided by LG, and it is not a complete implementation for every TV model.

Check compatibility and TV setup instructions on the root's README.md.

Requirements

• Node 16+ (at least ES2017)
• NPM or Yarn Classic

Installation

# Using NPM
npm install lgtv-ip-control


# Using Yarn
yarn add lgtv-ip-control

Usage

Here's a very basic example of how to control the TV:

import { Inputs, LGTV } from 'lgtv-ip-control';

const lgtv = new LGTV('192.168.1.100', '1a:2b:3c:4d:5e:6f', 'KEY1C0DE');

lgtv
  .connect()
  .then(async () => {
    console.log('Disconnect now');
    await new Promise((resolve) => setTimeout(resolve, 5000));
    console.log('Unmutting...');
    await lgtv.setVolumeMute(false);
    console.log('Select HDMI1 input...');
    await lgtv.setInput(Inputs.hdmi1);
    console.log('Done!');
  })
  // Log any errors
  .catch(console.error)
  // Tries disconnecting once done
  .finally(() => lgtv.disconnect());

To use import, you need to make sure to save the file as .mjs or to specify "type": "module" on your package.json. Learn more about Node.js' support for ESM.

Otherwise replace the first line with:

const { Inputs, LGTV } = require('lgtv-ip-control');

new LGTV()

Returns a new instance to control a TV.

const lgtv = new LGTV(
  /**
   * TV IP Address
   */
  '192.168.1.100',

  /**
   * TV MAC Address for being able to turn the TV on remotely, `null` otherwise
   */
  '1a:2b:3c:4d:5e:6f',

  /**
   * Encryption Keycode, as generated during "Setting Up the TV" above.
   * If not provided, uses clear text, but is required by most models.
   */
  'KEY1C0DE',

  /**
   * Additional options (optional)
   *
   * See src/constants/DefaultSettings.ts file.
   */
  {
    ...DefaultSettings,
  },
);

.connect(): Promise<void>

Connects to the TV using TCP.

Required before sending any commands.

await lgtv.connect();

.disconnect(): void

Disconnects from the TV.

lgtv.disconnect();

.getCurrentApp(): Promise<Apps | string | null>

Gets the current app. May be one of the Apps enum or an arbitrary string if the app type is unknown. Might return null if the TV is powered off but still responding.

const currentApp = await lgtv.getCurrentApp();

.getCurrentVolume(): Promise<number>

Gets the current volume as an integer from 0 to 100.

const currentVolume = await lgtv.getCurrentVolume();

.getIpControlState(): Promise<boolean>

Gets the ip control state.

const ipControlState = await lgtv.getIpControlState();

.getMacAddress(type: 'wired' | 'wifi'): Promise<string>

Gets the MAC address by network interface.

const macAddress = await lgtv.getMacAddress('wired');

.getMuteState(): Promise<boolean>

Gets the mute state.

const muteState = await lgtv.getMuteState();

.getPowerState(): Promise<PowerStates>

Gets the current TV power state.

Because the TV might be offline, you should call this function before calling .connect(), otherwise you can get a TimeoutError.

const powerState = await lgtv.getPowerState();

See PowerStates for available states.

.powerOff(): Promise<void>

Powers the TV off.

await lgtv.powerOff();

.powerOn(): void

Powers the TV on, using Wake On Lan. Requires MAC address to be set when creating the LGTV instance.

lgtv.powerOn();

.powerOnAndConnect(): Promise<void>

Powers the TV on, using Wake On Lan, and connects to it. Requires MAC address to be set when creating the LGTV instance. Returns a promise that resolves once the connection is established, or rejects after a number of retries.

await lgtv.powerOnAndConnect();

.sendKey(key: Keys): Promise<void>

Sends a key, as if it was pressed on the TV remote control.

await lgtv.sendKey(Keys.menu);

See Keys for available keys.

.setEnergySaving(level: EnergySavingLevels): Promise<void>

Sets the current energy saving level. Note that screenOff is known not to work for some models.

await lgtv.setEnergySaving(EnergySavingLevels.maximum);

See EnergySavingLevels for available levels.

.setInput(input: Inputs): Promise<void>

Sets the current TV input.

await lgtv.setInput(Inputs.hdmi1);

See Inputs for available inputs.

.setVolume(volume: number): Promise<void>

Sets the volume level as an integer from 0 to 100.

await lgtv.setVolume(15);

.setVolumeMute(isMuted: boolean): Promise<void>

Sets the volume mute state.

await lgtv.setVolumeMute(false);

.setScreenMute(mode: ScreenMuteModes): Promise<void>

Sets the current screen mute mode. This can be used to either completely blank the screen or just blank the video feed while leaving the OSD visible. Returns a promise.

await lgtv.setScreenMute(ScreenMuteModes.screenmuteon);

See ScreenMuteModes for available modes.

Available Lists

EnergySavingLevels

Key	Brightness Level
auto	Automatic
screenOff	Screen Off
maximum	Low
medium	Medium
minimum	High
off	Maximum

Inputs

Key	Input
dtv	Digital TV
atv	Analog TV
cadtv	Cable Digital TV
catv	Cable TV
av	AV Composite
component	Component
hdmi1	HDMI 1
hdmi2	HDMI 2
hdmi3	HDMI 3
hdmi4	HDMI 4

Keys

Key	Remote Button
arrowDown	Arrow Down
arrowLeft	Arrow Left
arrowRight	Arrow Right
arrowUp	Arrow Up
aspectRatio	Aspect Ratio Toggle
audioMode	Audio Mode Toggle
back	Back
blueButton	Blue Button
captionSubtitle	–
channelDown	Channel Down
channelList	Channel List
channelUp	Channel Up
deviceInput	Device Input Toggle
energySaving	Energy Saving Toggle
fastForward	–
greenButton	Green Button
home	Home
info	Info
liveTV	Live TV
menu	Open Menu
number0	Number 0
number1	Number 1
number2	Number 2
number3	Number 3
number4	Number 4
number5	Number 5
number6	Number 6
number7	Number 7
number8	Number 8
number9	Number 9
ok	Ok
play	–
previousChannel	Previous Channel
programGuide	Show Program Guide
record	–
redButton	Red Button
rewind	–
sleepTimer	Sleep Timer Toggle
userGuide	Open User Guide
videoMode	Video Mode Toggle
volumeDown	Volume Down
volumeMute	Mute Toggle
volumeUp	Volume Up
yellowButton	Yellow Button

PowerStates

Key	State
on	The TV is on and responding to connections
off	The TV is off or powering off
unknown	The state of the TV is unknown, possibly off

ScreenMuteModes

Key	Effect
screenMuteOn	Blank screen
videoMuteOn	Blank video, OSD visible
allMuteOff	Normal Operation