street-lingo/STREET_LINGO_README.md

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`