HTTP API Dokumentation

Transkript

1 T: F:

2 Inhaltsverzeichnis 1 Allgemeine Informationen HTTP API API-Key Ausgabeformat Wichtige Daten Systemmanager Systemmanager öffnen Wiedergabelisten vs. Warteschlangen Unterstützung Funktionsbeschreibung Grundfunktionalität Räume Zonen Räume und Zonen Haussperre Haussperre über die API Web Service Location API Antwort Format Beispiel API Antwort Codes Antwort Code bei erfolgreicher Anfrage Fehler IDs Allgemeine Abfragen Räume Abfragen über Systemmanager über API Zonen Abfragen Player Status Abfragen Zonen Abfrage und Player Status kombiniert Zone steuern Wiedergabe stoppen Wiedergabe starten vorheriger Titel nächster Titel Zufallswiedergabe T: F: info@inveoo.com Seite 2 von 23

3 8.6 Endloswiedergabe Lautstärke erhöhen Lautstärke verringern Lautstärke einstellen alle Zonen stoppen Räume steuern Lautstärke erhöhen Lautstärke verringern Lautstärke einstellen Raum stoppen Raum / Zonen Zuordnung Raum zu einer Zone hinzufügen Raum aus einer Zone entfernen Musik Wiedergabe Musik in der Zone abspielen Musik in einem Raum abspielen Fehlerbehandlung Warteschlange einer Zone leeren Haussperre aktivieren Haussperre deaktivieren T: F: info@inveoo.com Seite 3 von 23

4 1 Allgemeine Informationen 1.1 HTTP API Die HTTP API (application programming interface) von veoovibes ermöglicht einen automatisierten, maschinengeeigneten Zugriff zur Steuerung von veoovibes. Der Zugriff erfolgt via HTTP, die Antworten werden als JSON, XML oder PHP zurück geliefert. 1.2 API-Key Jede veoovibes Installation verfügt über einen eigenen einzigartigen API-Key. Dieser wird benötigt um die jeweilige veoovibes Installation zu steuern. Der API-Key muss bei allen Abfragen im Parameter api_key übermittelt werden. Geschieht dieses nicht oder wird ein ungültiger API-Key verwendet, wird der Befehl nicht ausgeführt und die API meldet den Fehlercode 20 (siehe API Antwort Codes). 1.3 Ausgabeformat Alle Anfragen und Rückgabewerte sind UTF-8 kodiert. Standardmäßig erfolgt die Rückgabe der API-Schnittstelle im JSON-Format. Das Format kann jedoch geändert werden (siehe API Antwort Format). In diesem Dokument werden alle Ausgaben als JSON dargestellt. 1.4 Wichtige Daten Alle wichtigen Daten, welche Sie für die Kommunikation mit der veoovibes Schnittstelle benötigen finden Sie im Systemmanager unter dem Menüpunkt API. T: F: Seite 4 von 23

5 1.5 Systemmanager Der Systemmanager von veoovibes ist ein eigener Service, welcher auf jeder veoovibes Installation vorhanden ist. Darüber können Wartungsaufgaben und Systemdiagnosen durchgeführt werden. Auch werden über den Systemmanager die API Einstellungen festgelegt Systemmanager öffnen Den Systemmanager können Sie über die veoovibes Oberfläche über: veoovibes Einstellungen -> System -> Systemmanager öffnen aufrufen. 1.6 Wiedergabelisten vs. Warteschlangen In veoovibes werden die Begriffe Wiedergabelisten und Warteschlangen verwendet. Wiedergabelisten sind vom Endbenutzer erstelle Listen, welche eine beliebige Anzahl von Musiktiteln enthalten. Warteschlangen gibt es pro Zone, diese stellen die abzuspielenden Titel der Zone dar. 1.7 Unterstützung Sie benötigen Hilfe? Unser Support-Team steht Ihnen mit Rat und Tat zur Seite. Bitte senden Sie Ihre Anfragen per E- Mail an: oder besuchen Sie 2 Funktionsbeschreibung Mit der veoovibes HTTP API, können Sie Ihr veoovibes Multiroom Audio System über Netzwerkkomponenten steuern und so problemlos in Automatisierungsprozesse einbinden. T: F: info@inveoo.com Seite 5 von 23

