Amazon Alexa per Shell fernsteuern (Echo remote control)

Hier gibt es einen aktuelleren Post zu diesem Thema. Please look here for an updated post!
UPDATE 2021-09-20

Nachdem Amazon mit dem Multiroom Feature der Echos meine alten Multiroom Audio Bemühungen quasi nebenbei erledigt hat, fehlte mir zu meinem Glück noch die Fernsteuerung meiner Echos.

Wenn ich nach Hause komme, soll die Home Automation bitte auch gleich das Radio auf den Amazon Echos einschalten.
Für den umgekehrten Weg nutze ich HA-Bridge, welches meine Intertechno Billigsteckdosen per Alexa Sprachkommando schaltet. Daher kenne ich auch die Möglichkeit, über einen Browser auf das Alexa Interface zuzugreifen.

Was ein Browser kann, das sollte sich doch auch per Shell bewältigen lassen...

Ich habe die Entwicklertools im Firefox benutzt (Shift + Strg + i) und auf dem Reiter "Netzwerkanalyse" den Datenverkehr verfolgt. Zusätzlich habe ich Javascript abgeschaltet, da ich nicht mit irgendwelchen riesigen Frameworks hantieren wollte - und meine Shell kann kein Javascript.

Zunächst hatte mein cURL keine Cookies speichern wollen. Das änderte sich erst, nachdem ich den "User-Agent" Header hinzugefügt habe. 

Komischerweise schlägt auf diese Weise selbst im Browser die erste Anmeldung fehl. Bei genauerer Betrachtung ändert sich allerdings die Referer URL, in die nun die Session kodiert ist. So klappt dann auch das Login.

Außerdem ist zwingend ein "Accept-Language:" Header erforderlich - daraus leitet Amazon wahrscheinlich die Region für das Login ab.
Update 2018-01-28: Nachdem ich einfach nur "Mozilla/5.0" als Browser String verwendet hatte, funktionierte es auch eine Weile. Inzwischen muss ich einen real existierenden (aktuellen) Browser String verwenden!

Im Alexa Webfrontend angekommen, sind hauptsächlich die POST Anfragen interessant, immer dann habe ich eine Aktion im Frontend ausgelöst.

Da bei vielen Anfragen nur JSON Antworten zurückkommen, brauchte ich noch einen JSON Parser für die Kommandozeile und bin auf jq gestoßen. Die Einarbeitung ist etwas kryptisch, aber die Ergebnisse sehr lohnenswert.
Und wenn man schon einen JSON Parser hat, kann man eigentlich auch gleich die TuneIn Sender per Sendernamen suchen lassen und aus dem ersten Antworteintrag die StationID extrahieren...

Es gibt auch eine Version ohne JSON Parser mit weniger Funktionen (kein -i, -p, -P, -S, keine Radio Stationsnamen).

Funktionsbeschreibung

Am Anfang ist es evtl hilfreich eine Liste der Alexa kompatiblen Geräte zu holen

alexa_remote_control.sh -a

Wird später kein Gerät ausgewählt, nutzt das Script immer das erste Echo(dot)-Gerät in der Liste.
Ein Gerät darf selbstverständlich auch eine Multiroom-Gruppe sein.

Jetzt kann man bei TuneIn einen Sender suchen lassen und diesen auf einem Gerät (z.B. Wohnzimmer) in der Liste abspielen...

alexa_remote_control.sh -d Wohnzimmer -r "radioeins vom rbb"

...oder man kennt die TuneIn StationID.

alexa_remote_control.sh -d Wohnzimmer -r s25111

Möchte man sämtliche Wiedergaben stoppen, gibt es ein spezielles Gerät ALL.

alexa_remote_control.sh -d ALL -e pause

Es gibt weiterhin ein paar Funktionen, um die Amazon Bibliotheken abzufragen:

alexa_remote_control.sh -i

Legt eine Liste der zu Amazon hochgeladenen Tracks an "/tmp/.alexa.IMPORTED.list". Die enthaltene trackId wird für die für Option -s verwendet.

