Samsung TV WS

https://github.com/xchwarze/samsung-tv-ws-api
Admin
Samsung TV WS is a Python library for remotely controlling Samsung Smart TVs via WebSocket and REST...
Tokens:78,194
Snippets:640
Trust Score:9.9
License:LGPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### start_listening() usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Example of starting to listen for events and sending a key from any thread while listening.

```python
tv = SamsungTVWS("192.168.1.50")

def on_event(event, response):
    print(event, response)

tv.start_listening(on_event)
# tv.send_key("KEY_HOME")  # safe from any thread while listening
```

--------------------------------

### Start listening with event callback

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-connection.md

Example of using start_listening with a callback that handles events. The callback is invoked with event and response, and this example sleeps for 10 seconds before closing.

```python
async def main():
    tv = SamsungTVWSAsyncRemote("192.168.1.50")

    async def on_event(event, response):
        if event == "ed.installedApp.get":
            print("installed apps event")

    await tv.start_listening(on_event)
    await asyncio.sleep(10)
    await tv.close()
```

--------------------------------

### open() usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Example of opening a connection to a TV and checking if it is alive.

```python
from samsungtvws.remote import SamsungTVWS

tv = SamsungTVWS("192.168.1.50", port=8002)
tv.open()
print("connected:", tv.is_alive())
tv.close()
```

--------------------------------

### app_list usage example with check

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Retrieves the app list and prints the names of installed apps if the list is not None.

```python
apps = tv.app_list()
if apps:
    print([a["name"] for a in apps])
```

--------------------------------

### Usage example with SamsungTVAsyncRest

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-rest.md

Shows how to create a SamsungTVAsyncRest instance with a shared aiohttp session, get device info, run, check status, and close an app. The session is managed with an async context manager.

```python
import asyncio, aiohttp, contextlib
from samsungtvws.async_rest import SamsungTVAsyncRest

async def main():
    async with aiohttp.ClientSession() as session:
        rest = SamsungTVAsyncRest("192.168.1.50", session=session, port=8002)
        print(await rest.rest_device_info())
        await rest.rest_app_run("3201606009684")
        print(await rest.rest_app_status("3201606009684"))
        await rest.rest_app_close("3201606009684")

asyncio.run(main())
```

--------------------------------

### Example of installed app item shape

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/event.md

Shows the expected shape of each item in the list returned by `parse_installed_app`.

```python
{"appId": "111299001912", "app_type": 2, "icon": "/.../250x250.png", "is_lock": 0, "name": "YouTube"}
```

--------------------------------

### Install samsungtvws from GitHub

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Installs the latest main branch of samsungtvws from GitHub with all extras.

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

--------------------------------

### SendRemoteKey.guide()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-commands.md

Static factory for the guide key.

```APIDOC
## SendRemoteKey.guide()

### Description
Static factory for the guide key.

### Method
N/A (static method)

### Endpoint
N/A

### Parameters
None

### Request Example
```python
SendRemoteKey.guide()
```

### Response
Returns a `SendRemoteKey` for `KEY_GUIDE`.
```

--------------------------------

### List installed apps

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Lists installed applications on the TV.

```bash
samsungtv --host 192.168.1.50 apps
```

--------------------------------

### Install samsungtvws with all extras

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Installs samsungtvws with all optional extras: async I/O support, encrypted API support for older Orsay TVs, and the CLI.

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

--------------------------------

### Install extras (pyproject.toml)

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/configuration.md

Install the samsungtvws package with optional extras for async support, encrypted API, and CLI.

```APIDOC
## Install extras

### Description
Install the samsungtvws package with optional extras for async support, encrypted API, and CLI.

### Command
```bash
pip install "samsungtvws[async,encrypted,cli]"
```

### Extras
- `async` - Enables `samsungtvws.async_*` modules. Dependencies: `aiohttp>=3.8.1`, `websockets>=13`, `async_timeout>=4.0.3` (Python < 3.11)
- `encrypted` - Enables v1 encrypted API for Orsay TVs. Dependencies: `cryptography>=35.0.0`, `py3rijndael>=0.3.3`
- `cli` - Enables `samsungtv` command. Dependencies: `typer>=0.20`, `wakeonlan>=3.0.0`

### Base Dependencies
- `websocket-client>=0.57.0`
- `requests>=2.21.0`
- `yarl>=1.9`
- Python `>=3.10`
```

--------------------------------

### Usage example: parse_installed_app with event handler

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/event.md

Demonstrates how to use `ED_INSTALLED_APP_EVENT` and `parse_installed_app` inside an event callback to print installed app names.

```python
from samsungtvws.event import ED_INSTALLED_APP_EVENT, parse_installed_app

def on_event(event, response):
    if event == ED_INSTALLED_APP_EVENT:
        apps = parse_installed_app(response)
        print([app["name"] for app in apps])
```