6 3 Grundfunktionalität 3.1 Räume In veoovibes können derzeit bis zu 8 Räume konfiguriert werden. Jeder Raum kann entweder direkt angeschlossen (Soundkarte), per AirPlay oder via DLNA angesteuert werden. Die AirPlay und DLNA Unterstützung muss jedoch in den Einstellungen jeweils einzeln aktiviert werden. 3.2 Zonen Analog zu den 8 Räumen gibt es auch 8 Zonen. Diese Zonen spielen die Musik und beinhalten zugleich auch die Warteschlangen, sowie weitere Einstellungen (Zufallswiedergabe, Warteschlange wiederholen). 3.3 Räume und Zonen Die in veoovibes konfigurierten Räume werden in Zonen gruppiert. Die Zonen spielen die Musik ab, die mit der Zone verbundenen Räume geben die Musik auf das jeweilige Ausgabegerät aus. Somit ist sichergestellt, dass die Räume beliebig zu einer Zone hinzugefügt bzw. entfernt werden können. Zone 1 Wiedergabe: Webradio Zone2 Wiedergabe: gestoppt Zone2 Wiedergabe: gestoppt Raum: Wohnzimmer Ausgabe: Soundkarte Raum: Küche Ausgabe: Soundkarte Raum: Badezimmer Ausgabe: Soundkarte Raum: Schlafzimmer Ausgabe: Soundkarte 3.4 Haussperre Bei der Haussperre in veoovibes handelt es sich um eine Funktion, welche der Endbenutzer aktivieren kann um die Wiedergabe in allen Räumen / Zonen zu stoppen. Zudem werden während einer aktiven Haussperre die Wecker und Timer deaktiviert. Der Endbenutzer muss, bevor er veoovibes wieder wie gewohnt verwenden kann, die Sperre aufheben Haussperre über die API Werden Befehle über die API an veoovibes gesendet, so wird hierbei vom System automatisch geprüft, ob die Sperre aktiv ist. Ist dies der Fall, so wird die Haussperre automatisch aufgehoben und im Anschluss wird der eigentliche Befehl ausgeführt. Hinweis: Durch das Deaktivieren der Haussperre kann sich die Befehlsausführung bzw. Rückmeldung um ein paar Sekunden verzögern. T: F: info@inveoo.com Seite 6 von 23

7 4 Web Service Location Die folgende Basis URI (Uniform Resource Identifier) wird für alle weiteren Befehle benötigt. Platzhalter <IP-Adresse> <API-Key> IP-Adresse von veoovibes (Hostname kann verwendet werden, wird aber nicht empfohlen) API-Key, dieser kann aus den Einstellungen von veoovibes ausgelesen werden Basis URI Hinweis: Der API-Key MUSS bei jeder Anfrage übermittelt werden. Fehlt der API-Key oder ist dieser ungültig, wird die Anfrage vom System nicht verarbeitet. 5 API Antwort Format Alle Antworten erfolgen standardmäßig in JSON, es kann jedoch über den URL Parameter output das Format geändert werden. Beschreibung Content-Type Erweiterung JSON (Standard) application/json;charset=utf-8 json XML text/xml;charset=utf-8 xml PHP text/plain;charset=utf-8 Php 5.1 Beispiel Antworten als XML Ausgabe erhalten 6 API Antwort Codes Jede Anfrage / jeder Befehl an die Schnittstelle wird mit folgenden Angaben (im gewählten Format, siehe API Antwort Format ) beantwortet: Name status code error_message Kann entweder succeeded (erfolgreich) oder failed (fehlgeschlagen) sein Sollte immer 0 sein, außer es trat ein Fehler auf, dann wird hier die Fehler ID ausgegeben Beinhaltet die Fehlermedung (sofern vorhanden), trat kein Fehler auf, bleibt diese leer Antwort Code bei erfolgreicher Anfrage Bei erfolgreichen Abfragen wird zusätzlich auch folgender übertragen: Name result Enthält die angeforderten Daten oder einen Status Text Fehler IDs Code Bedeutung Beschreibung 1 Exception Ein allgemeiner Fehler ist aufgetreten 2 Http Method Die angeforderte http Methode wird für diese Anfrage nicht unterstützt 3 Required Parameter Ein benötigter Parameter wurde nicht übergeben oder dessen war leer 10 API disabled Die API ist deaktiviert, wenden Sie sich an den Support 20 Access Token Ungültiger oder fehlender API Key T: F: info@inveoo.com Seite 7 von 23

