Interface

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:

// API Url
$url = 'http://<LOXBERRY-IP>/plugins/text2speech/index.php';
	
// Get text from syntax
$text = ($_GET['text']);

// Get greeting if requested
if (isset($_GET['greet']))  {
	$greet = 1;
} else {
	$greet = 0;
}

// Initiate cURL.
$ch = curl_init($url);
	 
// populate JSON data.
$jsonData = array(
	'text' => $text,
	'greet' => $greet
);
	 
// Encode the array into JSON.
$jsonDataEncoded = json_encode($jsonData);
		 
// Tell cURL that we want to send a POST request.
curl_setopt($ch, CURLOPT_POST, 1);
	 
// Attach our encoded JSON string to the POST fields.
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);
	 
// Set the content type to application/json
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json')); 
		 
// Execute the request
$result = curl_exec($ch);

// Optional
// was the request successful?
if($result === false)  {
	echo "ERROR: The POST wasn't successfull. Please check your code!";
} else {
	echo "The POST was successfull";
}
// close cURL
curl_close($ch);

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:

// Make sure that it is a POST request.
if(strcasecmp($_SERVER['REQUEST_METHOD'], 'POST') != 0){
	LOGERR("T2S Interface ** Request method must be POST!");
	exit;
}
	
// Make sure that the content type of the POST request has been set to application/json
$contentType = isset($_SERVER["CONTENT_TYPE"]) ? trim($_SERVER["CONTENT_TYPE"]) : '';
if(strcasecmp($contentType, 'application/json') != 0){
	LOGERR("T2S Interface ** Content type must be: application/json");
	exit;
}
	
// Receive the RAW post data.
$content = trim(file_get_contents("php://input"));
	
// Attempt to decode the incoming RAW post data from JSON.
$decoded = json_decode($content, true);
	
// If json_decode failed, the JSON is invalid.
if(!is_array($decoded)){
	LOGERR("T2S Interface ** Received content contained invalid JSON!");
	exit;
}
LOGOK("T2S Interface ** POST request has been successful processed!");
return ($decoded);

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.

// open file to retrieve data
// NOTE: Original path been generated by variables
$string = file_get_contents("/opt/loxberry/data/plugins/text2speech/share/t2s_source.json");

// decode JSON data into Array
$json_a = json_decode($string, true);

// select key full-server-URL and add to Play Queue
$sonos->AddToQueue("x-file-cifs://".$json_a['full-server-URL']);

// set Player to preselected Sonos Zone 'kueche'
$sonos->SetQueue("x-rincon-queue:".trim($sonoszone[$master][1])."#0");

// set Track to play from the actual position of the playlist
$sonos->SetTrack(1);

// set Zone specific Standard Volume for the T2S
$sonos->SetVolume($volume);

// Play T2S
$sonos->Play();

// wait until fully played
usleep($json_a['duration-ms'] * 1000);

// clear Queue
$sonos->ClearQueue();

Wenn Unterstützung während der Entwicklung notwendig ist bin ich gerne behilflich.