5.0 KiB
5.0 KiB
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
# 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
# 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
# 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
cd backend
python main.py
Indonesian App
npm run dev
German App
cd apps/german-app
npm run dev
API Endpoints
Language-Specific Scenarios
GET /api/scenarios/indonesian
- Indonesian scenariosGET /api/scenarios/german
- German scenariosGET /api/scenarios
- All scenarios for all languages
WebSocket Connections
ws://localhost:8000/ws/speech/indonesian
- Indonesian speech interfacews://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
- Create new language directory in
backend/languages/
- Implement language-specific models and services
- Create frontend app in
apps/[language]-app/
- Update routing in
main.py
Adding New Scenarios
- Define scenarios in
backend/languages/[language]/models.py
- Create personality with goals and helpful phrases
- 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
-
WebSocket Connection Failed
- Check if backend is running on port 8000
- Verify CORS settings in backend
-
Speech Recognition Not Working
- Ensure microphone permissions are granted
- Check Google Cloud credentials
-
Audio Playback Issues
- Verify browser audio permissions
- Check TTS service configuration
-
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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new features
- 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