API Client

Config

Global object of the A.V.A.T.A.R client configuration.

{
    "language": "en",  // the application language
    "version": "4.0.0", // application version
    "http": {
        "server": { "port": "3000" }, // server IP
        "client": { "ip": "127.0.0.1", "port": "", "route": "" } // client IP
    },
    "UDP": { "port": "3333", "target": "192.168.2.88"," restart": 15 }, // udp target, port
    "modules": {  // properties of loaded plugins (see below)
        ...  
    }
    ....
}

const lang = Config.language;
// returns "en"

const ip = Config.http.client.ip;
// returns "127.0.0.1"

Config.modules

Plugin configuration object. This object is generally used to retrieve a property key value.

<Plugin>.prop<Plugin>.js

 {
    "modules": { 
        "myFirstPlugin": {
            "version": "1.0",
            "name": "my first plugin",
            "rules": {
                "test": ["test * (command|order)"]
            }
        }
    }
}

 const name = Config.modules.myFirstPlugin.name;
 // returns "my first plugin"

Message loggers

Logger methods are used to display messages in the A.V.A.T.A.R. client console.

All methods are identical to the server methods. Please, see the Message loggers section of the API server for further details.

Warning

infoConsole is displayed by clicking on the F10 key (F11 on the server).

Dialog

Avatar.speak(tts[,callback, end, voice, volume, speed, pitch])

Executes a tts on audio system (loudspeaker or other declared system).

Parameter	Type	Mandatory	Default value	Values	Description
tts	string object	yes			The text or an array of texts to be vocalized. Can be a single text, several texts separated by a pipe ('|') or an array of texts (texts can be separated by a pipe ('|')). One of the values will be chosen at random
callback	function	no			Callback function executed after speak
end	boolean	no	true	true false	Defines if the client's listening is restituted after speak true: restores listening false: does not restore listening
voice	string	no	Config .voices .current[Config.voices.type]		Voice to use
volume	number	no	Config.voices.volume		Voice volume
speed	number	no	Config.voices.speed		Voice speed
pitch	number	no	Config.voices.pitch		Voice pitch

Examples :

1. Vocalizes le tts and restores listening

   Avatar.speak('Hello, what can i do for you?')
   

2. Vocalizes one of the tts randomly on the Living room client and restores listening

   Avatar.speak('Hello, what can i do for you?|Hi, can I help you?')
   

3. Vocalizes one of the tts randomly and does not restore listening

   Avatar.speak('Hello, what can i do for you?|Hi, can I help you?', null, false)
   

4. Vocalizes the tts, restores listening and executes a callback

   Avatar.speak(['Hello, what can i do for you?', 'Hi, can I help you?'], () => {
       // Do stuff
   })
   

5. Vocalizes the tts, does not restore listening and executes a callback

   Avatar.speak('Hello, what can i do for you?', () => {
       // Do stuff
   }, false)
   

6. Vocalizes one of the tts randomly, does not restore listening and executes a callback

   Avatar.speak(['Hello, what can i do for you?|Hi, can I help you?', 'I\'m home. Can I get you anything?'], () => {
       // Do stuff
   }, false)
   

7. Vocalizes the tts with a specific voice definition and restores listening

   // definition: voice name, volume, speed, pitch
   Avatar.speak('Hello, what can i do for you?',null, null, "Microsoft Julie - French (France)", 100, 80, 1)
   
   //Another definition: voice name and speed
   Avatar.speak('Hello, what can i do for you?', null, null,"Microsoft Julie - French (France)", null, 70)
   

Avatar.Listen.end([activateListen])

Restores listening to the client.

Parameter	Type	Mandatory	Default value	Values	Description
activateListen	boolean	no	true	true false	Defines if the listening restoration must be performed In all cases, the unmute method is executed

Examples:

1. Restores listening

   // Reactivation of listening
   Avatar.Listen.end();
   
   // Do stuff
   

2. tts on the client without listening restoration (end = false) then, after executing an action in the callback, restores listening

   Avatar.speak('Hello, what can i do for you?', () => {
       // Do Stuff
       // .......
   
       // Then reactivation of listening
       Avatar.Listen.end();
   }, false) 
   

Avatar.Listen.stop(forced)

Stops listening

Parameter	Type	Mandatory	Description
forced	boolean	no	Forces listening to stop even if the listening is already stopped normally

Avatar.Listen.stop(true);

Avatar.Listen.start(forced)

Restarts listening

Parameter	Type	Mandatory	Description
forced	boolean	no	Forces listening to restart even if the listening is already running normally

Avatar.Listen.start(true);

Avatar.Listen.startListenAction()

Triggers a dialog (same as trigger keyword).

Avatar.Listen.startListenAction();

Avatar.Listen.stopListenAction([forced])

Stops current dialog.

Parameter	Type	Mandatory	Default value	Values	Description
forced	boolean	no	true	true false	Defines if the listening restoration must be performed In all cases, the unmute method is executed

Avatar.Listen.stopListenAction(true);

Music play

Avatar.play(music[, type, end, callback])

Plays a sound file.

Parameter	Type	Mandatory	Default value	Values	Description
music	string	oui			The sound file to be played. Can be: - A file - A local or remote web address. __dirname is replaced by <A.V.A.T.A.R>/resources/app/core
type	string	yes		local url	- local: File on client or server - url: Local or remote http link
end	string	no	after	before after	Defines whether the listening restoration on the client is performed before or after the sound file is played
callback	function	no			Callback function executed after playing the sound file

Examples:

1. Absolute path, reactivates listening before playing, no callback

   Avatar.play('C:/music/siren.mp3', 'before'); 
   

2. <A.V.A.T.A.R>/resources/app/core path on the client, reactivates listening after playing and a callback
   

   Avatar.play('__dirname/music/siren.mp3', 'local', 'after', () => {
      // Do stuff
   }); 
   

