Client Integration
Client integration is based on web socket provided by Core runner service.

Java/Android Client

If you want to create your own client in Java or Android platforms, you can use Promethist Common Client library for that. The whole source code of it is a part of Promethist Core project and can be found on GitHub.
We recommend using Java version 8 (Oracle or OpenJDK). Newer version can have certain problems with specific functionalities (e.g. screen visualisations based on JavaFX technology) therefore we do not officially support them yet.
First, add PromethistAI artifact repository to your project
Maven
Gradle
1
<repositories>
2
<repository>
3
<id>promethistai</id>
4
<name>PromethistAI repository</name>
5
<url>https://repository.promethist.ai/maven/</url>
6
</repository>
7
</repositories>
Copied!
1
allprojects {
2
repositories {
3
maven { url 'https://repository.promethist.ai/maven/' }
4
}
5
}
Copied!
and set dependency to promethist-client-common to your project or module
Maven
Gradle
1
<dependency>
2
<groupId>org.promethist.client</groupId>
3
<artifactId>promethist-client-common</artifactId>
4
<version>2.19</version>
5
</dependency>
Copied!
1
dependencies {
2
implementation 'org.promethist.client:promethist-client-common:2.19'
3
}
Copied!
Latest stable version number can be checked here

Callback Object

First of all, every client has to implement BotClientCallback interface - following example demonstrates it (you can replace method implementations just printing what's has occurred with audio/visual processing logic of your client)
1
class Callback : BotClientCallback {
2
3
override fun onOpen(client: BotClient) = println("{Open}")
4
override fun onReady(client: BotClient) = println("{Ready}")
5
override fun onClose(client: BotClient) = println("{Closing}")
6
override fun onError(client: BotClient, text: String) = println("{Error $text}")
7
override fun onFailure(client: BotClient, t: Throwable) = t.printStackTrace()
8
override fun audioCancel() = println("{Audio Cancel}")
9
override fun command(client: BotClient, command: String, code: String?) = println("{Command $command $code}")
10
override fun httpRequest(client: BotClient, url: String, request: HttpRequest?) = HttpUtil.httpRequest(url, request)
11
12
override fun onSessionId(client: BotClient, sessionId: String?) = println("{Session ID $sessionId}")
13
override fun onBotStateChange(client: BotClient, newState: BotClient.State) = println("{State change to $newState}")
14
override fun onWakeWord(client: BotClient) = println("{Wake word}")
15
16
override fun audio(client: BotClient, data: ByteArray) = println("{Audio ${data.size} bytes}")
17
override fun video(client: BotClient, url: String) = println("{Video $url}")
18
override fun image(client: BotClient, url: String) = println("{image $url}")
19
override fun text(client: BotClient, text: String) = println("< $text")
20
21
override fun onRecognized(client: BotClient, text: String) = println("> $text")
22
override fun onLog(client: BotClient, logs: MutableList<LogEntry>) = logs.forEach { println(it) }
23
}
Copied!
Then, you need to create BotContext object defining relation between client a conversational application
1
val context = BotContext(
2
"https://core.promethist.com", // Core service URL
3
"5ea17702d28fd40eec1e9076", // application ID
4
"device_ID", // CHANGE TO unique sender device identification
5
Dynamic("clientType" to "client_type:1.0.0-SNAPSHOT"), // CHANGE TO your-client-name:version
6
autoStart = false // set to true if you want to start application immediately as soon as client is open
7
)
Copied!

Bot Client

Client is represented by BotClient class which implements network communication with the Core service using web socket, processing input audio and playing output audio. To understand better networking part of implementation please take a look on web socket page too.

State

It is always in one of following states accessible via public property state
State
Description
Sleeping
No conversation is going on
Listening
Waiting for user input (if input audio device is available as described below, sending input audio to the server; otherwise waiting for text input by calling doText method)
Processing
User text input sent or text recognized in input audio on server side, waiting for response
Responding
Processing server response = display response text(s)/images and playing audio(s). As soon as the last audio play is finished it will go back to Listening state IF the response have not finished session (in that case client goes immediately to Sleeping state)
Open
Short time state between opening web socket and obtaining response to Init event.
Closed
Network connection is closed (after calling close method)
Failed
Network connection has failed. Client will keep trying to restore it every 20 seconds

Methods

Method
Description
open()
Open communication to the server. Call this method first and once before any other
doText(text: String, attributes: PropertyMap = emptyMap())
Send text input to the server e.g. #signal, what's the weather. Optionally you can also use this method to update some client attributes
doIntro()
Initiate conversation - equal to call toText("#intro")
touch()
Touch client (usually - client calls it after user clicks or touches "play" button). Depending on client state
  • Sleeping - cancel audio playing, calls doIntro()
  • Responding - if client has pausing enabled, it will pause; otherwise output audio will be canceled and client will go to Listening
  • Paused - resume output audio
  • Closed or Failed - error audio response
close()
Close client. Output audio play is cancelled, input audio device and network socked are close.

Text Bot

If you want to create client without audio support, you can instantiate BotClient without AudioDevice object
1
val audioDevice: AudioDevice? = null
2
val client = BotClient(context, OkHttp3BotClientSocket(context.url), audioDevice, Callback())
3
client.open()
Copied!
You can try to create simple client using standard input/output handling TextConsole object
1
val console = TextConsole() {
2
override fun afterInput(text: String) = client.doText(text)
3
}
4
console.run()
Copied!

Voice Bot

If you want to create voice (input audio) using client, you have to create object of AudioDevice class and pass it to BotClient constructor. When using Java JRE, you can take Microphone class from Standalone application using Java Sound API.
1
val audioDevice = Microphone()
2
3
// if your microphone has multiple channels, you have to specify
4
// count and index of microphone channel to be used
5
val audioDevice = Microphone(channels = 6, channel = 1)
Copied!
Microphone sample rate is set to 16000 Hz, size 16 bits, signed, little endian by default.

Custom Input Audio Device

If case that you have specific device providing audio input you can implement your own InputAudioDevice
1
class MyAudioDevice : InputAudioDevice() {
2
override fun read(buffer: ByteArray): Int = TODO("Add audio data reading code here")
3
}
Copied!
Example of custom InputAudioDevice implementation for Android
1
class AudioRecorder(var autoClose: Boolean = false) : InputAudioDevice() {
2
3
companion object {
4
5
private val SAMPLE_RATE_CANDIDATES = intArrayOf(16000, 11025, 22050, 44100)
6
private val CHANNEL = AudioFormat.CHANNEL_IN_MONO
7
private val ENCODING = AudioFormat.ENCODING_PCM_16BIT
8
}
9
10
var bufferSize: Int = 0
11
var audioRecord: AudioRecord? = null
12
13
override fun start() {
14
audioRecord = createAudioRecord()
15
audioRecord!!.startRecording()
16
if (audioRecord?.recordingState == AudioRecord.RECORDSTATE_RECORDING)
17
super.start()
18
}
19
20
override fun stop() {
21
super.stop()
22
if (audioRecord?.state == AudioRecord.RECORDSTATE_RECORDING)
23
audioRecord?.stop()
24
audioRecord?.release()
25
audioRecord = null
26
}
27
28
override fun read(buffer: ByteArray): Int = audioRecord!!.read(buffer, 0, buffer.size)
29
30
private fun createAudioRecord(): AudioRecord {
31
for (sampleRate in SAMPLE_RATE_CANDIDATES) {
32
var sizeInBytes = AudioRecord.getMinBufferSize(sampleRate, CHANNEL, ENCODING)
33
if (sizeInBytes == AudioRecord.ERROR_BAD_VALUE) {
34
continue
35
}
36
sizeInBytes = sizeInBytes * 4
37
val audioRecord = AudioRecord(
38
MediaRecorder.AudioSource.MIC,
39
sampleRate,
40
CHANNEL,
41
ENCODING, sizeInBytes
42
)
43
if (audioRecord.state == AudioRecord.STATE_INITIALIZED) {
44
bufferSize = sizeInBytes
45
return audioRecord
46
} else {
47
audioRecord.release()
48
}
49
}
50
throw RuntimeException("Cannot instantiate AudioRecorder")
51
}
52
}
Copied!
Last modified 9mo ago