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  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.

Den Systemmanager können Sie über die veoovibes Oberfläche über: „veoovibes Einstellungen -> System -> Systemmanager öffnen“ aufrufen.

1.5  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.6  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: support@veoovibes.com oder besuchen Sie http://support.veoovibes.com

2  API Steuerungsdefinitionen

2.1  Web Service Location

Die folgende Basis URI (Uniform Resource Identifier) wird für alle weiteren Befehle benötigt.

http://<IP-Adresse>/api/v1/?api_key=<API-Key>

2.2  API Antwort Format

Alle Antworten erfolgen standardmäßig in JSON, es kann jedoch über den URL Parameter output das Format geändert werden.

http://<IP-Adresse>/api/v1/<befehl>/?api_key=<API-Key>&output=xml

2.3  API Antwort Codes

Jede Anfrage / jeder Befehl an die Schnittstelle wird mit folgenden Angaben (im gewählten Format, siehe "API Antwort Format") beantwortet:

Antwort Code bei erfolgreicher Anfrage

Fehler IDs

3  Räume steuern

3.1  Wiedergabe starten (Raum)

Parameter

http://<IP-Adresse>/api/v1/room_play?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.2  Wiedergabe stoppen (Raum)

Parameter

http://<IP-Adresse>/api/v1/room_stop?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.3  Nächste Titel (Raum)

Parameter

http://<IP-Adresse>/api/v1/room_next?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.4  Vorheriger Titel (Raum)

Parameter

http://<IP-Adresse>/api/v1/room_prev?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.5  Lautstärke erhöhen (Raum)

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.

Parameter

http://<IP-Adresse>/api/v1/room_vol_up?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.6  Lautstärke verringern (Raum)

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.

Parameter

http://<IP-Adresse>/api/v1/room_vol_down?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.7  Lautstärke einstellen (Raum)

Lautstärke des angegebenen Raumes auf einen Wert zwischen 0 – 100% einstellen.

Parameter

http://<IP-Adresse>/api/v1/room_vol_set?api_key=<API-Key>&room=<Room-ID>&vol=<Volume>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.8  Musik abspielen (Raum)

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 (siehe Wiedergabelisten vs. Warteschlangen) 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.

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“ (siehe Wiedergabelisten vs. Warteschlangen) hinterlegt werden.

Parameter

http://<IP-Adresse>/api/v1/music_room?api_key=<API-Key>&room=<Room-ID>&group=<Group-ID>&prog=<Prog-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.9  Zufallswiedergabe (Raum)

Parameter

http://<IP-Adresse>/api/v1/room_random?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.10  Endloswiedergabe (Raum)

Parameter

http://<IP-Adresse>/api/v1/room_repeat?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

3.11  Player Status Abfragen (Raum)

ab Version 1.1.780 verfügbar

Gibt eine Auflistung aller Informationen über den Wiedergabestatus inkl. Metadaten für den Raum aus.

Parameter

http://<IP-Adresse>/api/v1/room_player_status?api_key=<API-Key>&room=<Room-ID>

{
   "status":"succeeded",
   "code":0,
   "error_message":"",
   "result":{
      "mediatime_total":"",
      "mediatime_now":"",
      "mediatime_progress":100,
      "is_playing":1,
      "zone_volume":33,
      "random":0,
      "repeat":1,
      "status_code":"playing",
      "status":"Wiedergabe",
      "album":"",
      "artist":"",
      "title":"Soap&Skin; - Heal | FM4 Reality Check",
      "cover":"http://api.veoovibes.com/radiostations/220c77af02f8ad8561b150d93000ddff.png",
      "is_radio":true,
      "radio_name":"FM4",
      "type":"",
      "current_volume":19
   }
}

3.12  Räume Abfragen

Gibt eine Liste mit allen im System konfigurierten Räumen zurück.

Parameter

http://<IP-Adresse>/api/v1/listrooms?api_key=<API-Key>

