Skip to main content

​
What you are running

The Playground is a Vite + React SPA (playground/web/) served by a small Python harness that runs the agent in-process. It ships inside the supervoice repo, which pins unpod and superdialog as editable sibling deps, plus bundled example flows and playbooks - so it runs self-contained.
Agent flows are authored with superdialog; the call runtime is the unpod SDK AgentRunner. The harness re-implements the WS audio protocol from scratch - there is no pipecat / rtvi client dependency.

​
Prerequisites

An LLM key

OPENAI_API_KEY or ANTHROPIC_API_KEY. Copy playground/.env.example to .env at the repo root and set it.

A speech backend

Something the harness can reach for audio. Resolved in the order below - a fresh clone needs no local supervoice if you use a hosted URL.

​
How the speech backend is resolved

The harness (harness/api.py) picks a backend in this order:
  1. UNPOD_BASE_URL → the hosted wss://<host> speech service. For hosted voice with zero local backend: UNPOD_BASE_URL=api.unpod.ai plus UNPOD_API_KEY=<key>.
  2. Otherwise ws://127.0.0.1:9000 → a local supervoice-dev.
Legacy SUPERVOICE_URL still overrides both if set (with a deprecation warning) - prefer UNPOD_BASE_URL. The harness boots and serves the UI even with no speech backend reachable; only clicking Connect (which opens an audio call) needs one.

​
Run it

From the supervoice/ repo root (cp playground/.env.example .env, set an LLM key):
Or manually:
Open http://localhost:9100, click Connect, allow the mic, and talk.

One-click Docker

task pg-docker - playground on :9100 + local dev-speech on :9000, in containers. Set OPENAI_API_KEY / ANTHROPIC_API_KEY in supervoice/.env first.

Local speech

task pg-stack - boots a local dev-speech on :9000 unless a hosted speech URL is set.

​
Frontend hot-reload loop

Run the harness on :9100 and Vite separately on :5173 (it proxies /playground/* to the harness):

​
Architecture (M1)

Two planes, deliberately separate:
  • Audio rides the supervoice WS bridge directly (16 kHz mic up, 24 kHz playback down). The wire codec is a small proto3 Frame encoder/decoder in web/src/transport/protobuf.ts; capture/playback in web/src/transport/audio.ts.
  • Transcript / current checkpoint ride the harness’s own side channel (/playground/events), fed by SDK Session hooks - not the audio bridge. This keeps the transcript accurate even when audio is under load.

​
Configuration

One host + one credential drive every unpod plane. The harness derives the auth, platform, playbook-API, and hosted-speech bases from UNPOD_BASE_URL via the unpod SDK resolver.
Default builds bake no client-side auth base - the SPA reaches auth through the harness’s same-origin proxy at /playground/auth. The deprecated VITE_API_URL still overrides this (pointing the SPA straight at a hosted backend) if set explicitly mid-migration.

SuperDialog engine

The brain behind every playbook - engines, the Agent protocol, and embedding.

Embedding guides

Drop SuperDialog into LiveKit, PipeCat, FastAPI, or the CLI directly.

Speech Stack

The voice infrastructure that serves live calls in production.

Build an agent playbook

The builder-facing walkthrough of the same Playground.