Skip to main content


Samsung Smart TV WS API wrapper Version Lint & Tests

This project is a Python library for remotely controlling Samsung televisions via a TCP/IP connection.

It supports modern (post-2016) Samsung Smart TVs running Tizen OS, connected via Ethernet or Wi-Fi.


Documentation

Most of the general usage and features are documented in this README. Some advanced topics are covered in dedicated documents:

  • Commands
    Detailed remote key reference, including the full key list and all supported ways to send keys via the CLI.

  • Applications (App IDs)
    Extended documentation about application IDs, how to find them, and how to install or launch applications from the TV.

Features

  • WebSocket and REST APIs
  • Sync and async support
  • Encrypted v1 API support for older TVs
  • Legacy remote support for pre-2014 TVs (port 55000)
  • Full Art Mode support (Frame TVs)
  • Command-line interface (CLI)

Installation

Requires Python >= 3.10.

Core library:

pip install samsungtvws

Common install (async + encrypted + CLI):

pip install "samsungtvws[async,encrypted,cli]"

Optional extras

  • async: async I/O support (aiohttp, websockets)
  • encrypted: v1 encrypted API support for older Orsay TVs (cryptography, py3rijndael)
  • cli: installs the samsungtv command (typer, wakeonlan)

Examples:

pip install "samsungtvws[cli]"
pip install "samsungtvws[async]"
pip install "samsungtvws[encrypted]"

Install from GitHub (latest main branch)

pip install "git+https://github.com/xchwarze/samsung-tv-ws-api.git#egg=samsungtvws[async,encrypted,cli]"

Local development install

git clone https://github.com/xchwarze/samsung-tv-ws-api.git
cd samsung-tv-ws-api
pip install --editable ".[async,encrypted,cli]"

--editable installs the package in development mode and can be omitted for a regular local install.


CLI check

If installed with the cli extra:

samsungtv --help

Usage

This library can be used either programmatically or via the CLI, depending on the integration needs.

Programmatic usage

For custom integrations or advanced control flows, the library can be consumed directly from Python code.

The examples/ directory contains ready-to-run programmatic examples, including:

  • WebSocket and REST usage
  • Async integrations
  • Encrypted API usage
  • Art Mode control

Reviewing these examples is the recommended starting point for manual integrations.


CLI usage

For quick testing, automation, or scripting, the library provides a fully featured command-line interface. Requires installation with the cli extra.

Once installed:

samsungtv --help

CLI examples

Power on TV using Wake-on-LAN:

samsungtv --host 192.168.1.50 wol

Toggle power:

samsungtv --host 192.168.1.50 power

List installed applications:

samsungtv --host 192.168.1.50 apps

Run an application by ID:

samsungtv --host 192.168.1.50 app-run 3201606009684

Open a URL in the TV browser:

samsungtv --host 192.168.1.50 open-browser https://duckduckgo.com

Get device information:

samsungtv --host 192.168.1.50 device-info

Enable Art Mode:

samsungtv --host 192.168.1.50 art-mode on

Upload an image to Art Mode:

samsungtv --host 192.168.1.50 art-upload image.jpg

The CLI exposes most of the library functionality, including:

  • App management
  • Remote control keys
  • Device information
  • Wake-on-LAN
  • Full Art Mode management

Supported TVs

This library is designed to support all Samsung Smart TVs running Tizen OS (2016+).

It also provides support for older Orsay-based TVs, specifically:

  • H series (2014)
  • Part of J series (2015)

Support for Orsay devices is mainly provided through the encrypted v1 API.

Pre-2014 TVs (C, D, E and F series) only accept key presses through the legacy remote protocol on port 55000:

from samsungtvws.legacy.remote import SamsungTVLegacyAsyncRemote

async with SamsungTVLegacyAsyncRemote("192.168.1.10", timeout=30) as remote:
    await remote.control("KEY_VOLUP")

The first connection shows a prompt on the TV; timeout also bounds how long the user has to allow it. A denied or cancelled prompt raises UnauthorizedError, an unknown reply raises ResponseError and a lost connection raises ConnectionFailure.

Official Samsung compatibility references:

Known issues and restrictions

Subnet / VLAN

Samsung Smart TVs do not allow WebSocket connections across different subnets or VLANs. If your TV is not on the same subnet as Home Assistant, the connection may fail.

Depending on the network setup, this limitation might be mitigated using:

  • IP masquerading (NAT)
  • A proxy

Samsung TV keeps asking for permission

The default setting on newer televisions is to ask for permission on every connection attempt.

To avoid this behavior, adjust:

Device Connection Manager → Access Notification Settings → First Time Only

It is also recommended to clean up previous attempts in:

Device Connection Manager → Device List

Patreon and Tips!

(I have this block in all my GPL projects) Those who want to help buy testing hardware or just give me a tip, you can do it by sending donations to my Binance account. I also made a Patreon

patreon binance-qr

License

LGPL-3.0

Metadata

Release files for samsungtvws 3.0.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for samsungtvws 3.0.7
File Size Uploaded Provenance Actions
samsungtvws-3.0.7.tar.gz 54.3 kB With provenance Details for samsungtvws-3.0.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for samsungtvws 3.0.7
File Interpreter ABI Platform Actions
samsungtvws-3.0.7-py3-none-any.whl Python 3 none any Details for samsungtvws-3.0.7-py3-none-any.whl

Total release size: 105.9 kB

Release files / samsungtvws-3.0.7.tar.gz

Download URL samsungtvws-3.0.7.tar.gz
Size 54.3 kB
Tags Source
SHA-256 checksum
How to use checksums
979a61f64221f7ddf8cb3b254a41cabfc6eae1331182aaee941948b3b7d0b918
BLAKE2b-256 checksum
How to use checksums
b3f6cfe421b69e7ff9c1d4a5ae2f2ee24567581d696ebcdc27e7c6233bfdff6d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / samsungtvws-3.0.7-py3-none-any.whl

Download URL samsungtvws-3.0.7-py3-none-any.whl
Size 51.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3ab372cdd8fae8f097e9b580d28a653bbd42b8de9b6d32ccf55b8eaf86531001
BLAKE2b-256 checksum
How to use checksums
a186f83163083acb7c47cc225d37f942f2ae51c460304d350a9fec64ba167fec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for samsungtvws 3.0.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for samsungtvws-3.0.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.0.7 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page