{
   "status":"succeeded",
   "code":0,
   "error_message":"",
   "result":{
      "95":{
         "id_room":95,
         "api_room_id":12,
         "api_room_name":"kueche",
         "type":"Soundkarte",
         "name":"Küche",
         "current_volume":13,
         "eq_bands":"",
         "is_hidden":0,
         "is_available":true
      },
      "91":{
         "id_room":91,
         "api_room_id":91,
         "api_room_name":"allgemein",
         "type":"Soundkarte",
         "name":"Allgemein",
         "current_volume":13,
         "eq_bands":"",
         "is_hidden":0,
         "is_available":true
      }
   }
}

3.13  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.

Parameter

http://<IP-Adresse>/api/v1/stop_room?api_key=<API-Key>&room=<Room-ID>&action=<Action-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4  Zone steuern

4.1  Wiedergabe starten (Zone)

Setzt die Wiedergabe an der letzten Position der Warteschlange (siehe Wiedergabelisten vs. Warteschlangen) fort.

Parameter

http://<IP-Adresse>/api/v1/play?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.2  Wiedergabe stoppen (Zone)

Stoppt die Wiedergabe der angegeben Zone.

Parameter

http://<IP-Adresse>/api/v1/stop?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.3  Nächster Titel (Zone)

Den nächsten Titel der Warteschlange (siehe Wiedergabelisten vs. Warteschlangen) abspielen.

Parameter

http://<IP-Adresse>/api/v1/next?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.4  Vorheriger Titel (Zone)

Den vorherigen Titel der Warteschlange (siehe Wiedergabelisten vs. Warteschlangen) abspielen.

Parameter

http://<IP-Adresse>/api/v1/prev?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.5  Lautstärke erhöhen (Zone)

Lautstärke aller mit der Zone verbundenen Räumen schrittweise erhöhen.

Parameter

http://<IP-Adresse>/api/v1/vol_up?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.6  Lautstärke verringern (Zone)

Lautstärke aller mit der Zone verbundenen Räumen schrittweise verringern.

Parameter

http://<IP-Adresse>/api/v1/vol_down?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.7  Lautstärke einstellen (Zone)

Setzt die Lautstärke aller mit der Zone verbundenen Räume auf einen Wert zwischen 0 – 100%.

Parameter

http://<IP-Adresse>/api/v1/vol_set?api_key=<API-Key>&zone=<Zone-ID>&vol=<Volume>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.8  Musik abspielen (Zone)

Für das Abspielen von einem Speicherplatz in einer Zone. Alle mit der Zone verbunden Räume geben diesen Speicherplatz wieder.

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“ (siehe Wiedergabelisten vs. Warteschlangen) hinterlegt werden.

Parameter

http://<IP-Adresse>/api/v1/music_zone?api_key=<API-Key>&zone=<Zone-ID>&group=<Group-ID>&prog=<Prog-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.9  Zufallswiedergabe (Zone)

Die Zufallswiedergabe der Zone für die aktuelle Warteschlange (siehe Wiedergabelisten vs. Warteschlangen) aktivieren / deaktivieren.

Parameter

http://<IP-Adresse>/api/v1/random?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.10  Endloswiedergabe (Zone)

Die Einträge der Warteschlange (siehe Wiedergabelisten vs. Warteschlangen) wiederholen aktivieren / deaktivieren.

Parameter

http://<IP-Adresse>/api/v1/repeat?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.11  Player Status Abfragen (Zone)

in Version 1.1.780 geändert

Gibt eine Auflistung aller Informationen über den Wiedergabestatus inkl. Metadaten für alle Zonen oder einen bestimmten Zone aus.

Parameter

http://<IP-Adresse>/api/v1/player_status?api_key=<API-Key>

