Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

aiolibresync

An asyncio client for audio hubs built on the Libre Wireless LibreSync platform, such as the Platin Stereo Hub. It controls them over the local network, with no vendor app and no cloud.

The same hardware and protocol are sold under at least a dozen brands, including Platin, Buchardt, System Audio, Econik and Triangle. See docs/devices.md for the list and how confident each entry is.

  • Pure Python, no runtime dependencies, fully typed.
  • Push-driven: the hub announces volume, source, transport and metadata as they change, and a slow poll covers the two properties nothing announces.
  • Discovery over SSDP, plus a probe for an address you already know.
  • Written against the Home Assistant integration quality scale, but it does not depend on Home Assistant.

Status

Alpha. Everything the library sends has been sent to a real hub and its effect observed, on a Platin Stereo Hub running firmware 1.52. Other brands and firmware versions have not been tested yet, and reports from owners are very welcome. diagnostics() produces a redacted dump designed for exactly that.

Install

pip install aiolibresync

Python 3.12 or later.

Finding a hub

from aiolibresync import async_discover, async_probe

for device in await async_discover():
    print(device.host, device.udn, device.name)

device = await async_probe("192.168.1.50")  # an address you already have

async_discover() sends an SSDP search, fetches the device description from whatever answers, and confirms that the control port is open. The probe sends nothing to the control port: it only opens a TCP connection.

Two stable identifiers are available. The factory serial (await async_read_serial(host), or state.serial on a connected client) does not depend on the UPnP daemon and is the one to prefer. The UDN (device.udn) is what discovery sees. Either can be None: a unit may lack a valid factory serial, and the UDN is served by a UPnP daemon that occasionally stops on its own until the hub is power-cycled. See docs/devices.md.

await async_query_lssdp(host) asks the hub on Libre's own discovery port, UDP 1800, and returns an LssdpInfo whose module is LS9 on the original Stereo Hub and LS10 on the newer hubs (Stereo Hub HT, Surround Hub). An LS10 hub's port 7777 does not accept a plaintext session, so use the module to choose media=False or media_ssl before connecting (see The newer hubs). None means the hub did not answer, not that it is an original one.

Controlling it

import asyncio
from aiolibresync import DeviceState, LibreSyncClient

async def main() -> None:
    client = LibreSyncClient("192.168.1.50")

    def on_state(state: DeviceState) -> None:
        print(state)

    client.subscribe(on_state)
    await client.async_connect(timeout=10)
    await client.async_set_volume(30)
    await asyncio.sleep(60)
    await client.async_disconnect()

asyncio.run(main())

With a timeout, async_connect() returns once both ports are open, and raises NotConnectedError if they are not in time, after disconnecting again so that nothing is left running. Without one it returns as soon as the two sockets have been scheduled, so a command issued on the next line raises NotConnectedError. Either way state.available becomes false on any disconnection and true again when the client has reconnected on its own, so treat it as a condition that can change at any time.

Method What it does
async_set_power(on) reads the power state first and toggles only if needed, because the device has no discrete on or off
async_select_source(index) selects a source by the device's own index, from state.sources
async_set_volume(level) 0–100
async_media_play(), _pause(), _stop(), _next_track(), _previous_track() transport, for the streaming renderer
async_set_room_correction(enabled), async_set_manual_eq(enabled) the two DSP switches
async_select_eq_preset(preset) 1–3, the presets built in the vendor's app
async_refresh() re-reads everything
subscribe(callback) called with a new DeviceState on every change; returns an unsubscribe function
diagnostics() a redacted snapshot with frame counters and any unrecognised frames

Every command waits for the device to confirm the new state and raises ConfirmationTimeout if it does not.

The newer hubs

On the Surround Hub, port 7777 is wrapped in mutual TLS. The Stereo Hub HT is built on the same module (LS10, see async_query_lssdp) and resets a plaintext registration the same way, so it very likely is too, but nobody has run a handshake against one yet. Either pass media=False to use port 50006 alone, or pass media_ssl, an ssl.SSLContext carrying a client certificate the hub accepts, and the client works as it does on the original hub. The library bundles no certificate, reads no file and builds no context. Loading a certificate with load_cert_chain is blocking I/O, so in Home Assistant build the context in the executor. See docs/protocol-media.md.

Things that will surprise you

Power is not power. Switching the hub off is a stop: it ends the playback session. Switching it back on restores nothing and only allows playback again. When playback starts on a hub that is off, power-on arrives last, as a consequence of the session starting. The hub answers on both ports while "off". Keep available and power apart.

There is no mute you can set. The device accepts a mute write, reports the new value back, and leaves the audio alone. state.muted reflects mute set from the remote or the vendor's app, but the library offers no way to set it. See docs/protocol-media.md.

Read state.playback, not state.play_state. The hub reports playback twice. play_state is the streaming renderer's transport, and it says PLAYING on any physical input whether or not anything is connected. audio_state says whether sound is actually coming out. playback gives you the one to believe.

Room correction is never announced. It is polled, so a change made in the vendor's app shows up within one poll interval (POLL_INTERVAL, 30 s).

Preset 0 is the vendor app's EQ editor. While someone has the editor open, state.eq_preset is 0. It is a legitimate state, not an error.

Documentation

docs/devices.md what the device is, which brands share it, how a hub is found and identified
docs/protocol-system-control.md port 50006: framing, events, power, what must be polled
docs/protocol-media.md port 7777: the LUCI media session, message boxes, metadata
docs/commands.md every known frame on both ports, with how firmly each is known

Everything here was established by observing a real hub. Each frame in the reference is labelled with how it is known, from sent-and-observed down to inferred.

Development

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy

The tests run the codec against real traffic captured from a hub, with personal data replaced (see tests/fixtures/README.md), and the client against a fake hub that speaks both ports.

Independent reverse engineering, for interoperability. Not affiliated with Platin, Hansong, or Libre Wireless Technologies. LibreSync is a trademark of Libre Wireless Technologies, Inc. MIT licensed.

Metadata

Release files for aiolibresync 0.6.0b4

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

Source distribution (sdist)

Source distribution for aiolibresync 0.6.0b4
File Size Uploaded Provenance Actions
aiolibresync-0.6.0b4.tar.gz 123.5 kB With provenance Details for aiolibresync-0.6.0b4.tar.gz

Built distribution (wheel)

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

Total release size: 171.0 kB

Release files / aiolibresync-0.6.0b4.tar.gz

Download URL aiolibresync-0.6.0b4.tar.gz
Size 123.5 kB
Tags Source
SHA-256 checksum
How to use checksums
dfe6fe928b121cf2e74a46c6f40ffbd87182d678bc678f7511fc538e2dace570
BLAKE2b-256 checksum
How to use checksums
a38b4331a9bec0beef6e4eb8735876ab776e9584a96f1c3a3e50526ae73d17e3
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 13, 2026.

Transparency log

Release files / aiolibresync-0.6.0b4-py3-none-any.whl

Download URL aiolibresync-0.6.0b4-py3-none-any.whl
Size 47.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ab5a2ec67e7780ba20cf6c26ea3373abc1f668edd6c294c98a3b124f3f65d696
BLAKE2b-256 checksum
How to use checksums
f04d4fe767aaf3c796eb58aabff289cd64cb168305fef5fa49a6e7aefecba44e
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 13, 2026.

Transparency log

Security for aiolibresync 0.6.0b4

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 aiolibresync-0.6.0b4.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 13, 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.

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