205 lines
5.0 KiB
Markdown
205 lines
5.0 KiB
Markdown
# Street Lingo Platform 🌍
|
|
|
|
Learn languages through real-world scenarios with AI-powered conversations.
|
|
|
|
## Available Languages
|
|
|
|
### 🇮🇩 Indonesian (Learn Indonesian)
|
|
- **URL**: `http://localhost:3000`
|
|
- **Scenarios**: Warung, Ojek, Alfamart, Coffee Shop
|
|
- **Focus**: Everyday Indonesian conversations and cultural contexts
|
|
|
|
### 🇩🇪 German (Deutsch lernen in Berlin)
|
|
- **URL**: `http://localhost:3001`
|
|
- **Scenarios**: Späti, WG Viewing, Bürgeramt, Biergarten, U-Bahn
|
|
- **Focus**: Berlin-specific German for expats
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
- Python 3.8+
|
|
- Node.js 16+
|
|
- Google Cloud credentials (for Speech-to-Text and Text-to-Speech)
|
|
- OpenAI API key
|
|
|
|
### 1. Environment Setup
|
|
```bash
|
|
# Backend environment
|
|
cp backend/.env.example backend/.env
|
|
# Edit backend/.env with your API keys
|
|
|
|
# Set up Google Cloud credentials
|
|
export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/service-account-key.json"
|
|
```
|
|
|
|
### 2. Install Dependencies
|
|
```bash
|
|
# Backend dependencies
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
|
|
# Indonesian app dependencies (if not already installed)
|
|
cd ..
|
|
npm install
|
|
|
|
# German app dependencies
|
|
cd apps/german-app
|
|
npm install
|
|
```
|
|
|
|
### 3. Start All Services
|
|
```bash
|
|
# From the project root
|
|
./start-street-lingo.sh
|
|
```
|
|
|
|
This will start:
|
|
- Backend API server on port 8000
|
|
- Indonesian app on port 3000
|
|
- German app on port 3001
|
|
|
|
## Manual Setup (Alternative)
|
|
|
|
### Backend
|
|
```bash
|
|
cd backend
|
|
python main.py
|
|
```
|
|
|
|
### Indonesian App
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### German App
|
|
```bash
|
|
cd apps/german-app
|
|
npm run dev
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Language-Specific Scenarios
|
|
- `GET /api/scenarios/indonesian` - Indonesian scenarios
|
|
- `GET /api/scenarios/german` - German scenarios
|
|
- `GET /api/scenarios` - All scenarios for all languages
|
|
|
|
### WebSocket Connections
|
|
- `ws://localhost:8000/ws/speech/indonesian` - Indonesian speech interface
|
|
- `ws://localhost:8000/ws/speech/german` - German speech interface
|
|
|
|
### Translation
|
|
- `POST /api/translate` - Translate text between languages
|
|
|
|
## Architecture
|
|
|
|
```
|
|
street-lingo/
|
|
├── backend/ # Shared backend
|
|
│ ├── core/ # Core language-agnostic services
|
|
│ ├── languages/ # Language-specific implementations
|
|
│ │ ├── indonesian/ # Indonesian models & services
|
|
│ │ └── german/ # German models & services
|
|
│ └── main.py # Main FastAPI application
|
|
├── src/ # Indonesian frontend
|
|
├── apps/german-app/ # German frontend
|
|
└── start-street-lingo.sh # Startup script
|
|
```
|
|
|
|
## Features
|
|
|
|
### 🎙️ Speech Recognition
|
|
- Real-time speech-to-text in Indonesian and German
|
|
- Optimized for conversational speech patterns
|
|
|
|
### 🗣️ Text-to-Speech
|
|
- Character-specific voices for immersive conversations
|
|
- Indonesian: Chirp3-HD voices
|
|
- German: Neural2 voices with regional characteristics
|
|
|
|
### 🤖 AI Conversations
|
|
- Context-aware conversations using OpenAI GPT
|
|
- Goal-based learning with progress tracking
|
|
- Cultural and linguistic authenticity
|
|
|
|
### 🎯 Scenario-Based Learning
|
|
- Real-world situations you'll encounter
|
|
- Progressive difficulty and goal completion
|
|
- Immediate feedback and corrections
|
|
|
|
## Development
|
|
|
|
### Adding New Languages
|
|
1. Create new language directory in `backend/languages/`
|
|
2. Implement language-specific models and services
|
|
3. Create frontend app in `apps/[language]-app/`
|
|
4. Update routing in `main.py`
|
|
|
|
### Adding New Scenarios
|
|
1. Define scenarios in `backend/languages/[language]/models.py`
|
|
2. Create personality with goals and helpful phrases
|
|
3. Add to `SCENARIO_PERSONALITIES` dictionary
|
|
|
|
## Environment Variables
|
|
|
|
### Backend (.env)
|
|
```
|
|
OPENAI_API_KEY=your_openai_api_key
|
|
GOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json
|
|
SPEECH_ENCODING=WEBM_OPUS
|
|
SPEECH_SAMPLE_RATE=48000
|
|
TTS_LANGUAGE_CODE=id-ID # or de-DE
|
|
HOST=localhost
|
|
PORT=8000
|
|
DEBUG=true
|
|
```
|
|
|
|
### Frontend
|
|
```
|
|
VITE_WS_BASE_URL=ws://localhost:8000
|
|
VITE_API_BASE_URL=http://localhost:8000
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **WebSocket Connection Failed**
|
|
- Check if backend is running on port 8000
|
|
- Verify CORS settings in backend
|
|
|
|
2. **Speech Recognition Not Working**
|
|
- Ensure microphone permissions are granted
|
|
- Check Google Cloud credentials
|
|
|
|
3. **Audio Playback Issues**
|
|
- Verify browser audio permissions
|
|
- Check TTS service configuration
|
|
|
|
4. **API Errors**
|
|
- Verify OpenAI API key is valid
|
|
- Check Google Cloud Speech/TTS quotas
|
|
|
|
### Logs
|
|
- Backend logs: Console output from `python main.py`
|
|
- Frontend logs: Browser developer console
|
|
- WebSocket logs: Network tab in browser dev tools
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests for new features
|
|
5. Submit a pull request
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. See LICENSE file for details.
|
|
|
|
## Support
|
|
|
|
For issues and questions:
|
|
- Open an issue on GitHub
|
|
- Check the troubleshooting section
|
|
- Review API documentation at `http://localhost:8000/docs` |