PyLoxone-Audio 0.1.0__tar.gz

pyloxone_audio-0.1.0/API.md

@@ -0,0 +1,86 @@
+# PyLoxone-Audio 0.1.0 — local release candidate
+
+A separately installable Apache-2.0 Python library containing the concrete native
+audio implementation used by one existing PyLoxone integration. This is not a
+second integration, new login, facade-only prototype, published index version or
+claim of upstream automatic adoption. See NOTICE.md for attribution/provenance.
+
+## Concrete public API and ownership
+
+The explicit exports in pyloxone_audio/__init__.py are the public API:
+
+- AudioServerCommands(host, current_credentials) owns bounded native command
+  authentication, correlation, cancellation, close and uncertain-write fences.
+  The callback supplies the current username/token; there is no token persistence.
+- AudioServerListener and AudioEventReceiver receive/parse exact-player metadata;
+  AudioZoneMetadata is the neutral snapshot. AudioMetadataCoordinator supports
+  exact-player subscriptions, optional host task scheduling, start and awaited stop.
+- AudioCatalogue(commands, player_id), CatalogueTarget, ConfiguredSource and
+  AudioFavourite own discovery, opaque browser targets, last-good source history,
+  configured favourites, provider/account qualification and neutral search values.
+- MediaNode, SearchResult and MediaKind contain no HA entity or UI dependency.
+- async_select_catalogue, async_select_favourite, async_select_radio_station and
+  async_native_catalogue_noop own source dispatch, settlement and fresh exact-room
+  provider feedback. Browser selection remains strict exact-item proof. Source
+  return does not require matching an obsolete historical track, and may attempt
+  at most one optional best-effort position restore. Optional failure does not
+  undo confirmed playback; a fixed warning is emitted, never exception payloads.
+- async_source_route and async_optional_native_resume own native/retained routing
+  and safety decisions; NativeResumeOutcome, SourceRoute and
+  SourceContentRequiredError describe their outcomes. Hosts provide lifecycle/
+  newest-request liveness callbacks, snapshot bootstrap and their existing optional
+  linked-session bridge. UNAVAILABLE is not permission to ignore changed native
+  identity or uncertain writes. No blind fallback, replay or retry is introduced.
+- manual_seek_supported, manual_seek_position, native_track_identity,
+  ManualSeekQualification and async_seek_track retain strict current-track/manual
+  seek capability, account/identity, echo and observed-progress qualification.
+- passive_history_eligible and confirmed_library_session own reusable native
+  history eligibility. Genuine ordered observed feedback is distinct from intent.
+- SpotifySessionBridge, SpotifyNativeSession, NativeSessionUnavailableError and
+  async_resume_native_session consume the host's optional existing read-only
+  linked Spotify session. Spotify owns session/queue; no queue reconstruction or
+  abandoned explicit HA Spotify handover feature is added.
+- async_send_prepared_announcement handles prepared bounded WAV bytes through
+  the native event operation; the host supplies an existing lazy HTTP session.
+- audioserver_uri and parse_audio_events retain their concrete native semantics.
+
+SourceEnvironment(clock=callable) is immutable per-consumer clock configuration.
+Pass environment= to source/seek/routing/Spotify functions when injecting a clock.
+The callable must return aware UTC datetimes in the metadata.received_at domain.
+The default is the library's aware UTC clock, not HA or another consumer's state.
+Its async_observed_change method executes the concrete native settlement algorithm;
+asyncio deadlines remain monotonic. No process-wide clock replacement is required.
+
+The host retains HA setup/entities/registries/services, newest-request tasks and
+unload cancellation, account locks/OAuth storage, error translation, artwork and
+HA media/TTS preparation. It must keep liveness checks valid across awaits, drain
+owned tasks before teardown and close commands before metadata/token owners.
+ManualSeekQualification must be checked against actual current native metadata
+and the host revision/duration, not merely a cached UI value. Optional native
+completion requires settled dispatch and fresh exact-room/provider/account proof.
+
+## Development tracing excluded
+
+There is no shipped diagnostics module, SourceDiagnostics, snapshot/collector
+API, source-stage logger, trace decorator, last_source_failure attribute or
+compatibility no-op. Those pre-release development-only interfaces are intentionally
+removed before this first 0.1.0 cutoff. Functional native dispatch callbacks,
+source/announcement fences, clocks and cancellation remain. Ordinary fixed
+warning/error logs and actual exception propagation/HA translation remain.
+
+## Tested boundary and installation
+
+Only the canonical Python 3.14.7 / HA 2026.9.1 / websockets 15.0.1 /
+pycryptodome 4.0.1 / aiohttp 3.14.3 environment is exercised here. The metadata
+requires Python >=3.14 but is not a wider tested compatibility promise. HA-free
+portable runs explicitly reject HA imports. External I/O in tests is synthetic;
+AF_UNIX wire tests use actual websocket/crypto implementations with TCP blocked.
+No all-version/firmware/room, physical playback or adapter hardware claim follows.
+
+For offline local installation use the supplied exact wheel with --no-index,
+--find-links pointing to its local assets directory, and PyLoxone-Audio==0.1.0.
+The supplied host manifest pins exactly that version, retaining integration domain
+loxone, name PyLoxone and integration version 0.10.2. Existing dependencies must
+already be available, or be provided independently offline; --no-deps validates
+artifact identity only, not public dependency resolution. No PyPI lookup,
+publication, namespace reservation, HA deployment or upstream uptake is implied.

