T2S Interface
Zusätzlich stellt das Plugin eine bi-direktionale Schnittstelle für Drittanwendungen bzw. Plugins zur Verfügung. Mit Hilfe dieser Schnittstelle können T2S Requests per http-POST Befehl oder JSON request geschickt werden, welche dann vom T2S Plugin in MP3 Dateien umgewandelt und gespeichert werden. Die notwendigen Infos zum weiteren Prozessieren in Drittanwendung/Plugin werden dann in einem JSON Response zur Verfügung gestellt.
T2S Request
Der Request um eine T2S zu generieren muss über http-POST im JSON Format an folgende URL gesendet werden. Wie man diesen Request in der jeweiligen Programmiersprache umsetzt muss der Entwickler eroieren, das würde a: hier den Rahmen sprengen und b: ich kenne nicht alle Sprachen:
http://<LOXBERRY IP>/plugins/text2speech/index.php
Um den Text, der in eine MP3 umgewandelt werden soll, mitzuschicken muss in der URL-Syntax der Drittanwendung/Plugin der Text deklariert sein z.B. über einen Parameter &text=Dies ist ein test
Zusätzlich liefert das Plugin per Zufallsgenerator 5 verschiedene Grußtexte je nach Tageszeit die ebenfalls mit generiert werden können (näheres dazu siehe oben). Um diese Grußtexte vor der eigentlichen MP3 miteinzubinden muss zusätzlich der Parameter &greet angegeben werden. Wenn &greet mitangeben wurde muss dieser zur Vorbereitung des Requests entweder mit einer 0 (Null) oder einer 1 (Eins) gefüllt werden. &greet=1.
Beispiel Syntax aus dem Sonos Plugin heraus. Der Text "Dies ist ein Test" mit einer vorangestellten Grußformel soll in eine MP3 gewandelt und anschließend auf dem Player "kueche" angesagt werden:
http://<LOXBERRY-IP/plugins/sonos4lox/index.php/?zone=kueche&action=ttsp&t2stext=Dies ist ein test$greeting
Der Text "Dies ist ein Test" ohne einer vorangestellten Grußformel soll in eine MP3 gewandelt und anschließend auf dem Player "kueche" angesagt werden:
http://<LOXBERRY-IP/plugins/sonos4lox/index.php/?zone=kueche&action=ttsp&t2stext=Dies ist ein test
// extrahiere den Inhalt von &text aus der Syntax $text = ($_GET['t2stext']); // prüfe ob &greet angegeben wurde if (isset($_GET['greeting'])) { // &greet wurde in der Syntax mitangegeben $greet = 1; } else { // &greet wurde in der Syntax nicht mitangegeben $greet = 0; }
Die verwendeten Parameter sind grundsätzlich frei wählbar, müssen dann nur für den POST request in die entsprechenden Variablen geschrieben werden.
Generiere JSON Daten
Zur Vorbereitung des Requests müssen die gelesenen Parameter aus der Syntax in eine Array übertragen und anschließend JSON encoded werden. Dies erfolgt wie im obigen Abschnitt beschrieben über das Auslesen der Syntax und mit anschließender Übergabe an das zu erstellende Array, welches dann in das JSON Format konvertiert werden muss. Hier ein PHP code Beispiel:
// erstelle ein Array (named keys) mit den ausgelesenen Parametern. // Die Keys 'text' bzw. 'greet' müssen verwendet werden da sonst das Interface den Request fehlinterpretiert und keine T2S generiert wird $jsonData = array('text' => $text,'greet' => $greet); // Wandele das erstellte Array in das JSON Format. $jsonDataEncoded = json_encode($jsonData);
Das war es im Grunde schon zur Vorbereitung des T2S Requests. Mit Hilfe der URL und der JSON Daten muss jetzt der Request an das Text2speech Plugin zur Generierung der MP3 Files gesendet werden. Um eine erfolgreiche Übertragung zu gewährleisten muss dem http-request im content header noch das entsprechende Datenformat mitgegeben werden. Dieses lautet 'Content-Type: application/json'. und der komplette Request muss noch als Typ POST deklariert werden
Kompletter Request
Hier ein komplettes Bespiel eine T2S Requests aus PHP (Sonos Plugin) heraus welches zusätzlich die cURL Library nutzt:
Validierung des Requests
Das Text2speech Plugin validiert ob der empfangene Request korrekt empfangen wurde und loggt den jeweiligen Status. Hier der entsprechende Code, der aber für den Entwickler nicht maßgeblich ist:
T2S Answer
Das Text2speech Plugin nimmt das Request welches per Interface reinkommt, wandelt den Text, ggf. mit vorangestellter Grußformel, in eine MP3 um und speichert diese. Den Speicherort der MP3 kann sich der User im Plugin selber aussuchen, es werden aber nur read AND write Verzeichnisse unterstützt. Im Falle der User hat ein USB device als Speicherort gewählt, wird das MP3 file in den Standard plugindata folder (/opt/loxberry/data/plugins/text2speech/) verschoben und ist somit vom Interface nutzbar.
Der genaue Speicherort der MP3, und alle anderen notwendigen Details, werden in Form einer JSON Datei an einem fixen Platz auf dem LoxBerry abgelegt. Mit Hilfe dieser Information kann dann in der Drittanwendung/Plugin die Verarbeitung fortgesetzt werden.
Antwortdetails
Nach der Abarbeitung des T2S Requests und dem Erstellen der MP3 Datei generiert das Interface ein Array, welches anschließend in eine JSON codierte Datei mit folgendem Inhalt gespeichert wird:
Array ( [full-ttspath] => /opt/loxberry/data/plugins/text2speech/test/tts/945d31838a43c3ed8b59f4e30a6f5989.mp3 [path] => /opt/loxberry/data/plugins/text2speech/test/ [full-cifsinterface] => //192.168.50.xx/plugindata/text2speech/interfacedownload/945d31838a43c3ed8b59f4e30a6f5989.mp3 [cifsinterface] => //192.168.50.xx/plugindata/text2speech/interfacedownload/ [full-httpinterface] => http://192.168.50.xx/plugins/text2speech/interfacedownload/945d31838a43c3ed8b59f4e30a6f5989.mp3 [httpinterface] => http://192.168.50.xx/plugins/text2speech/interfacedownload/ [mp3-filename-MD5] => 945d31838a43c3ed8b59f4e30a6f5989 [duration-ms] => 3264 [bitrate] => 32000 [sample-rate] => 24000 [text] => Dies ist ein test )
Hier einige Details zu den jeweiligen Keys:
im Key full-ttspath befindet sich der komplette LoxBerry Pfad und der Dateiname der erstellten MP3 Datei (nur für LoxBerry Plugins nutzbar)
- im Key path befindet sich nur der Pfad (nur für LoxBerry Plugins nutzbar)
- im Key full-cifsinterface befindet sich die komplette URL mit Pfad und der Dateiname der erstellten MP3 Datei (für Drittanwendungen nutzbar)
- im Key cifsinterface befindet sich die komplette URL mit Pfad (für Drittanwendungen nutzbar)
- im Key full-httpinterface befindet sich die komplette http URL mit Pfad und der Dateiname der erstellten MP3 Datei (für Drittanwendungen nutzbar)
- im Key httpinterface befindet sich die komplette http URL mit Pfad (für Drittanwendungen nutzbar)
- im Key mp3-filename-MD5 befindet sich der Dateiname
- im Key duration-ms befindet sich die Nettospieldauer der MP3
- im Key bitrate befindet sich die bitrate der MP3
- im Key sample-rate befindet sich die samplerate der MP3
- im Key text befindet sich der Text der in eine MP3 umgewandelt wurde.
Am einfachsten ist es den Key full-path für LoxBerry Plugins bzw. den Key full-server-URL für Drittanwendungen zu nutzen da sämtliche relevante Daten enthalten sind
Nach erfolgter JSON Codierung sieht das File dann folgendermaßen aus:
{"full-ttspath":"\/opt\/loxberry\/data\/plugins\/text2speech\/test\/tts\/945d31838a43c3ed8b59f4e30a6f5989.mp3","path":"\/opt\/loxberry\/data\/plugins\/text2speech\/test\/","full-cifsinterface":"\/\/192.168.50.xx\/plugindata\/text2speech\/interfacedownload\/945d31838a43c3ed8b59f4e30a6f5989.mp3","cifsinterface":"\/\/192.168.50.xx\/plugindata\/text2speech\/interfacedownload\/","full-httpinterface":"http:\/\/192.168.50.xx\/plugins\/text2speech\/interfacedownload\/945d31838a43c3ed8b59f4e30a6f5989.mp3","httpinterface":"http:\/\/192.168.50.xx\/plugins\/text2speech\/interfacedownload\/","mp3-filename-MD5":"945d31838a43c3ed8b59f4e30a6f5989","duration-ms":3264,"bitrate":32000,"sample-rate":24000,"text":"Dies ist ein test"}
Das generierte JSON file wird statisch abgelegt und hat einen festen Dateinamen. Um das File für alle Anwendungen zugänglich zu machen liegt es in einem separaten Verzeichnis im plugindata samba share. Der genaue Pfad lautet:
/opt/loxberry/plugindata/text2speech/interface/
und der dazugehörige Dateiname lautet:
t2s_source.json
Von hier kann es von der Drittanwendung bzw. dem Plugin eingelesen und weiterverarbeitet werden.
Beispiel einer Weiterverarbeitung der JSON Datei aus dem Sonos Plugin.
Wenn Unterstützung während der Entwicklung notwendig ist bin ich gerne behilflich.