Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Python 3.9+ for the backend
  • Node.js 14+ and npm for the frontend
  • OpenAI API Key - Get one from OpenAI Platform
You’ll need an OpenAI API key with access to the Whisper API to run LangShazam. The API is not free, so monitor your usage.

​
Installation

1

Clone the repository

Clone the LangShazam repository to your local machine:
git clone https://github.com/KocKaan/LanguageDetection.git
cd LanguageDetection
2

Set up the backend

Install the Python dependencies:
cd backend
pip install -r requirements.txt
The backend requires these packages:
  • fastapi==0.109.0 - Web framework
  • uvicorn==0.27.0 - ASGI server
  • openai==1.66.3 - OpenAI API client
  • psutil==5.9.8 - System metrics
  • python-multipart==0.0.9 - File upload support
  • websockets==12.0 - WebSocket support
3

Configure your OpenAI API key

Set your OpenAI API key as an environment variable:
export OPENAI_API_KEY="your-api-key-here"
Never commit your API key to version control. Use environment variables or a .env file (added to .gitignore).
4

Start the backend server

Run the FastAPI server using uvicorn:
uvicorn src.main:app --host 0.0.0.0 --port 10000
The server will start on http://localhost:10000. You should see:
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:10000
5

Set up the frontend

In a new terminal, navigate to the frontend directory and install dependencies:
cd frontend/language-detector-ui
npm install
6

Start the frontend

Start the React development server:
npm start
The app will open in your browser at http://localhost:3000.

​
Test Your Setup

Once both servers are running:
  1. Open your browser to http://localhost:3000
  2. Click the “Start Detection” button
  3. Allow microphone access when prompted
  4. Speak in any language for 4-15 seconds
  5. The detected language will appear on screen
For best results, speak clearly and ensure you’re in a quiet environment. The system requires at least 4 seconds of audio.

​
API Endpoints

Your local backend exposes these endpoints:
EndpointMethodDescription
/GETHealth check - returns {"message": "Server is running!"}
/metricsGETServer metrics including CPU, memory, and request stats
/wsWebSocketReal-time language detection endpoint

​
Configuration

You can customize the backend behavior with environment variables:
VariableDefaultDescription
OPENAI_API_KEYRequiredYour OpenAI API key
PORT10000Backend server port
DEBUGfalseEnable debug logging
See the Environment Variables page for the complete list.

​
Troubleshooting

If your browser blocks microphone access:
  1. Check browser permissions (usually in the address bar)
  2. Ensure you’re using HTTPS or localhost
  3. Try a different browser (Chrome and Firefox work best)
If the frontend can’t connect to the backend:
  1. Verify the backend is running on port 10000
  2. Check that CORS is configured correctly in settings.py
  3. Ensure http://localhost:3000 is in the CORS_ORIGINS list
If you see API-related errors:
  1. Verify your API key is set correctly
  2. Check you have credits in your OpenAI account
  3. Ensure you have access to the Whisper API
  4. Check rate limits (max 3 concurrent calls by default)
If your audio is rejected:
  1. Speak for at least 4 seconds (minimum required)
  2. Ensure audio is being captured (check the microphone level indicator)
  3. Verify your microphone is working in other applications

​
Next Steps

Explore Features

Learn about real-time detection and audio processing

Deploy to Production

Deploy LangShazam to your infrastructure

API Reference

Dive into the WebSocket API documentation

Architecture

Understand the system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us