alexa_remote_control.sh -p

Legt eine Liste der bei Amazon gekauften Tracks an "/tmp/.alexa.PURCHASES.list". Die enthaltene trackId wird für die für Option -s verwendet.

alexa_remote_control.sh -P

Legt eine Liste aller Amazon Playlists an "/tmp/.alexa.prime-playlist-browse-nodes.list". Die enthaltene asin wird für die für Option -t verwendet

alexa_remote_control.sh -S

Legt eine Liste aller Amazon Stationen an "/tmp/.alexa.prime-sections.list". Die enthaltene seedId wird für die für Option -u verwendet

Um einen Bibliothekstrack abzuspielen, benötigt man die trackId

alexa_remote_control.sh -d Esszimmer -s 162ab3024d22a-401a-93f4-123456-7890ab

Alternativ kann man auch ein Bibliotheksalbum abspielen und benötigt dazu den Artist und den Albumtitel

alexa_remote_control.sh -d Esszimmer -s 'Beethoven' 'Sinfonie No.9'

Um eine Prime Playlist abzuspielen, benötigt man die asin

alexa_remote_control.sh -d Esszimmer -t B01DWABCDE

Um einen Prime Radiostation abzuspielen, benötigt man die seedId

alexa_remote_control.sh -d Esszimmer -u A30GBP8ABCDEF

Als Prime Benutzer kann man per Sprachkommando auch bestimmte Interpreten spielen lassen. In der Oberfläche fehlt eine entsprechende Steuermöglichkeit. Fragt man den aktuellen Play-Status in diesem Fall aber mit de -q Option ab, so erhält man eine queueId (Device spezifisch), die man später mit folgendem Kommando erneut abspielen kann:

alexa_remote_control.sh -d Esszimmer -v 1f4919d7-45db-45cf-a47f-123456-7890ab

Es können nun auch Multiroom Gruppen angelegt und gelöscht werden

alexa_remote_control.sh -m <Gruppe>

löscht die Multiroomgruppe

alexa_remote_control.sh -m <Gruppe> <Gerät1> ... <GerätX>

löscht die Multiroomgruppe und legt sie mit den Geräten 1..X neu an

Bluetooth Verbindungen werden mit der Option -b hergestellt/getrennt/gelistet:

alexa_remote_control.sh -d Esszimmer -b list

Listet alle bekannten Bluetooth Geräte für Esszimmer. Als Adresse kann je nach Bluetooth-Gerät evtl. auch ein mehrstelliger Code angezeigt werden - es muss nicht zwangsläufug eine Bluetooth HW-Adresse sein.

alexa_remote_control.sh -d Esszimmer -b "AA:BB:CC:DD:EE:FF"

Verbindet Gerät "AA:BB:CC:DD:EE:FF"

alexa_remote_control.sh -d Esszimmer -b

Trennt Bluetooth im Esszimmer
Evtl. muss das erste Pairing zuvor einmalig mit der Alexa App erfolgt sein.

Für die aktuellen Abspielinformationen (Option -q) kommen prinzipiell drei URLs zum Einsatz (ab Zeile 687):

https://layla.amazon.de/api/np/player?deviceSerialNumber=${DEVICESERIALNUMBER}&deviceType=${DEVICETYPE}&lemurId=${PARENTID}&lemurDeviceType=${PARENTDEVICE}
https://layla.amazon.de/api/media/state?deviceSerialNumber=${DEVICESERIALNUMBER}&deviceType=${DEVICETYPE}
https://layla.amazon.de/api/np/queue?deviceSerialNumber=${DEVICESERIALNUMBER}&deviceType=${DEVICETYPE}

Die Ausgaben werden momentan von "jq" ungefiltert ausgegeben.