--------------------------------

### Install samsungtvws with individual extras

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Installs samsungtvws with individual optional extras: cli, async, or encrypted.

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

--------------------------------

### Basic CLI usage examples

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/cli.md

Basic CLI usage examples for common commands: list apps, send a key multiple times, run an app by ID, upload art with no matte, and wake on LAN using a MAC address.

```bash
samsungtv --host 192.168.1.50 apps
samsungtv --host 192.168.1.50 send-key KEY_VOLUP --times 3 --delay 0.2
samsungtv --host 192.168.1.50 app-run 3201606009684
samsungtv --host 192.168.1.50 art-upload image.jpg --matte none
samsungtv --host 192.168.1.50 wol CC:6E:A4:XX:XX:XX
```

--------------------------------

### ChannelEmitCommand.get_installed_app()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-commands.md

Static factory for getting the installed app.

```APIDOC
## ChannelEmitCommand.get_installed_app()

### Description
Static factory returning a `ChannelEmitCommand` to get the installed app.

### Method
N/A (static method)

### Endpoint
N/A

### Parameters
None

### Request Example
```python
ChannelEmitCommand.get_installed_app()
```

### Response
Returns a `ChannelEmitCommand` with params `{"event": "ed.installedApp.get", "to": "host"}`.
```

--------------------------------

### Local development install

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Clones the repository and installs in editable (development) mode with all extras. The --editable flag can be omitted for a regular local install.

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

--------------------------------

### app_list()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Gets the list of installed applications on the TV.

```APIDOC
## `app_list()`

### Description
Retrieves the list of installed applications on the TV. Sends a `ChannelEmitCommand.get_installed_app()` frame and waits for the `ed.installedApp.get` response. Returns the parsed list of apps or `None` if the TV does not respond.

### Method
WebSocket (ms.channel.emit)

### Parameters
None.

### Request Example
```python
apps = tv.app_list()
if apps:
    print([a["name"] for a in apps])
```

### Response
Returns a list of dictionaries representing installed apps, or `None` if unavailable.
```

--------------------------------

### Install core samsungtvws from PyPI

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Installs the core samsungtvws library from PyPI. Requires Python >= 3.10.

```bash
pip install samsungtvws
```

--------------------------------

### open() error handling example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Example of handling UnauthorizedError and ConnectionFailure when opening a connection.

```python
from samsungtvws.exceptions import UnauthorizedError, ConnectionFailure

tv = SamsungTVWS("192.168.1.50")
try:
    tv.open()
except UnauthorizedError:
    print("TV refused the token — authorize the app on screen")
except ConnectionFailure:
    print("TV unreachable or not on the same subnet/VLAN")
```

--------------------------------

### Basic usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/rest.md

Shows how to instantiate SamsungTVRest and call methods for device info, app status, and app run.

```python
from samsungtvws.rest import SamsungTVRest

rest = SamsungTVRest("192.168.1.50", port=8002, timeout=5)
print(rest.rest_device_info())
print(rest.rest_app_status("3201606009684"))
rest.rest_app_run("3201606009684")
```

--------------------------------

### send-key examples: volume up, repeat, press, release

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/COMMANDS.md

Four examples of using send-key: clicking volume up once, clicking volume up 5 times, pressing with a custom delay, and releasing a key. The --cmd option accepts only Click, Press, or Release; --delay overrides --key-press-delay for the invocation.

```bash
# Click volume up once
samsungtv --host 192.168.1.50 send-key KEY_VOLUP
```

```bash
# Click volume up 5 times
samsungtv --host 192.168.1.50 send-key KEY_VOLUP --times 5
```

```bash
# Press (no release) + custom delay between repeats
samsungtv --host 192.168.1.50 send-key KEY_RIGHT --times 3 --cmd Press --delay 0.2
```

```bash
# Release a key
samsungtv --host 192.168.1.50 send-key KEY_RIGHT --cmd Release
```

--------------------------------

### Context manager usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Example of using the connection as a context manager, with automatic closing.

```python
with SamsungTVWS("192.168.1.50") as tv:
    tv.send_key("KEY_HOME")
# connection closed automatically
```

--------------------------------

### Show samsungtv CLI help

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Displays CLI help. Requires installation with the cli extra.

```bash
samsungtv --help
```

--------------------------------

### send_command() usage example with SendRemoteKey.click

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Example of sending a click command with a key press delay.

```python
from samsungtvws.remote import SamsungTVWS, SendRemoteKey

tv = SamsungTVWS("192.168.1.50")
tv.send_command(SendRemoteKey.click("KEY_VOLUP"), key_press_delay=0.5)
```

--------------------------------

### End-to-end pairing example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/encrypted-remote.md