{
   "status":"succeeded",
   "code":0,
   "error_message":"",
   "result":{
      "1":{
         "id_zone":1,
         "player":{
            "mediatime_total":"",
            "mediatime_now":"",
            "mediatime_progress":100,
            "is_playing":1,
            "zone_volume":13,
            "random":0,
            "repeat":1,
            "status_code":"playing",
            "status":"Wiedergabe",
            "album":"",
            "artist":"",
            "title":"Sarah Jane Morris - Nothing Comes From Nothing",
            "cover":"http://api.veoovibes.com/radiostations/c4fa856e631d52fce97c4eb37d17bb19.png",
            "is_radio":true,
            "radio_name":"Lounge FM Digital",
            "type":""
         }
      },
      "2":{
         "id_zone":2,
         "player":{
            "mediatime_total":"",
            "mediatime_now":"",
            "mediatime_progress":100,
            "is_playing":0,
            "zone_volume":24,
            "random":0,
            "repeat":1,
            "status_code":"stopped",
            "status":null,
            "album":"",
            "artist":"",
            "title":"",
            "cover":"",
            "is_radio":false,
            "radio_name":"",
            "type":""
         }
      }
   }
}

4.12  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.

Parameter

http://<IP-Adresse>/api/v1/listzones?api_key=<API-Key>

{
   "status":"succeeded",
   "code":0,
   "error_message":"",
   "result":{
      "1":{
         "id_zone":1,
         "rooms":"91,90,96",
         "room_detail":{
            "91":{
               "id_room":91,
               "api_room_id":91,
               "api_room_name":"allgemein",
               "type":"Soundkarte",
               "name":"Allgemein",
               "current_volume":13,
               "eq_bands":"",
               "is_hidden":0,
               "is_available":true
            },
            "90":{
               "id_room":90,
               "api_room_id":90,
               "api_room_name":"kueche",
               "type":"Soundkarte",
               "name":"Küche",
               "current_volume":13,
               "eq_bands":"",
               "is_hidden":0,
               "is_available":true
            }
         }
      },
      "2":{
         "id_zone":2,
         "rooms":126,
         "room_detail":{
            "126":{
               "id_room":126,
               "api_room_id":126,
               "api_room_name":"terrasse",
               "type":"Soundkarte",
               "name":"Dachterrasse",
               "current_volume":24,
               "eq_bands":"-8,-5.2,-2.8,0,0,0,0,0,0,0",
               "is_hidden":0,
               "is_available":true
            }
         }
      }
   }
}

4.13  Zonen & Player Status kombiniert

Gibt eine kombinierte Antwort aus den beiden Einzelabfragen "Zonen Abfragen" und "Player Status Abfragen" zurück.

Parameter

http://<IP-Adresse>/api/v1/listzones_player_status?api_key=<API-Key>

{
   "status":"succeeded",
   "code":0,
   "error_message":"",
   "result":{
      "1":{
         "id_zone":1,
         "rooms":"91,90",
         "room_detail":{
            "91":{
               "id_room":91,
               "api_room_id":91,
               "api_room_name":"allgemein",
               "type":"Soundkarte",
               "name":"Allgemein",
               "current_volume":13,
               "eq_bands":"",
               "is_hidden":0,
               "is_available":true
            },
            "90":{
               "id_room":90,
               "api_room_id":90,
               "api_room_name":"guenter",
               "type":"Soundkarte",
               "name":"G\u00fcnters B\u00fcro",
               "current_volume":13,
               "eq_bands":"",
               "is_hidden":0,
               "is_available":true
            }
         },
         "player":{
            "mediatime_total":"",
            "mediatime_now":"",
            "mediatime_progress":100,
            "is_playing":1,
            "zone_volume":13,
            "random":0,
            "repeat":1,
            "status_code":"playing",
            "status":"Wiedergabe",
            "album":"",
            "artist":"",
            "title":"DJ Vadim featuring Katherin DeBoer - Black Is the Night",
            "cover":"http:\/\/api.veoovibes.com\/radiostations\/c4fa856e631d52fce97c4eb37d17bb19.png",
            "is_radio":true,
            "radio_name":"Lounge FM Digital",
            "type":""
         }
      },
      "2":{
         "id_zone":2,
         "rooms":126,
         "room_detail":{
            "126":{
               "id_room":126,
               "api_room_id":126,
               "api_room_name":"terrasse",
               "type":"Soundkarte",
               "name":"Dachterrasse",
               "current_volume":24,
               "eq_bands":"-8,-5.2,-2.8,0,0,0,0,0,0,0",
               "is_hidden":0,
               "is_available":true
            }
         },
         "player":{
            "mediatime_total":"",
            "mediatime_now":"",
            "mediatime_progress":100,
            "is_playing":0,
            "zone_volume":24,
            "random":0,
            "repeat":1,
            "status_code":"stopped",
            "status":null,
            "album":"",
            "artist":"",
            "title":"",
            "cover":"",
            "is_radio":false,
            "radio_name":"",
            "type":""
         }
      }
   }
}