8 7 Allgemeine Abfragen 7.1 Räume Abfragen über Systemmanager Eine Liste aller im System verfügbaren Räume, kann im Systemmanager eingesehen werden. Dort werden der Name und dessen ID angezeigt. Alternativ zu dieser einfachen Möglichkeit, steht auch ein entsprechender API Befehl zur Verfügung, welche alle Räume, deren IDs und weitere Details anzeigt über API Gibt eine Liste mit allen im System konfigurierten Räumen zurück. Die Rückgabe enthält die API Antwort Codes und das Element result, welche alle Räume auflistet. Das Element result beinhaltet für jeden Raum folgende e: Bezeichnung id_room Die Datenbank ID des Raums type Definiert die Anschlussart des Raums. Mögliche e: Soundkarte, Airplay, DNLA name Der vom Benutzer definierte Anzeigename für den Raum current_volume Die aktuell eingestellte Lautstärke für den Raum, bereich: is_available Gibt an, ob der Raum verfügbar ist, mögliche e sind true oder false "result": "22": "id_room": 22, "type": "Soundkarte", "name": "Wohnzimmer", "current_volume": 20, "is_available": true, "23": "id_room": 23, "type": "Soundkarte", "name": "Schlafzimmer", "current_volume": 16, "is_available": true, "24": "id_room": 24, "type": "Soundkarte", "name": "Küche", "current_volume": 16, "is_available": true T: F: info@inveoo.com Seite 8 von 23

9 7.2 Zonen Abfragen Gibt eine Liste mit der aktuellen Zonenkonfiguration zurück. Die Rückgabe enthält die API Antwort Codes und das Element result, welche alle Zonen auflistet. Das Element result beinhaltet für jede Zone folgende e: id_zone rooms room_detail Bezeichnung Die Datenbank ID der Zone Eine kommagetrennte Liste der IDs der Räume Ein Array pro Raum mit denselben Angaben wie unter Räume Abfragen (listrooms) "result": "2": "id_zone": 2, "rooms": "22,23", "room_detail": "22": "id_room": 22, "type": "Soundkarte", "name": "Wohnzimmer", "current_volume": 20, "is_available": true, "23": "id_room": 23, "type": "Soundkarte", "name": "Schlafzimmer", "current_volume": 16, "is_available": true, "3": "id_zone": 3, "rooms": "24", "room_detail": "24": "id_room": 24, "type": "Soundkarte", "name": "Küche", "current_volume": 16, "is_available": true T: F: Seite 9 von 23

10 7.3 Player Status Abfragen Gibt eine Auflistung aller Informationen über den Wiedergabestatus inkl. Metadaten für alle Zonen aus. "result": "2": "id_zone": 2, "player": "mediatime_total": "03:56", "mediatime_now": "01:03", "mediatime_progress": , "is_playing": 1, "zone_volume": 11, "random": 0, "repeat": 0, "status_code": "playing", "status": "Wiedergabe", "album": "", "artist": "Hi-Lights", "title": "Soul Limbo", "cover": "arts/artist/ be6c2f865ebd41ea ae.jpg", "is_radio": false, "radio_name": "", "type": "", "3": "id_zone": 3, "player": "mediatime_total": "", "mediatime_now": "", "mediatime_progress": 100, "is_playing": 0, "zone_volume": 16, "random": 0, "repeat": 0, "status_code": "stopped", "status": "Wiedergabe gestoppt", "album": "", "artist": "", "title": "", "cover": "", "is_radio": false, "radio_name": "", "type": "" T: F: Seite 10 von 23

11 7.4 Zonen Abfrage und Player Status kombiniert Gibt eine kombinierte Antwort aus den beiden Einzelabfragen Zonen Abfragen und Player Status Abfragen zurück. Ausgabe gekürzt! "result": "2": "id_zone": 2, "rooms": "22,23", "room_detail": "28": "id_room": 28, "type": "Soundkarte", "name": "Wohnzimmer", "current_volume": 20, "is_available": true, "26": "id_room": 23, "type": "Soundkarte", "name": "Schlafzimmer", "current_volume": 16, "is_available": true, "player": "mediatime_total": "03:25", "mediatime_now": "03:22", "mediatime_progress": , "is_playing": 1, "zone_volume": 11, "random": 0, "repeat": 0, "status_code": "playing", "status": "Wiedergabe", "album": "", "artist": "Eva Cassidy", "title": "Ain't No Sunshine", "cover": "arts/artist/ ce5fb311de812d0d6777cfcd7.jpg", "is_radio": false, "radio_name": "", "type": "" T: F: Seite 11 von 23