pyloxone_audio-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pyloxone_audio-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+# Keep complete integration previews out of Python source distributions.
+prune preview-build
+prune checks
+prune adapters
+prune tools
+prune tests/adapter
+include API.md
+include NOTICE.md
+include LICENSE
+include README.md
+include SPOTIFY.md
+prune tests/release
+recursive-include tests/library *.py *.ini *.json *.txt *.md

pyloxone_audio-0.1.0/NOTICE.md

@@ -0,0 +1,15 @@
+# Provenance and licence — concrete offline extraction
+
+This local 0.1.0 release candidate is supplied under Apache-2.0. `LICENSE` is copied verbatim from the local PyLoxone repository's Apache License, Version 2.0 file. No package has been published or registered. The library's 0.1.0 metadata and exact local host dependency are not a public index release or installed production change.
+
+The HA entry ownership, exact-player mapping, current-token callback and entity-property delegation are adapted from the PyLoxone integration maintained by JoDehli and its contributors, specifically the sealed `media_player.py`, `audio.py` and `coordinator.py` call graph. Those inspected source files contain no additional per-file copyright notices to remove or replace. This draft does not assign invented upstream copyright ownership.
+
+The original native protocol source retains this attribution, which must accompany any future adaptation of its event mapping:
+
+> Event names adapted from SebastianEitzert's Apache-2.0 POC in #523, comment 6251138699. See tests/fixtures/audioserver/README.md for provenance.
+
+The actual parser/event mapping is now extracted into `pyloxone_audio/native.py`, retaining that attribution. Native transport/authentication, metadata coordination, source policy, radio and catalogue implementations are derived from the immutable accepted source tree identified by `baseline-verification.json` and the extraction provenance receipts. Native announcement ownership and the native read-only-bridge Spotify session selection are also extracted; HA preparation, provider session storage and UI responsibilities stay with the host. Relevant upstream attribution and Apache-2.0 terms are retained; no invented copyright assignment is made.
+
+Historical fake-facade, extraction and operational evidence remains outside release assets. The concrete package exports real native classes and source-policy functions instead. Synthetic fixture provenance is preserved under `tests/library/fixtures/audioserver/README.md` outside the wheel. The older path in the attribution quoted above is historical; the current location applies to this repository and its source archive. Development-only detailed tracing and HA failure-summary publication are excluded from both library and adapter at this cutoff.
+
+Dave directed requirements, behaviour decisions and normal-use validation. Implementation and offline testing were AI-assisted through Hermes with OpenAI primary models; release-cutoff implementation uses gpt-6.1-sol and the independently recorded review uses an actual primary OpenAI invocation. AI assistance is provenance, not an invented human author, a transfer of upstream ownership, hardware certification or a guarantee of defect freedom. Independent review identity and limitations are recorded in release-level evidence, not claimed as a substitute for tests.

