AI-powered voice coach
Transform your speaking skills with real-time AI feedback. Talkly uses OpenAI's advanced Realtime API to provide comprehensive voice coaching through natural conversations.
- Direct voice-to-voice communication with AI using WebRTC
- Instant feedback on speech patterns, clarity, and fluency
- Natural conversation practice without awkward text interfaces
- Advanced speech analysis powered by GPT-4o Realtime API
- Sleek, professional interface with dark mode design
- Intuitive navigation from landing page to coaching session
- Responsive design that works on all devices
- Accessible components built with Headless UI
- Production-ready architecture with TypeScript
- Secure API handling with ephemeral tokens
- Error recovery and connection management
- Real-time status monitoring and notifications
- Node.js 18+ and npm
- OpenAI API key with Realtime API access
- Modern browser with microphone support
# Clone the repository
git clone https://github.com/itsmeasadali/talkly.git
cd talkly
# Install dependencies
npm install
# Set up environment
cp .env.example .env.local
echo "OPENAI_API_KEY=your_api_key_here" >> .env.local
# Start development server
npm run devOpen http://localhost:3000 and start improving your English!
- Node.js: Version 18.0 or higher
- Browser: Chrome 90+, Firefox 88+, Safari 14+, or Edge 90+
- Network: Stable internet connection for real-time communication
- Active OpenAI account with billing enabled
- Realtime API access (currently in beta - request access)
- Valid API key with sufficient credits
Note: The OpenAI Realtime API is currently in beta. Contact OpenAI support if you need access.
| Technology | Purpose | Version |
|---|---|---|
| Next.js | React framework with App Router | 15.5.0 |
| TypeScript | Type-safe development | 5.x |
| Tailwind CSS | Modern styling framework | 4.x |
| Headless UI | Accessible component library | 2.x |
| OpenAI Realtime API | Voice processing and AI coaching | GPT-4o |
| WebRTC | Real-time audio communication | Native |
| Lucide React | Beautiful icon library | Latest |
- Launch Talkly at http://localhost:3000
- Choose your focus from conversation, voice clarity, fluency, or confidence
- Click "Let's improve" to start your coaching session
- Grant microphone permission when prompted
- Start speaking naturally - the AI will provide real-time feedback
- Clear value proposition with skill selection
- Feature explanations and benefits
- Social proof and credibility indicators
- Multiple call-to-action points
- One-click session start with clear status indicators
- Real-time connection monitoring and error handling
- Professional settings panel with technical details
- Instant notifications for session events
- Connection status monitoring
- Audio configuration details (24kHz PCM16 mono)
- Model information (GPT-4o Realtime Preview)
- WebRTC connection details
| Variable | Description | Required | Example |
|---|---|---|---|
OPENAI_API_KEY |
Your OpenAI API key | Yes | sk-... |
The application automatically configures optimal audio settings:
- Sample Rate: 24kHz (optimal for speech recognition)
- Format: PCM16 mono
- Echo Cancellation: Enabled
- Noise Suppression: Enabled
- Voice Activity Detection: Server-side with smart silence detection
Problem: Application shows setup screen instead of coaching interface
Solutions:
# Verify API key is set correctly
cat .env.local
# Check API key format (should start with 'sk-' and be ~51 characters)
# Restart development server
npm run devPossible causes: Invalid API key, no Realtime API access, network issues
Solutions:
# Test API key
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.openai.com/v1/models
# Check browser console for detailed errors (F12 → Console)Solutions:
- Ensure microphone permission is granted
- Use HTTPS in production (required for microphone access)
- Test microphone in other applications
- Check browser microphone settings
| Browser | Status | Notes |
|---|---|---|
| Chrome 90+ | ✅ Recommended | Best compatibility |
| Firefox 88+ | ✅ Full support | Excellent performance |
| Safari 14+ | ✅ Supported | Minor WebRTC limitations |
| Edge 90+ | ✅ Full support | Chromium-based |
Enable detailed logging in browser console:
localStorage.setItem('debug', 'true');
// Refresh page to see detailed logs# Build the application
npm run build
# Start production server
npm startDevelopment:
# .env.local
OPENAI_API_KEY=sk-dev-key-hereProduction (set in hosting platform):
OPENAI_API_KEY=sk-prod-key-here- Vercel:
vercel --prod(recommended) - Netlify: Connect GitHub repository
- AWS/GCP/Azure: Use Docker or standard Node.js deployment
Important: HTTPS is required in production for microphone access. Most hosting platforms provide this automatically.
- No audio storage: All processing happens in real-time
- Ephemeral authentication: Short-lived, secure tokens
- No user registration: Anonymous usage by default
- Local settings: Preferences stored in browser only
- Environment variables: Never expose API keys in client code
- Secure tokens: Ephemeral tokens for client authentication
- HTTPS enforcement: Required for production microphone access
- Rate limiting: Built-in OpenAI API rate limits
npm run dev # Start development server with Turbopack
npm run build # Build for production
npm run start # Start production server
npm run lint # Run ESLint with auto-fix
npm run lint:check # Check linting without fixes
npm run type-check # Run TypeScript type checking
npm run clean # Clean build artifacts- TypeScript: Full type safety throughout codebase
- ESLint: Strict linting rules with Next.js configuration
- Prettier: Consistent code formatting
- Git hooks: Pre-commit linting and type checking
src/
├── app/ # Next.js App Router
│ ├── api/ # API routes
│ │ └── realtime-session/ # OpenAI session management
│ ├── globals.css # Global styles and animations
│ ├── layout.tsx # Root layout component
│ └── page.tsx # Landing page
├── components/ # React components
│ ├── AudioToAudioWebRTC.tsx # Main coaching interface
│ └── VoiceCoach.tsx # Alternative coaching component
└── lib/ # Utility libraries
├── audioToAudioWebRTC.ts # WebRTC implementation
└── realtimeAI.ts # Alternative AI implementation
We welcome contributions! Please see our Contributing Guidelines for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes with proper TypeScript types
- Run tests:
npm run lint && npm run type-check - Commit using conventional format:
git commit -m "feat(ui): add new feature" - Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
- OpenAI for the groundbreaking Realtime API
- Vercel for Next.js and excellent hosting platform
- Tailwind Labs for the amazing CSS framework
- Headless UI for accessible component primitives
- Check this README for common solutions
- Search existing issues on GitHub
- Create a new issue with detailed information
- Join discussions for community support
- GitHub Issues: Project Issues
- GitHub Discussions: Community Discussions
Built with ❤️ using modern web technologies and OpenAI's Realtime API.
Transform your speaking skills with AI-powered voice coaching. Start speaking with confidence today!