Complete example of pairing with a Samsung TV and sending a remote key command using the encrypted WebSocket remote.

```APIDOC
## End-to-end pairing example

### Description
Complete example of pairing with a Samsung TV and sending a remote key command using the encrypted WebSocket remote.

### Prerequisites
- Python 3.7+
- `aiohttp` library
- `samsungtvws` library

### Example
```python
import asyncio, aiohttp
from samsungtvws.encrypted.authenticator import SamsungTVEncryptedWSAsyncAuthenticator
from samsungtvws.encrypted.remote import SamsungTVEncryptedWSAsyncRemote, SendRemoteKey

async def pair(host: str, session: aiohttp.ClientSession) -> tuple[str, str]:
    auth = SamsungTVEncryptedWSAsyncAuthenticator(host, web_session=session, port=8080)
    await auth.start_pairing()
    token = None
    while not token:
        token = await auth.try_pin(input("PIN: "))
    return token, await auth.get_session_id_and_close()

async def main():
    async with aiohttp.ClientSession() as session:
        token, session_id = await pair("192.168.1.50", session)
        remote = SamsungTVEncryptedWSAsyncRemote(
            host="192.168.1.50", web_session=session,
            token=token, session_id=session_id, port=8000,
        )
        await remote.start_listening()
        await remote.send_command(SendRemoteKey.click("KEY_POWEROFF"))
        await remote.close()

asyncio.run(main())
```
```

--------------------------------

### send_command() usage example with SendRemoteKey.hold

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Example of sending a hold command for a key for a duration.

```python
tv.send_command(SendRemoteKey.hold("KEY_POWER", 3))  # press + sleep(3) + release
```

--------------------------------

### rest_app_install(app_id)

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-rest.md

Installs an application on the TV via a PUT request to /api/v2/applications/{app_id}.

```APIDOC
## PUT /api/v2/applications/{app_id}

### Description
Installs the specified application on the TV.

### Method
PUT

### Endpoint
/api/v2/applications/{app_id}

### Parameters
#### Path Parameters
- **app_id** (str) - Required - The application ID

### Request Example
```python
await rest.rest_app_install("3201606009684")
```

### Response
#### Success Response (200)
- **dict[str, Any]** - Parsed JSON response

#### Response Example
```json
{
  "success": true
}
```

### Errors
- **HttpApiError** - Raised when aiohttp.ClientConnectionError occurs, message: "TV unreachable or feature not supported on this model."
```

--------------------------------

### rest_app_install(app_id)

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Installs an application from the store via the REST API.

```APIDOC
## `rest_app_install(app_id)`

### Description
Installs an application from the store via the REST API. Delegates to `SamsungTVRest.rest_app_install(app_id)`.

### Method
PUT

### Endpoint
`/api/v2/applications/{app_id}`

### Parameters
- **app_id** (str) - Required - The application ID.

### Request Example
```python
from samsungtvws.exceptions import HttpApiError

try:
    tv.rest_app_install("3201606009684")
except HttpApiError as err:
    print("Install failed:", err)
```

### Response
Returns a dictionary with the response from the TV.
```

--------------------------------

### Use shortcuts and art accessors

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote.md

Example of using the shortcuts and art accessors to control power and art mode.

```python
tv.shortcuts().power()
if tv.art().supported():
    tv.art().set_artmode(True)
```

--------------------------------

### app_list()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-remote.md

Asynchronously retrieves the list of installed applications on the TV.

```APIDOC
## app_list()

### Description
Retrieves the list of installed applications on the TV. This method sends a command to get the installed apps and waits for the response. It returns None if the TV does not respond within the timeout.

### Method
Async Function

### Endpoint
N/A

### Parameters
None

### Request Example
```python
apps = await tv.app_list()
```

### Response
#### Success Response (200)
- **list** (list[dict[str, Any]]) - A list of dictionaries containing app information.

#### Response Example
```python
[{"name": "Netflix", "id": "11101200001"}, ...]
```

#### Error Response (Timeout)
- **None** - Returned if the TV does not respond within the timeout.
```

--------------------------------

### Hold-key examples for volume and left keys

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/COMMANDS.md

Example invocations of hold-key: holding volume up for 5 seconds and left for 0.8 seconds.

```bash
# Hold volume up for 5 seconds
samsungtv --host 192.168.1.50 hold-key KEY_VOLUP 5

# Hold left for 0.8 seconds
samsungtv --host 192.168.1.50 hold-key KEY_LEFT 0.8
```

--------------------------------

### PUT /api/v2/applications/{app_id}

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/rest.md

Installs a specific application from the official store.

