Skip to content

Table Read

Table Read is an AI-powered script rehearsal app where actors practice scenes with an AI scene partner and receive real-time directing feedback.

Code Video Cerebral Valley

Core trick

A director agent scores each actor's spoken turn in a LiveKit room separately from the scene-partner voice agent.

Tags

creative/musicvoiceagents

Description

Table Read is an AI-powered script rehearsal app where actors practice scenes with an AI scene partner and receive real-time directing feedback. A human actor joins a LiveKit voice room and rehearses a scripted scene beat-by-beat with an AI character agent (powered by Cartesia Sonic-3 TTS and Anthropic Claude). A separate AI Director agent listens to each delivery in real time, evaluates whether the actor is truly acting or merely reading, and provides scoring, engagement analysis, and actionable notes. Scenes are managed via a Notion database and a Next.js frontend, and the final rehearsed script can be locked as a versioned artifact.
yanxiyc/table-read★ 00 forksPythonCreated Feb 7, 2026 · last push Feb 9, 2026

README excerpt

# table-read

Director-driven voice rehearsal MVP built with FastAPI + Cartesia integrations.

## Run

1. Install dependencies:
```bash
python3 -m pip install fastapi uvicorn jinja2 python-multipart httpx websockets PyJWT
```

2. Configure environment:
```bash
cp .env.example .env
```

Edit `.env` and set:
```bash
CARTESIA_API_KEY=your_key
CARTESIA_AGENT_ID=your_agent_id
```

3. Start server:
```bash
python3 -m uvicorn app.main:app --reload
```

4. Open `http://127.0.0.1:8000/create`.

## Script Format

Use character names directly in script lines:

```text
MOTHER: You’re late.
YOU:
MOTHER: Don’t do this here.
YOU:
```

Set `AI Character Name` to the exact character label that should be spoken by TTS.
All other character lines are treated as human/actor turns.

## API

- `POST /api/scenes`
- `GET /api/scenes/{scene_id}`
- `POST /api/scenes/{scene_id}/start`
- `POST /api/scenes/{scene_id}/end`
- `GET /api/scenes/{scene_id}/state`
- `GET /api/scenes/{scene_id}/agent-session` (Cartesia agent stream URL + token)
- `POST /api/scenes/{scene_id}/utterance`
- `GET /api/scenes/{scene_id}/livekit-token`
- `WS /api/scenes/{scene_id}/stream` (continuous STT stream)
- `GET /api/scenes/{scene_id}/audio/{filename}`

## Tests

```bash
python3 -m pytest -q
```

## TTS Expression Controls

Director style commands update runtime style, and TTS applies:
- `generation_config.speed` from style pace
- `generation_config.emotion` from tension/warmth mapping
- SSML expression tags (`<emotion .../>`,

Team