IPA Learning - AI-Powered Pronunciation Training System

An innovative AI-powered system for pronunciation and accent acquisition, providing targeted, multi-modal feedback to language learners.

Features

• Real-time Speech Analysis: Advanced phoneme recognition and comparison
• IPA Visualization: See the phonetic transcription of your speech
• 3D Articulation Viewer: Interactive visualization of tongue and mouth positions
• Voice Cloning: Hear target pronunciations in your own voice
• Multi-Accent Support: Practice British, American, Australian, and more accents
• Progress Tracking: Detailed analytics and achievement system
• Personalized Feedback: AI-generated tips based on your specific challenges

Project Structure

IPALearning/
├── backend/              # FastAPI backend server
│   ├── api/             # API endpoints
│   ├── services/        # Business logic
│   ├── models/          # Data models
│   └── utils/           # Utility functions
├── frontend/            # React TypeScript frontend
│   ├── src/
│   │   ├── components/  # Reusable UI components
│   │   ├── pages/       # Application pages
│   │   ├── services/    # API client services
│   │   ├── hooks/       # Custom React hooks
│   │   └── types/       # TypeScript definitions
├── data/                # Accent and phoneme data
└── scripts/             # Setup and utility scripts

Quick Start

Prerequisites

• Python 3.8 or higher
• Node.js 14 or higher
• npm or yarn

Installation

1. Clone the repository

   git clone https://github.com/yourusername/IPALearning.git
   cd IPALearning

2. Run the setup script

   ./scripts/setup.sh

   This will:

   • Create Python virtual environment
   • Install all dependencies
   • Create configuration files
   • Set up initial data

3. Configure API keys (optional)

   Edit backend/.env and add any API keys:

   OPENAI_API_KEY=your_key_here
   GOOGLE_CLOUD_API_KEY=your_key_here

Running the Application

1. Start the backend server

   cd backend
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   python main.py

   The API will be available at http://localhost:8000

2. Start the frontend development server

   cd frontend
   npm start

   The application will open at http://localhost:3000

API Documentation

Once the backend is running, visit http://localhost:8000/docs for interactive API documentation.

Key Endpoints

Speech Analysis

• POST /api/speech/analyze - Analyze recorded speech
• POST /api/speech/transcribe - Transcribe audio to text
• GET /api/speech/practice-phrases - Get practice phrases

Feedback

• POST /api/feedback/generate - Generate personalized feedback
• POST /api/feedback/ipa-comparison - Compare user and target IPA
• GET /api/feedback/articulation/{phoneme} - Get articulation data

Accents

• GET /api/accents - List available accents
• POST /api/accents/voice-clone - Generate voice clone
• POST /api/accents/reference-audio - Get reference pronunciation

Development Setup

Docker (Recommended)

1. 构建并启动完整生产镜像

   docker compose up --build -d
   # 前端: http://localhost:3000  后端: http://localhost:8000
2. 热重载开发模式

   docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

使用 Docker 后，无需在本机安装 Node / Python / 依赖，只要安装好 Docker 即可一键运行。

Backend Development

cd backend
source venv/bin/activate

# Install new dependencies
pip install package_name
pip freeze > requirements.txt

# Run with auto-reload
uvicorn main:app --reload

Frontend Development

cd frontend

# Install new dependencies
npm install package_name

# Run tests
npm test

# Build for production
npm run build

Code Style

• Backend: Follow PEP 8 guidelines
• Frontend: Use ESLint and Prettier configurations
• Commit messages: Use conventional commits format

Testing

Backend Tests

cd backend
pytest tests/

Frontend Tests

cd frontend
npm test

Deployment

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

Manual Deployment

1. Backend: Deploy to any Python-supporting platform (Heroku, AWS, etc.)
2. Frontend: Build and deploy to static hosting (Netlify, Vercel, etc.)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Whisper by OpenAI for speech recognition
• Coqui TTS for voice synthesis
• React Three Fiber for 3D visualizations
• FastAPI for the backend framework

Support

For support, email support@ipalearning.com or join our Discord community.

---

Built with ❤️ by the IPA Learning Team