```APIDOC
## [PUT] /api/v2/applications/{app_id}

### Description
Installs a specific application from the official store.

### Method
PUT

### Endpoint
/api/v2/applications/{app_id}

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The application ID.

### Response
#### Success Response (200)
- **response** (object) - JSON object returned by the TV.

#### Response Example
{
  "success": true
}

### Errors
- **HttpApiError** - Raised when the TV is unreachable or the feature is not supported on this model.
```

--------------------------------

### SamsungTVEncryptedWSAsyncRemote.start_listening

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/encrypted-remote.md

Starts the WebSocket connection and receive loop.

```APIDOC
## SamsungTVEncryptedWSAsyncRemote.start_listening()

### Description
Opens the WebSocket connection and starts the receive loop. Fetches the socket.io session key, connects to the WebSocket, sends the handshake, and begins draining frames (events are only logged).

### Method
Async method

### Signature
`async def start_listening(self) -> None`

### Exceptions
- **ConnectionFailure** - Raised when already listening ("Connection already exists").
```

--------------------------------

### rest_app_install method

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-rest.md

Installs an app via PUT /api/v2/applications/{app_id}.

```python
async def rest_app_install(self, app_id: str) -> dict[str, Any]:

```

--------------------------------

### Get device information

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/README.md

Retrieves device information from the TV.

```bash
samsungtv --host 192.168.1.50 device-info
```

--------------------------------

### Encrypted remote usage example - Connect and send KEY_POWEROFF

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/encrypted-remote.md

Complete example of using the encrypted remote: creates a session, connects, sends a power-off command, waits 15 seconds, and closes. Requires the encrypted extra and a valid token and session_id.

```python
import asyncio, aiohttp
from samsungtvws.encrypted.remote import SamsungTVEncryptedWSAsyncRemote, SendRemoteKey

async def main():
    async with aiohttp.ClientSession() as session:
        remote = SamsungTVEncryptedWSAsyncRemote(
            host="192.168.1.50",
            web_session=session,
            token="b231074ae524245f4dd581154c112936",
            session_id="1",
            port=8000,
        )
        await remote.start_listening()
        await remote.send_command(SendRemoteKey.click("KEY_POWEROFF"))
        await asyncio.sleep(15)
        await remote.close()

asyncio.run(main())
```

--------------------------------

### Error handling example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/rest.md

Demonstrates catching HttpApiError from rest_app_install and ValueError from rest_ime_input with a None token.

```python
from samsungtvws.exceptions import HttpApiError

rest = SamsungTVRest("192.168.1.50")
try:
    rest.rest_app_install("3201606009684")
except HttpApiError as err:
    print("REST API unavailable:", err)

try:
    rest.rest_ime_input("secret", token=None)
except ValueError as err:
    print(err)   # "IME input requires a valid security token"
```

--------------------------------

### Using channel and digit methods

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/shortcuts.md

Example usage of channel and digit methods showing the keys sent for each call.

```python
sc.channel(12)      # KEY_1, KEY_2, KEY_ENTER
sc.digit(5)         # KEY_5
```

--------------------------------

### ArtChannelEmitCommand usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art-media.md

Imports ArtChannelEmitCommand and sends an art_app_request with a request payload.

```python
from samsungtvws.art.art import ArtChannelEmitCommand

tv.send_command(ArtChannelEmitCommand.art_app_request({"request": "get_current_artwork"}))
```

--------------------------------

### Send text input

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote.md

Example of sending text and confirming with the enter key.

```python
tv.send_text("hello world")
tv.send_key("KEY_ENTER")
```

--------------------------------

### Example: start_pairing usage

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/encrypted-authenticator.md

Shows how to create an authenticator and call start_pairing to display the PIN page on the TV. Requires an aiohttp session.

```python
import asyncio, aiohttp
from samsungtvws.encrypted.authenticator import (
    SamsungTVEncryptedWSAsyncAuthenticator,
)

async def main():
    async with aiohttp.ClientSession() as session:
        auth = SamsungTVEncryptedWSAsyncAuthenticator("192.168.1.50", web_session=session, port=8080)
        await auth.start_pairing()
        print("check the TV for the PIN page")

asyncio.run(main())
```

--------------------------------

### open_browser usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Opens a URL in the Tizen browser using the open_browser method.

```python
tv.open_browser("https://duckduckgo.com")
```

--------------------------------

### Installed app item shape

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/types.md

Example of an installed app item as returned by parse_installed_app, SamsungTVWS.app_list, and SamsungTVWSAsyncRemote.app_list. The appId field is the app identifier, app_type is an integer, icon is an absolute path on the TV, is_lock is a lock flag (0/1), and name is the human-readable name.

```python
{
    "appId": "111299001912",
    "app_type": 2,
    "icon": "/opt/share/webappservice/apps_icon/FirstScreen/111299001912/250x250.png",
    "is_lock": 0,
    "name": "YouTube",
}
```

--------------------------------

### ChannelEmitCommand class definition

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-commands.md

