# devanshrai23/iml-music-genre-mood architecture

> Architecture diagram of the GitHub repository devanshrai23/iml-music-genre-mood, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devanshrai23/iml-music-genre-mood
- Repository: https://github.com/devanshrai23/iml-music-genre-mood

## Overview

This repository is an explainable music genre and mood classification product, exposed as a web demo backed by Python inference services. The primary workflow is audio upload → clip preprocessing and feature/spectrogram generation → genre-model predictions and explanations → interactive playback and attention visualization. A separate mood workflow predicts calibrated mood from Spotify-style descriptors. Training, benchmark reporting, and cross-paradigm explanation are additional product capabilities described in the README; their internal wiring is not fully shown in the sampled source.

Main entry points: [`web/src/App.tsx`](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/App.tsx) (Web app router), [`musicml/predict.py`](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/predict.py) (Genre predictor), [`web/src/components/AnalysisPlayer.tsx`](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/components/AnalysisPlayer.tsx) (Analysis player), [`web/src/api.ts`](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Web app router<br/>[App.tsx]"]
  node_genre_lab["Genre lab<br/>[Lab.tsx]"]
  node_explain_page["Explanation view<br/>[Explain.tsx]"]
  node_results_page["Results explorer<br/>[Results.tsx]"]
  node_mood_page["Mood explorer<br/>[Mood.tsx]"]
  node_analysis_player["Analysis player<br/>[AnalysisPlayer.tsx]"]
  node_audio_playback["Audio playback<br/>[useAudio.ts]"]
  node_spectrogram_view["Attention spectrogram"]
  node_genre_labels["Genre display helpers<br/>[genres.ts]"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_service["Inference service"]
  node_api_server["FastAPI service<br/>[main.py]"]
end

subgraph group_genre["Genre analysis"]
  node_genre_predictor["Genre predictor<br/>[predict.py]"]
  node_audio_pipeline["Audio preprocessing<br/>[audio.py]"]
  node_genre_models["Genre networks<br/>[models.py]"]
  node_model_config["Model configuration<br/>[config.py]"]
end

subgraph group_mood["Mood analysis"]
  node_mood_predictor["Mood predictor<br/>[predict.py]"]
  node_mood_training["Mood model training<br/>[mood_final.py]"]
end

subgraph group_research["Model development"]
  node_feature_extraction["Handcrafted features"]
  node_spectrogram_creation["Mel spectrograms"]
  node_cnn_training["Attention-CNN training<br/>[train_cnn.py]"]
  node_crnn_training["Attention-CRNN training<br/>[train_crnn.py]"]
  node_shap_analysis["TreeSHAP analysis<br/>[explain_shap.py]"]
  node_attention_comparison["Explanation comparison"]
end

node_visitor(("Listener"))

node_visitor -->|"uses"| node_app
node_app -->|"routes to"| node_genre_lab
node_app -->|"routes to"| node_explain_page
node_app -->|"routes to"| node_results_page
node_app -->|"routes to"| node_mood_page
node_genre_lab -.->|"requests analysis"| node_web_api
node_web_api -.->|"calls endpoints"| node_api_server
node_mood_page -->|"requests mood"| node_web_api
node_results_page -->|"loads metrics"| node_web_api
node_api_server -->|"invokes analysis"| node_genre_predictor
node_api_server -->|"invokes prediction"| node_mood_predictor
node_genre_predictor -->|"preprocesses audio"| node_audio_pipeline
node_genre_predictor -->|"loads networks"| node_genre_models
node_audio_pipeline -->|"uses parameters"| node_model_config
node_genre_predictor -->|"uses labels"| node_model_config
node_genre_lab -.->|"presents analysis"| node_analysis_player
node_analysis_player -->|"controls playback"| node_audio_playback
node_analysis_player -->|"renders overlay"| node_spectrogram_view
node_analysis_player -->|"formats predictions"| node_genre_labels
node_mood_page -.->|"sends descriptors"| node_mood_predictor
node_feature_extraction -.->|"provides descriptors"| node_genre_predictor
node_spectrogram_creation -.->|"provides spectrograms"| node_cnn_training
node_spectrogram_creation -.->|"provides spectrograms"| node_crnn_training
node_mood_training -.->|"produces model"| node_mood_predictor
node_feature_extraction -.->|"explains features"| node_shap_analysis
node_crnn_training -.->|"provides attention model"| node_attention_comparison
node_shap_analysis -->|"compares attributions"| node_attention_comparison

click node_app "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/App.tsx"
click node_genre_lab "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Lab.tsx"
click node_explain_page "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Explain.tsx"
click node_results_page "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Results.tsx"
click node_mood_page "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Mood.tsx"
click node_analysis_player "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/components/AnalysisPlayer.tsx"
click node_audio_playback "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/components/useAudio.ts"
click node_spectrogram_view "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/components/SpectrogramView.tsx"
click node_genre_labels "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/genres.ts"
click node_web_api "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/api.ts"
click node_api_server "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/api/main.py"
click node_genre_predictor "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/predict.py"
click node_audio_pipeline "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/audio.py"
click node_genre_models "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/models.py"
click node_model_config "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/config.py"
click node_mood_predictor "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/predict.py"
click node_feature_extraction "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/extract_features.py"
click node_spectrogram_creation "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/make_spectrograms.py"
click node_cnn_training "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/train_cnn.py"
click node_crnn_training "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/train_crnn.py"
click node_mood_training "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/mood_final.py"
click node_shap_analysis "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/explain_shap.py"
click node_attention_comparison "https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/compare_explanations.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_app,node_genre_lab,node_explain_page,node_results_page,node_mood_page,node_analysis_player,node_audio_playback,node_spectrogram_view,node_genre_labels,node_web_api toneBlue
class node_api_server toneAmber
class node_genre_predictor,node_audio_pipeline,node_genre_models,node_model_config toneMint
class node_mood_predictor,node_mood_training toneRose
class node_feature_extraction,node_spectrogram_creation,node_cnn_training,node_crnn_training,node_shap_analysis,node_attention_comparison,node_visitor toneIndigo
```

## Components

### Web experience

- [Web app router](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Genre lab](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Lab.tsx): `web/src/pages/Lab.tsx`
- [Explanation view](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Explain.tsx): `web/src/pages/Explain.tsx`
- [Results explorer](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Results.tsx): `web/src/pages/Results.tsx`
- [Mood explorer](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/pages/Mood.tsx): `web/src/pages/Mood.tsx`
- [Analysis player](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/components/AnalysisPlayer.tsx): `web/src/components/AnalysisPlayer.tsx`
- [Audio playback](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/components/useAudio.ts): `web/src/components/useAudio.ts`
- [Attention spectrogram](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/components/SpectrogramView.tsx): `web/src/components/SpectrogramView.tsx`
- [Genre display helpers](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/genres.ts): `web/src/genres.ts`
- [API client](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/web/src/api.ts): `web/src/api.ts`

### Inference service

- [FastAPI service](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/api/main.py): `api/main.py`

### Genre analysis

- [Genre predictor](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/predict.py): `musicml/predict.py`
- [Audio preprocessing](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/audio.py): `musicml/audio.py`
- [Genre networks](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/models.py): `musicml/models.py`
- [Model configuration](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/config.py): `musicml/config.py`

### Mood analysis

- [Mood predictor](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/musicml/predict.py): `musicml/predict.py`
- [Mood model training](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/mood_final.py): `src/mood_final.py`

### Model development

- [Handcrafted features](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/extract_features.py): `src/extract_features.py`
- [Mel spectrograms](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/make_spectrograms.py): `src/make_spectrograms.py`
- [Attention-CNN training](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/train_cnn.py): `src/train_cnn.py`
- [Attention-CRNN training](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/train_crnn.py): `src/train_crnn.py`
- [TreeSHAP analysis](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/explain_shap.py): `src/explain_shap.py`
- [Explanation comparison](https://github.com/devanshrai23/iml-music-genre-mood/blob/main/src/compare_explanations.py): `src/compare_explanations.py`

### Other components

- **Listener**

## Connections

- Listener → Web app router: uses (evidence: `web/src/App.tsx`)
- Web app router → Genre lab: routes to (evidence: `web/src/App.tsx`)
- Web app router → Explanation view: routes to (evidence: `web/src/App.tsx`)
- Web app router → Results explorer: routes to (evidence: `web/src/App.tsx`)
- Web app router → Mood explorer: routes to (evidence: `web/src/App.tsx`)
- Genre lab → API client: requests analysis
- API client → FastAPI service: calls endpoints
- Mood explorer → API client: requests mood (evidence: `web/src/pages/Mood.tsx`)
- Results explorer → API client: loads metrics (evidence: `web/src/pages/Results.tsx`)
- FastAPI service → Genre predictor: invokes analysis (evidence: `api/main.py`)
- FastAPI service → Mood predictor: invokes prediction (evidence: `api/main.py`)
- Genre predictor → Audio preprocessing: preprocesses audio (evidence: `musicml/predict.py`)
- Genre predictor → Genre networks: loads networks (evidence: `musicml/predict.py`)
- Audio preprocessing → Model configuration: uses parameters (evidence: `musicml/audio.py`)
- Genre predictor → Model configuration: uses labels (evidence: `musicml/predict.py`)
- Genre lab → Analysis player: presents analysis
- Analysis player → Audio playback: controls playback (evidence: `web/src/components/AnalysisPlayer.tsx`)
- Analysis player → Attention spectrogram: renders overlay (evidence: `web/src/components/AnalysisPlayer.tsx`)
- Analysis player → Genre display helpers: formats predictions (evidence: `web/src/components/AnalysisPlayer.tsx`)
- Mood explorer → Mood predictor: sends descriptors
- Handcrafted features → Genre predictor: provides descriptors
- Mel spectrograms → Attention-CNN training: provides spectrograms
- Mel spectrograms → Attention-CRNN training: provides spectrograms
- Mood model training → Mood predictor: produces model
- Handcrafted features → TreeSHAP analysis: explains features
- Attention-CRNN training → Explanation comparison: provides attention model
- TreeSHAP analysis → Explanation comparison: compares attributions (evidence: `README.md`)