update readme

Author: muntasir-islam

README.md

@@ -1,54 +1,60 @@
-# 🎓 ModalX: The Smart Faculty Grading Assistant
-**AI-Powered Presentation Assessment System**
+# ModalX-AI Challenge: Presentation Assessment System
 
-> 🔴 **Live Demo:** [ml.muntasirislam.com/modalx](https://ml.muntasirislam.com/modalx)
+**Team Name:** NL Circuits
+**Team Members:** Muntasir Islam, Nazmus Sakib
+**Student IDs:** 0242220005131010, 0242220005131017
+**Event:** ModalX-AI Challenge (Daffodil International University)
 
 ---
 
-## 💡 The Problem We Are Solving
-Faculty members and lecturers face a massive challenge: **Grading Fatigue.**
+## Project Overview
 
-Imagine sitting through 50 student presentations in a single day. By the 40th student, it becomes incredibly difficult to remain objective, track every pause, or measure eye contact accurately. Grading becomes subjective, and providing detailed, personalized feedback for every single student is nearly impossible due to time constraints.
+ModalX is an automated grading system for student presentations. It replaces subjective human grading with data-driven metrics. The system analyzes three key areas:
+1.  **Audio:** Speaking pace, volume, and pitch variation.
+2.  **Visual:** Eye contact, body posture, and slide detection (analyzing both slide content and visuals).
+3.  **Emotion:** Vocal tone and confidence levels.
 
-**ModalX is built to be the Lecturer's "Helping Hand".**
-It automates the tedious parts of grading (measuring pace, volume, slide density, and posture) so the faculty member can focus on what matters most: the **content and the idea**.
+This repository is organized into three folders corresponding to the competition phases.
 
 ---
 
-## ⚙️ How It Helps the Faculty
-We designed this system to act as an objective, "Responsible AI" grader that follows a standard rubric.
-
-### 1. Automated Rubric & Evidence
-Instead of just giving a grade like "B+", ModalX generates a **Detailed PDF Report** for every student. This serves as:
-* **Proof of Assessment:** A physical record of why a student received a specific grade.
-* **Objectivity:** The AI doesn't get tired. It grades the first student and the last student with the exact same criteria.
-
-### 2. The "Context-Aware" Grading Engine
-Lecturers encounter different types of presentations. A "One-size-fits-all" AI fails here. We built a **"Smart Pivot"** engine that adapts:
-
-* **Scenario A: The Speech.** If the student is on camera, the AI uses `MediaPipe` to grade **Eye Contact** and **Posture Stability**.
-* **Scenario B: The Screen Share.** If the student is showing slides (and their face is hidden), the AI automatically switches to **OCR Mode**. It reads the slides using `Tesseract` to check for **Readability** and **Text Density** (avoiding "Death by PowerPoint").
-
-### 3. Deep Audio Forensics
-We go beyond simple transcription.
-* **Confidence scoring:** Using RMS Energy to detect mumbling vs. projection.
-* **Hesitation Analysis:** Distinguishing between a "Dramatic Pause" (good) and "Nervous Stuttering" (needs improvement).
+## Repository Structure
+
+### 1. Phase_1_Speech_Analysis
+This folder contains the logic for processing audio.
+* **Focus:** Speech Clarity, Confidence, and Delivery.
+* **Key Metrics:**
+    * **Words Per Minute (WPM):** measures speaking speed.
+    * **Pitch Variation:** detects if the voice is monotone.
+    * **Pause Ratio:** measures hesitation.
+    * **Emotion Analysis:** detects emotions and measures confidence scales.
+* **Tech Stack:** OpenAI Whisper, Librosa, TensorFlow.
+
+### 2. Phase_2_Visual_Analysis
+This folder contains the logic for computer vision (Face, Body movement analysis, and Slide content/visual analysis).
+* **Focus:** Body Language, Engagement, and Slide Contents.
+* **Key Metrics:**
+    * **Eye Contact:** tracks if the speaker is looking at the camera.
+    * **Posture Stability:** checks for slouching, movement, hand movements, and gestures.
+    * **Slide Detection:** differentiates between a person speaking and screen-shared slides; measures slide content density and visual content ratios.
+* **Tech Stack:** MediaPipe Holistic, OpenCV.
+
+### 3. Phase_3_Full_System
+This is the final integrated application. It combines Phase 1 and Phase 2, adds the Emotion Engine, and generates the final report.
+* **Focus:** System Integration and Reporting.
+* **Features:**
+    * **Emotion Engine:** A CNN model that detects happy, nervous, or neutral tones.
+    * **Content Analysis:** Scans the transcript for professional vocabulary.
+    * **PDF Report:** Automatically generates a scorecard with a final grade.
+* **Main File:** `app.py` (Streamlit Dashboard).
 
 ---
 
-## 📂 Project Architecture (Phase by Phase)
-This repository documents our development journey for the ModalX AI Challenge:
-
-* **`Phase_1_Speech_Analysis/`**: The core audio processing logic. We built the "Prosody Engine" here to measure pitch and pacing.
-* **`Phase_2_Visual_Analysis/`**: The computer vision layer. This contains the logic for the "Smart Pivot" (Face vs. Slide detection).
-* **`Phase_3_Full_System/`**: The production-ready web application hosted on the live server.
-
----
+## Installation Guide
 
-## 🛠️ Deployment & Usage
-The project is currently hosted live, but you can run a local instance for testing.
+Follow these steps to set up the project on your local machine.
 
-**1. Clone & Install**
+**1. Clone the Repository**
 ```bash
-git clone https://github.com/muntasir-islam/ModalX-AI-Challenge.git
-pip install -r requirements.txt
+git clone [https://github.com/muntasir-islam/ModalX-AI-Challenge.git](https://github.com/muntasir-islam/ModalX-AI-Challenge.git)
+cd ModalX-AI-Challenge