12 8 Zone steuern Einer dieser beiden Parameter wird für alle folgenden e der Zonensteuerung benötigt. Name Platzhalter zone <ZoneID> Die ID der zu steuernden Zone, siehe Zonen Abfragen Parameter ab Version verfügbar Alternativ zu <Zone-ID>, wenn die Zone-ID nicht bekannt ist, kann auch die Raumzoneroom <ZoneRoomID> ID angegeben werden. Hinweis: Wird <ZoneRoom-ID> verwendet, wird der von <Zone-ID> ignoriert (insofern angegeben). 8.1 Wiedergabe stoppen Stoppt die Wiedergabe der angegebenen Zone. über Zonenparameter über Raumparameter Wiedergabe starten Setzt die Wiedergabe an der letzten Position der Warteschlange fort. über Zonenparameter über Raumparameter T: F: info@inveoo.com Seite 12 von 23

13 8.3 vorheriger Titel Den vorherigen Titel der Warteschlange abspielen. über Zonenparameter über Raumparameter nächster Titel Den nächsten Titel der Warteschlange abspielen. über Zonenparameter über Raumparameter T: F: Seite 13 von 23

14 8.5 Zufallswiedergabe Die Zufallswiedergabe der Zone für die aktuelle Warteschlange aktivieren / deaktivieren. über Zonenparameter über Raumparameter Endloswiedergabe Die Einträge der Warteschlange wiederholen aktivieren / deaktivieren. über Zonenparameter über Raumparameter T: F: info@inveoo.com Seite 14 von 23

15 8.7 Lautstärke erhöhen Lautstärke aller mit der Zone verbundenen Räumen schrittweise erhöhen. über Zonenparameter über Raumparameter Lautstärke verringern Lautstärke aller mit der Zone verbundenen Räumen schrittweise verringern. über Zonenparameter über Raumparameter T: F: Seite 15 von 23

16 8.9 Lautstärke einstellen Setzt die Lautstärke aller mit der Zone verbundenen Räume auf einen zwischen 0 100%. Die Räume werden dabei prozentuell aufgrund Ihrer letzten Einstellung (vorherige Raumlautstärke) angepasst Platzhalter <Volume> Ein zwischen 0 und 100 als Ganzzahl über Zonenparameter über Raumparameter alle Zonen stoppen Stoppt die Wiedergabe in allen Zonen. T: F: info@inveoo.com Seite 16 von 23

17 9 Räume steuern Dieser Parameter wird für alle folgenden e für die Raumsteuerung benötigt. Platzhalter <RoomID> Die ID des zu steuernden Raumes, siehe Räume Abfragen 9.1 Lautstärke erhöhen Lautstärke des angegebenen Raumes schrittweise erhöhen. Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird die Zonenlautstärke mit der neuen Lautstärke des Raums gleichgesetzt Lautstärke verringern Lautstärke des angegebenen Raumes schrittweise verringern. Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird die Zonenlautstärke mit der neuen Lautstärke des Raums gleichgesetzt. T: F: info@inveoo.com Seite 17 von 23

18 9.3 Lautstärke einstellen Lautstärke des angegebenen Raumes auf einen zwischen 0 100% einstellen. Platzhalter <Volume> Ein zwischen 0 und 100 als Ganzzahl Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird die Zonenlautstärke mit der neuen Lautstärke des Raums gleichgesetzt Raum stoppen Da die Zone die Musik steuert, ist es im Normalfall erforderlich, die mit dem Raum verbundene Zone zu stoppen. Diese Funktion ermöglicht Ihnen die Zone aufgrund des angegebenen Raums zu stoppen ohne vorher die dazugehörige Zone abzufragen. Dabei kann entschieden werden, ob die gesamte Zone gestoppt werden soll oder ob der angegebene Raum aus der Zone entfernt werden soll. Platzhalter <RoomID> <ActionID> Die ID des zu steuernden Raumes, siehe Räume Abfragen 1 = (Standard) Den Raum aus der aktuellen Zone entfernen somit wird der Raum gestoppt und verliert gleichzeitig jedoch die Warteschlange aufgrund der neuen Zone. 2 = Die für den Raum zuständige Zone stoppen, somit werden ev. weitere verbunden Räume ebenfalls nichts mehr Wiedergeben. Hinweis: Ist der Raum als einziger Raum mit der Zone verbunden, so wird unabhängig von der Angabe unter <Action> die Zone gestoppt, damit die aktuelle Warteschlange nicht verloren geht. T: F: info@inveoo.com Seite 18 von 23

