street-lingo/STREET_LINGO_README.md

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 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