How svpino/cartesia-demo works
Project type and purpose
• This is a Python-based “voice assistant” service that connects into a LiveKit real-time audio streaming room, processes audio via AI back-ends (OpenAI for language and Cartesia for spatial/semantic functions), and makes itself available in the hosted Agents Playground UI. It is a single “backend” service (no frontend code here) invoked via a CLI wrapper (uv run python voice.py …).
File structure
• Top level:
• voice.py – the only application entrypoint (defines commands download-files and start)
• pyproject.toml & uv.lock – Python dependency & lock files
• README.md – usage instructions & environment variables
• .gitignore/.python-version – dev files
• No separate “frontend” or “src” folders → everything is in one script, so it’s a thin orchestration layer calling external services.
README
• Requires environment variables for LiveKit, Cartesia, OpenAI.
• Two-phase operation:
a. voice.py download-files (pre-fetch assets)
b. voice.py start (boot into the LiveKit session as an agent)
• After starting, end users join via the hosted Agents Playground UI (in a browser) that connects to the same LiveKit room.
a. Main components
• Voice Assistant Service (voice.py)
• LiveKit Server (real-time audio/video server)
• Agents Playground UI (hosted web client)
• OpenAI API (LLM/text generation)
• Cartesia API (spatial/semantic processing)
• Local File System (downloaded assets)
b. Relationships & interactions
1. Agents Playground UI ⇄ LiveKit Server — streams audio/video to/from browser
2. Voice Assistant Service ⇄ LiveKit Server — joins the same room as a client, receives incoming audio streams and publishes responses
3. Voice Assistant Service → OpenAI API — for transcription, chat completion, or response generation
4. Voice Assistant Service → Cartesia API — for spatial/semantic enrichment or other domain-specific processing
5. Voice Assistant Service → Local File System — on download-files command, fetches and stores required assets
c. Architectural patterns & principles
• Single-service orchestration layer
• Event-driven / streaming interactions via WebSockets (LiveKit)
• Clear separation between real-time transport (LiveKit) and compute (OpenAI/Cartesia)
• Configuration via environment variables for secrets/URLs
d. Key technologies
• Python 3.x, CLI orchestration (uv CLI tool or custom wrapper)
• LiveKit (WebRTC signaling and media server)
• OpenAI REST API
• Cartesia REST API
• pyproject.toml for dependency management
Detailed capture of essential elements
• Environment variables grouping next to the Voice Assistant component
• A note that the Agents Playground is “hosted separately” but uses the same LiveKit room
• If desired, break out the “audio in → transcription → response generation → audio out” flow inside the Voice Assistant for a deeper view