Karotz developper zone

Make your own Karotz application !

Web API

Please visit : How to start an apps (descriptor.xml, screen.xml)

Introduction

This page describes all specific methods defined in karotz scripts.

Concepts

Karotz Web API allows to remotly manipulate your Karotz through our servers.
First step is to create a session between your remote application and your Karotz, by getting an interactiveID.
After that, you can use the following functions to create your applications.

REST functions

Interactive mode

http://api.karotz.com/api/karotz/interactivemode

stop

Stop the current running application on Karotz

  • action (required): action to be done, must be “stop”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/interactivemode?action=stop&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Ears

http://api.karotz.com/api/karotz/ears

move

Move Karotz Ears to a position or continuously

  • left (optional): position of left ear, must be an integer
  • right (optional): position of right ear, must be an integer
  • relative (optional): move is relative to current position, must be true or false
  • reset (optional): reset position, must be true or false
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Raise Event when ears movements ends

Example

http://api.karotz.com/api/karotz/ears?left=20&right=-30&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Automatic Speech Recognition (ASR)

http://api.karotz.com/api/karotz/asr

grammar
  • grammar (required): grammar to be recognized ( “,” separator )
  • lang (optional): the language of the text to say. Default is EN
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Raise Event on recognition

Example

http://api.karotz.com/api/karotz/asr?grammar=yes,no&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

file
  • file (required): the file containing the grammar
  • interactiveId (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Raise Event on recognition

Example

http://api.karotz.com/api/karotz/asr?file=file.txt&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Led

Set the led color and behavior

pulse
  • action (required): behavior of the led, must be set to “pulse”
  • color (required): color of pulse, an hex color defined on 6 chars ex: FE78CC
  • period (required): period of the pulse behavior in milliseconds
  • pulse (required): period of a pulse in milliseconds
  • interactiveid (required): current session interactiveId, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Raise Event when pulse ends

Example

http://api.karotz.com/api/karotz/led?action=pulse&color=77FF44&period=3000&pulse=500&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

fade
  • action (required): behavior of the led, must be set to “fade”
  • color (required): color of fade, an hex color defined on 6 chars ex: FE78CC
  • period (required): period of the pulse behavior in milliseconds
  • interactiveid (required): current session interactiveId, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Raise Event when fade ends

Example

http://api.karotz.com/api/karotz/led?action=fade&color=77FF44&period=3000&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

light
  • action (required): behavior of the led, must be set to “light”
  • color (optional): color of light, an hex color defined on 6 chars ex: FE78CC, if omitted led off.
  • interactiveid (required): current session interactiveId, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/led?action=light&color=77FF44&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Text To Speech (TTS)

speak
  • action (required): must be set to “speak”
  • lang (optional): the language of the text to say. Default is EN
  • text (required): the text to say
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/tts?action=speak&lang=EN&text=hello%20world&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

stop
  • action (required): must be set to “stop”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/tts?action=stop&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Multimedia

play
  • action (required): behavior of the multimedia, must be set to “play”
  • url (required): Url that point the sound to play
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Raise Event when sound ends

Example

http://api.karotz.com/api/karotz/multimedia?action=play&url=http%3A%2F%2Fgoogle.com%2Ftest.mp3&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

pause
  • action (required): behavior of the multimedia, must be set to “pause”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=pause&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

resume
  • action (required): behavior of the multimedia, must be set to “resume”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>}

Example

http://api.karotz.com/api/karotz/multimedia?action=resume&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

stop
  • action (required): behavior of the multimedia, must be set to “stop”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=stop&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

previous
  • action (required): behavior of the multimedia, must be set to “previous”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=previous&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

next
  • action (required): behavior of the multimedia, must be set to “next”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=next&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

record
  • action (required): behavior of the multimedia, must be set to “play”
  • url (required): Url where the recorded sound will be post
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=record&url=http%3A%2F%2Fgoogle.com%2Frecord&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

list all songs
  • action (required): behavior of the multimedia, must be set to “allsong”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>...
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=allsong&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

list folders
  • action (required): behavior of the multimedia, must be set to “folder”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>...
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=folder&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

list artists
  • action (required): behavior of the multimedia, must be set to “artist”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>...
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=artist&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

list genre
  • action (required): behavior of the led, must be set to “genre”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>...
</voosmsg>

Example

http://api.karotz.com/api/karotz/multimedia?action=genre&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

list playlist
  • action (required): behavior of the led, must be set to “playlist”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>...
</voosmsg>

http://api.karotz.com/api/karotz/multimedia?action=playlist&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Webcam

http://api.karotz.com/api/karotz/webcam

photo

Post a picture from the webcam to a specified URL

  • action (required): behavior of the webcam, must be set to “photo”
  • url (required): URL where the picture should be post
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

api/karotz/webcam?action=photo&url=http://blah&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

video (MJPEG)

Get a MJPEG stream

  • action (required): behavior of the webcam, must be set to “video”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

api/karotz/webcam?action=video&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

The stream can be displayed in a html page :

<img src="http://api.karotz.com/api/karotz/webcam?action=video&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc" />

choreography

http://api.karotz.com/api/karotz/choreography

start

Start a choreography on karotz_

  • start (required): the choreography to play
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/choreography?start=THECHOREOGRAPHY&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

file
  • file (required): play the choreography defined in file
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/choreography?file=choreography1.cho&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

stop
  • action (required): behaviour of the karotz must be set to “stop”
  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
  <id>28665c15-bd73-4bbd-b2b8-02703cba8ee9</id>
  <correlationid>73b1200d-2e23-46be-961e-a88a5590f020</correlationid>
  <interactiveid>5c1e5b94-927e-44a7-b096-a29d188a21a7</interactiveid>
  <response>
    <code>OK</code>
  </response>
</voosmsg>

Example

http://api.karotz.com/api/karotz/choreography?action=stop&interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Config

http://api.karotz.com/api/karotz/config

Retrieve config of the current instance

  • interactiveid (required): current session interactiveid, see Authentication and InteractiveMode section

Response:

<voosmsg>
...
</voosmsg>

Example

http://api.karotz.com/api/karotz/config?interactiveid=3e910454-a6e4-48b0-bd16-4483360947fc

Example of php callback

For a double clic on the button, callback data contain :

<voosmsg>
    <id>message id</id>
    <interactiveId>interractive id</interactiveId>
    <buttonCallback>
        <type>DOUBLE</type>
    </buttonCallback>
</voosmsg>

PHP example :

<?php
if($_GET["interactiveid"]){
    //first callback start interractive mode
    session_start();
    $_SESSION['interactiveid']=$_GET["interactiveid"];
    header('Location: /test/started_prod.php');
 
    $h = fopen("received.txt", 'a');
    fwrite($h, "interactiveID received: " . $_SESSION['interactiveid']);
    fwrite($h,"\n==============\n");
    fclose($h);
}
else {
    //posted event
    $data = file_get_contents("php://input");

    try {
        $voosMsg =simplexml_load_string($data);

        $interactiveId = $voosMsg->interactiveId;
        $type = $voosMsg->buttonCallback->type;
        if ( isset($type) && isset($interactiveId))
        {
            if($type == "DOUBLE")
            {
                //EXIT
                doGet("http://api.karotz.com/api/karotz/interactivemode?action=stop&interactiveid=" . $interactiveId);
            }
        }
    }
    catch (Exception $e) {
        fwrite($h, 'Exception : ' .  $e->getMessage() . "\n");
    }
}
?>
Google Groupes
Abonnement au groupe KarotzDev
E-mail :
Visiter ce groupe