​
Installation

npm install vocode

Or, start from our Replit template.

​
Usage

​
Setting up the conversation

​
Hosted

You’ll need to get an API key from our dashboard to get started. Similar to the Python Quickstart, we provide a TypeScript interface for the conversation configuration.

import {
  AudioDeviceConfig,
  ConversationConfig,
  ChatGPTAgentConfig,
  DeepgramTranscriberConfig,
  AzureSynthesizerConfig,
  VocodeConfig,
} from "vocode";

const transcriberConfig: Omit<
  DeepgramTranscriberConfig,
  "samplingRate" | "audioEncoding"
> = {
  type: "transcriber_deepgram",
  chunkSize: 2048,
};
const agentConfig: ChatGPTAgentConfig = {
  type: "agent_chat_gpt",
  initialMessage: {
    type: "message_base",
    text: "Hello!",
  },
  promptPreamble: "The AI is having a pleasant conversation about life",
};
const synthesizerConfig: Omit<
  AzureSynthesizerConfig,
  "samplingRate" | "audioEncoding"
> = {
  type: "synthesizer_azure",
  shouldEncodeAsWav: true,
};
const vocodeConfig: VocodeConfig = {
  apiKey: process.env.REACT_APP_VOCODE_API_KEY || "",
};
const audioDeviceConfig: AudioDeviceConfig = {};

​
Running the conversation

We provide a React hook to facilitate conversations created from the configuration above.

import { useConversation } from "vocode";

const { status, start, stop, analyserNode } = useConversation({
  transcriberConfig,
  agentConfig,
  synthesizerConfig,
  vocodeConfig,
  audioDeviceConfig,
});
  • start opens the microphone stream and starts sending audio from the conversation to the user
  • stop closes the microphone and speaker streams
  • status is an enum that contains the status of the conversation, one of idle, connecting, connected, and error
  • analyserNode is an object (defined by the Web Audio API here) that allows for audio visualizations based on the audio output of the conversation

​
Self-hosted

Our self-hosted backend allows you to expose a websocket route in the same format that our hosted backend does. This allows you to deploy any agent you’d to into the conversation.

To get started, clone the Vocode repo or copy the client backend app directory.

​
Environment

Copy the .env.template and add your API keys.

cp .env.template .env

You’ll need:

  • Deepgram (for speech transcription)
  • OpenAI (for the underlying agent)
  • Azure (for speech synthesis)
DEEPGRAM_API_KEY=
OPENAI_API_KEY=
AZURE_SPEECH_KEY=
AZURE_SPEECH_REGION=

​
Running with Docker

From the client_backend directory:

docker build -t vocode-client-backend .
docker run --env-file=.env -p 3000:3000 -t vocode-client-backend

​
Running with Python

pip3 install vocode
uvicorn main:app --port 3000

You now have a server with a Vocode websocket route at localhost:3000! You can now use the useConversation hook with your self-hosted backend as follows:

const { status, start, stop, analyserNode } = useConversation({
  backendUrl: "<YOUR_BACKEND_URL>", // looks like ws://localhost:3000/conversation or wss://asdf1234.ngrok.app/conversation if using ngrok
  audioDeviceConfig: {},
});

​
Demo installation and setup

Clone the vocode-react-demo repository.

$ git clone https://github.com/vocodedev/vocode-react-demo.git

Run npm install inside the directory to download all of the dependencies.

$ npm install

Set your Client SDK key inside of your .env

REACT_APP_VOCODE_API_KEY=YOUR KEY HERE

Start the application

$ npm start