Sonos HTTP API

Die Sonos HTTP API stellt eine REST API zur Verfügung, mit deren Hilfe - zum Beispiel via Webhooks - Sonos Boxen gesteuert werden können. Damit kannst Du nicht nur die Musik und die Lautstärke Deiner Boxen steuern, sondern auch Sprachmeldungen wie „Schatz, die Waschmaschine ist fertig!“ auf Deinen Boxen ausgeben (inkl. einem optionalen Ankündigungston wie ein Gong vor der Sprachausgabe).

In diesem Wiki-Artikel soll erklärt werden, wie das ganze im Zusammenspiel mit homee funktioniert. Die hier beschriebenen Methoden lassen sich natürlich auch auf andere Smart Home Systeme übertragen, welche Webhooks oder beliebige URL-Aufrufe unterstützen.

homee unterstützt von Haus aus bisher noch keine Sonos-Boxen, auch wenn der Gerätevorschlag zur Sonos-Integration einer der meist gelikten und diskutierten der homee Community ist.

Installation

Die API kann manuell installiert werden - siehe Zusatzinfos am Ende dieses Artikels - oder via homeean.

Die manuelle Installation ist nicht im Fokus dieses Artikels, wir konzentrieren uns auf die Installation und Konfiguration im Zusammenspiel mit homeean. Die manuelle Installation ist auf der Webseite der API ausreichend dokumentiert.

Die Installationsvoraussetzungen und die eigentliche Installation sind im nachfolgend verlinkten Wiki-Artikel ausführlich beschrieben:

Installation & Nutzung von homeean

Wenn die Installation gem. der oben verlinkten Anleitung abgeschlossen ist, dann erreicht Ihr in einem beliebigen Webbrowser eines Rechners, der sich im selben LAN-Segment wie Euer Raspberry Pi und Eure Sonos-Boxen befindet, die Weboberfläche der Sonos HTTP API wie folgt:

http://[IP-Eures-Raspis]:5005

Die IP-Adresse Eures Raspberry Pis muss Euch eigentlich schon bekannt sein, denn ansonsten hätte Ihr keine SSH-Verbindung zu diesem aufbauen können, als Hinweis gilt noch zu vermerken, dass homeean am Ende jeder Installation versucht den Hostnamen des Raspberry Pis auf homeean zu ändern, so dass oft (das ist jedoch u.U. abhängig von Eurem Router) auch http://homeean:5005 zum Erfolg führen wird.

Wenn die nachfolgende Seite erscheint, dann war die Installation erfolgreich:

Bildschirmfoto-2018-03-25-um-22.54.20.png

Wenn die Installation nicht erfolgreich war und diese Webseite nicht erscheint, dann meldet Euch im Support-Thread auf der homee Community mit einer Fehlerbeschreibung.

Nach erfolgreicher Installation schadet es nichts Stefan Himpler (dem Brain hinter homeean) einen Kaffee auszugeben.

Konfiguration

Die Sonos HTTP API muss in der Regel gar nicht mehr konfiguriert werden. Nach der Installation wird das Paket Eure Sonos-Boxen automatisch erkennen. Ob das der Fall ist erkennt Ihr nach Aufruf der API-Website unter
 http://[IP-Eures-Raspis]:5005

Wenn die Installation ohne Fehlermeldungen durchgelaufen ist, dann findet Ihr im Home-Verzeichnis des Users pi unter /home/pi ein neues Verzeichnis mit dem Namen node-sonos-http-api.

Mit dem Befehl cd node-sonos-http-api wechselt Ihr bei Bedarf in dieses Unterverzeichnis - der Gesamtpfad lautet:  
/home/pi/node-sonos-http-api

In diesem Verzeichnis befinden sich alle Dateien der API, individuelle Konfigurationen können (gem. der offiziellen Dokumentation) dort auch abgelegt werden.

Beispiele

REST-APIs

Eine REST-API zeichnet sich stark vereinfach dadurch aus, dass Sie über einen eindeutigen URL-Aufruf und eine dazu benutzte Methode (Get/Post/Put/Delete...) aufgerufen wird. In der Regel ist eine solche API dokumentiert, die Dokumentation der Sonos HTTP API findet sich hier.

homee Webhooks zum Aufruf von REST-APIs

homee unterstützt dieses Prinzip mit dem sogenannten Webhook, der als Aktion in einem Homeegramm benutzt werden kann (siehe nachfolgendes Beispielbild).

Bildschirmfoto-2018-03-26-um-22.30.14.png