19 10 Raum / Zonen Zuordnung 10.1 Raum zu einer Zone hinzufügen Fügt einen Raum einer Zone hinzu. Platzhalter <RoomID> <ZoneID> Die ID des Raumes, siehe Räume Abfragen Die ID der Zone, siehe Zonen Abfragen Befindet sich der Raum bereits in der angegebenen Zone, so erhalten Sie folgende Rückmeldung: "status": "failed", "code": 1, "error_message": "selected room is already assigned to this zone" 10.2 Raum aus einer Zone entfernen Entfernt einen Raum aus einer Zone. Platzhalter <RoomID> Die ID des Raumes, siehe Räume Abfragen T: F: info@inveoo.com Seite 19 von 23

20 11 Musik Wiedergabe Für die Musikwiedergabe müssen im Systemmanager die Programme festgelegt werden, welche hier über den Befehl Musik Wiedergeben abgespielt werden können. Dabei gilt es zu beachten, dass max. 12 Programmgruppen angelegt werden können. Jede Programmgruppe kann bis zu 12 Speicherplätze enthalten. Pro Speicherplatz kann jeweils ein Radiosender oder ein pers. Radiosender oder eine Wiedergabeliste hinterlegt werden Musik in der Zone abspielen Für das Abspielen von einem Speicherplatz in einer Zone. Alle mit der Zone verbunden Räume geben diesen Speicherplatz wieder. Platzhalter zone <ZoneID> Die ID der Zone, siehe Zonen Abfragen group <GroupID> Die ID der zur verwendenden Programmgruppe prog <ProgID> Die ID des Speicherplatzes innerhalb der Programmgruppe Parameter ab Version verfügbar Alternativ zu <Zone-ID>, wenn die Zone-ID nicht bekannt ist, kann auch die Raumzoneroom <ZoneRoom-ID> ID angegeben werden. Hinweis: Wird <ZoneRoom-ID> verwendet, wird der von <Zone-ID> ignoriert (insofern angegeben). über Zonenparameter <API-Key> über Raumparameter api_key=<api-key> T: F: Seite 20 von 23

21 11.2 Musik in einem Raum abspielen Für das Abspielen von einem Speicherplatz in einem Raum. Dabei gilt folgende Logik: Ist der Raum der einzige in der Zone, so wird der angegebene Speicherplatz in die Warteschlange aufgenommen und abgespielt. Befinden sich in der Zone des angegebenen Raumes mehrere Räume, so wird der Raum aus der Zone entfernt und der angegebene Speicherplatz wiedergegeben. Platzhalter <RoomID> <GroupID> <ProgID> Die ID des zu steuernden Raumes, siehe Räume Abfragen Die ID der zur verwendenden Programmgruppe Die ID des Speicherplatzes innerhalb der Programmgruppe <API-Key> T: F: Seite 21 von 23

22 11.3 Fehlerbehandlung Wird über Musik in einer Zone abspielen oder Musik in einem Raum abspielen ein Speicherplatz aufgerufen welcher keinem Radiosender, pers. Radiosender oder einer Wiedergabeliste zugeordnet ist, so erhalten Sie über die API eine Fehlermeldung. Rückgabe / Fehlermeldung (JSON) "status": "failed", "code": 1, "error_message": "group / prog not defined" Da die Speicherplätze aufgrund der einfacheren Verwaltung durch den Endkunden auch geändert bzw. gelöscht werden können, erfolgt in diesem speziellen Fall eine akustische Rückmeldung an den Benutzer! Zusätzlich zur obigen Fehlermeldung erfolgt eine Sprachausgabe in der Zone oder dem gewählten Raum mit dem Inhalt: Dieser Programmplatz kann nicht wiedergegeben werden. Bitte überprüfen Sie die Einstellungen Warteschlange einer Zone leeren Leert / Löscht die komplette Warteschlange der angegebenen Zone. Platzhalter <ZoneID> Die ID der Zone, siehe Zonen Abfragen T: F: info@inveoo.com Seite 22 von 23

23 11.5 Haussperre aktivieren Aktiviert die Haussperre. Mehr Informationen zur Haussperre unter Grundfunktionalität Haussperre deaktivieren Deaktiviert die Haussperre. Mehr Informationen zur Haussperre unter Grundfunktionalität. T: F: Seite 23 von 23