Sessions

Introduction

This sample project covers working with sessions and pipelines, which is the most advanced feature so far. While it may require some initial effort to get familiar with, it’s designed to simplify common workflows as much as possible. You will still need to adapt the configuration to match your VDK Service setup.

Assets

Along with this project, we provide you with assets you can use to try different features.

vdk-service-sample-assets-1.0.0.zip

Known limitations

The sample may not cover all use cases, but it is sufficient to get started and build your own implementation from it.

The main issue is that the sample has been designed around multiple one-time operations, whereas service sessions are continuous over time. The session WebSocket only supports a single connection.

Getting started

You can see the different routes available in: REST API ‎ in the Session section.

Python

Download and extract the zip below
Head inside the project
Create and activate a virtual environment (Python Venv documentation)
Install the project : pip install .
Run the script : vdk-session --help

If you see the list of options, you can start your configured VDK Service and interact with it using the options available.

VdkServiceSample-Session-Python-v1.0.0.zip

C#

Download and extract the zip below
Open the project solution (.sln)
Build and run project with the argument “--help”

If you see the list of options, you can start your configured VDK Service and interact with it using the options available.

VdkServiceSample-Session-CSharp-v1.0.0.zip

CLI Options

Connection

Basic parameters used to connect to the VDK Service.

--scheme, -P
Protocol to use (http or https)
Default: http
--host, -h
VDK Service host
Default: 127.0.0.1
--port, -p
VDK Service port
Default: 39806

Target Identifiers

Used to target specific resources.

--session-id, -s → Target session
--pipeline-id, -i → Target pipeline
--modifier-id, -m → Target modifier
--consumer-id, -o → Target consumer

Input / Configuration

Used when creating or updating resources.

--config, -c
Path to a JSON configuration file
(session creation, pipeline creation/update)
--filepath, -f
Path to an audio file to stream (WAV only)

Session Management

--list-sessions, -L
List all sessions
--session-status, -E
Get session status
--create-session, -A
Create a session (requires --config)
--delete-session, -D
Delete a session
--connect, -C
Open a WebSocket connection to a session

Pipeline Management

--create-pipeline, -I
Create a pipeline (requires --config)
--delete-pipeline, -H
Delete a pipeline
--load-pipeline, -B
Load a pipeline (allocate resources)
--unload-pipeline, -U
Unload a pipeline (release resources)

Pipeline Execution

--start-pipeline, -S
--stop-pipeline, -X
--pause-pipeline, -J
--resume-pipeline, -R

Pipeline Updates

--update-pipeline-producer, -T
--update-pipeline-modifier, -M
--update-pipeline-consumer, -O

Each command requires a configuration file (-c) specifying the fields to update. See the sessions documentation page for the supported options for each component.

Streaming

--stream, -V
Stream audio to the session using microphone if filepath (-f) isn’t specified.

This is only needed if you want to manage audio production yourself using a Stream Producer. Otherwise, you can use a File Producer or an AudioRecorder Producer.

Requires that no other terminal is already connected to the WebSocket (see Known Limitations).

Utilities

--run-sequence, -x
Run a full workflow (create session → load pipeline → start → stop → delete session)
Requires a configuration file (-c) like the following:

JSON

{
  "session_config": "path/to/session_configuration.json",
  "pipeline_id": "pipeline_name_to_run"
}

--verbose, -v
Enable verbose output

Example

This example shows a typical workflow using the sample project with VDK Service.

Create a session

Create a session --create-session(-A) using a configuration file --config(-c)

BASH

./vdk-session -A -c "path/to/session.json"
...
[INFO] Session created, id is : <session-id>

This session ID is required for most subsequent commands --session-id(-s).
You can also specify a pipeline upfront using --pipeline-id (-i).

BASH

./vdk-session -s "5ae7245bdf-424b-a1af-8fae-d460edfb6e" -i "mic_static_asr" (-B/-S/..)

Load the pipeline

Load the pipeline to allocate and lock the required resources: --load-pipeline(-B).

This example uses a VoiceRecognition consumer and an AudioRecorder as the producer. The pipeline is named mic_static_asr.

It assumes a valid configuration. Refer to the sample session configuration in the assets, or to the vdk-service sessions documentation.

BASH

./vdk-session -s "<session-id>" -i "mic_static_asr" -B

The pipeline is now ready to be started.

Connect to the session

Before starting the pipeline, connect to the session to receive events: --connect, -C

BASH

./vdk-session -C -s "<session-id>"

This terminal will display real-time events from the pipeline.

Start the pipeline

In another terminal, start the pipeline: --start-pipeline(-S)

BASH

./vdk-session -s "<session-id>" -i "mic_static_asr" -S

Stop and clean up

Stop the pipeline: --stop-pipeline(-X)

BASH

./vdk-session -s "<session-id>" -i "mic_static_asr" -X

Delete the session: --delete-session(-D)

BASH

./vdk-session -s "<session-id>" -D

Running a sequence

Managing commands manually can become tedious, especially when session IDs change frequently.

The --run-sequence (-x) option allows you to run a full workflow in a single command:

Workflow:
create session → load pipeline → start → stop → delete session

JSON

{
  "session_config": "path/to/session.json",
  "pipeline_id": "mic_static_asr"
}

BASH

./vdk-session -x -c "path/to/sequence.json"