Skip to content

README.md

Latest commit

 

History

History
118 lines (91 loc) · 3.92 KB

README.md

File metadata and controls

118 lines (91 loc) · 3.92 KB
Raw

EVI Proxy

This example contains an EVI "proxy" that accepts a websocket connection from a client, connects to EVI, and forwards messages back and forth between the client and EVI.

This app is useful as an example in its own right: it demonstrates

  • how to connect to EVI from a Typescript backend,
  • how to accept websocket connections, process messages, and send them upstream to EVI

See upstream.ts and downstream.ts for more details.

It is also useful as a debugging tool: it supports

  • recording and replaying EVI conversations,
  • simulating error conditions that you might want to handle to make your EVI application more robust.

Prerequisites

  • Node.js (for running the proxy and building the web frontend)
  • Hume AI API credentials

Installation

  1. Clone this repository:

    git clone <repository-url>
cd eviproxy

  2. Install dependencies for both app and web components:

    cd app && npm install
cd ../web && npm install && npm run build
cd ..

Environment Variables

Create a .env file in the app/ directory with the following variables:

HUME_API_KEY=your_hume_api_key_here
HUME_CONFIG_ID=your_config_id_here  # Optional

To get your API key:

  1. Log into the Hume AI Platform
  2. Visit the API keys page
  3. See the documentation for detailed instructions

Usage

Start the Proxy Server

cd app && npm start

This starts the WebSocket proxy server on port 3000 with an interactive CLI interface. The CLI allows you to:

  • Switch between record and playback modes
  • Control recording sessions
  • Manage saved conversation scripts

Connect Your Own Applications

To connect your own Hume EVI applications to this proxy instead of directly to Hume's servers, configure them to use http://localhost:3000 as the environment:

TypeScript/JavaScript:

const hume = new HumeClient({
    environment: "http://localhost:3000"
});

Python:

client = AsyncHumeClient(
    environment="http://localhost:3000",
)

Access the Web Interface

The proxy also includes a built-in web interface available at:

http://localhost:3000

The interface is built using Vite. If you modify any frontend code, run npm run build in the web/ directory again to rebuild the static assets.

Recording and Playback

  1. Record Mode: Captures real conversations with Hume EVI and saves them to JSONL files
  2. Playback Mode: Replays saved conversations for testing and debugging
  3. Script Files: Conversations are saved in JSONL format (default: recording.jsonl)

Project Structure

eviproxy/
├── app/                      # Main proxy server (Node.js)
│   ├── main.ts               # Entry point and state machine
│   ├── cli.ts                # Interactive CLI interface
│   ├── upstream.ts           # Hume API connections
│   ├── downstream.ts         # Client WebSocket server
│   ├── api.ts                # HTTP API endpoints for web-based control
│   └── util.ts               # Helpers
├── web/                      # React frontend
│   ├── app.tsx               # Main React application entry point
│   ├── EVIChat.tsx           # Main chat interface using @humeai/voice-react
│   ├── ChatControls.tsx      # Voice controls (mute, stop, etc.)
│   ├── ChatMessages.tsx      # Message display component
│   ├── StartCall.tsx         # Call initiation component
│   ├── WebSocketControls.tsx # WebSocket connection controls
│   ├── index.html            # HTML entry point
│   └── package.json          # Frontend dependencies
└── shared/                   # Shared TypeScript types
    └── types.ts              # Common interfaces and types