Builds commands with method 'ms.channel.emit'. Provides static methods for getting installed apps, launching apps, and signaling text received.

```python
class ChannelEmitCommand(SamsungTVCommand):
    def __init__(self, params: dict[str, Any]) -> None:
        super().__init__("ms.channel.emit", params)

    @staticmethod
    def get_installed_app() -> ChannelEmitCommand:                  # remote.py:42
    @staticmethod
    def launch_app(
        app_id: str, app_type: str = "DEEP_LINK", meta_tag: str = ""
    ) -> ChannelEmitCommand:                                        # remote.py:51
    @staticmethod
    def text_received() -> ChannelEmitCommand:                      # remote.py:69
```

--------------------------------

### ChannelEmitCommand.launch_app(app_id, app_type, meta_tag)

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-commands.md

Static factory to launch an app.

```APIDOC
## ChannelEmitCommand.launch_app(app_id, app_type, meta_tag)

### Description
Static factory to launch an app.

### Method
N/A (static method)

### Endpoint
N/A

### Parameters
- **app_id** (str) - Required - The app ID.
- **app_type** (str) - Optional - Default `"DEEP_LINK"`.
- **meta_tag** (str) - Optional - Default `""`.

### Request Example
```python
ChannelEmitCommand.launch_app("1234", "DEEP_LINK", "")
```

### Response
Returns a `ChannelEmitCommand` with params `{"event": "ed.apps.launch", "to": "host", "data": {"action_type": app_type, "appId": app_id, "metaTag": meta_tag}}`.
```

--------------------------------

### generate_connection_id usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/helper.md

Example usage of generate_connection_id. It prints a random integer, e.g., 128039182.

```python
from samsungtvws.helper import generate_connection_id

print(generate_connection_id())   # e.g. 128039182
```

--------------------------------

### run_app usage examples

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Shows how to launch apps using run_app. The first call launches Spotify with default DEEP_LINK, the second launches the Tizen browser with NATIVE_LAUNCH and a URL.

```python
from samsungtvws import SamsungTVWS

tv = SamsungTVWS("192.168.1.50")
tv.run_app("3201606009684")                      # Spotify (DEEP_LINK)
tv.run_app("org.tizen.browser", "NATIVE_LAUNCH", "https://example.com")
```

--------------------------------

### get_ssl_context usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/helper.md

Example usage of get_ssl_context. It prints the verify_mode of the returned SSLContext, which is ssl.VerifyMode.CERT_NONE.

```python
from samsungtvws.helper import get_ssl_context

ctx = get_ssl_context()
print(ctx.verify_mode)   # ssl.VerifyMode.CERT_NONE
```

--------------------------------

### serialize_string usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/helper.md

Example usage of serialize_string. It prints the base64-encoded result of the input string.

```python
from samsungtvws.helper import serialize_string

print(serialize_string("SamsungTvRemote"))
# U2Ftc3VuZ1R2UmVtb3Rl
```

--------------------------------

### Create SamsungTVArt via tv.art()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art.md

Shows how to obtain a SamsungTVArt instance via the SamsungTVWS.art() factory method.

```python
from samsungtvws import SamsungTVWS

tv = SamsungTVWS("192.168.1.50")
art = tv.art()               # direct: SamsungTVArt("192.168.1.50")
```

--------------------------------

### start_listening(callback)

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Opens the connection and starts a daemon thread that loops receiving frames and invokes the callback for each parsed frame. Returns None.

```APIDOC
## start_listening(callback)

### Description
Opens the connection and starts a daemon `threading.Thread` (`_do_start_listening`) that loops `connection.recv()`, routes every frame through `_websocket_event` and invokes `callback(event, response)` for each parsed frame.

### Method
start_listening(callback)

### Signature
```python
def start_listening(
    self, callback: Callable[[str, Any], None] | None = None
) -> None:
```

### Parameters
- **callback** (Callable[[str, Any], None] | None) - Optional - Function to call with each parsed event and response.

### Returns
- **None**

### Throws
- **ConnectionFailure** - If `self.connection` is already set.

### Example
```python
tv = SamsungTVWS("192.168.1.50")

def on_event(event, response):
    print(event, response)

tv.start_listening(on_event)
# tv.send_key("KEY_HOME")  # safe from any thread while listening
```
```

--------------------------------

### rest_device_info method

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-rest.md

Gets device information via GET /api/v2/ and returns parsed JSON.

```python
async def rest_device_info(self) -> dict[str, Any]:

```

--------------------------------

### Brightness and color temperature usage

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art.md

Example usage for setting the brightness sensor, adjusting brightness, and retrieving color temperature.

```python
art.set_brightness_sensor_setting(False)   # brightness sensor off
art.set_brightness(70)
print(art.get_color_temperature())
```

--------------------------------