4.14  Warteschlange einer Zone anzeigen

ab Version 1.0.860 verfügbar

Gibt die komplette Warteschlange der angegebenen Zone aus.

Parameter

http://<IP-Adresse>/api/v1/list_queue?api_key=<API-Key>&zone=<Zone-ID>

{
   "status":"succeeded",
   "code":0,
   "error_message":"",
   "result":[
      {
         "id":6,
         "title":"Lounge FM Digital",
         "artist":"",
         "duration":0
      },
   {
         "id":16,
         "title":"ANTENNE BAYERN - Top 40",
         "artist":"",
         "duration":0
      }
   ]
}

4.15  Wiedergabe eines Eintrags der Warteschlange

ab Version 1.0.860 verfügbar

Spielt den angegebenen Eintrag der Warteschlange ab. Hinweis: Dieser Befehl startet ggf. die Wiedergabe!

Parameter

http://<IP-Adresse>/api/v1/play_queue_item?api_key=<API-Key>&zone=<Zone-ID>&item=<Item-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.16  Warteschlange einer Zone leeren

ab Version 1.0.854 verfügbar

Leert / Löscht die komplette Warteschlange der angegebenen Zone.

Parameter

http://<IP-Adresse>/api/v1/empty_queue?api_key=<API-Key>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

4.17  Alle Zonen stoppen

Stoppt die Wiedergabe in allen Zonen.

Parameter

http://<IP-Adresse>/api/v1/stop_all?api_key=<API-Key>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

5  veoovibes Steuerung

5.1  Haussperre aktivieren

Aktiviert die Haussperre. Mehr Informationen zur Haussperre unter "Grundfunktionalität".

Parameter

http://<IP-Adresse>/api/v1/lock_system?api_key=<API-Key>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

5.2  Haussperre deaktivieren

Deaktiviert die Haussperre. Mehr Informationen zur Haussperre unter "Grundfunktionalität".

Parameter

http://<IP-Adresse>/api/v1/unlock_system?api_key=<API-Key>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

5.3  Türgong abspielen

ab Version 1.2.217 verfügbar

Spielt einen Türgong in den im Admin-Bereich hinterlegten Räumen (und eingestellten Lautstärke) ab.

Parameter

http://<IP-Adresse>/api/v1/chime?api_key=<API-Key>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

6  Raum / Zonen Zuordnung

6.1  Raum zu einer Zone hinzufügen

Fügt einen Raum einer Zone hinzu.

Parameter

http://<IP-Adresse>/api/v1/add_room_to_zone?api_key=<API-Key>&room=<Room-ID>&zone=<Zone-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}

6.2  Raum aus einer Zone entfernen

Entfernt einen Raum aus einer Zone.

Parameter

http://<IP-Adresse>/api/v1/remove_room_from_zone?api_key=<API-Key>&room=<Room-ID>

{
"status": "succeeded",
"code": 0,
"error_message": "",
"result": "OK"
}