Quick Start

This guide shows how to start a single-direction Voice Translation session using the Krisp Voice Translation SDK. In this example, spoken English audio is translated into Spanish in real time.

Each translation session processes audio in one direction (source → target). For bi-directional translation, create two independent sessions, one per direction.

High-Level Flow

All platform integrations follow the same basic flow:

Initialize the Voice Translation SDK
Create a translation session with source and target languages
Provide audio input to the session
Receive translated audio (and optional transcripts)
Stop and clean up the session

Installation

npm i @krisp.ai/krisp-vt-sdk

package.json:

{
  "dependencies": {
    "@krisp.ai/krisp-vt-sdk": "^1.1.1"
  }
}

The package ships ESM with TypeScript declarations and zero runtime dependencies. The SDK runs in the browser and needs a secure context (HTTPS or localhost) for microphone access.

Code Snippet (English → Spanish Translation)

import {
    KrispVTSDK,
    LogLevel
} from '@krisp.ai/krisp-vt-sdk';

// 1. Initialize SDK with your Krisp API key
const sdk = new KrispVTSDK({
    apiKey: 'YOUR_KRISP_API_KEY',
    logLevel: LogLevel.WARN, // NONE, ERROR, WARN, INFO, or DEBUG
});

// 2. Set up event hooks
sdk.setHooks({
    onProcessedAudio: (stream) => {
        // Play or send the translated audio
        const audio = new Audio();
        audio.srcObject = stream;
        audio.play();
    },
    onTranscript: (event) => {
        // Recognized speech in the source language
        console.log('Original:', event.text, event.final ? '(final)' : '(interim)');
    },
    onTranslate: (event) => {
        // Translated text in the target language
        console.log('Translated:', event.text);
    },
    onError: (error) => {
        console.error('SDK error:', error.code, error.message);
    },
});

// 3. Start translation service
await sdk.start({
    from: 'en-US', // Source language (BCP 47)
    to: 'es-ES', // Target language (BCP 47)
    voice: 'female', // 'male' or 'female' (default: 'male')
    transcript: { // Optional — omit to enable all three
        interim: true, // Partial results while the speaker talks
        final: true, // Completed utterances
        translate: true, // Translated text
    },
});

// 4. Get microphone and process audio
const mic = await navigator.mediaDevices.getUserMedia({
    audio: true
});
await sdk.process(mic);

// 5. Stop when done
await sdk.stop();

Text event shape

Both onTranscript and onTranslate receive the same object:

Field	Type	Description
`text`	`string`	Text as sent by the server. Never empty.
`final`	`boolean`	`false` for an interim result superseded by a later event, `true` for a completed utterance.
`utteranceId`	`string \| undefined`	Links the transcript and translate events of one utterance — use it to pair the two.
`start`	`string \| undefined`	ISO 8601 start of the covered audio. Transcript events only.
`durationMs`	`number \| undefined`	Duration of the covered audio in milliseconds. Transcript events only.

onTranscript requires transcript.interim and/or transcript.final; onTranslate requires transcript.translate. Omitting the transcript block entirely enables all three; passing {} leaves all of them off.

Deprecated: the untyped onMessage hook still fires for every inbound frame and remains available for backward compatibility, but new integrations should use onTranscript / onTranslate. It will be removed in a future major version.

Python SDK

The Voice Translation SDK is also available for Python. The flow is the same: create a session config, open the session with callbacks for transcripts, translations, audio, events and errors, then stream audio at real-time pace.

The Python SDK is a download, not a pip package: get it from Voice Translation → Downloads in the Developers Portal and install the wheel (Python 3.10 or later):

pip install krisp_voice_translation-<version>-py3-none-any.whl

Then import the classes you need:

from krisp_voice_translation import (
    Vt, VtSessionConfig, VtVoice, VtCustomVocabularyData, VtSessionMetadata,
    get_vt_session_key, get_vt_languages_list,
)

get_vt_session_key(API_KEY) is a convenience for prototypes. In production, create the session token on your backend with POST /v2/sdk/tokens/session and usage_type: "vt" (see Authentication), and pass it to the client as VtSessionConfig.auth_token, so the API key never reaches the client.

# 1. Get a short-lived session key (or have your backend mint one).
session_key = get_vt_session_key(API_KEY)["session_key"]

# 2. Build a session config.
config = VtSessionConfig(
    auth_token           = session_key,
    input_language_code  = "en-US",         # BCP-47, source
    output_language_code = "fr-FR",         # BCP-47, target
    voice                = VtVoice.FEMALE,   # "male" | "female"
    # input/output_sample_rate, input_frame_duration default to 16 kHz / 20 ms
    custom_vocabulary    = VtCustomVocabularyData(
        vocabulary = ["Krisp", "AcmeCorp"], # ASR boost for domain terms (optional)
        dictionary = {                      # force specific translations (optional)
            "hello": "bonjour",
            "goodbye": "au revoir",
        },
    ),
    metadata             = VtSessionMetadata(
        reference_id = "your-reference-id",  # optional correlation id for support
    ),
    # Optional opt-in feature flags (default False), e.g.:
    # background_voice_cancellation = True,    # filter other voices server-side
)

# 3. Open the session; register five callbacks. They all fire on the SDK's
#    background thread, so route results through a queue if you need them
#    back on the main thread.
vt = Vt.create(
    config,
    original_transcript_callback   = on_source_text,       # interim + final source text
    translated_transcript_callback = on_target_text,       # interim + final target text
    audio_result_callback          = on_translated_audio,  # raw int16 PCM bytes
    event_callback                 = on_event,             # INPUT_ALLOWED / INPUT_NOT_ALLOWED
    error_callback                 = on_error,             # VtErrorType
)

# 4. Stream audio in real time. One PCM chunk per `input_frame_duration` ms.
#    16 kHz mono s16le => 640 bytes per 20 ms chunk.
for chunk in pcm_chunks:
    vt.process(chunk)
    sleep(0.020)                       # pace in real time — required by the API

# 5. Drain trailing events, then close.
sleep(2.0)                             # let the final transcript / translation / audio land
vt.close()                             # idempotent