### Constructor

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-remote.md

Initializes a new SamsungTVWSAsyncRemote instance with the specified parameters.

```APIDOC
## Constructor

### Description
Initializes a new instance of the SamsungTVWSAsyncRemote class.

### Method
Constructor

### Endpoint
N/A

### Parameters
- **host** (string) - Required - The IP address or hostname of the Samsung TV.
- **token** (string) - Optional - The authentication token for the TV.
- **token_file** (string) - Optional - Path to a file containing the authentication token.
- **port** (integer) - Optional - The port number for the WebSocket connection (default: 8001).
- **timeout** (float) - Optional - The timeout in seconds for operations.
- **key_press_delay** (float) - Optional - The delay in seconds between key presses (default: 1).
- **name** (string) - Optional - The name of the remote (default: "SamsungTvRemote").

### Request Example
```python
SamsungTVWSAsyncRemote("192.168.1.50", port=8002, timeout=10)
```

### Response
#### Success Response (200)
- **instance** (SamsungTVWSAsyncRemote) - The created instance.

#### Response Example
```python
<__main__.SamsungTVWSAsyncRemote object at 0x...>
```
```

--------------------------------

### process_api_response ResponseError example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/helper.md

Example showing how process_api_response raises ResponseError when the input is not JSON and contains no braces. The error message is printed.

```python
from samsungtvws.exceptions import ResponseError

try:
    process_api_response(b"not-json-and-no-braces")
except ResponseError as err:
    print(err)
```

--------------------------------

### start_listening() method signature

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-connection.md

Method signature for start_listening. Opens the connection and schedules _do_start_listening as an asyncio task. Raises ConnectionFailure if connection already exists.

```python
async def start_listening(
    self, callback: Callable[[str, Any], Awaitable[None] | None] | None = None
) -> None:
```

--------------------------------

### send_password usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Shows how to send a password using send_password. Requires a token_file for authentication. Prints whether the password was accepted based on the boolean return.

```python
tv = SamsungTVWS("192.168.1.50", token_file="/tmp/tv-token")
ok = tv.send_password("p4ssw0rd")
print("password accepted" if ok else "password rejected")
```

--------------------------------

### process_api_response JSON bytes example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/helper.md

Example usage of process_api_response with a bytes input containing JSON. It prints the 'event' field from the parsed frame.

```python
from samsungtvws.helper import process_api_response

frame = process_api_response(b'{"data": 200, "event": "ed.apps.launch"}')
print(frame["event"])   # ed.apps.launch
```

--------------------------------

### get_slideshow_status()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art.md

Gets the slideshow status.

```APIDOC
## get_slideshow_status()

### Description
Retrieves the slideshow status from the TV.

### Method
Call

### Parameters
None

### Returns
The slideshow status.

### Example
```python
print(art.get_slideshow_status())
```
```

--------------------------------

### process_api_response binary tail example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/helper.md

Example showing how process_api_response attaches a binary tail (e.g., an inline JPEG thumbnail) to the frame as 'binary' and 'binary_len' for Art API 0.97. It writes the binary data to a file.

```python
# Binary tail (thumbnail) attached for Art API 0.97
frame = process_api_response(raw_binary_frame)
if frame.get("binary"):
    with open("thumb.jpg", "wb") as f:
        f.write(frame["binary"])
    print("inline thumbnail bytes:", frame["binary_len"])
```

--------------------------------

### End-to-end pairing and remote command example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/encrypted-remote.md

Demonstrates async pairing with SamsungTVEncryptedWSAsyncAuthenticator, obtaining a token and session ID, then using SamsungTVEncryptedWSAsyncRemote to send a key and close. Includes PIN input and uses aiohttp session.

```python
import asyncio, aiohttp
from samsungtvws.encrypted.authenticator import SamsungTVEncryptedWSAsyncAuthenticator
from samsungtvws.encrypted.remote import SamsungTVEncryptedWSAsyncRemote, SendRemoteKey

async def pair(host: str, session: aiohttp.ClientSession) -> tuple[str, str]:
    auth = SamsungTVEncryptedWSAsyncAuthenticator(host, web_session=session, port=8080)
    await auth.start_pairing()
    token = None
    while not token:
        token = await auth.try_pin(input("PIN: "))
    return token, await auth.get_session_id_and_close()

async def main():
    async with aiohttp.ClientSession() as session:
        token, session_id = await pair("192.168.1.50", session)
        remote = SamsungTVEncryptedWSAsyncRemote(
            host="192.168.1.50", web_session=session,
            token=token, session_id=session_id, port=8000,
        )
        await remote.start_listening()
        await remote.send_command(SendRemoteKey.click("KEY_POWEROFF"))
        await remote.close()

asyncio.run(main())
```

--------------------------------

### get_auto_rotation_status()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art.md

