AsyncWebOSTV

An asynchronous Python client for LG webOS TVs — control, real-time events, discovery, and secure connections, all on asyncio. It's a modern async port of the popular pywebostv library.

Python 3.11+ · MIT · typed (py.typed)

Highlights

• One object, batteries included. WebOSTV connects, pairs, and hands you six ready-to-use controls (tv.media, tv.system, tv.input, …) — and cleans them all up on close().
• Events, not polling. Subscribe to volume, power state, channel, foreground app, and audio routing; the TV pushes changes to an async callback.
• The whole remote. A Magic-Remote-style pointer, every named button, text entry, and a read of the current HDMI input — over webOS's dedicated pointer socket, managed for you.
• Secure by pinning. wss:// with the TV's self-signed certificate pinned as the trust anchor, plus helpers to extract and verify it.
• Finds its own TVs. SSDP discovery returns ready-to-use clients for every LG TV on the subnet.
• Typed end to end. Ships py.typed and generated stubs for the runtime-built control methods, so consumers get real autocomplete and type-checking.

Install

pip install asyncwebostv

Quick taste

import asyncio
from asyncwebostv import WebOSTV

async def main():
    tv = WebOSTV("192.168.1.100", client_key="your-saved-key")
    async with tv:                                  # connects, registers, builds controls
        await tv.system.notify("Hello from AsyncWebOSTV!")
        await tv.media.volume_up()

        async def on_volume(success, payload):
            if success:
                print("Volume:", payload["volume"], "muted:", payload["muted"])

        await tv.media.subscribe_get_volume(on_volume)
        await asyncio.sleep(30)                      # live volume events

asyncio.run(main())

First run? You won't have a client_key yet — drop it from the constructor, call await tv.connect(), accept the prompt on the TV, and save tv.client_key for next time. The Quickstart walks through it.

Documentation

• Architecture overview — the layers, the one import rule, and the connection lifecycle.
• Quickstart — install, pair, and send your first commands.
• Controls — the full command surface across the six control classes.
• Subscriptions — the six real-time events, their payloads, and the reconnect contract.
• Input control — the pointer, the buttons, text entry, and reading the current input.
• Secure connections — certificates and verified wss://.
• Discovery — finding TVs on the network.
• Pointer protocol — the wire-level reference for the input socket.

Development

git clone https://github.com/droman42/asyncwebostv.git
cd asyncwebostv
pip install -e ".[dev]"
pytest

Three CI-enforced health gates (import layering, no TYPE_CHECKING guards, and pyright at zero errors) guard every commit — see Contributing for how to run them locally and how the typed control stubs are regenerated.

Acknowledgements

• The original pywebostv library, for the protocol groundwork and inspiration.
• aiowebostv and the Home Assistant LG community, whose hardware findings informed several webOS-quirk fixes.
• LG, for the webOS platform.

License

MIT — see LICENSE.