Docs Documentation

Documentation

Everything you need to open a voice or text session with Svelte 5, keep the API key on the server, and release its browser resources on the way out.

What this is

svelte-elevenlabs is an independent Svelte 5 package for ElevenLabs Conversational AI. It owns the browser side of one live session: the WebSocket handshake, microphone capture, agent playback, transcript state, tools, and teardown. Your component owns the interface.

The package is not an official ElevenLabs SDK. It follows the public Conversational AI WebSocket protocol, exposes a typed surface, and reports failures with stable error codes instead of leaving a silent dead line. The included SvelteKit showcase in this repository is a working reference for the core session flow described here.

Platforms: Browser UI / server on Node 22.17+ or Bun 1.4+
Reactivity: Svelte 5 runes
Transport: WebSocket / ConvAI
Audio: PCM16 and µ-law
Auth: Public id or signed URL
Teardown: Automatic or manual
License: MIT

What you get

One reactive controller. Status, speaking and listening flags, levels, transcripts, latency, queue state, and errors update directly in markup.
Voice or text. Capture the microphone and play streamed agent audio, or run the same socket in text only mode without requesting a device.
A real audio pipeline. AudioWorklet capture, resampling, PCM16 framing, one playback clock, and immediate barge-in flushing.
Server-held credentials. The signed URL route exchanges an agent id for a short-lived URL so the API key never reaches the browser.
Conversation tooling. Named client tools, a provider scoped tool hook, MCP approval handling, feedback, typed turns, and contextual updates.
Optional UI. Live spectra and a complete conversation widget ship in the same package, both driven by a conversation controller.

How it fits together

Your component calls a controller. useConversation creates a ConversationController and registers an $effect teardown. Use createConversation in stores, tests, or any place where you want to own cleanup.
The controller runs the session. It resolves the target, prepares audio inside the user gesture when needed, fetches a signed URL when asked, opens the socket, negotiates formats, and reduces protocol events into Svelte state and derived values.
The audio manager handles the browser. AudioManager owns microphone tracks, the worklet, the playback clock, analyser nodes, and device routing. You only touch it directly when you need a custom audio surface.

For AI tools

The documentation is also published as plain Markdown. llms.txt is a compact index of every page, and llms-full.txt contains the complete reference with options, controller fields, error codes, and deployment notes. The index is mirrored at /docs/llms.txt for agents that look beside the docs they are reading.

For Claude Code, Cursor, OpenCode, Copilot, Windsurf, Cline, Gemini CLI, and other coding agents, the agent kit installs one reviewed guide into the file each tool already reads. Run bunx svelte-elevenlabs agents install in your project.

Start here

Start here Install Add the package, set the server key, and verify the build. First session Quickstart A working voice panel in one Svelte component. Guide Sessions Lifecycle, transcripts, text turns, feedback, and cleanup. Guide Audio Formats, capture, playback, devices, and analyser data. Guide Client tools Named tools, provider registration, and MCP approvals. Security Signed URLs The server route contract and the deployment checklist. Tooling Agent kit One command that teaches coding agents the correct API. Demo Live widget A real session with a focus view for recording.

Edit this page on GitHub