3. Music on the web, reactivates listening after playing and a callback
   

   Avatar.play("https://ccrma.stanford.edu/~jos/mp3/cello.mp3", 'url', () => {
       // Do stuff
   });
   

4. HTTP static folder, reactivates listening after playing

   const music = `http://${Config.http.client.ip}:${Config.http.client.port}/Love_Is_a_Battlefield.mp3`;
   
   // sets static local folder
   Avatar.static.set('C:/music', () => {
       // Plays music
       Avatar.play(music, 'url');
   });
   

Avatar.stop([callback])

Stops sound file playback.

Parameter	Type	Mandatory	Description
callback	function	no	Callback function executed after playback stop

Exemple :

Avatar.stop();

Files & folders

Avatar.static.set(folder[, calbback])

Defines a static folder on the client.

Parameter	Type	Mandatory	Description
folder	string	yes	Folder to be set static
callback	function	no	Callback function

Example:

// sets static folder on the client
Avatar.static.set('C:/music', () => {
     // Do stuff
});

Plugin methods

Avatar.getProperty(file[, property])

Returns the properties of the JSON file or the value of property.

Identical to the server method. Please, see the getProperty() method section of the API server for further details.

Avatar.trigger(listener[, options])

Triggers a listener module.

Identical to the server method. Please, see the trigger() method section of the API server for further details.

Avatar.listen(listener[, callback(options)])

Declaration of a listener module.

Identical to the server method. Please, see the listen() method section of the API server for further details.

Avatar.call(plugin[, options, callback])

Calls a plugin to be executed.

Identical to the server method. Please, see the call() method section of the API server for further details.

Avatar.run(plugin[, options, callback])

Same to Avatar.call() but is executed for a plugin call by an HTTP request unlike Avatar.call().

Identical to the server method. Please, see the run() method section of the API server for further details.

Avatar.find(plugin)

Searchs for the script of a plugin. Usefull to execute a exported method of the plugin.

Identical to the server method. Please, see the find() method section of the API server for further details.

Avatar.exists(plugin)

Test if the plugin exists.

Identical to the server method. Please, see the exists() method section of the API server for further details.

Language pack

Language packs allow you to localize the plugin's messages. Language packs must be created in the plugin's locales directory and be in the form <country shortcode>.pak.

All methods are identical to the server methods. Please, see the Language pack section of the API server for further details.

Encrypt/decrypt a value

These functions add extra protection to data stored on disk, using the cryptography provided by the operating system.

All methods are identical to the server methods. Please, see the Encrypt/decrypt a value section of the API server for further details.

HTTP request

Plugin access via HTTP request.

Format: http://<IP address>:<Port>/avatarclient-<route>/<Plugin>?key=value&key=value

Parameter	Mandatory	Description
IP address	yes	A.V.A.T.A.R. client IP address
Port	yes	A.V.A.T.A.R. client communication port
route	yes	The HTTP route defined in the client properties. The prefix avatarclient- is automatically added.
Plugin	yes	The name of the plugin to run
key=value	no	The parameters of the data object to be passed to the plugin's action method If a parameter key is equal to command then the data object will be {action: {command: value, key: value} sinon {key: value}

Tip

The HTTP port and route must be defined in the Plugin properties.

Examples:

/** Client IP address: 192.168.2.35
// Port: 4100
// Route: '[avatarclient-]livingroom'
// Plugin: myPlugin
// keys: command=updateInfo&id=225665
// Object data received in the plugin: {action: {command: updateInfo, id: 225665}}
*/
try {
    const response = await axios (url: 'http://192.168.2.35:4100/avatarclient-livingroom/myPlugin?command=updateInfo&id=225665');
    if (response.status !== 200) {
        throw new Error ('status '+response.status);
    }
} catch (err) {
    error ('HTTP error:', err);
}

/** Serveur IP address: 192.168.2.35
// Port: 4100
// Route: '[avatarclient-]livingroom'
// Plugin: myPlugin
// keys: id=225665
// Object data received in the plugin: {id: 225665}
*/
try {
    const response = await axios ('http://192.168.2.35:4100/avatarclient-livingroom/myPlugin?id=225665');
    if (response.status !== 200) {
        throw new Error ('status '+response.status);
    }
} catch (err) {
    error ('HTTP error:', err);
}

Interface

Avatar.Interface.mainWindow()

Returns the BrowserWindow instance of A.V.A.T.A.R.'s main window.

NOTE: See the Avatar.Interface.mainWindow() server API method for more details.

Avatar.Interface.BrowserWindow(options, html[, isMenu])

Creates a new BrowserWindow with the native properties defined by the options.

NOTE: See the Avatar.Interface.BrowserWindow() server API method for more details.

Avatar.Interface.ipcMain()

Allows asynchronous communication from the main process with rendering processes.
Returns A.V.A.T.A.R.'s ipcMain module.

NOTE: See the Avatar.Interface.ipcMain() server API method for more details.

Avatar.Interface.Menu()

Returns Menu module.

NOTE: See the Avatar.Interface.Menu() server API method for more details.

Avatar.Interface.dialog()

Returns dialog module.

NOTE: See the Avatar.Interface.dialog() server API method for more details.

Avatar.Interface.shell()

Returns shell module.

NOTE: See the Avatar.Interface.shell() server API method for more details.

Avatar.Interface.globalShortcut()

Returns globalShortcut module.

NOTE: See the Avatar.Interface.globalShortcut() server API method for more details.

Avatar.Interface.showRestartBox(msg)

Displays a restart dialog box in the A.V.A.T.A.R. interface.

NOTE: See the Avatar.Interface.showRestartBox() server API method for more details.

Developer Guide