Update 2018-02-27:
Wer bei HA-Bridge bereits versucht hat den IP-Filter zu nutzen, um Geräte im jeweiligen Raum mit dem gleichen Kommando einzuschalten, wird damit wahrscheinlich gescheitert sein, da Amazon die HUE-Verarbeitung bei mehreren Echos im Round-Robin Prinzip verteilt. D.h. das Bridge-Kommando kommt nicht unbedingt von dem Echo, der das Sprachkommando empfangen hat.
Dazu hat Markus Wennesheimer in seinem Blog eine Lösung gefunden, indem er den Activity-Feed hinsichtlich der letzten Aktion befragt.
Das Gerät, welches zuletzt einen Voice Befehl empfangen hat fragt dazu folgendes Kommando ab:

alexa_remote_control.sh -lastalexa

(Die Plain-Version kann nur die DeviceSerialNumber wiedergeben.)

Noch ein Wort zum Cookie; das Script (also eigentlich cURL) legt eine Datei /tmp/.alexa.cookie an, in die aktuell gültigen Cookie Infrmationen abgelegt sind. Analog dazu existiert eine Session auf den Amazon Servern. Bei jedem Script-Start wird überprüft, ob die Session noch gültig ist. Falls nicht, beginnt der Login Prozess erneut und die "frischen" Session Informationen werden ins Cookie geschrieben.

Zum Einen erzeugt man auf diese Weise nicht unnötig viele Login/Logout Vorgänge, die Amazon evtl. zur Sperrung veranlassen könnte. Allerdings bedeutet das auch, dass die aktuelle Session auch bei Amazon aktiv ist. D.h. wenn man das Script auf hunderten verschiedener Geräte ausführt, sollte man vielleicht lieber mit dem "-l" Parameter die Session beenden (damit wird die Cookie-Datei ebenfalls gelöscht).

Auf einem Multi-User System ist das Cookie außerdem für jeden lesbar (kann so aber auch von mehreren Prozessen verwendet werden). Schreiben darf allerdings nur der Benutzer, dem das Cookie gehört - wenn man als "root" getestet hat, kann eine "normaler Benutzer" das Cookie nie erneuern!!

Update 2018-06-12:
Das meistnachgefragte Feature TextToSpeech (TTS) ist nun endlich verfügbar. Dazu habe ich mich mit Hilfe von Ralf Otto bei den Sourcen des openHAB2 Amazon Echo Control Bindings von Michael Geramb bedient.
Text2Speech:

alexa_remote_control.sh -d Esszimmer -e speak:'Guten_Appetit!'

Routinen sollten sich nun ebenfalls starten lassen

alexa_remote_control.sh -d Esszimmer -e automation:'Welcome home'

Neben den "speak" und "automation" Funktionen gibt es noch weitere Kommandos

alexa_remote_control.sh -e [weather,traffic,flashbriefing,goodmorning,singasong,tellstory]

Update 2019-01-22:
Die Konfigurationsvariablen können nun auch per Environment an das Script übergeben werden (z.B. von Webserver mit PHP):

EMAIL     - your login email
PASSWORD  - your login password
BROWSER   - the User-Agent your browser sends in the request header
LANGUAGE  - the Accept-Language your browser sends in the request header
AMAZON    - your Amazon domain
ALEXA     - the URL you would use for the Alexa Web App
CURL      - location of your cURL binary
OPTS      - any cURL options you require
TMP       - location of the temp dir
OATHTOOL  - command line for oathtool MFA
MFA_SECRET- the MFA secret
SPEAKVOL  - the volume for speak messages
NORMALVOL - if no current playing volume can be determined, fall back to normal volume
VOLMAXAGE - max. age in minutes before volume is re-read from API
DEVICEVOLNAME   - a list of device names with specific volume settings (space separated)
DEVICEVOLSPEAK  - a list of speak volume levels - matching the devices above
DEVICEVOLNORMAL - a list of normal volume levels- matching the devices above
USE_ANNOUNCEMENT_FOR_SPEAK - Announcements can be made to multiple devices, while regular SPEAK cannot
                             but the announcement feature has to be turned on for those devices