Unter URL wird die URL des Raspberry Pis (hier: die lokale IP-Adresse des Beispielgerätes) mit dem Port 5005 aufgerufen, dahinter folgen jeweils nach einem "/" der Name des gewünschten Gerätes (hier Wohnzimmer), dahinter die Aktion (hier: Lautstärke), danach der gewünschte Parameter (+5%).

Als Methode benutzt die Sonos HTTP API immer GET und den Content Type braucht Ihr nicht verändern.

Selbstverständlich lassen sich auch komplexe JSON-Datenstrukturen an die API übergeben, aber das sprengt den Rahmen dieses WIKI-Artikels und wird hier nicht betrachtet.

Die Sonos HTTP API

Wir folgern also daraus, dass die Sonos HTTP API in der Regel (es gibt Ausnahmen, die aber dokumentiert sind) wie folgt aufgerufen wird:

http://[IP-Eures-Raspis]:5005/{zone name}/{action}[/{parameter}

{zone name} steht für den Namen der Zone, welche Ihr ansprechen wollt. Die Namen dieser Zonen habt Ihr in der Sonos-APP selbst bereits vergeben.

Wenn Ihr diese einmal vergebenen Zonennamen nicht in der APP findet (unter Einstellungen), dann hilft Euch die API auch weiter. Ein Klick auf /zones im Infokasten des Webinterfaces liefert Euch die Zoneneinstellungen Eurer Sonos-Installation als JSON-Datei zurück. Sucht in der Datei (spätestens jetzt versteht Ihr, warum JSON-Datenstrukturen den Rahmen dieses Artikels sprengen) nach allen Instanzen von roomname. Bei mir liefert die API folgendes (2 Mal) zurück:

,"roomName":"Wohnzimmer",

Auf die selbe Art und Weise könnt Ihr im Webinterface übrigens auch Eure favorites (Favoriten) und Eure playlists (Playlisten) auslesen.

Damit habt Ihr den Namen der ansprechbaren Zonen identifiziert. Ihr könnt jede Zone separat ansprechen oder (je nach Aktionstyp) auch alle gleichzeitig (pauseall / resumeall).

{action} steht dabei für eine der in der Dokumentation beschriebenen Aktionen, in unserem Beispiel volume (Lautstärke).

{parameter} steht dabei für einen (teilweise) optionalen Parameter, wie +5, der in unserem Beispiel die Lautstärke der ausgewählten Zone um 5% erhöhen wird. Ein absoluter Wert wie 15 würde die Lautstärke auf 15% des Maximums (100%) setzen.

Weitere Beispiele für actions und parameter findet Ihr auf der Doku-Seite der Sonos HTTP API.

Hervorzuheben sind meiner Meinung nach die folgenden (es schadet aber nichts sich alle mal anzusehen und auch mal damit herumzuspielen):

  • play (spielt etwas ab, was Ihr im Parameter definiert, was Ihr aber vorher in der Sonos APP konfiguriert haben müsst)
  • pause (pausiert eine vorher definierte Zone)
  • playpause (wechselt zwischen Play und Pause, je nachdem was Eure Boxen der gewählten Zone gerade tun)
  • say bzw. sayall führt zur Ausgabe eines im Parameter definierten Textes wie "Schatz, die Waschmaschine ist fertig!" auf einer definierten Zone oder (sayall) allen Zonen. Dieses Beispiel gehen wir als nächstes an.

Unser Beispielaufruf um die Lautstärke Eurer Wohnzimmerzone um 5% zu erhöhen (wie oben im Screenshot des Webhooks zu sehen) lautet also:

http://[IP-Eures-Raspis]:5005/Wohnzimmer/volume/+5

Kleiner Exkurs zu Anwendungsmöglichkeiten

Ihr fragt Euch warum man mit einem Webhook die Lautstärke einer Zone einstellen können will? Weil man damit z.B. mit Hilfe von Wandtastern, Homeegrammen, Webhooks und der Sonos HTTP API seine Sonos-Anlage bequem vom Esstisch aus (fern-)steuern kann. Wie das geht ist hier beschrieben und nachfolgend beispielhaft an gelaserten Eltako FT55 Enocean Tastern zu sehen:

sonos-taster.png

Sprachausgabe auf den Sonos-Boxen

Die Sonos HTTP API unterstützt auch die Ausgabe von Sprache über eine sogenannte Text2Speech (Text zu Sprache) API auf Deinen Sonos-Boxen. Bei einer Installation der Sonos HTTP API wird automatisch die kostenlose Google TTS Schnittstelle vorkonfiguriert (selbstverständlich verbunden mit der Warnung, dass Google jederzeit seine APIs oder seine Lizenzbedingungen ändern kann). Aus diesem Grund unterstützt die Sonos HTTP API auch andere Sprachdienste (u.a. Microsoft Bing und Amazon Polly), die jedoch manuell konfiguriert werden müssen, was in der Dokumentation der API gut festgehalten ist.

