Need help with samsungctl?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

541 Stars 180 Forks MIT License 96 Commits 58 Opened issues


Remote control Samsung televisions via a TCP/IP connection

Services available


Need anything else?

Contributors list



samsungctl is a library and a command line tool for remote controlling Samsung televisions via a TCP/IP connection. It currently supports both pre-2016 TVs as well most of the modern Tizen-OS TVs with Ethernet or Wi-Fi connectivity.


  • Python 3
  • websocket-client
    (optional, for 2016+ TVs)
  • curses
    (optional, for the interactive mode)


samsungctl can be installed using



# pip install samsungctl

Alternatively you can clone the Git repository and run:


# python install

It's possible to use the command line tool without installation:


$ python -m samsungctl

Command line usage

You can use

command to send keys to a TV:


$ samsungctl --host  [options]  [key ...]

is the hostname or IP address of the TV.
is a key code, e.g.
. See
Key codes

There is also an interactive mode (ncurses) for sending the key presses:


$ samsungctl --host  [options] --interactive


samsungctl --help
for more information about the command line arguments:


usage: samsungctl [-h] [--version] [-v] [-q] [-i] [--host HOST] [--port PORT]
                  [--method METHOD] [--name NAME] [--description DESC]
                  [--id ID] [--timeout TIMEOUT]
                  [key [key ...]]

Remote control Samsung televisions via TCP/IP connection

positional arguments: key keys to be sent (e.g. KEY_VOLDOWN)

optional arguments: -h, --help show this help message and exit --version show program's version number and exit -v, --verbose increase output verbosity -q, --quiet suppress non-fatal output -i, --interactive interactive control --host HOST TV hostname or IP address --port PORT TV port number (TCP) --method METHOD Connection method (legacy or websocket) --name NAME remote control name --description DESC remote control description --id ID remote control id --timeout TIMEOUT socket timeout in seconds (0 = no timeout)

E.g. samsungctl --host --name myremote KEY_VOLDOWN

The settings can be loaded from a configuration file. The file is searched from

, and
in this order. A simple default configuration is bundled with the source as

Library usage

samsungctl can be imported as a Python 3 library:

.. code-block:: python

import samsungctl

A context managed remote controller object of class

can be constructed using the

.. code-block:: python

with samsungctl.Remote(config) as remote:
    # Use the remote object

The constructor takes a configuration dictionary as a parameter. All configuration items must be specified.

=========== ====== =========================================== Key Type Description =========== ====== =========================================== host string Hostname or IP address of the TV. port int TCP port number. (Default:

) method string Connection method (
) name string Name of the remote controller. description string Remote controller description. id string Additional remote controller ID. timeout int Timeout in seconds.
means no timeout. =========== ====== ===========================================


object is very simple and you only need the
method. The only parameter is a string naming the key to be sent (e.g.
). See
Key codes
_. You can call
multiple times using the same
object. The connection is automatically closed when exiting the

When something goes wrong you will receive an exception:

================= ======================================= Exception Description ================= ======================================= AccessDenied The TV does not allow you to send keys. ConnectionClosed The connection was closed. UnhandledResponse An unexpected response was received. socket.timeout The connection timed out. ================= =======================================

Example program

This simple program opens and closes the menu a few times.

.. code-block:: python

#!/usr/bin/env python3

import samsungctl import time

config = { "name": "samsungctl", "description": "PC", "id": "", "host": "", "port": 55000, "method": "legacy", "timeout": 0, }

with samsungctl.Remote(config) as remote: for i in range(10): remote.control("KEY_MENU") time.sleep(0.5)

Key codes

The list of accepted keys may vary depending on the TV model, but the following list has some common key codes and their descriptions.

================= ============ Key code Description ================= ============ KEYPOWEROFF Power off KEYUP Up KEYDOWN Down KEYLEFT Left KEYRIGHT Right KEYCHUP P Up KEYCHDOWN P Down KEYENTER Enter KEYRETURN Return KEYCHLIST Channel List KEYMENU Menu KEYSOURCE Source KEYGUIDE Guide KEYTOOLS Tools KEYINFO Info KEYRED A / Red KEYGREEN B / Green KEYYELLOW C / Yellow KEYBLUE D / Blue KEYPANNELCHDOWN 3D KEYVOLUP Volume Up KEYVOLDOWN Volume Down KEYMUTE Mute KEY0 0 KEY1 1 KEY2 2 KEY3 3 KEY4 4 KEY5 5 KEY6 6 KEY7 7 KEY8 8 KEY9 9 KEYDTV TV Source KEYHDMI HDMI Source KEYCONTENTS SmartHub ================= ============

Please note that some codes are different on the 2016+ TVs. For example,

on the newer TVs.


I did not reverse engineer the control protocol myself and samsungctl is not the only implementation. Here is the list of things that inspired samsungctl.


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.