Mini AI Speaking Coach โ Real-time browser speech recording, deterministic word-level metric analysis (WPM, fillers, pauses), and personalized AI coaching powered by Structured Outputs and Voice AI.
- Live Web App: https://speaksharp.vercel.app
- Instant Demo Review: Click "Try Demo" on the landing page โ no signup, credit card, or email verification needed. You can record a response and receive complete coaching in under 30 seconds.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ 1. Pick a Speaking Prompt โ 2. Record in Browser โ 3. Instant Coach โ
โ โ
โ "Introduce yourself in 60s" [ 0:42 / 2:00 ] Score: 8 / 10 โ
โ "Pitch a startup idea" โโโ
โโโโ
โโ (Live Mic) 135 WPM (Good) โ
โ "Explain a proud project" [โน Stop & Submit] 3 Fillers (um...) โ
โ 1.4s Long Pause โ
โ Polished Rewrite โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
flowchart TD
subgraph Browser ["Client: React 18 + Vite + Tailwind CSS"]
A["User Speech"] --> B["MediaRecorder API<br/>(WebM/Opus / MP4/AAC)"]
B --> C["Audio Analysis & Mic Visualizer<br/>(AudioContext AnalyserNode)"]
C --> D["Multipart Upload + JWT<br/>POST /api/sessions"]
R["Results Page<br/>(Recharts + Highlighted Transcript)"]
end
subgraph API ["Backend: Node.js + Express + TypeScript"]
D --> E["Auth Middleware<br/>(Supabase JWT / Demo Token)"]
E --> F["Rate Limiter<br/>(20/day reg, 5/day anon)"]
F --> G["Session Controller<br/>(Status: 'processing')"]
G --> H["Audio Storage<br/>(Supabase Storage: speaksharp-audio)"]
G --> I["Async Analysis Pipeline"]
end
subgraph STT ["Speech-to-Text"]
I --> J["Whisper Model<br/>(verbose_json + word timestamps)"]
end
subgraph Engine ["Deterministic Metrics Engine (/packages/shared)"]
J --> K["Pure TypeScript Analytics:<br/>โข WPM (excluding silence)<br/>โข Single & Multi-word Fillers<br/>โข Position-aware 'like'/'so'<br/>โข Pauses > 1.0s & Longest Pause<br/>โข Lexical Diversity (TTR)"]
end
subgraph AI ["Qualitative Coaching: LLM"]
K --> L["gpt-4o-mini / Llama-3.3<br/>Structured Outputs (strict: true)<br/>Ingests Transcript + Computed Metrics"]
L --> M["Typed Coaching Schema:<br/>โข 4 Categories: Clarity, Structure,<br/> Confidence, Conciseness<br/>โข Direct Quotes as Evidence<br/>โข Concrete Actionable Tips<br/>โข Polished Rewrite (โค150 words)"]
end
subgraph Persistence ["Database: Supabase Postgres + RLS"]
M --> N["Update Session Status: 'complete'"]
N --> O[("sessions, transcripts,<br/>metrics, feedback tables")]
end
O -.->|Poll /api/sessions/:id| R
A frequent pitfall in AI voice applications is delegating everything to an LLM prompt (e.g. asking an LLM "estimate my speaking speed and count my filler words"). LLMs generate plausible-sounding guesses rather than accurate numbers, leading to hallucinated filler counts and inconsistent feedback.
SpeakSharp solves this with an intentional Hybrid Architecture:
- Deterministic Metrics in Pure TypeScript (
packages/shared/src/metrics.ts):- Computes hard mathematical truth: exact Words Per Minute excluding silence, single and multi-word filler instances (
um,uh,you know,kind of), position-aware hesitation filtering forlikeandso, pauses $> 1.0$s, and vocabulary diversity (Type-Token Ratio). - Fast, deterministic, and protected by 22 automated unit tests.
- Computes hard mathematical truth: exact Words Per Minute excluding silence, single and multi-word filler instances (
- Qualitative AI Coaching via Structured Outputs:
- The LLM is provided with the transcript and the real calculated numbers.
- It acts purely as a coach: analyzing rhetoric, tone, narrative structure, citing verbatim quotes for evidence, and authoring a polished rewrite.
- Guaranteed valid typed JSON via OpenAI Structured Outputs (
strict: true) validated with Zod.
SpeakSharp is engineered to run completely free ($0.00) without spending a single penny:
| Service | Free Tier Configuration |
|---|---|
| Supabase | Free tier ($0): 500MB Postgres, Auth, 1GB Storage. Works out-of-the-box or with our local in-memory fallback adapter. |
| Speech-to-Text | Use Groq Free Tier (whisper-large-v3 with word timestamps) or built-in Offline Mock Mode (AI_PROVIDER=mock). |
| LLM Coaching | Use Groq Free Tier (llama-3.3-70b-versatile / llama-3.1-8b-instant) or built-in offline coach generator. |
| Text-to-Speech | Plays directly in browser using native Web Speech Synthesis API (high quality on iOS Safari, Chrome, and macOS with $0 cost). |
| Hosting | Vercel Free Tier (Frontend) + Render Free Tier (Backend). |
- Monorepo: npm workspaces (
apps/web,apps/api,packages/shared) - Frontend:
- React 18, TypeScript, Vite
- Tailwind CSS (Mobile-first, responsive down to iPhone SE)
- React Router 7
- TanStack Query v5
- Recharts v2 (Progress line charts with target pace reference bands)
- Lucide React icons
- Backend:
- Node.js, Express, TypeScript (Strict, no
any) - Multer (in-memory multipart audio streaming)
- Zod (Runtime request and schema validation)
- OpenAI Node.js SDK (configured with custom
OPENAI_BASE_URLfor Groq/OpenAI)
- Node.js, Express, TypeScript (Strict, no
- Database, Auth & Storage:
- Supabase Postgres with Row Level Security (RLS) on all tables
- Supabase Storage (private
speaksharp-audiobucket) - Supabase Auth (Email Magic Link, Google OAuth, and Anonymous Demo sessions)
- Testing & Tooling:
- Vitest (Unit tests for metrics engine + Supertest for API routes)
- ESLint 9 (Flat config) + Prettier
SpeakSharp/
โโโ apps/
โ โโโ web/ # React 18 SPA (Vite + Tailwind + Recharts)
โ โ โโโ src/
โ โ โ โโโ components/ # Navbar, MetricCards, TranscriptViewer, MicVisualizer, ErrorBoundary
โ โ โ โโโ context/ # AuthContext (Supabase + 1-Click Demo)
โ โ โ โโโ hooks/ # useRecorder (cross-browser audio recording)
โ โ โ โโโ lib/ # Supabase client, typed API client
โ โ โ โโโ pages/ # LandingPage, PracticePage, ResultsPage, HistoryPage
โ โ โ โโโ App.tsx
โ โ โโโ vercel.json # Vercel SPA deployment config
โ โ
โ โโโ api/ # Express Backend
โ โโโ src/
โ โ โโโ lib/ # Config, Store (Supabase + memory fallback), Logger
โ โ โโโ middleware/ # Auth, Rate limiting (20/day reg, 5/day anon)
โ โ โโโ routes/ # sessions, prompts, audio
โ โ โโโ services/ # stt, llm, tts, pipeline
โ โ โโโ index.ts
โ โโโ __tests__/ # Supertest API integration tests
โ โโโ render.yaml # Render deployment config
โ
โโโ packages/
โ โโโ shared/ # Pure TypeScript shared package
โ โโโ src/
โ โ โโโ constants.ts # Filler words, pace thresholds
โ โ โโโ types.ts # Typed API contracts
โ โ โโโ schemas.ts # Zod validation & Structured Outputs JSON schemas
โ โ โโโ metrics.ts # Pure deterministic metrics engine
โ โโโ __tests__/ # 22 comprehensive unit tests
โ
โโโ supabase/
โ โโโ migrations/ # SQL migrations: profiles, prompts, sessions, transcripts, metrics, feedback, storage
โ
โโโ .github/workflows/ci.yml # GitHub Actions CI (Typecheck, Lint, Test)
โโโ .env.example
โโโ tsconfig.base.json
โโโ package.json
- Node.js
$\ge 20$ (Recommended: Node 22) - npm
$\ge 10$
git clone https://github.com/shyam/SpeakSharp.git
cd SpeakSharp
npm installCopy .env.example to .env:
cp .env.example .env(By default, AI_PROVIDER=mock is set, allowing SpeakSharp to run immediately with 100% functionality without entering any API keys).
If you want live cloud AI with Groq (100% Free):
AI_PROVIDER=groq
OPENAI_BASE_URL=https://api.groq.com/openai/v1
OPENAI_API_KEY=gsk_your_free_groq_key
OPENAI_STT_MODEL=whisper-large-v3
OPENAI_LLM_MODEL=llama-3.3-70b-versatile# Build the shared library first
npm run build --workspace=@speaksharp/shared
# Start backend (Port 3001) and frontend (Port 5173) simultaneously
npm run devVisit http://localhost:5173 in your browser.
# 1. Run all unit and integration tests (31 tests total)
npm test
# 2. Run only the metrics engine unit tests
npm test --workspace=@speaksharp/shared
# 3. Run API integration tests
npm test --workspace=@speaksharp/api
# 4. Strict TypeScript typechecking across all workspaces
npm run typecheck
# 5. ESLint linting
npm run lint- Zero Client Secrets: OpenAI API keys and Supabase service-role keys exist strictly on the backend.
- Row Level Security (RLS): Enforced on all Supabase tables (
profiles,sessions,transcripts,metrics,feedback). Users can strictly view and update only their own speaking data. - Strict TypeScript:
noImplicitAny: true,noUncheckedIndexedAccess: true, zeroanyusage. - Per-User Rate Limiting: Built-in sliding daily tracker prevents API cost overruns (20 sessions/day registered, 5/day anonymous).
- Graceful Error Recovery: Top-level React
ErrorBoundaryand backend structured JSON logger.
- Real-time Streaming WebSockets:
- Current: Batch processing after speech finishes (~1-2s total latency).
- Future: Live streaming STT via WebSockets to show rolling real-time WPM meters as you speak.
- Pronunciation & Acoustic Scoring:
- Current: High-level transcript articulation tips.
- Future: Phoneme alignment using models like Wav2Vec2 to pinpoint mispronounced vowels and consonants.
- Multi-Language Coaching:
- Current: English filler detection and heuristics.
- Future: Spanish ("este", "o sea"), French ("euh"), and Japanese filler word support.
- Team & Executive Dashboards:
- Current: Individual user progress charts.
- Future: Organization dashboards for sales and support teams to track speaking clarity across cohorts.
MIT License ยฉ 2026 SpeakSharp