Example Workflow

In this section an example workflow is described to show how this Socket.IO Channel API can be used create a Register Session. python client implementation will be used to show code snippets.

Warning

SocketIO library implements two types of transports: HTTP long-polling and WebSocket. We encourage you to use WebSocket transport when implementing a client as in the example below.

Let's suppose that the base URL of the service is: https://api.eu.veri-das.com/socket.io. Let's also suppose that the base URL of the Authentication server is: https://api.eu.veri-das.com/socket.io/oauth2/token.

# example.py

import socketio
import requests

sio = socketio.Client()

@sio.on('*', namespace='/socket.io/register')
def catch_all(event, data, collected_audio):
    print(data)
    if event == 'info-consumer-ready':
        # Start sending audio
    elif event == 'result-success':
        # Store collected_audio for later use

def get_access_token():
    url = "https://api.eu.veri-das.com/socket.io/oauth2/token"
    payload={
        'client_id': '$CLIENT_ID',
        'client_secret': '$CLIENT_SECRET',
        'grant_type': 'client_credentials'
    }
    response = requests.request("POST", url, data=payload)
    return response.json()

token = get_access_token()
headers = {
    'Authorization': f'{token["token_type"]} {token["access_token"]}'
}
sio.connect(
    'https://api.eu.veri-das.com/socket.io',
    headers=headers,
    namespaces=['/socket.io/register'],
    transports=['websocket']
)
data = {
    'metadata': {
        'audio_protocol': 'audiohook',
        'audio_format': 'raw',
        'audio_codec': 'mulaw',
        'sample_format': '',
        'sample_rate': '8000',
        'channels': '1',
        'call_id': '888806c3-3391-4d73-bb86-e5874e6ed5b4'
    },
    'register_request': {
        'authenticity_threshold': 0.8,
        'audio_total_duration': 5.0,
        'model_hash': '<MODEL_HASH>'
    }
}
sio.emit('initialize', data, namespace='/socket.io/register')
sio.wait()

Let's analyze this snippet on the following steps.

Step1: Create Socket.IO client and listen for events

First, a Socket.IO client is initialized using python-socketio library.

sio = socketio.Client()

Then, a listener for all events in /socket.io/register namespace is created.

@sio.on('*', namespace='/socket.io/register')
def catch_all(event, data):
    print(data)
    if event === 'info-consumer-ready':
        # Start sending audio
    elif event == 'result-success':
        # Store collected_audio for later use

Note that when info-consumer-ready event is received, this is, a Register Session is created, user must start sending audio via Audio Channel.

Step2: Obtain an OAuth access token

As said, authentication method employed by Socket.IO channel API is OAuth 2.0 Client Credentials Grant. Then, first, a valid access token is needed in order to call the service. Users will need to have a valid CLIENT_ID and a valid CLIENT_SECRET to call authentication server.

def get_access_token():
    url = "https://api.eu.veri-das.com/socket.io/oauth2/token"
    payload={
        'client_id': '$CLIENT_ID',
        'client_secret': '$CLIENT_SECRET',
        'grant_type': 'client_credentials'
    }
    response = requests.request("POST", url, data=payload)
    return response.json()

token = get_access_token()

Once a response is obtained from authentication server, Authorization header must be created in order to call das-Peak Streaming.

headers = {
    'Authorization': f'{token["token_type"]} {token["access_token"]}'
}

Step3: Connect to server and start registration process

To connect server, Socket.IO client is employed:

sio.connect(
    'https://api.eu.veri-das.com/socket.io',
    headers=headers,
    namespaces=['/socket.io/register'],
    transports=['websocket']
)

Note how websocket transport is used here.

Then, initialize event is emmited to start a registration process.

data = {
    'metadata': {
        'audio_protocol': 'audiohook',
        'audio_format': 'raw',
        'audio_codec': 'mulaw',
        'sample_format': '',
        'sample_rate': '8000',
        'channels': '1',
        'call_id': '888806c3-3391-4d73-bb86-e5874e6ed5b4'
    },
    'register_request': {
        'authenticity_threshold': 0.8,
        'audio_total_duration': 5.0,
        'model_hash': '<MODEL_HASH>'
    }
}
sio.emit('initialize', data, namespace='/socket.io/register')

Step4: Receiving results

When running this code with valid credentials and URLs, events are handled and printed as follows:

$ python example.py 
{"event": "info-consumer-ready", "content": "Audio consumer for provided audio protocol is ready"}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 0.0, "vad_percentage": 0}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 0.01, "vad_percentage": 0}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 0.52, "vad_percentage": 10}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 1.03, "vad_percentage": 20}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 1.54, "vad_percentage": 30}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 2.06, "vad_percentage": 41}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 2.57, "vad_percentage": 51}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 3.08, "vad_percentage": 61}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 3.59, "vad_percentage": 71}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 4.1, "vad_percentage": 82}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 4.62, "vad_percentage": 92}
{"event": "info-vad-status", "content": "Voice activity detection percentage", "audio_seconds": 5.13, "vad_percentage": 102}
{"event": "result-success", "authenticity": 0.99, "voice_audio_collected": 5.13, "content": "Registration: approved", "credential": "$CREDENTIAL"}