🌟 EchoFriend - Interactive Language Learning Assistant

EchoFriend is an AI-powered conversational Dutch language learning tool with real-time voice interaction and a beautiful web interface. Practice real-world scenarios like shopping at a supermarket while receiving instant feedback and guidance.

✨ Features

• 🎤 Real-time Voice Interaction: Press and hold to record your voice, get instant AI responses
• 🗣️ Speech Recognition: Powered by OpenAI Whisper for accurate Dutch transcription
• 🤖 AI Conversation: GPT-4 drives natural, contextual dialogue as a virtual shop assistant
• 🔊 Text-to-Speech: Hear AI responses with natural-sounding Dutch pronunciation
• 📊 Learning Feedback: Receive detailed performance analysis after each session
• 💬 Conversation History: Review past conversations and track your progress
• 🌐 Modern Web UI: Beautiful, responsive interface that works on desktop and mobile
• 📱 Progressive Design: Adapts to different screen sizes for optimal experience

🎯 Learning Scenarios

Currently supports:

• Supermarket Shopping: Practice ordering items, asking about products, and making purchases

More scenarios coming soon!

🖼️ Screenshots

Home Screen

View your conversation history and start new practice sessions.

Active Conversation

Real-time dialogue with the AI assistant in a realistic shopping scenario.

Performance Feedback

Detailed analysis of your language usage, highlighting strengths and areas for improvement.

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• OpenAI API key (or compatible API endpoint)
• Microphone for voice input
• Modern web browser (Chrome, Firefox, Safari, Edge)

Installation

1. Clone the repository

   git clone https://github.com/ztang75/EchoFriend.git
   cd EchoFriend

2. Install dependencies

   pip install -r requirements.txt

3. Set up environment variables

   Create a .env file in the project root:

   OPENAI_API_KEY=your-api-key-here
   # Optional: Use custom API endpoint
   # OPENAI_BASE_URL=https://your-custom-endpoint.com/v1

4. Run the application

   python app.py

5. Open your browser

   Navigate to http://localhost:5000

📖 Usage

Web Interface

1. Start a New Conversation

   • Click the microphone button on the home screen
   • You'll enter an active conversation session

2. Record Your Voice

   • Press and hold the microphone button to start recording
   • Speak in Dutch (or any language you're practicing)
   • Release to stop recording (or click anywhere on the recording overlay)

3. Listen to AI Response

   • The AI will transcribe your speech, generate a contextual response, and play it back
   • Continue the conversation naturally

4. End Session & Get Feedback

   • Click "End Conversation" when you're done
   • Review detailed feedback on your performance
   • See highlights of what you did well and suggestions for improvement

5. Review History

   • Click on any orange history card to review past conversations
   • Track your progress over time

Command Line Interface (Original)

For the original CLI experience:

python echofriend.py

Follow the on-screen instructions to record and interact via terminal.

🛠️ Technology Stack

Backend

• Python 3.8+: Core application logic
• Flask: Web server and API framework
• OpenAI API:
  • GPT-4 for conversation
  • Whisper for speech recognition
  • TTS for voice generation
• PyAudio: Audio recording
• Pygame: Audio playback

Frontend

• HTML5: Structure
• CSS3: Styling with gradients, animations, and responsive design
• Vanilla JavaScript: Interactive functionality
• Web Audio API: Browser-based audio recording

📁 Project Structure

EchoFriend/
├── app.py                  # Flask web server and API endpoints
├── echofriend.py          # Core EchoFriend logic (also works standalone)
├── test_microphone.py     # Microphone testing utility
├── requirements.txt       # Python dependencies
├── .env                   # Environment variables (create this)
├── static/               
│   ├── index.html        # Main web interface
│   ├── styles.css        # Styling
│   ├── app.js            # Frontend JavaScript
│   └── assistant.png     # Assistant character image (optional)
├── audio_files/          # Generated audio files (auto-created)
└── README.md             # This file

🔧 API Endpoints

The Flask server provides the following REST API endpoints:

• GET / - Serve the main web interface
• POST /api/start_session - Start a new conversation session
• POST /api/process_audio - Process recorded audio and get AI response
• POST /api/end_session - End session and generate feedback
• GET /api/history - Get all conversation history
• GET /api/history/<session_id> - Get specific session details

⚙️ Configuration

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	Your OpenAI API key
OPENAI_BASE_URL	No	Custom API endpoint (for third-party APIs)

Customization

You can customize the learning scenario by modifying the scenario parameter in:

• Web: app.js → startNewConversation() function
• CLI: echofriend.py → main() function

🎨 Features in Detail

Voice Recording

• Press-and-hold interaction (like voice messaging apps)
• Visual feedback with pulsing animation
• Works on both desktop and mobile devices

AI Conversation Flow

1. User speaks in Dutch
2. Whisper transcribes speech to text
3. GPT-4 generates contextual response (as shop assistant)
4. TTS converts response to natural-sounding speech
5. Audio plays automatically

Learning Feedback System

Uses GPT-4 to analyze:

• Overall communication effectiveness
• Vocabulary usage and correctness
• Grammar patterns
• Pronunciation (inferred from text)
• Suggestions for improvement

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📝 License

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

🐛 Troubleshooting

Microphone Not Working

• Browser: Grant microphone permissions when prompted
• CLI: Check PyAudio installation and microphone device index

API Errors

• Verify your OPENAI_API_KEY is correct
• Check API rate limits and quota
• For custom endpoints, ensure OPENAI_BASE_URL is properly configured

Audio Playback Issues

• Web: Check browser audio permissions
• CLI: Ensure Pygame is installed: pip install pygame

Flask Server Won't Start

• Check if port 5000 is already in use
• Try a different port: modify app.run() in app.py

🔮 Roadmap

• Multiple learning scenarios (restaurant, hotel, airport, etc.)
• Support for multiple languages
• Progress tracking and statistics
• Gamification with achievements
• Mobile app version
• Offline mode with local models
• Pronunciation scoring
• Social features (compete with friends)

👏 Acknowledgments

• OpenAI for GPT-4, Whisper, and TTS APIs
• Flask community for excellent web framework
• All contributors and testers

📧 Contact

ztang75 - GitHub Profile

Project Link: https://github.com/ztang75/EchoFriend

---

⭐ If you find EchoFriend helpful, please consider giving it a star on GitHub!