Stress Detection System

A machine learning-based stress detection system that analyzes voice patterns to identify stress levels in audio recordings. The system uses acoustic feature extraction and RandomForest classification to predict stress from voice signals.

🎯 Features

• Voice Pattern Analysis: Extracts 21 acoustic features from audio recordings
• Real-time Prediction: Fast API-based backend for stress detection
• Interactive Frontend: Modern React interface with:
  • File upload support
  • Voice recording capability
  • Real-time waveform visualization
  • Pre-loaded test samples
• Multi-format Support: Accepts .wav, .m4a, .mp3, and .webm audio files
• Dataset Integration: Uses CREMA-D Dataset for training

📋 Table of Contents

• Installation
• Quick Start
• Project Structure
• API Documentation
• Dataset Information
• Usage
• Features
• Technology Stack

🚀 Installation

Prerequisites

• Python 3.12+
• Node.js 16+ and npm
• ffmpeg (optional, for .m4a file support)

Backend Setup

1. Navigate to the backend directory:

cd backend

2. Create and activate virtual environment:

python -m venv venv
# Windows
.\venv\Scripts\Activate.ps1
# Linux/Mac
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Prepare the dataset:

python prepare_crema_d.py

5. Train the model:

python train_model.py

6. Start the API server:

uvicorn main:app --reload

The API will be available at http://localhost:8000

Frontend Setup

1. Navigate to the frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The frontend will be available at http://localhost:5173

🏃 Quick Start

1. Start Backend:

   cd backend
   .\venv\Scripts\Activate.ps1  # Windows
   uvicorn main:app --reload

2. Start Frontend (in a new terminal):

   cd frontend
   npm run dev

3. Open Browser: Navigate to http://localhost:5173

4. Test the System:

   • Upload an audio file (.wav, .m4a, or .mp3)
   • Record your voice using the Record tab
   • Try pre-loaded test samples

📁 Project Structure

stress_detection/
├── backend/
│   ├── main.py                 # FastAPI server
│   ├── feature_extraction.py   # Feature extraction functions
│   ├── audio_utils.py          # Audio processing utilities
│   ├── train_model.py          # Model training script
│   ├── prepare_crema_d.py      # CREMA-D dataset preparation script
│   ├── requirements.txt        # Python dependencies
│   ├── model.pkl               # Trained model (generated)
│   ├── dataset/                # Prepared dataset (generated)
│   │
├── CREMA-D-download/            # CREMA-D dataset (in project root)
│   ├── AudioWAV/               # Audio recordings (7,442 files)
│   └── docs/                   # Dataset documentation
│
├── frontend/
│   ├── src/
│   │   ├── App.jsx             # Main React component
│   │   ├── App.css             # Styles
│   │   ├── api.js              # API client
│   │   ├── AudioVisualizer.jsx # Waveform visualization
│   │   └── main.jsx            # Entry point
│   ├── public/
│   │   └── test-samples/       # Test audio files
│   ├── package.json
│   └── vite.config.js
│
├── API_DOCUMENTATION.md        # Complete API documentation
├── DATASET.md                  # Dataset information
├── SYSTEM_DESIGN.md            # System design document
└── README.md                   # This file

📚 Documentation

• API Documentation: Complete API reference, endpoints, and data flow
• Dataset Documentation: Dataset structure, files, and usage information
• System Design: System architecture and design decisions

🎤 Usage

Upload Audio File

1. Click on the Upload tab
2. Drag and drop an audio file or click to browse
3. View the waveform visualization
4. Click Analyze Stress to get prediction

Record Voice

1. Click on the Record tab
2. Click Start Recording
3. Speak into your microphone
4. Click Stop Recording when done
5. Click Analyze Stress to get prediction

Test Samples

1. Click on the Test Samples tab
2. Select a pre-loaded sample
3. View automatic prediction and waveform

🔬 Features Extracted

The system extracts 21 acoustic features from audio:

1. Pitch Features (2): Mean and standard deviation
2. Jitter (1): Pitch instability
3. Shimmer (1): Amplitude instability
4. Energy (1): RMS energy
5. MFCC (13): Mel-frequency cepstral coefficients
6. Spectral Features (3): Centroid, bandwidth, rolloff

See API_DOCUMENTATION.md for detailed feature descriptions.

🛠 Technology Stack

Backend

• FastAPI: Web framework
• scikit-learn: Machine learning (RandomForestClassifier)
• librosa: Audio processing and feature extraction
• numpy: Numerical computations
• pandas: Data manipulation

Frontend

• React: UI framework
• Vite: Build tool and dev server
• Axios: HTTP client
• Web Audio API: Audio recording and visualization

📊 Dataset

The system uses the CREMA-D (Crowd-sourced Emotional Multimodal Actors Dataset):

• 7,442 audio recordings (.wav format)
• 91 actors (48 male, 43 female, ages 20-74)
• 6 emotions mapped to binary stress labels
• Emotion codes embedded in filenames
• High-quality professional recordings

Label Mapping:

• Stressed: Anger, Disgust, Fear, Sad
• Not Stressed: Happy, Neutral

For detailed dataset information, see DATASET.md.

🔄 API Endpoints

Health Check

GET http://localhost:8000/

Predict Stress

POST http://localhost:8000/predict
Content-Type: multipart/form-data
Body: audio file (.wav, .m4a, .mp3, or .webm)

Response:

{
  "label": "stressed",
  "confidence": 85.42
}

See API_DOCUMENTATION.md for complete API reference.

🧪 Model Training

To train the model:

1. Prepare the dataset (organize CREMA-D files):

   cd backend
   python prepare_crema_d.py

2. Train the model:

   python train_model.py

The trained model will be saved as backend/model.pkl and training results in backend/training_result.txt.

📝 Notes

• The model is trained on CREMA-D dataset (7,442 samples) for robust performance
• Model Performance: 92.15% accuracy, 95.11% F1-score, 96.34% precision for stressed detection
• Model Configuration: 500 trees, max_depth=30, GridSearchCV optimized hyperparameters
• Class imbalance is handled automatically with class_weight='balanced'
• All audio files are in .wav format (standardized)
• The system supports real-time recording via browser microphone
• Training results are automatically saved to training_result.txt
• Frontend includes 8 test samples from CREMA-D dataset

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

The CREMA-D dataset is licensed under the Open Database License (ODbL) 1.0. Please refer to the dataset documentation for usage terms: http://opendatacommons.org/licenses/odbl/1.0/

🙏 Acknowledgments

• CREMA-D Dataset (Cao et al., 2014) for providing the emotional speech dataset
• librosa for audio processing capabilities
• FastAPI and React communities

📧 Contact

For questions or issues, please open an issue on the repository.

---

Built with ❤️ for stress detection research