pyloxone_audio-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: PyLoxone-Audio
+Version: 0.1.0
+Summary: Native audio transport and source policies for PyLoxone
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/davehocking/PyLoxone-Audio
+Project-URL: Repository, https://github.com/davehocking/PyLoxone-Audio
+Project-URL: Issues, https://github.com/davehocking/PyLoxone-Audio/issues
+Project-URL: Releases, https://github.com/davehocking/PyLoxone-Audio/releases
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: websockets<16,>=14
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: aiohttp
+Dynamic: license-file
+
+# PyLoxone-Audio
+
+A Python library for extending [PyLoxone](https://github.com/JoDehli/PyLoxone) capabilities on the Loxone Audio Server.
+
+PyLoxone-Audio is a separately maintained, testable audio library used through a companion PyLoxone adapter. Home Assistant retains **one integration, one setup and the existing room entities**.
+
+## Version 0.1.0
+
+The 0.1.0 scope covers Audio Server communication, now-playing metadata, playback and source-return behaviour, together with the PyLoxone adapter and tests for both.
+
+Package availability and release-specific compatibility information belong on the [Releases page](https://github.com/davehocking/PyLoxone-Audio/releases). The library version is separate from the PyLoxone integration version; publishing a library package does not itself add support to an upstream PyLoxone release.
+
+## Why a separate library?
+
+Audio communication and playback behaviour are developed and tested independently of Home Assistant-specific configuration and entities. Keeping that work in a library gives it its own tests and releases, while the adapter tests cover its use within PyLoxone. PyLoxone still needs host-side review and compatibility testing when it adopts an adapter or dependency update.
+
+PyLoxone is the main consumer, but the library remains Home Assistant-independent so other Python applications can use it.
+
+This project complements PyLoxone; it is not a replacement for PyLoxone, Home Assistant or Loxone's own applications.
+
+## Architecture and responsibilities
+
+```text
+Home Assistant
+  └─ PyLoxone: configuration, entities and Home Assistant services
+       └─ Audio adapter: translates between the integration and library
+            └─ PyLoxone-Audio: native audio communication and playback state
+```
+
+**The library** handles audio communication, now-playing and source metadata, playback/source operations, source-return behaviour, and its own connection lifecycle, events and errors. It does not import Home Assistant.
+
+**The PyLoxone adapter** connects the library to the existing integration's configuration, room/player mapping, entities, services, availability and setup/unload lifecycle. It supplies existing authenticated access rather than introducing a second user setup. Non-audio PyLoxone functionality remains the responsibility of PyLoxone.
+
+The adapter is maintained alongside the library in this repository under `adapters/pyloxone/`. It is applied within PyLoxone, not installed as a separate Home Assistant integration. The adapter documentation identifies its supported host base and the matching library version.
+
+The current reference adapter targets released PyLoxone **0.10.2**, exact public commit `3db77b81f69c77cc814675d191061533b464df5e`, with library **0.1.0**. The maintained `preview-build/` directory supplies a complete pinned integration ZIP, provenance/checksums, repeatable build/verification and install/update/rollback/native-UI test instructions. Its focused `adapters/pyloxone/jo-review/` pack is for upstream review; no upstream adoption is claimed.
+
+The adapter uses the library's public interface. Ordinary internal library bug fixes should not require structural adapter changes. New capabilities or intentional breaking API changes may still need coordinated updates.
+
+Home Assistant uses standard media-player entities and controls: **no patched Home Assistant Core or frontend, injected JavaScript/CSS, or project-specific custom card**.
+
+## Audio behaviour
+
+Version 0.1.0 focuses on Loxone Audio Server-backed rooms. Supported sources are **Local Library, Loxone Radio, Spotify, TuneIn and Line-In**, where available and configured in Loxone. Not every installation has every source or subscription. SoundSuit is outside the 0.1.0 scope.
+
+Line-In appears last in the available-source list. Home Assistant's mobile source selector can require scrolling; placing Line-In last keeps the more frequently used sources easier to reach.
+
+The main playback principles are:
+
+- **Confirm the requested source.** A successful native command is followed by fresh now-playing feedback from the correct room identifying the requested source.
+- **Respect the active provider.** Spotify keeps ownership of its live session and queue. Returning to a source does not always mean returning to the exact previously played track. Ordinary Spotify transfer uses Spotify Connect.
+- **Remember useful last-good state.** Local Library returns to the remembered track where available. Failed or unconfirmed attempts do not erase the last qualified source history.
+- **Treat position restoration as an extra.** Where applicable, make at most one bounded best-effort attempt to restore a remembered position. Exact-position proof is not required, and failure of that optional step does not turn confirmed source playback into an error.
+- **Avoid surprise playback.** No blind retries, replay or substitute content when an operation cannot be confirmed. Superseded Home Assistant requests and integration unload are handled cleanly.
+
+## Is Home Assistant's Spotify integration required?
+
+**No. Spotify configured in Loxone and Home Assistant's separate Spotify integration are different things.** The library does not depend on Home Assistant, and the PyLoxone adapter does not require HA's Spotify integration to load.
+
+- **Without HA Spotify:** native room controls, now-playing information, source selection and Loxone-backed Browse/Search remain available where configured and supported. That includes Spotify configured in Loxone. Spotify return uses the current native session or qualified remembered content where available; an empty source with no usable session/history needs a selection in Browse or Spotify Connect, not an invented replacement track. Supported native seeking and best-effort position restoration do not require HA Spotify.
+- **With HA Spotify and an explicit room/account/device binding:** the adapter can check the authenticated Spotify user and current receiver, then ask **Loxone** to resume that account's existing Spotify session. This can use the live session rather than restarting a remembered track. **It does not seek back to a saved playback position: position remains Spotify's responsibility.** Installing HA Spotify alone does not configure that binding.
+- **What this enhancement does not do:** it does not rebuild Spotify's queue, restore a playlist or exact position through Spotify's API, transfer playback from another receiver, or supply Spotify Browse/Search or now-playing metadata. Those are not reasons to install HA Spotify for this project.
+- **When the optional evidence is unavailable:** missing/unloaded HA Spotify, unreadable state or no reported session do not by themselves block a valid native return, and do not produce missing-integration warnings. Positive evidence of another account/receiver is a conflict, not permission to silently fall back and take over playback. Ordinary errors and newer-request/lifecycle cancellation still apply.
+
+See [Spotify support and the exact function/API map](https://github.com/davehocking/PyLoxone-Audio/blob/v0.1.0/SPOTIFY.md) for setup fields, active versus retained legacy methods, concrete fallback cases and test coverage.
+
+## Repository layout
+
+The 0.1.0 source tree separates the portable library from its Home Assistant adapter:
+
+```text
+pyloxone_audio/       Home Assistant-independent library
+adapters/pyloxone/    PyLoxone adapter, host-base information and instructions
+preview-build/       Complete pinned integration preview and tester instructions
+tests/library/       Portable library tests
+tests/adapter/       Audio-adapter and library/host contract tests
+```
+
+This repository contains tests for this project and its adapter, not a copy of the full PyLoxone test suite. General PyLoxone connection, authentication, sensor and other non-audio tests belong to the host project and are excluded here. Broader host regression runs are separate compatibility checks, not part of this library's published test suite.
+
+The Python package contains the portable library. The adapter stays separate from that package so installing the library does not install Home Assistant integration files.
+
+## Installation and releases
+
+**For Home Assistant users:** use a PyLoxone build that includes the matching audio adapter. Its manifest pins a tested library version, and Home Assistant installs that dependency automatically. The normal installation unit is PyLoxone; a separate integration or manual `pip` step is not required for a released, compatible pair. The presence of the adapter in this repository does not mean an upstream PyLoxone release already includes it.
+
+The maintained preview targets **PyLoxone 0.10.2 with PyLoxone-Audio 0.1.0**. Before installing it, verify that the exact library version is listed on [PyPI](https://pypi.org/project/PyLoxone-Audio/0.1.0/) and check the matching [release](https://github.com/davehocking/PyLoxone-Audio/releases). A source checkout or preview ZIP alone is not proof of publication. The preview is excluded from both Python wheel and sdist, but retained in the library repository. Its provenance records offline bundle validation; public dependency availability is a separate release check. No upstream adoption or universal hardware/HAOS compatibility is claimed.
+
+**For Python developers:** the library is packaged as a versioned wheel and source distribution, independently of the Home Assistant adapter. Use the artifacts and compatibility information for the selected release. Installing the Python library alone does not add an integration to Home Assistant.
+
+A new library release does **not** automatically update existing PyLoxone installations. Adoption happens when a PyLoxone release selects a tested compatible version, which need *not* be the newest published version. Breaking interface changes need explicit compatibility notes and coordinated adapter updates.
+
+## Testing and compatibility
+
+The project has two test groups:
+
+- **Library tests** cover metadata parsing, playback/source policy, state and timing, communication errors, delayed events, disconnects and cancellation. They run without importing Home Assistant.
+- **Adapter tests** exercise the audio library within the owning PyLoxone/Home Assistant paths, including room mapping, native entity behaviour, setup/unload, source selection and the library/adapter contract.
+
+Automated tests use sanitised fixtures and synthetic transports rather than controlling a household's devices. Real-device checks supplement those tests; passing offline tests is not proof of every device, firmware or audible playback outcome.
+
+Compatibility claims apply to the Python, Home Assistant, PyLoxone and device/firmware versions actually tested. No universal device or legacy Music Server compatibility is claimed.
+
+Detailed development tracing, private rolling captures and household-specific tooling are excluded from the library and adapter deliverables. Ordinary useful runtime warnings and errors remain.
+
+## Contributing
+
+Focused issues, reproducible reports and sanitised test contributions are welcome. Include relevant software/device versions and the expected versus observed behaviour. Keep library tests independent of Home Assistant and adapter tests focused on audio integration behaviour; general PyLoxone tests belong with PyLoxone.
+
+**Do not post passwords, tokens, credentials or unredacted device exports.** Remove household-specific information from logs and fixtures before sharing them.
+
+## Acknowledgements and licence
+
+This independent project builds on work from [PyLoxone](https://github.com/JoDehli/PyLoxone) and its contributors. It does not imply official affiliation with Loxone or upstream approval of unreleased changes.
+
+Thanks also to [Sebastian (@SebastianEitzert)](https://github.com/SebastianEitzert) for his contributions to this project.
+
+Development is human-directed, with LLM assistance for drafting and implementation under supervisory review.
+
+Licensed under the [Apache License 2.0](LICENSE), matching PyLoxone. Relevant upstream copyright, attribution and notice requirements are retained when code is reused.

pyloxone_audio-0.1.0/PyLoxone_Audio.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: PyLoxone-Audio
+Version: 0.1.0
+Summary: Native audio transport and source policies for PyLoxone
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/davehocking/PyLoxone-Audio
+Project-URL: Repository, https://github.com/davehocking/PyLoxone-Audio
+Project-URL: Issues, https://github.com/davehocking/PyLoxone-Audio/issues
+Project-URL: Releases, https://github.com/davehocking/PyLoxone-Audio/releases
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE.md
+Requires-Dist: websockets<16,>=14
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: aiohttp
+Dynamic: license-file
+
+# PyLoxone-Audio
+
+A Python library for extending [PyLoxone](https://github.com/JoDehli/PyLoxone) capabilities on the Loxone Audio Server.
+
+PyLoxone-Audio is a separately maintained, testable audio library used through a companion PyLoxone adapter. Home Assistant retains **one integration, one setup and the existing room entities**.
+
+## Version 0.1.0
+
+The 0.1.0 scope covers Audio Server communication, now-playing metadata, playback and source-return behaviour, together with the PyLoxone adapter and tests for both.
+
+Package availability and release-specific compatibility information belong on the [Releases page](https://github.com/davehocking/PyLoxone-Audio/releases). The library version is separate from the PyLoxone integration version; publishing a library package does not itself add support to an upstream PyLoxone release.
+
+## Why a separate library?
+
+Audio communication and playback behaviour are developed and tested independently of Home Assistant-specific configuration and entities. Keeping that work in a library gives it its own tests and releases, while the adapter tests cover its use within PyLoxone. PyLoxone still needs host-side review and compatibility testing when it adopts an adapter or dependency update.
+
+PyLoxone is the main consumer, but the library remains Home Assistant-independent so other Python applications can use it.
+
+This project complements PyLoxone; it is not a replacement for PyLoxone, Home Assistant or Loxone's own applications.
+
+## Architecture and responsibilities
+
+```text
+Home Assistant
+  └─ PyLoxone: configuration, entities and Home Assistant services
+       └─ Audio adapter: translates between the integration and library
+            └─ PyLoxone-Audio: native audio communication and playback state
+```
+
+**The library** handles audio communication, now-playing and source metadata, playback/source operations, source-return behaviour, and its own connection lifecycle, events and errors. It does not import Home Assistant.
+
+**The PyLoxone adapter** connects the library to the existing integration's configuration, room/player mapping, entities, services, availability and setup/unload lifecycle. It supplies existing authenticated access rather than introducing a second user setup. Non-audio PyLoxone functionality remains the responsibility of PyLoxone.
+
+The adapter is maintained alongside the library in this repository under `adapters/pyloxone/`. It is applied within PyLoxone, not installed as a separate Home Assistant integration. The adapter documentation identifies its supported host base and the matching library version.
+
+The current reference adapter targets released PyLoxone **0.10.2**, exact public commit `3db77b81f69c77cc814675d191061533b464df5e`, with library **0.1.0**. The maintained `preview-build/` directory supplies a complete pinned integration ZIP, provenance/checksums, repeatable build/verification and install/update/rollback/native-UI test instructions. Its focused `adapters/pyloxone/jo-review/` pack is for upstream review; no upstream adoption is claimed.
+
+The adapter uses the library's public interface. Ordinary internal library bug fixes should not require structural adapter changes. New capabilities or intentional breaking API changes may still need coordinated updates.
+
+Home Assistant uses standard media-player entities and controls: **no patched Home Assistant Core or frontend, injected JavaScript/CSS, or project-specific custom card**.
+
+## Audio behaviour
+
+Version 0.1.0 focuses on Loxone Audio Server-backed rooms. Supported sources are **Local Library, Loxone Radio, Spotify, TuneIn and Line-In**, where available and configured in Loxone. Not every installation has every source or subscription. SoundSuit is outside the 0.1.0 scope.
+
+Line-In appears last in the available-source list. Home Assistant's mobile source selector can require scrolling; placing Line-In last keeps the more frequently used sources easier to reach.
+
+The main playback principles are:
+
+- **Confirm the requested source.** A successful native command is followed by fresh now-playing feedback from the correct room identifying the requested source.
+- **Respect the active provider.** Spotify keeps ownership of its live session and queue. Returning to a source does not always mean returning to the exact previously played track. Ordinary Spotify transfer uses Spotify Connect.
+- **Remember useful last-good state.** Local Library returns to the remembered track where available. Failed or unconfirmed attempts do not erase the last qualified source history.
+- **Treat position restoration as an extra.** Where applicable, make at most one bounded best-effort attempt to restore a remembered position. Exact-position proof is not required, and failure of that optional step does not turn confirmed source playback into an error.
+- **Avoid surprise playback.** No blind retries, replay or substitute content when an operation cannot be confirmed. Superseded Home Assistant requests and integration unload are handled cleanly.
+
+## Is Home Assistant's Spotify integration required?
+
+**No. Spotify configured in Loxone and Home Assistant's separate Spotify integration are different things.** The library does not depend on Home Assistant, and the PyLoxone adapter does not require HA's Spotify integration to load.
+
+- **Without HA Spotify:** native room controls, now-playing information, source selection and Loxone-backed Browse/Search remain available where configured and supported. That includes Spotify configured in Loxone. Spotify return uses the current native session or qualified remembered content where available; an empty source with no usable session/history needs a selection in Browse or Spotify Connect, not an invented replacement track. Supported native seeking and best-effort position restoration do not require HA Spotify.
+- **With HA Spotify and an explicit room/account/device binding:** the adapter can check the authenticated Spotify user and current receiver, then ask **Loxone** to resume that account's existing Spotify session. This can use the live session rather than restarting a remembered track. **It does not seek back to a saved playback position: position remains Spotify's responsibility.** Installing HA Spotify alone does not configure that binding.
+- **What this enhancement does not do:** it does not rebuild Spotify's queue, restore a playlist or exact position through Spotify's API, transfer playback from another receiver, or supply Spotify Browse/Search or now-playing metadata. Those are not reasons to install HA Spotify for this project.
+- **When the optional evidence is unavailable:** missing/unloaded HA Spotify, unreadable state or no reported session do not by themselves block a valid native return, and do not produce missing-integration warnings. Positive evidence of another account/receiver is a conflict, not permission to silently fall back and take over playback. Ordinary errors and newer-request/lifecycle cancellation still apply.
+
+See [Spotify support and the exact function/API map](https://github.com/davehocking/PyLoxone-Audio/blob/v0.1.0/SPOTIFY.md) for setup fields, active versus retained legacy methods, concrete fallback cases and test coverage.
+
+## Repository layout
+
+The 0.1.0 source tree separates the portable library from its Home Assistant adapter:
+
+```text
+pyloxone_audio/       Home Assistant-independent library
+adapters/pyloxone/    PyLoxone adapter, host-base information and instructions
+preview-build/       Complete pinned integration preview and tester instructions
+tests/library/       Portable library tests
+tests/adapter/       Audio-adapter and library/host contract tests
+```
+
+This repository contains tests for this project and its adapter, not a copy of the full PyLoxone test suite. General PyLoxone connection, authentication, sensor and other non-audio tests belong to the host project and are excluded here. Broader host regression runs are separate compatibility checks, not part of this library's published test suite.
+
+The Python package contains the portable library. The adapter stays separate from that package so installing the library does not install Home Assistant integration files.
+
+## Installation and releases
+
+**For Home Assistant users:** use a PyLoxone build that includes the matching audio adapter. Its manifest pins a tested library version, and Home Assistant installs that dependency automatically. The normal installation unit is PyLoxone; a separate integration or manual `pip` step is not required for a released, compatible pair. The presence of the adapter in this repository does not mean an upstream PyLoxone release already includes it.
+
+The maintained preview targets **PyLoxone 0.10.2 with PyLoxone-Audio 0.1.0**. Before installing it, verify that the exact library version is listed on [PyPI](https://pypi.org/project/PyLoxone-Audio/0.1.0/) and check the matching [release](https://github.com/davehocking/PyLoxone-Audio/releases). A source checkout or preview ZIP alone is not proof of publication. The preview is excluded from both Python wheel and sdist, but retained in the library repository. Its provenance records offline bundle validation; public dependency availability is a separate release check. No upstream adoption or universal hardware/HAOS compatibility is claimed.
+
+**For Python developers:** the library is packaged as a versioned wheel and source distribution, independently of the Home Assistant adapter. Use the artifacts and compatibility information for the selected release. Installing the Python library alone does not add an integration to Home Assistant.
+
+A new library release does **not** automatically update existing PyLoxone installations. Adoption happens when a PyLoxone release selects a tested compatible version, which need *not* be the newest published version. Breaking interface changes need explicit compatibility notes and coordinated adapter updates.
+
+## Testing and compatibility
+
+The project has two test groups:
+
+- **Library tests** cover metadata parsing, playback/source policy, state and timing, communication errors, delayed events, disconnects and cancellation. They run without importing Home Assistant.
+- **Adapter tests** exercise the audio library within the owning PyLoxone/Home Assistant paths, including room mapping, native entity behaviour, setup/unload, source selection and the library/adapter contract.
+
+Automated tests use sanitised fixtures and synthetic transports rather than controlling a household's devices. Real-device checks supplement those tests; passing offline tests is not proof of every device, firmware or audible playback outcome.
+
+Compatibility claims apply to the Python, Home Assistant, PyLoxone and device/firmware versions actually tested. No universal device or legacy Music Server compatibility is claimed.
+
+Detailed development tracing, private rolling captures and household-specific tooling are excluded from the library and adapter deliverables. Ordinary useful runtime warnings and errors remain.
+
+## Contributing
+
+Focused issues, reproducible reports and sanitised test contributions are welcome. Include relevant software/device versions and the expected versus observed behaviour. Keep library tests independent of Home Assistant and adapter tests focused on audio integration behaviour; general PyLoxone tests belong with PyLoxone.
+
+**Do not post passwords, tokens, credentials or unredacted device exports.** Remove household-specific information from logs and fixtures before sharing them.
+
+## Acknowledgements and licence
+
+This independent project builds on work from [PyLoxone](https://github.com/JoDehli/PyLoxone) and its contributors. It does not imply official affiliation with Loxone or upstream approval of unreleased changes.
+
+Thanks also to [Sebastian (@SebastianEitzert)](https://github.com/SebastianEitzert) for his contributions to this project.
+
+Development is human-directed, with LLM assistance for drafting and implementation under supervisory review.
+
+Licensed under the [Apache License 2.0](LICENSE), matching PyLoxone. Relevant upstream copyright, attribution and notice requirements are retained when code is reused.