python-amazon-echo 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- python_amazon_echo-0.1.0/.gitignore +12 -0
- python_amazon_echo-0.1.0/CHANGELOG.md +33 -0
- python_amazon_echo-0.1.0/LICENSE +21 -0
- python_amazon_echo-0.1.0/PKG-INFO +268 -0
- python_amazon_echo-0.1.0/README.md +244 -0
- python_amazon_echo-0.1.0/pyproject.toml +131 -0
- python_amazon_echo-0.1.0/src/amazon_echo/__init__.py +61 -0
- python_amazon_echo-0.1.0/src/amazon_echo/__main__.py +132 -0
- python_amazon_echo-0.1.0/src/amazon_echo/auth.py +404 -0
- python_amazon_echo-0.1.0/src/amazon_echo/client.py +1626 -0
- python_amazon_echo-0.1.0/src/amazon_echo/const.py +260 -0
- python_amazon_echo-0.1.0/src/amazon_echo/exceptions.py +37 -0
- python_amazon_echo-0.1.0/src/amazon_echo/local.py +94 -0
- python_amazon_echo-0.1.0/src/amazon_echo/models.py +165 -0
- python_amazon_echo-0.1.0/src/amazon_echo/push.py +298 -0
- python_amazon_echo-0.1.0/src/amazon_echo/py.typed +0 -0
- python_amazon_echo-0.1.0/tests/__init__.py +0 -0
- python_amazon_echo-0.1.0/tests/conftest.py +165 -0
- python_amazon_echo-0.1.0/tests/fixtures/automations.json +41 -0
- python_amazon_echo-0.1.0/tests/fixtures/devices.json +106 -0
- python_amazon_echo-0.1.0/tests/fixtures/graphql_endpoints.json +65 -0
- python_amazon_echo-0.1.0/tests/fixtures/history.json +36 -0
- python_amazon_echo-0.1.0/tests/fixtures/notifications.json +44 -0
- python_amazon_echo-0.1.0/tests/fixtures/np_player.json +11 -0
- python_amazon_echo-0.1.0/tests/test_auth.py +352 -0
- python_amazon_echo-0.1.0/tests/test_client.py +1557 -0
- python_amazon_echo-0.1.0/tests/test_local.py +100 -0
- python_amazon_echo-0.1.0/tests/test_models.py +68 -0
- python_amazon_echo-0.1.0/tests/test_push.py +365 -0
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [0.1.0] - 2026-11-15
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- `AmazonEchoClient`: cookie + `csrf` authentication, one cookie exchange and
|
|
12
|
+
retry on 401/403, back-off on 429/503, typed errors, `on_credentials_update`.
|
|
13
|
+
- Login without password storage: `build_authorize_url` + `register_device`
|
|
14
|
+
(external browser, PKCE) and `Credentials.from_alexa_media`.
|
|
15
|
+
- Inventory: account, devices merged with the GraphQL endpoints (MAC, model,
|
|
16
|
+
endpoint id), routines, music providers.
|
|
17
|
+
- Bulk state: do-not-disturb, volumes, Bluetooth, notifications, alarm volumes,
|
|
18
|
+
wake words, ascending alarms, GraphQL endpoint state (temperature,
|
|
19
|
+
reachability, Fire TV remote battery and ambient mode), now playing.
|
|
20
|
+
- Per-device settings: Wi-Fi, equalizer, earcons, AUX ports, alarm sounds,
|
|
21
|
+
default alarm sound, available wake words and any setting key.
|
|
22
|
+
- Account preferences: whisper mode, adaptive volume.
|
|
23
|
+
- Actions through the sequence API: volume, stop, speak, announce, text command,
|
|
24
|
+
sound, music, skill launch, routines; transport commands, Bluetooth
|
|
25
|
+
connect/disconnect, reboot.
|
|
26
|
+
- Alarms, timers and reminders: list, create, delete.
|
|
27
|
+
- Lists: shopping, to-do and custom lists with item create/update/delete.
|
|
28
|
+
- Voice history.
|
|
29
|
+
- `call_feature`: GraphQL `setEndpointFeatures` escape hatch.
|
|
30
|
+
- `PushClient`: HTTP/2 push stream with reconnect back-off; every event is
|
|
31
|
+
passed through.
|
|
32
|
+
- `probe_local` / `is_reachable`: LAN identification and liveness.
|
|
33
|
+
- `amazon-echo` command line interface.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Hudson Brendon
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,268 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: python-amazon-echo
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Async Python client for Amazon Echo / Alexa devices: state, settings, media, notifications, lists, HTTP/2 push and LAN discovery
|
|
5
|
+
Project-URL: Homepage, https://github.com/hudsonbrendon/python-amazon-echo
|
|
6
|
+
Project-URL: Repository, https://github.com/hudsonbrendon/python-amazon-echo
|
|
7
|
+
Project-URL: Issues, https://github.com/hudsonbrendon/python-amazon-echo/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/hudsonbrendon/python-amazon-echo/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: aiohttp,alexa,amazon,async,echo,fire-tv,home-assistant
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Framework :: AsyncIO
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.14
|
|
21
|
+
Requires-Dist: aiohttp>=3.10
|
|
22
|
+
Requires-Dist: httpx[http2]>=0.27
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
# python-amazon-echo
|
|
26
|
+
|
|
27
|
+
[](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml)
|
|
28
|
+
[](LICENSE)
|
|
29
|
+
|
|
30
|
+
Async Python client for Amazon Echo / Alexa devices: device inventory, state,
|
|
31
|
+
settings, media, text-to-speech, alarms/timers/reminders, lists, voice history,
|
|
32
|
+
an HTTP/2 push channel and LAN discovery. It is the library behind the
|
|
33
|
+
`amazon_echo` Home Assistant integration.
|
|
34
|
+
|
|
35
|
+
It was written from a reverse-engineering pass over the Alexa app
|
|
36
|
+
(`com.amazon.dee.app` 2.2.730155.0), the Alexa web API and what an Echo exposes
|
|
37
|
+
on the local network. It is not affiliated with Amazon.
|
|
38
|
+
|
|
39
|
+
## Features
|
|
40
|
+
|
|
41
|
+
- **No password storage.** You log in in your own browser (passkeys, 2FA and
|
|
42
|
+
captchas just work) and paste the final URL; the library keeps a refresh token
|
|
43
|
+
and cookies. A session of the `alexa_media` integration can be imported too.
|
|
44
|
+
- **Self-healing session.** A 401/403 triggers one cookie exchange with the
|
|
45
|
+
refresh token and a retry; 429/503 are retried with a short back-off; every
|
|
46
|
+
change of tokens or cookies is reported through `on_credentials_update`.
|
|
47
|
+
- **Inventory and state in bulk.** Devices merged with the GraphQL endpoints
|
|
48
|
+
(MAC, model, endpoint id), and one call each for volumes, do-not-disturb,
|
|
49
|
+
Bluetooth, notifications, alarm volumes, wake words, ascending alarms and the
|
|
50
|
+
GraphQL state (temperature, reachability, Fire TV remote battery, ambient mode).
|
|
51
|
+
- **Settings nobody else exposes.** Equalizer, request sounds (earcons), alarm
|
|
52
|
+
volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
|
|
53
|
+
mode, adaptive volume and any per-device setting key (speaking rate, time zone,
|
|
54
|
+
captions, …).
|
|
55
|
+
- **Actions.** Volume, stop, speak, announce, text command, sounds, music,
|
|
56
|
+
skills, routines, transport commands, Bluetooth, reboot.
|
|
57
|
+
- **Alarms, timers and reminders.** List all, create and delete.
|
|
58
|
+
- **Lists.** Shopping, to-do and custom lists with full item CRUD.
|
|
59
|
+
- **Voice history.**
|
|
60
|
+
- **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
|
|
61
|
+
Bluetooth, notification, list and activity events; unknown events are passed
|
|
62
|
+
through, never dropped.
|
|
63
|
+
- **LAN.** Identify an Echo by IP (name, model, multi-room groups, active Spotify
|
|
64
|
+
user) and check that it is alive, without the cloud.
|
|
65
|
+
- Fully typed (`py.typed`), `aiohttp` with an injectable session, `httpx[http2]`
|
|
66
|
+
for push.
|
|
67
|
+
|
|
68
|
+
## Installation
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
pip install python-amazon-echo
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Python 3.14 or newer.
|
|
75
|
+
|
|
76
|
+
## Quick start
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
import asyncio
|
|
80
|
+
import json
|
|
81
|
+
from pathlib import Path
|
|
82
|
+
|
|
83
|
+
from amazon_echo import AmazonEchoClient, Credentials
|
|
84
|
+
|
|
85
|
+
PATH = Path("credentials.json")
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def save(credentials: Credentials) -> None:
|
|
89
|
+
PATH.write_text(json.dumps(credentials.to_dict()))
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
async def main() -> None:
|
|
93
|
+
credentials = Credentials.from_dict(json.loads(PATH.read_text()))
|
|
94
|
+
async with AmazonEchoClient(credentials, on_credentials_update=save) as client:
|
|
95
|
+
devices = await client.get_devices()
|
|
96
|
+
volumes = await client.get_volumes()
|
|
97
|
+
for device in devices:
|
|
98
|
+
print(device.name, device.model, device.online, volumes.get(device.serial))
|
|
99
|
+
|
|
100
|
+
echo = next(d for d in devices if d.family == "ECHO")
|
|
101
|
+
await client.set_volume(echo, 30)
|
|
102
|
+
await client.speak(echo, "Hello from Python")
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
asyncio.run(main())
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Push events:
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
from amazon_echo import PushClient, PushEvent
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def on_event(event: PushEvent) -> None:
|
|
115
|
+
print(event.command, event.device_serial, event.payload)
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
push = PushClient(client, on_event, on_state=lambda up: print("push up:", up))
|
|
119
|
+
await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 600 s)
|
|
120
|
+
...
|
|
121
|
+
await push.stop()
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
LAN:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from amazon_echo import is_reachable, probe_local
|
|
128
|
+
|
|
129
|
+
info = await probe_local("192.168.1.50") # None if it is not an Amazon device
|
|
130
|
+
print(info.name, info.model, info.groups, info.spotify_user)
|
|
131
|
+
print(await is_reachable("192.168.1.50"))
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Logging in with your own browser
|
|
135
|
+
|
|
136
|
+
```python
|
|
137
|
+
from amazon_echo import build_authorize_url, register_device
|
|
138
|
+
|
|
139
|
+
request = build_authorize_url(language="en-US")
|
|
140
|
+
print(request.url) # 1. open it and log in to Amazon
|
|
141
|
+
redirect = input("Paste the final URL: ") # 2. see below
|
|
142
|
+
credentials = await register_device(request, redirect)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
1. Open `request.url` in any browser and log in as usual (password, passkey,
|
|
146
|
+
2FA, captcha — whatever Amazon asks for). The login always starts on
|
|
147
|
+
amazon.com, also for accounts of other marketplaces.
|
|
148
|
+
2. When the login is done the browser lands on a blank or "page not found" page
|
|
149
|
+
whose address starts with `https://www.amazon.com/ap/maplanding?` and contains
|
|
150
|
+
`openid.oa2.authorization_code=…`. That is expected. Copy the whole address.
|
|
151
|
+
3. Pass it to `register_device`. The one-time code is exchanged for a device
|
|
152
|
+
registration ("Amazon Echo for Home Assistant" shows up in your Amazon
|
|
153
|
+
account under *Manage your content and devices*), the account's own
|
|
154
|
+
marketplace is discovered and cookies for it are fetched.
|
|
155
|
+
|
|
156
|
+
Keep the same `AuthorizeRequest` between steps 1 and 3 (it carries the PKCE
|
|
157
|
+
verifier), and persist `credentials.to_dict()`.
|
|
158
|
+
|
|
159
|
+
The command line does the same: `amazon-echo login`.
|
|
160
|
+
|
|
161
|
+
To reuse a session of the `alexa_media` integration instead:
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
credentials = Credentials.from_alexa_media(entry_data, cookies)
|
|
165
|
+
# entry_data: the `data` of the alexa_media config entry
|
|
166
|
+
# cookies: the "cookies" list of .storage/alexa_media.<email>.cookies
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Such a session shares one device registration with `alexa_media`. Everything
|
|
170
|
+
works except push while both run (see *Known limitations*).
|
|
171
|
+
|
|
172
|
+
## Command line
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
amazon-echo login
|
|
176
|
+
amazon-echo devices # also: account, states, volumes, dnd, bluetooth,
|
|
177
|
+
# notifications, routines, lists, history, providers
|
|
178
|
+
amazon-echo push # print push events
|
|
179
|
+
amazon-echo probe 192.168.1.50
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Credentials are read from `~/.config/amazon-echo/credentials.json`
|
|
183
|
+
(`--credentials` to change).
|
|
184
|
+
|
|
185
|
+
## Verification
|
|
186
|
+
|
|
187
|
+
How each part was checked against a real amazon.com.br account on 2026-11-15. Everything is also covered by unit tests with mocked
|
|
188
|
+
HTTP.
|
|
189
|
+
|
|
190
|
+
- **live read** — called against Amazon through this library, answer parsed.
|
|
191
|
+
- **no-op write** — the value just read was written back to one Echo Plus and
|
|
192
|
+
read again; Amazon accepted the request.
|
|
193
|
+
- **ported** — implemented from the app / existing open-source clients and unit
|
|
194
|
+
tested only. Not replayed live (audible or disruptive).
|
|
195
|
+
|
|
196
|
+
| API | Status |
|
|
197
|
+
|---|---|
|
|
198
|
+
| `request`, 429/503 retry, non-JSON detection | live read |
|
|
199
|
+
| `async_get_access_token` (`auth/token`) | live (token refreshed) |
|
|
200
|
+
| Cookie exchange on 401/403 (`auth/token`, `auth_cookies`) | ported — never triggered live |
|
|
201
|
+
| `build_authorize_url`, `register_device` | ported (the authorize URL answers 302 as expected; no registration was made) |
|
|
202
|
+
| `get_account`, `get_devices`, `get_routines`, `get_music_providers`, `get_service_urls` | live read |
|
|
203
|
+
| `get_dnd`, `get_volumes`, `get_bluetooth`, `get_notifications`, `get_alarm_volumes`, `get_wake_words`, `get_ascending_alarms`, `get_endpoint_states` | live read |
|
|
204
|
+
| `get_media` | live read (idle player only) |
|
|
205
|
+
| `get_wifi`, `get_equalizer`, `get_earcons`, `get_aux`, `get_setting`, `get_available_wake_words`, `get_alarm_sounds`, `get_default_alarm_sound` | live read |
|
|
206
|
+
| `get_whisper_mode`, `get_adaptive_volume` | live read |
|
|
207
|
+
| `set_whisper_mode`, `set_adaptive_volume` | no-op write during the reverse engineering (same request), not replayed by the library |
|
|
208
|
+
| `set_dnd`, `set_equalizer`, `set_earcons`, `set_alarm_volume`, `set_ascending_alarm`, `set_default_alarm_sound`, `set_setting` | no-op write |
|
|
209
|
+
| `set_aux_direction` | no-op write accepted; the body field name is unconfirmed |
|
|
210
|
+
| `set_volume` (sequence pipeline) | no-op write |
|
|
211
|
+
| `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
|
|
212
|
+
| `create_alarm` | ported |
|
|
213
|
+
| `create_timer` | ported — body inferred from field names in the app, never sent |
|
|
214
|
+
| `set_wake_word` | ported |
|
|
215
|
+
| `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
|
|
216
|
+
| `media_command`, `bluetooth_connect`, `bluetooth_disconnect`, `reboot` | ported |
|
|
217
|
+
| `get_lists`, `get_list_items` | live read |
|
|
218
|
+
| `add_list_item`, `update_list_item`, `delete_list_item` | ported |
|
|
219
|
+
| `get_voice_history` | live read |
|
|
220
|
+
| `call_feature` | ported |
|
|
221
|
+
| `PushClient` | handshake live (HTTP/2, 200, multipart boundary). the stream is then closed within ~1 s because the test session shares its registration with a running `alexa_media` (one stream per registration, see *Known limitations*); event parsing is unit tested only |
|
|
222
|
+
| `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
|
|
223
|
+
|
|
224
|
+
## Known limitations
|
|
225
|
+
|
|
226
|
+
- **An Echo has no local control API.** On the LAN it only answers the Spotify
|
|
227
|
+
Connect zeroconf endpoint (TCP 4070), advertises itself as a Matter controller
|
|
228
|
+
and Thread border router, and accepts TCP on its multi-room audio port (55442).
|
|
229
|
+
"Local" in this library therefore means discovery, name/model/group lookup and
|
|
230
|
+
liveness. Every command and every other piece of state goes through Amazon's
|
|
231
|
+
cloud; push only removes the polling.
|
|
232
|
+
- **Push with an imported `alexa_media` session.** Amazon keeps one push stream per
|
|
233
|
+
app registration and the newest connection wins. Verified on 2026-11-15 with
|
|
234
|
+
`alexa_media` debug logging on: opening our stream made `alexa_media` log
|
|
235
|
+
`HTTP2 Connection Closed`, it reconnected at once, and that closed ours about a
|
|
236
|
+
second later. So do not run `PushClient` on an imported session while
|
|
237
|
+
`alexa_media` is running; poll instead, or sign in with the browser flow to get
|
|
238
|
+
an own registration. `PushClient` does not re-declare AVS capabilities for
|
|
239
|
+
imported sessions.
|
|
240
|
+
- **Alarm and reminder times** are read by Amazon in the Echo's own time zone and
|
|
241
|
+
the API takes no zone. Aware datetimes are converted to the system time zone;
|
|
242
|
+
pass a naive datetime in the Echo's local time if the host lives elsewhere.
|
|
243
|
+
- **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
|
|
244
|
+
and ignored.
|
|
245
|
+
- **`create_timer` is unverified** (see the table). Use
|
|
246
|
+
`text_command(device, "set a timer for 5 minutes")` if it is rejected.
|
|
247
|
+
- **Voice history** comes 10 records per call; at most 50 are fetched.
|
|
248
|
+
- **Lists** return the first 100 items.
|
|
249
|
+
- **`get_notifications`** is a large, rate-limited answer; call it sparingly (push
|
|
250
|
+
sends `PUSH_NOTIFICATION_CHANGE`).
|
|
251
|
+
- `devices-v2` no longer reports MAC addresses or battery levels for most
|
|
252
|
+
devices; the MAC comes from GraphQL and is missing for apps and groups.
|
|
253
|
+
- Amazon can change or remove any of this without notice.
|
|
254
|
+
|
|
255
|
+
## Development
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
uv sync
|
|
259
|
+
uv run ruff check . && uv run ruff format --check .
|
|
260
|
+
uv run mypy src
|
|
261
|
+
uv run pytest
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
Test fixtures are hand-written; no real account data is in this repository.
|
|
265
|
+
|
|
266
|
+
## License
|
|
267
|
+
|
|
268
|
+
MIT
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# python-amazon-echo
|
|
2
|
+
|
|
3
|
+
[](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
|
|
6
|
+
Async Python client for Amazon Echo / Alexa devices: device inventory, state,
|
|
7
|
+
settings, media, text-to-speech, alarms/timers/reminders, lists, voice history,
|
|
8
|
+
an HTTP/2 push channel and LAN discovery. It is the library behind the
|
|
9
|
+
`amazon_echo` Home Assistant integration.
|
|
10
|
+
|
|
11
|
+
It was written from a reverse-engineering pass over the Alexa app
|
|
12
|
+
(`com.amazon.dee.app` 2.2.730155.0), the Alexa web API and what an Echo exposes
|
|
13
|
+
on the local network. It is not affiliated with Amazon.
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
|
|
17
|
+
- **No password storage.** You log in in your own browser (passkeys, 2FA and
|
|
18
|
+
captchas just work) and paste the final URL; the library keeps a refresh token
|
|
19
|
+
and cookies. A session of the `alexa_media` integration can be imported too.
|
|
20
|
+
- **Self-healing session.** A 401/403 triggers one cookie exchange with the
|
|
21
|
+
refresh token and a retry; 429/503 are retried with a short back-off; every
|
|
22
|
+
change of tokens or cookies is reported through `on_credentials_update`.
|
|
23
|
+
- **Inventory and state in bulk.** Devices merged with the GraphQL endpoints
|
|
24
|
+
(MAC, model, endpoint id), and one call each for volumes, do-not-disturb,
|
|
25
|
+
Bluetooth, notifications, alarm volumes, wake words, ascending alarms and the
|
|
26
|
+
GraphQL state (temperature, reachability, Fire TV remote battery, ambient mode).
|
|
27
|
+
- **Settings nobody else exposes.** Equalizer, request sounds (earcons), alarm
|
|
28
|
+
volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
|
|
29
|
+
mode, adaptive volume and any per-device setting key (speaking rate, time zone,
|
|
30
|
+
captions, …).
|
|
31
|
+
- **Actions.** Volume, stop, speak, announce, text command, sounds, music,
|
|
32
|
+
skills, routines, transport commands, Bluetooth, reboot.
|
|
33
|
+
- **Alarms, timers and reminders.** List all, create and delete.
|
|
34
|
+
- **Lists.** Shopping, to-do and custom lists with full item CRUD.
|
|
35
|
+
- **Voice history.**
|
|
36
|
+
- **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
|
|
37
|
+
Bluetooth, notification, list and activity events; unknown events are passed
|
|
38
|
+
through, never dropped.
|
|
39
|
+
- **LAN.** Identify an Echo by IP (name, model, multi-room groups, active Spotify
|
|
40
|
+
user) and check that it is alive, without the cloud.
|
|
41
|
+
- Fully typed (`py.typed`), `aiohttp` with an injectable session, `httpx[http2]`
|
|
42
|
+
for push.
|
|
43
|
+
|
|
44
|
+
## Installation
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pip install python-amazon-echo
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Python 3.14 or newer.
|
|
51
|
+
|
|
52
|
+
## Quick start
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
import asyncio
|
|
56
|
+
import json
|
|
57
|
+
from pathlib import Path
|
|
58
|
+
|
|
59
|
+
from amazon_echo import AmazonEchoClient, Credentials
|
|
60
|
+
|
|
61
|
+
PATH = Path("credentials.json")
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def save(credentials: Credentials) -> None:
|
|
65
|
+
PATH.write_text(json.dumps(credentials.to_dict()))
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
async def main() -> None:
|
|
69
|
+
credentials = Credentials.from_dict(json.loads(PATH.read_text()))
|
|
70
|
+
async with AmazonEchoClient(credentials, on_credentials_update=save) as client:
|
|
71
|
+
devices = await client.get_devices()
|
|
72
|
+
volumes = await client.get_volumes()
|
|
73
|
+
for device in devices:
|
|
74
|
+
print(device.name, device.model, device.online, volumes.get(device.serial))
|
|
75
|
+
|
|
76
|
+
echo = next(d for d in devices if d.family == "ECHO")
|
|
77
|
+
await client.set_volume(echo, 30)
|
|
78
|
+
await client.speak(echo, "Hello from Python")
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
asyncio.run(main())
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Push events:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
from amazon_echo import PushClient, PushEvent
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
def on_event(event: PushEvent) -> None:
|
|
91
|
+
print(event.command, event.device_serial, event.payload)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
push = PushClient(client, on_event, on_state=lambda up: print("push up:", up))
|
|
95
|
+
await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 600 s)
|
|
96
|
+
...
|
|
97
|
+
await push.stop()
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
LAN:
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
from amazon_echo import is_reachable, probe_local
|
|
104
|
+
|
|
105
|
+
info = await probe_local("192.168.1.50") # None if it is not an Amazon device
|
|
106
|
+
print(info.name, info.model, info.groups, info.spotify_user)
|
|
107
|
+
print(await is_reachable("192.168.1.50"))
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Logging in with your own browser
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from amazon_echo import build_authorize_url, register_device
|
|
114
|
+
|
|
115
|
+
request = build_authorize_url(language="en-US")
|
|
116
|
+
print(request.url) # 1. open it and log in to Amazon
|
|
117
|
+
redirect = input("Paste the final URL: ") # 2. see below
|
|
118
|
+
credentials = await register_device(request, redirect)
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
1. Open `request.url` in any browser and log in as usual (password, passkey,
|
|
122
|
+
2FA, captcha — whatever Amazon asks for). The login always starts on
|
|
123
|
+
amazon.com, also for accounts of other marketplaces.
|
|
124
|
+
2. When the login is done the browser lands on a blank or "page not found" page
|
|
125
|
+
whose address starts with `https://www.amazon.com/ap/maplanding?` and contains
|
|
126
|
+
`openid.oa2.authorization_code=…`. That is expected. Copy the whole address.
|
|
127
|
+
3. Pass it to `register_device`. The one-time code is exchanged for a device
|
|
128
|
+
registration ("Amazon Echo for Home Assistant" shows up in your Amazon
|
|
129
|
+
account under *Manage your content and devices*), the account's own
|
|
130
|
+
marketplace is discovered and cookies for it are fetched.
|
|
131
|
+
|
|
132
|
+
Keep the same `AuthorizeRequest` between steps 1 and 3 (it carries the PKCE
|
|
133
|
+
verifier), and persist `credentials.to_dict()`.
|
|
134
|
+
|
|
135
|
+
The command line does the same: `amazon-echo login`.
|
|
136
|
+
|
|
137
|
+
To reuse a session of the `alexa_media` integration instead:
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
credentials = Credentials.from_alexa_media(entry_data, cookies)
|
|
141
|
+
# entry_data: the `data` of the alexa_media config entry
|
|
142
|
+
# cookies: the "cookies" list of .storage/alexa_media.<email>.cookies
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Such a session shares one device registration with `alexa_media`. Everything
|
|
146
|
+
works except push while both run (see *Known limitations*).
|
|
147
|
+
|
|
148
|
+
## Command line
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
amazon-echo login
|
|
152
|
+
amazon-echo devices # also: account, states, volumes, dnd, bluetooth,
|
|
153
|
+
# notifications, routines, lists, history, providers
|
|
154
|
+
amazon-echo push # print push events
|
|
155
|
+
amazon-echo probe 192.168.1.50
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Credentials are read from `~/.config/amazon-echo/credentials.json`
|
|
159
|
+
(`--credentials` to change).
|
|
160
|
+
|
|
161
|
+
## Verification
|
|
162
|
+
|
|
163
|
+
How each part was checked against a real amazon.com.br account on 2026-11-15. Everything is also covered by unit tests with mocked
|
|
164
|
+
HTTP.
|
|
165
|
+
|
|
166
|
+
- **live read** — called against Amazon through this library, answer parsed.
|
|
167
|
+
- **no-op write** — the value just read was written back to one Echo Plus and
|
|
168
|
+
read again; Amazon accepted the request.
|
|
169
|
+
- **ported** — implemented from the app / existing open-source clients and unit
|
|
170
|
+
tested only. Not replayed live (audible or disruptive).
|
|
171
|
+
|
|
172
|
+
| API | Status |
|
|
173
|
+
|---|---|
|
|
174
|
+
| `request`, 429/503 retry, non-JSON detection | live read |
|
|
175
|
+
| `async_get_access_token` (`auth/token`) | live (token refreshed) |
|
|
176
|
+
| Cookie exchange on 401/403 (`auth/token`, `auth_cookies`) | ported — never triggered live |
|
|
177
|
+
| `build_authorize_url`, `register_device` | ported (the authorize URL answers 302 as expected; no registration was made) |
|
|
178
|
+
| `get_account`, `get_devices`, `get_routines`, `get_music_providers`, `get_service_urls` | live read |
|
|
179
|
+
| `get_dnd`, `get_volumes`, `get_bluetooth`, `get_notifications`, `get_alarm_volumes`, `get_wake_words`, `get_ascending_alarms`, `get_endpoint_states` | live read |
|
|
180
|
+
| `get_media` | live read (idle player only) |
|
|
181
|
+
| `get_wifi`, `get_equalizer`, `get_earcons`, `get_aux`, `get_setting`, `get_available_wake_words`, `get_alarm_sounds`, `get_default_alarm_sound` | live read |
|
|
182
|
+
| `get_whisper_mode`, `get_adaptive_volume` | live read |
|
|
183
|
+
| `set_whisper_mode`, `set_adaptive_volume` | no-op write during the reverse engineering (same request), not replayed by the library |
|
|
184
|
+
| `set_dnd`, `set_equalizer`, `set_earcons`, `set_alarm_volume`, `set_ascending_alarm`, `set_default_alarm_sound`, `set_setting` | no-op write |
|
|
185
|
+
| `set_aux_direction` | no-op write accepted; the body field name is unconfirmed |
|
|
186
|
+
| `set_volume` (sequence pipeline) | no-op write |
|
|
187
|
+
| `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
|
|
188
|
+
| `create_alarm` | ported |
|
|
189
|
+
| `create_timer` | ported — body inferred from field names in the app, never sent |
|
|
190
|
+
| `set_wake_word` | ported |
|
|
191
|
+
| `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
|
|
192
|
+
| `media_command`, `bluetooth_connect`, `bluetooth_disconnect`, `reboot` | ported |
|
|
193
|
+
| `get_lists`, `get_list_items` | live read |
|
|
194
|
+
| `add_list_item`, `update_list_item`, `delete_list_item` | ported |
|
|
195
|
+
| `get_voice_history` | live read |
|
|
196
|
+
| `call_feature` | ported |
|
|
197
|
+
| `PushClient` | handshake live (HTTP/2, 200, multipart boundary). the stream is then closed within ~1 s because the test session shares its registration with a running `alexa_media` (one stream per registration, see *Known limitations*); event parsing is unit tested only |
|
|
198
|
+
| `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
|
|
199
|
+
|
|
200
|
+
## Known limitations
|
|
201
|
+
|
|
202
|
+
- **An Echo has no local control API.** On the LAN it only answers the Spotify
|
|
203
|
+
Connect zeroconf endpoint (TCP 4070), advertises itself as a Matter controller
|
|
204
|
+
and Thread border router, and accepts TCP on its multi-room audio port (55442).
|
|
205
|
+
"Local" in this library therefore means discovery, name/model/group lookup and
|
|
206
|
+
liveness. Every command and every other piece of state goes through Amazon's
|
|
207
|
+
cloud; push only removes the polling.
|
|
208
|
+
- **Push with an imported `alexa_media` session.** Amazon keeps one push stream per
|
|
209
|
+
app registration and the newest connection wins. Verified on 2026-11-15 with
|
|
210
|
+
`alexa_media` debug logging on: opening our stream made `alexa_media` log
|
|
211
|
+
`HTTP2 Connection Closed`, it reconnected at once, and that closed ours about a
|
|
212
|
+
second later. So do not run `PushClient` on an imported session while
|
|
213
|
+
`alexa_media` is running; poll instead, or sign in with the browser flow to get
|
|
214
|
+
an own registration. `PushClient` does not re-declare AVS capabilities for
|
|
215
|
+
imported sessions.
|
|
216
|
+
- **Alarm and reminder times** are read by Amazon in the Echo's own time zone and
|
|
217
|
+
the API takes no zone. Aware datetimes are converted to the system time zone;
|
|
218
|
+
pass a naive datetime in the Echo's local time if the host lives elsewhere.
|
|
219
|
+
- **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
|
|
220
|
+
and ignored.
|
|
221
|
+
- **`create_timer` is unverified** (see the table). Use
|
|
222
|
+
`text_command(device, "set a timer for 5 minutes")` if it is rejected.
|
|
223
|
+
- **Voice history** comes 10 records per call; at most 50 are fetched.
|
|
224
|
+
- **Lists** return the first 100 items.
|
|
225
|
+
- **`get_notifications`** is a large, rate-limited answer; call it sparingly (push
|
|
226
|
+
sends `PUSH_NOTIFICATION_CHANGE`).
|
|
227
|
+
- `devices-v2` no longer reports MAC addresses or battery levels for most
|
|
228
|
+
devices; the MAC comes from GraphQL and is missing for apps and groups.
|
|
229
|
+
- Amazon can change or remove any of this without notice.
|
|
230
|
+
|
|
231
|
+
## Development
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
uv sync
|
|
235
|
+
uv run ruff check . && uv run ruff format --check .
|
|
236
|
+
uv run mypy src
|
|
237
|
+
uv run pytest
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Test fixtures are hand-written; no real account data is in this repository.
|
|
241
|
+
|
|
242
|
+
## License
|
|
243
|
+
|
|
244
|
+
MIT
|