Gets the current auto-rotation status.

```APIDOC
## get_auto_rotation_status()

### Description
Retrieves the auto-rotation status from the TV.

### Method
Call

### Parameters
None

### Returns
The auto-rotation status.

### Example
```python
# Typically used as a fallback for legacy TVs
```
```

--------------------------------

### POST /api/v2/applications/{app_id}

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/rest.md

Launches a specific application on the TV.

```APIDOC
## [POST] /api/v2/applications/{app_id}

### Description
Launches a specific application on the TV.

### Method
POST

### Endpoint
/api/v2/applications/{app_id}

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The application ID.

### Response
#### Success Response (200)
- **response** (object) - JSON object returned by the TV.

#### Response Example
{
  "success": true
}

### Errors
- **HttpApiError** - Raised when the TV is unreachable or the feature is not supported on this model.
```

--------------------------------

### Retrieve app list with SamsungTVWSAsyncRemote

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-remote.md

Example usage of SamsungTVWSAsyncRemote.app_list(). Requires start_listening() to be active for app_list() to complete. Prints a list of app names or None if the app list is not available.

```python
import asyncio
from samsungtvws.async_remote import SamsungTVWSAsyncRemote

async def main():
    tv = SamsungTVWSAsyncRemote("192.168.1.50", port=8002, timeout=10)
    await tv.start_listening()
    try:
        apps = await tv.app_list()
        print(apps and [a["name"] for a in apps])
    finally:
        await tv.close()

asyncio.run(main())

```

--------------------------------

### SamsungTVArt.__init__

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art.md

Constructs a SamsungTVArt instance to control Art Mode on a Frame TV. Parameters are identical to SamsungTVWS.

```APIDOC
## SamsungTVArt.__init__

### Description
Constructs a SamsungTVArt instance to control Art Mode on a Frame TV. Parameters are identical to SamsungTVWS.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    host,
    token=None,
    token_file=None,
    port=8001,
    timeout=None,
    key_press_delay=1,
    name="SamsungTvRemote",
):
```

### Parameters
- **host** (str) - Required - The IP address or hostname of the TV.
- **token** (str, optional) - Authentication token.
- **token_file** (str, optional) - Path to a file containing the token.
- **port** (int, optional) - Port number, default 8001.
- **timeout** (float, optional) - Timeout in seconds.
- **key_press_delay** (float, optional) - Delay between key presses, default 1.
- **name** (str, optional) - Name of the remote, default "SamsungTvRemote".

### Example
```python
from samsungtvws import SamsungTVWS

tv = SamsungTVWS("192.168.1.50")
art = tv.art()  # direct: SamsungTVArt("192.168.1.50")
```
```

--------------------------------

### CSS styles for mouse example page

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/example/mouse_example/mouse-example.html

CSS styles for the mouse example page, defining the track pad, draggable ball, and enter button appearance. Uses CSS variables for the ball diameter and radial gradients for the ball's look.

```css
:root { --ball-diameter: 50px; } .container { position: relative; left: calc(50% - 200px); top: calc(50% - 200px); width: 400px; height: 400px; text-align: center; vertical-align: middle; font-family: consolas; } #msgbox { margin: auto; } .track-pad { position: relative; height: 90%; width: 90%; left: 5%; top: 5%; border-radius: calc(var(--ball-diameter) / 2); background: lightgrey; -moz-box-shadow: inset 0 0 10px #000000; -webkit-box-shadow: inset 0 0 10px #000000; box-shadow: inset 0 0 10px #000000; } #ball { position: relative; top: calc(50% - var(--ball-diameter) / 2); left: calc(50% - var(--ball-diameter) / 2); width: var(--ball-diameter); height: var(--ball-diameter); border-radius: calc(var(--ball-diameter) / 2); background: black; background: radial-gradient(circle at 100px 100px, #fff, #000); cursor: grab; } #ball:active { background: radial-gradient(circle at 100px 100px, #0000ff, #000); } #enter { margin-top: 30px; position: relative; width: 300px; left: 50px; height: 50px; border-radius: 10px; border: 2px solid #4caf50; cursor: pointer; } #enter:hover { background-color: #4caf50; } #enter:active { background-color: #4caf50; box-shadow: inset 0 0 10px; } #enter div { position: relative; top: 15px; }
```

--------------------------------

### run_app(app_id, app_type, meta_tag)

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Launches an application on the TV via the WebSocket channel.

```APIDOC
## `run_app(app_id, app_type, meta_tag)`

### Description
Sends a `ChannelEmitCommand.launch_app` frame over the WebSocket `ms.channel.emit` channel to launch an app on the TV. The `action_type` is set verbatim to `app_type` (`DEEP_LINK` or `NATIVE_LAUNCH`). Returns `None`.

