pysamsungtv

pysamsungtv is an async Python library that talks to Samsung TVs over HTTPS JSON-RPC.

Why

Samsung, in their infinite wisdom, disabled ports 8001 and 8002. This breaks the existing Home Assistant integration/libraries for all 2024+ models. They still expose their JSON-RPC over port 1516/1515, but it is undocumented.

I got frustrated enough to do a clean-room implemenation of it here.

Installation

# pypi
pip install pysamsungtv

# local dev
just install

The package depends on aiohttp for HTTP/1.1 TLS transport. TLS verification is disabled by default because Samsung panels present self-signed certificates; set verify_ssl=True when the certificate chain is trusted on your host.

Usage

Check tests for example usage.

Every helper method corresponds to the JSON-RPC methods in the protocol notes (e.g. get_tv_states, direct_channel_control, volume_up_down, remote_key_control, sound_mode_control, etc). Each coroutine returns the parsed result body or raises a SamsungTVError subclass on transport/protocol failures. Custom RPCs can be issued with SamsungTVClient.send_request().

The optional on_update callback is invoked sequentially after every response. It receives the RPC method name and the parsed payload, making it easy to wire into Home Assistant's entity update routines.

Development

  • Install and run pre-commit (pip install pre-commit && pre-commit install) to ensure mypy and pytest pass locally before committing.
  • All code is typed and passes mypy using the configuration in pyproject.toml.
  • Run the test suite with pytest. Unit tests use fully mocked transports.
  • Integration tests require a real TV: set SAMSUNG_TV_HOST (plus optional SAMSUNG_TV_PORT and/or SAMSUNG_TV_TOKEN) and run pytest -m integration. If no token is supplied the first run will prompt for authorization and cache the returned token under .pytest_cache/samsung_tv_token for later runs.
  • A Justfile is included for convenience: just install, just install-tests, just test, just mypy, etc.
  • All command inputs are exposed as enums in pysamsungtv.enums (also re-exported at the package root) so you can rely on autocomplete/validation for things like InputSource, PictureMode, SoundMode, and RemoteKey.
  • Convenience helpers such as set_picture_mode, set_sound_mode, select_speaker, select_input_source, set_volume, mute()/unmute(), and art_mode_on()/art_mode_off() call the corresponding *_control RPCs for you.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for iloveicedgreentea2 from gravatar.com iloveicedgreentea2

Credits

Author: @iloveicedgreentea

Requires

Python >=3.11

Provides Extra

tests

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_samsungtv-1.0.2.tar.gz (10.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

py_samsungtv-1.0.2-py3-none-any.whl (11.5 kB view details)

Uploaded Python 3

File details

Details for the file py_samsungtv-1.0.2.tar.gz.

File metadata

  • Download URL: py_samsungtv-1.0.2.tar.gz
  • Upload date:
  • Size: 10.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for py_samsungtv-1.0.2.tar.gz
Algorithm Hash digest
SHA256 08c55d4b48991d09d00ad4d40bfcf5730b59d9e5d84f80af380a0b4c12c97e7b
MD5 618cf8a49973546b1cbc67b4a9daeac8
BLAKE2b-256 1524a36faef4b8c9151166a31e05de3234154f9390f93d5c97ffe3058f316e0a

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_samsungtv-1.0.2.tar.gz:

Publisher: publish.yaml on iloveicedgreentea/py-samsungtv

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file py_samsungtv-1.0.2-py3-none-any.whl.

File metadata

  • Download URL: py_samsungtv-1.0.2-py3-none-any.whl
  • Upload date:
  • Size: 11.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for py_samsungtv-1.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 61e4dfcf89e74f3e67b872889be982bb064967ba3885de18f22043fe1c824078
MD5 d9a7dffa4280bff7e9575c8f86df1855
BLAKE2b-256 24eed76d65bf7008aae3f91eb5ec6808d6f6f449ee15d0ec91a9f8c539e29847

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_samsungtv-1.0.2-py3-none-any.whl:

Publisher: publish.yaml on iloveicedgreentea/py-samsungtv

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.2 This release

2 files

1.0.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page