Update 2019-07-08:
Es ist ziemlich wahrscheinlich, dass Multi-Faktor (MFA) aktivierte Anmeldungen keine Captcha Screens bekommen. Außerdem sollte man alle Accounts, die die Möglichkeit bieten heutzutage per MFA sichern.
Dank dem User rich-gepp habe ich auf GitHub eine Code-Ergänzung erhalten, die die Einmalpasswortgenerierung per oathtool erledigt. Dazu sind folgende Schritte erforderlich:

1. MFA per App sollte im Amazon Account bereits eingerichtet sein und funktionieren
2. Neue App registrieren
3. Wenn der QR-Code angezeigt wird auf "kann nicht gescannt werden" klicken
4. Der MFA String wird angezeigt, z.B. "1234 5678 9ABC DEFG HIJK LMNO PQRS TUVW XYZ0 1234 5678 9ABC DEFG"
5. Die Antwort wird mit dem oathtool erzeugt: oathtool -b --totp "<MFA shared secret von oben>" und muss in die Eingabemaske eingetragen werden (Achtung, der Code ist nur ein paar Sekunden lang gültig!
6. Wenn das geklappt hat ist der MFA String das MFA_SECRET für das alexa_remote_control Script

Update 2020-01-03:
Ich habe in der "großen" Variante nun auch eine -z Option eingebaut, um die Lautstärke zu ermitteln.
Diese Funktionalität wird für das Zurücksetzen der Lautstärke nach Ansagen benötigt.
Am zuverlässigsten scheint das zu funktionieren, wenn Multiroom-Gruppen definiert sind, dort wird nämlich die Lautstärke für alle "Teilnehmer" mitgeführt.

Ich versuche zunächst die Lautstärke über /api/media/state zu holen und wenn das nicht funktioniert, suche ich das Multiroom-Parent-Device und hole mir dort den Status. Aus diesem Grund funktioniert es leider auch noch nicht in der "plain" Version - zu viel JQ parsing...

Aus Performancegründen cache ich die letzten Volume Einstellungen für "$VOLMAXAGE" Minuten.

Update 2020-02-09:
Nun gibt es (zunächst in der "großen" Variante") auch die Möglichkeit, sowohl SSML für TTS zu nutzen, als auch TTS auf Multiroom-Gruppen zu machen. (Ich ermittle dafür die Mitglieder einer Multiroom-Gruppe im Script.)
Realisiert wird das per Announcement/Ankündigung. Dafür muss dieses Feature in jedem Echo Gerät unter "Kommunikation" aktiviert sein!!!

alexa_remote_control.sh -d Überall \
 -e speak:'<speak><amazon:effect name="whispered">hallo du</amazon:effect></speak>'

Außerdem gibt es ein neues Kommando:

alexa_remote_control.sh -e sound:amzn_sfx_trumpet_bugle_04

Die möglichen Sound-Library-Einträge muss man leider ausprobieren. Von den vier möglichen Trompetenklängen funktioniert z.B. nur der oben gezeigte. Welche Klänge es gibt, sieht man wenn man einer Routine "Töne" hinzufügt.

Update 2021-05-27:
Die sogenannten Sequence-Kommandos (speak, weather, traffic, etc.) haben ein großes Update bekommen. Das Announcement/Ankündigung Feature führte leider zu merkwürdigem Verhalten und wird nicht mehr benutzt. Sämtliche SSML Funktionen lassen sich nun mit regulärem Alexa.Speak nutzen.

alexa_remote_control.sh -d Überall \
 -e speak:"<speak><voice name='Hans'>Hallo ich bin Hans</voice><audio src='soundbank://soundlibrary/musical/amzn_sfx_trumpet_bugle_03'/> und ich bin Alexa</speak>"

Die Lautstärkeregelung wurde in diesem Zusammenhang überarbeitet. Die Ermittlung der aktuellen Lautstärke per API Aufruf funktioniert inzwischen sehr zuverlässig, so dass nach einem Sequence Kommando die alte Lautstärke wiederhergestellt werden kann.
Besitzt man unterschiedliche Geräte, dann lässt sich die Sprachlautstärke pro Gerät einstellen:

DEVICEVOLNAME='EchoZimmer1 EchoZimmer2 EchoZimmer3' \
DEVICEVOLSPEAK='100 20 25' \
  alexa_remote_control.sh -d Überall \
  -e speak:Hallo

Außerdem habe ich mich entschieden, die "Plain" Variante nicht weiter zu pflegen. Es ist extrem mühselig JSON ohne Hilfe von JQ in der Shell zu parsen. Eine sinnvolle Weiterentwicklung ist so nicht möglich. Zudem sollte JQ inzwischen auf den meisten Plattformen verfügbar sein.

Update 2021-09-02:
TuneIn Stationen können wieder abgespielt werden. Amazon hat einen Teil der API geändert. Es kann gut sein, dass Prime Stations und Playlists nicht mehr funktionieren.

Allerdings ist es nun möglich auf die verschiendenen Musik Kanäle zuzugreifen:

alexa_remote_control.sh -d Esszimmer -e playmusic:AMAZON_MUSIC:'Beethoven Sinfonie No.9'

Alle möglichen Kanäle listet:

alexa_remote_control.sh -c

Abspielen auf Multi-Room Geräten wird bisher nicht unterstützt. Stattdessen versucht das Script auf allen Mitgliedern des Multi-Room Geräts parallel abzuspielen, was zu merkwürdigen Resultaten führen kann. Im besten fall spielt der Stream nicht ganz synchron....

Update 2021-09-20:

There is an updated post!

Fertiges Script

(download link / Version ohne "jq" - nicht mehr gepflegt!)

#
# Amazon Alexa Remote Control
#  alex(at)loetzimmer.de
#
# 2017-10-10: v0.1 initial release
# 2017-10-11: v0.2 TuneIn Station Search
# 2017-10-11: v0.2a commands on special device "ALL" are executed on all ECHO+WHA
# 2017-10-16: v0.3 added playback of library tracks
# 2017-10-24: v0.4 added playback information
# 2017-11-21: v0.5 added Prime station and playlist
# 2017-11-22: v0.6 added Prime historical queue and replaced getopts
# 2017-11-25: v0.6a cURL is now configurable
# 2017-11-25: v0.7 added multiroom create/delete, playback of library playlist
# 2017-11-30: v0.7a added US config, fixed device names containing spaces
# 2017-12-07: v0.7b added Bluetooth connect/disconnect
# 2017-12-18: v0.7c fixed US version
# 2017-12-19: v0.7d fixed AWK csrf extraction on some systems
# 2017-12-20: v0.7e moved get_devlist after check_status
# 2018-01-08: v0.7f added echo-show to ALL group, TuneIn station can now be up to 6 digits
# 2018-01-08: v0.8 added bluetooth list function
# 2018-01-10: v0.8a abort when login was unsuccessful
# 2018-01-25: v0.8b added echo-spot to ALL group
# 2018-01-28: v0.8c added configurable browser string
# 2018-02-17: v0.8d no need to write the cookie file on every "check_status"
# 2018-02-27: v0.8e added "lastalexa" option for HA-Bridge to send its command to a specific device
#               (Markus Wennesheimer: https://wennez.wordpress.com/light-on-with-alexa-for-each-room/)
# 2018-02-27: v0.9 unsuccessful logins will now give a short info how to debug the login
# 2018-03-09: v0.9a workaround for login problem, force curl to use http1.1
# 2018-05-17: v0.9b update browser string and accept language
# 2018-05-23: v0.9c update accept language (again)
# 2018-06-12: v0.10 introducing TTS and more
#               (thanks to Michael Geramb and his openHAB2 Amazon Echo Control binding)
#               https://github.com/openhab/openhab2-addons/tree/master/addons/binding/org.openhab.binding.amazonechocontrol
#               (thanks to Ralf Otto for implementing this feature in this script)
# 2018-06-13: v0.10a added album play of imported library
# 2018-06-18: v0.10b added Alexa routine execution
# 2019-01-22: v0.11 added repeat command, added environment variable parsing
# 2019-02-03: v0.11a fixed string escape for automation and speak commands
# 2019-02-10: v0.12 added "-d ALL" to the plain version, lastalexa now checks for SUCCESS activityStatus
# 2019-02-14: v0.12a reduced the number of replaced characters for TTS and automation
# 2019-06-18: v0.12b fixed CSRF
# 2019-06-28: v0.12c properly fixed CSRF
# 2019-07-08: v0.13 added support for Multi-Factor Authentication
#               (thanks to rich-gepp https://github.com/rich-gepp)
# 2019-08-05: v0.14 added Volume setting via routine, and $SPEAKVOL
# 2019-11-18: v0.14a download 200 routines instead of only the first 20
# 2019-12-23: v0.14b Trigger routines by either utterance or routine name
# 2019-12-30: v0.15 re-worked the volume setting for TTS commands
# 2020-01-03: v0.15a introduce some proper "get_volume"
# 2020-01-08: v0.15b cleaned merge errors
# 2020-02-03: v0.15c SPEAKVOL of 0 leaves the volume setting untouched
# 2020-02-09: v0.16 TTS to Multiroom groups via USE_ANNOUNCEMENT_FOR_SPEAK + SSML for TTS
#               (!!! requires Announcement feature to be enabled in each device !!!)
# 2020-02-09: v0.16a added sound library - only very few sounds are actually supported
#               ( https://developer.amazon.com/en-US/docs/alexa/custom-skills/ask-soundlibrary.html )
# 2020-06-15: v0.16b added "lastcommand" option
#               (thanks to Trinitus01 https://github.com/trinitus01)
# 2020-07-07: v0.16c fixed NORMALVOL if USE_ANNOUNCEMENT_FOR_SPEAK is set
# 2020-12-12: v0.17 added textcommand which lets you send anything via CLI you would otherwise say to Alexa
#               ( https://github.com/thorsten-gehrig/alexa-remote-control/issues/108 )
# 2020-12-12: v0.17a sounds now benefit from SPEAKVOL
#                    fixed TuneIn IDs to also play podcasts
# 2021-01-28: v0.17b fixed new API endpoint for automations
#               (thanks to Michael Winkler)
# 2021-01-28: v0.17c simplified volume detection using new DeviceVolumes endpoint
#               (thanks to Ingo Fischer)
# 2021-05-27: v0.18 complete rework of sequence commands especially for TTS
#                    Announcement feature is no longer required due to inconsistent SSML handling
# 2021-09-02: v0.19 Playing TuneIn works again using new entertainment API endpoint
#               Added playmusic (Alexa.Music.PlaySearchPhrase) as command, for available channels use "-c"
#               Note: playmusic is not multi-room capable, doing so might lead to unexpected results
# 2021-09-13: v0.20 implemented device registration refresh_token cookie exchange flow as an alternative
#               to logging in
# 2021-09-15: v0.20a optimized speak commands to use less JQ. This is useful in low-resource environments
# 2021-10-07: v0.20b fixed different cookie naming for amazon.com
# 2021-11-16: v0.20c fixed AlexaApp device selection: since they're all called "This Device" use corresponding
#               line in /tmp/.alexa.devicelist.txt, e.g.: -d "This Device=A2TF17PFR55MTB=ce0123456789abcdef01=VOX"
#               -lastalexa now returns this string. Make sure to put the device in double quotes!
#
###
#
# (no BASHisms were used, should run with any shell)
# - requires cURL for web communication
# - (GNU) sed and awk for extraction
# - jq as command line JSON parser (optional for the fancy bits)
# - base64 for B64 encoding (make sure "-w 0" option is available on your platform)
# - oathtool as OATH one-time password tool (optional for two-factor authentication)
#
##########################################

(see download links above)