### Method
WebSocket (ms.channel.emit)

### Parameters
- **app_id** (str) - Required - The application ID to launch.
- **app_type** (str) - Optional - The launch type, either `DEEP_LINK` or `NATIVE_LAUNCH`. Defaults to `DEEP_LINK`.
- **meta_tag** (str) - Optional - Additional metadata for the launch. Defaults to empty string.

### Request Example
```python
from samsungtvws import SamsungTVWS

tv = SamsungTVWS("192.168.1.50")
tv.run_app("3201606009684")                      # Spotify (DEEP_LINK)
tv.run_app("org.tizen.browser", "NATIVE_LAUNCH", "https://example.com")
```

### Response
Returns `None`.
```

--------------------------------

### start_listening() method signature

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/connection.md

Method signature for start_listening(), which opens the connection and starts a daemon thread that routes frames to the callback.

```python
def start_listening(
    self, callback: Callable[[str, Any], None] | None = None
) -> None:
```

--------------------------------

### SamsungTVAsyncRest.__init__

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-rest.md

Initializes the asynchronous REST client with the TV host, a shared aiohttp session, and optional port and timeout settings.

```APIDOC
## SamsungTVAsyncRest.__init__

### Description
Initializes the SamsungTVAsyncRest client. Requires a caller-provided aiohttp.ClientSession (keyword-only). All requests are made with ssl=False.

### Method
Constructor

### Endpoint
N/A

### Parameters
- **host** (str) - Required - TV IP/hostname
- **session** (aiohttp.ClientSession) - Required (keyword-only) - Shared session; the class does not close it
- **port** (int) - Optional - Default: 8001 (8001 = HTTP, 8002 = HTTPS)
- **timeout** (float | None) - Optional - Default: None - Applied per request via aiohttp.ClientTimeout; 0 → None

### Request Example
```python
rest = SamsungTVAsyncRest("192.168.1.50", session=session, port=8002)
```

### Response
#### Success Response
None (constructor)

#### Response Example
N/A
```

--------------------------------

### get_artmode()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art.md

Gets the current art mode status from the TV.

```APIDOC
## get_artmode()

### Description
Retrieves the current art mode status. Internally calls `_get_value('get_artmode_status', key='value')`.

### Method
Call

### Parameters
None

### Returns
The current art mode value.

### Example
```python
mode = art.get_artmode()
print("art mode:", mode)
```
```

--------------------------------

### rest_device_info()

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Gets device information via the REST API.

```APIDOC
## `rest_device_info()`

### Description
Retrieves device information (name, model, features) via the REST API. Delegates to `SamsungTVRest.rest_device_info()`.

### Method
GET

### Endpoint
`/api/v2/`

### Parameters
None.

### Request Example
```python
info = tv.rest_device_info()
print(info.get("device", {}).get("modelName"))
```

### Response
Returns a dictionary with device information.
```

--------------------------------

### Using SamsungTVShortcuts via SamsungTVWS

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/shortcuts.md

Shows how to obtain a SamsungTVShortcuts instance via SamsungTVWS.shortcuts() and call a convenience method like power().

```python
from samsungtvws import SamsungTVWS

tv = SamsungTVWS("192.168.1.50")
sc = tv.shortcuts()          # same as SamsungTVShortcuts(tv)
sc.power()
```

--------------------------------

### REST passthrough usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/remote-apps.md

Shows how to use rest_device_info, rest_app_run, rest_app_status, and rest_app_close. These methods perform HTTP requests to the TV's REST API.

```python
info = tv.rest_device_info()
print(info.get("device", {}).get("modelName"))

tv.rest_app_run("3201606009684")
status = tv.rest_app_status("3201606009684")
tv.rest_app_close("3201606009684")
```

--------------------------------

### select_image usage example

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/art-media.md

Calls art.select_image with a content_id, category, and show=True.

```python
art.select_image("MY_F0001", category="MY-C0004", show=True)
```

--------------------------------

### Complete async flow with SamsungTVWSAsyncRemote and SendRemoteKey

Source: https://github.com/xchwarze/samsung-tv-ws-api/blob/master/_autodocs/api-reference/async-remote.md

Complete async flow: create SamsungTVWSAsyncRemote with a token file, start listening, send a remote key command (KEY_POWER) using SendRemoteKey.click, wait 15 seconds, then close.

```python
import asyncio
from samsungtvws.async_remote import SamsungTVWSAsyncRemote
from samsungtvws.remote import SendRemoteKey

async def main():
    tv = SamsungTVWSAsyncRemote(host="192.168.1.50", port=8002, token_file="token_file")
    await tv.start_listening()
    await tv.send_command(SendRemoteKey.click("KEY_POWER"))
    await asyncio.sleep(15)
    await tv.close()

asyncio.run(main())

```
Tokens:
Raw