Wenn Ihr also Eurer besseren Hälfte mitteilen wollt, dass die Waschmaschine fertig ist, dann müsst Ihr im Webhook nichts anderes tun als folgende URL (im Beispiel benutzen wir wieder die Zone Wohnzimmer) aufzurufen:

http://[IP-Eures-Raspis]:5005/Wohnzimmer/say/Schatz%2C%20die%20Waschmaschine%20ist%20fertig!/de/15

Das sieht vor allem nach dem say etwas kryptisch aus, was einen einfachen Grund hat, zu dem wir gleich noch kommen. Zunächst wollen wir uns aber mal die Zusammensetzung des Aufrufes ansehen:

http://[IP-Eures-Raspis]:5005/{zone name}/say/{Text}/{sprachcode}/{parameter}

zone name brauchen wir nicht noch mal erklären, optional kann der Name der Zone auch entfallen, mit sayall wird die Sprachausgabe auf allen Zonen erfolgen. say wird nur in der zuvor definierten Zone benutzt.

Der eigentliche Text (Hier: Schatz, die Waschmaschine ist fertig!) folgt, im Beispiel deutlich kryptischer, dahinter. Weil wir im Deutschen viele Sonderzeichen benutzen, welche die Schnittstelle aus dem Tritt bringen kann (nein, wird) solltet Ihr es Euch zur Angewohnheit machen JEDEN Text, den Ihr an die Sprachausgabe übergeben wollt, prinzipiell URL zu encoden. 

Das klingt erst mal komplizierter als es eigentlich ist:
Ihr ruft dazu einen URL Encoder wie https://meyerweb.com/eric/tools/dencoder/ auf, gebt dort im Textfeld Euren gewünschten Text ein, drückt Encode und kopiert das Ergebnis in Euren Webhook. So einfach kann es sein. Das ist nötig, weil URL-Aufrufe nur bestimmte Zeichen des ASCII-Codes unterstützen. Die graue Theorie dazu findet sich hier.

Der sprachcode steht für einen für die jeweilige Schnittstelle dokumentierten Sprachcode (hier de). Witzige Effekte lassen sich übrigens mit anderen Sprachcodes erzielen - einfach mal herum experimentieren.

Die Sprachcodes unterscheiden sich bei den verschiedenen Alternativen wie Google, Microsoft oder Amazon, etwas. Wo Google einfach de benutzt, kann bei anderen de-DE verlangt werden. Ein Blick in die Doku der API hilft auch hier.

Der parameter schliesslich erlaubt es Euch die Lautstärke der Sprachausgabe festzulegen. 15 steht hier für 15% der maximalen Lautstärke.

Die Sprachausgabe lässt sich beispielsweise auch für die Alarmierung nutzen, indem ein "Eindringlingsalarm/Roter Alarm" in Dauerschleife gesprochen wird oder der Eindringling als solcher angesprochen und über die Alarmierung informiert wird, bevor dann die Alarmsirenen losheulen.

Noch eine Ergänzung aus der Community (Danke an mtbz - André):
Mit der Aktion clip kann man lokale Soundclips abspielen. Die Dateien müssen auf dem Raspberry im Verzeichnis der  Sonos-API /node-sonos-http-api/static/clips/ liegen und können dann über Webhook abgespielt werden:

Abspielen im Wohnzimmer mit Lautstärke 10%:
http://[IP-Eures-Raspis]:5005/Wohnzimmer/clip/sample_clip.mp3/10

Abspielen auf allen Geräten mit Lautstärke 10%:
http://[IP-Eures-Raspis]/clipall/sample_clip.mp3/10

Damit kann man in einem Homeegramm vor der Sprachausgabe ein Jingle (zum Beispiel einen Gong) abspielen um die Aufmerksamkeit zu erhöhen. Im selben Homeegramm sollte der zweite Webhook für die Sprachausgabe dann mit einer Verzögerung hinterlegt werden, damit der Jingle zu Ende laufen kann.

So einfach bringt Ihr Eurem Smart Home System das Sprechen bei.


Zusatzinfos

Mehr Infos zur API (inkl. der offiziellen Dokumentation) gibt es hier:
https://github.com/jishi/node-sonos-http-api

Thread zur API in der homee Community, wo Ihr weitere Fragen stellen könnt:
https://community.hom.ee/t/homeean-sonos-http-api/10668

Nach der Installation erreichst Du die API via:
http://[IP-Eures-Raspis]:5005

Lokal wird die API hier dokumentiert:
http://[IP-Eures-Raspis]:5005/docs

No Comments
Back to top