# rahulw311/facial-emotion-recognition architecture

> Architecture diagram of the GitHub repository rahulw311/facial-emotion-recognition, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rahulw311/facial-emotion-recognition
- Repository: https://github.com/rahulw311/facial-emotion-recognition

## Overview

BoomBox is a desktop music player with facial-emotion-based song suggestions. The main workflow is user-triggered: the GUI asks the recognition module to capture webcam frames, detect and classify a face, then return a shuffled set of songs for the detected emotion; the GUI places those songs in its playlist for playback. A separate optional path captures labeled faces and retrains the FisherFaces model. The README documents an emotion-to-song spreadsheet, but that file is absent from the tree; unsampled implementation details are not inferred.

Main entry points: [`emotion_recognition.py`](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py) (Recognition entry), [`music_player.py`](https://github.com/rahulw311/facial-emotion-recognition/blob/main/music_player.py) (Player GUI), [`Update_Model.py`](https://github.com/rahulw311/facial-emotion-recognition/blob/main/Update_Model.py) (Model updater), [`trained_emoclassifier.xml`](https://github.com/rahulw311/facial-emotion-recognition/blob/main/trained_emoclassifier.xml) (Trained model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop player"]
  node_player["Player GUI<br/>[music_player.py]"]
  node_playlist["Playlist controls<br/>[music_player.py]"]
  node_playback["Audio playback<br/>[music_player.py]"]
end

subgraph group_recognition["Emotion recognition"]
  node_recognition_entry["Recognition entry"]
  node_frame_processing["Frame processing"]
  node_face_detection["Face detection"]
  node_cascade["Cascade classifier"]
  node_emotion_classifier["Emotion classifier"]
end

subgraph group_recommendations["Music suggestions"]
  node_song_mapping["Emotion song mapping"]
  node_song_sheet["Song spreadsheet"]
  node_suggestion_queue["Shuffled suggestions"]
end

subgraph group_model["Model training"]
  node_trained_model["Trained model"]
  node_capture_training["Labeled capture"]
  node_training_images[("Training images")]
  node_model_update["Model updater<br/>[Update_Model.py]"]
end

node_user(("User"))
node_webcam["Webcam"]

node_user -->|"uses"| node_player
node_player -->|"requests suggestions"| node_recognition_entry
node_recognition_entry -->|"opens and reads"| node_webcam
node_recognition_entry -->|"runs detection"| node_frame_processing
node_frame_processing -->|"detects faces"| node_face_detection
node_face_detection -->|"loads classifier"| node_cascade
node_recognition_entry -->|"loads model"| node_trained_model
node_recognition_entry -->|"classifies captures"| node_emotion_classifier
node_emotion_classifier -->|"selects emotion songs"| node_song_mapping
node_song_mapping -->|"reads emotion lists"| node_song_sheet
node_song_mapping -->|"shuffles songs"| node_suggestion_queue
node_suggestion_queue -->|"returns suggestions"| node_player
node_player -->|"populates playlist"| node_playlist
node_user -->|"manages songs"| node_playlist
node_playlist -->|"selects track"| node_playback
node_user -->|"controls playback"| node_playback
node_recognition_entry -->|"optionally updates"| node_capture_training
node_capture_training -->|"captures labeled faces"| node_webcam
node_capture_training -->|"saves face images"| node_training_images
node_capture_training -->|"calls update"| node_model_update
node_model_update -->|"trains from images"| node_training_images
node_model_update -->|"writes model"| node_trained_model

click node_player "https://github.com/rahulw311/facial-emotion-recognition/blob/main/music_player.py"
click node_playlist "https://github.com/rahulw311/facial-emotion-recognition/blob/main/music_player.py"
click node_playback "https://github.com/rahulw311/facial-emotion-recognition/blob/main/music_player.py"
click node_recognition_entry "https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py"
click node_frame_processing "https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py"
click node_face_detection "https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py"
click node_cascade "https://github.com/rahulw311/facial-emotion-recognition/blob/main/haarcascade_frontalface_default.xml"
click node_emotion_classifier "https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py"
click node_trained_model "https://github.com/rahulw311/facial-emotion-recognition/blob/main/trained_emoclassifier.xml"
click node_song_mapping "https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py"
click node_suggestion_queue "https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py"
click node_capture_training "https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py"
click node_model_update "https://github.com/rahulw311/facial-emotion-recognition/blob/main/Update_Model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_player,node_playlist,node_playback,node_user toneBlue
class node_recognition_entry,node_frame_processing,node_face_detection,node_cascade,node_emotion_classifier toneAmber
class node_song_mapping,node_song_sheet,node_suggestion_queue toneMint
class node_trained_model,node_capture_training,node_training_images,node_model_update toneRose
class node_webcam toneIndigo
```

## Components

### Desktop player

- [Player GUI](https://github.com/rahulw311/facial-emotion-recognition/blob/main/music_player.py): `music_player.py`
- [Playlist controls](https://github.com/rahulw311/facial-emotion-recognition/blob/main/music_player.py): `music_player.py`
- [Audio playback](https://github.com/rahulw311/facial-emotion-recognition/blob/main/music_player.py): `music_player.py`

### Emotion recognition

- [Recognition entry](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py): `emotion_recognition.py`
- [Frame processing](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py): `emotion_recognition.py`
- [Face detection](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py): `emotion_recognition.py`
- [Cascade classifier](https://github.com/rahulw311/facial-emotion-recognition/blob/main/haarcascade_frontalface_default.xml): `haarcascade_frontalface_default.xml`
- [Emotion classifier](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py): `emotion_recognition.py`

### Music suggestions

- [Emotion song mapping](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py): `emotion_recognition.py`
- **Song spreadsheet**
- [Shuffled suggestions](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py): `emotion_recognition.py`

### Model training

- [Trained model](https://github.com/rahulw311/facial-emotion-recognition/blob/main/trained_emoclassifier.xml): `trained_emoclassifier.xml`
- [Labeled capture](https://github.com/rahulw311/facial-emotion-recognition/blob/main/emotion_recognition.py): `emotion_recognition.py`
- **Training images**
- [Model updater](https://github.com/rahulw311/facial-emotion-recognition/blob/main/Update_Model.py): `Update_Model.py`

### Other components

- **User**
- **Webcam**

## Connections

- User → Player GUI: uses (evidence: `README.md`)
- Player GUI → Recognition entry: requests suggestions (evidence: `music_player.py`)
- Recognition entry → Webcam: opens and reads (evidence: `emotion_recognition.py`)
- Recognition entry → Frame processing: runs detection (evidence: `emotion_recognition.py`)
- Frame processing → Face detection: detects faces (evidence: `emotion_recognition.py`)
- Face detection → Cascade classifier: loads classifier (evidence: `emotion_recognition.py`)
- Recognition entry → Trained model: loads model (evidence: `emotion_recognition.py`)
- Recognition entry → Emotion classifier: classifies captures (evidence: `emotion_recognition.py`)
- Emotion classifier → Emotion song mapping: selects emotion songs (evidence: `emotion_recognition.py`)
- Emotion song mapping → Song spreadsheet: reads emotion lists (evidence: `README.md`)
- Emotion song mapping → Shuffled suggestions: shuffles songs (evidence: `emotion_recognition.py`)
- Shuffled suggestions → Player GUI: returns suggestions (evidence: `emotion_recognition.py`)
- Player GUI → Playlist controls: populates playlist (evidence: `music_player.py`)
- User → Playlist controls: manages songs (evidence: `music_player.py`)
- Playlist controls → Audio playback: selects track (evidence: `music_player.py`)
- User → Audio playback: controls playback (evidence: `music_player.py`)
- Recognition entry → Labeled capture: optionally updates (evidence: `emotion_recognition.py`)
- Labeled capture → Webcam: captures labeled faces (evidence: `emotion_recognition.py`)
- Labeled capture → Training images: saves face images (evidence: `emotion_recognition.py`)
- Labeled capture → Model updater: calls update (evidence: `emotion_recognition.py`)
- Model updater → Training images: trains from images (evidence: `Update_Model.py`)
- Model updater → Trained model: writes model (evidence: `Update_Model.py`)
