# shivamshinde123/instrument-based-music-recommendation architecture

> Architecture diagram of the GitHub repository shivamshinde123/instrument-based-music-recommendation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shivamshinde123/instrument-based-music-recommendation
- Repository: https://github.com/shivamshinde123/instrument-based-music-recommendation

## Overview

##### Project type and purpose
- DeepMelody is a full-stack, data-driven ML application with two halves:
a. An offline pipeline that (a) ingest multitrack audio (Slakh2100), (b) preprocesses data, (c) trains a U-Net source-separation model, (d) extracts per-instrument embeddings, and (e) computes a similarity matrix.
b. An online Streamlit web app that serves personalized music recommendations based on those embeddings.

##### File structure
- Top level:
- Experimentation/: Jupyter notebooks for exploratory analysis.
- Metrics/: stored JSON metrics (validation_metrics.json).
- src/: production code, organized as sequential “step” scripts plus an app.
– step0_utility_functions.py: shared helpers
– step1_creating_csv.py: metadata consolidation
– step2_DatasetLoading.py: data preprocessing
– step3_calculate_similarity_scores.py: embedding & similarity matrix
– step4_ModelTraining.py: U-Net training
– prediction_funcs.py: inference utilities
– app.py: Streamlit front end
- Config & dependencies: params.yaml, requirements.txt.
- Documentation: README.md, project PDF, LICENSE.

##### README for additional insights
- Confirms a U-Net model for instrument isolation, creation of instrument embeddings, cosine-similarity–based recommendations, and a Streamlit UI.

a. Main components
1. Data Source
- Slakh2100 dataset (audio + metadata) on disk.
2. Offline Pipeline
- Data Consolidation (step1)
- Preprocessing & Loader (step2)
- Model Training (step4)
- Embedding Extraction & Similarity Computation (step3)
- Utility Functions (step0 + prediction_funcs)
3. Storage
- CSV metadata, processed data caches, trained model weights, embedding matrix, validation metrics.
4. Online Service (Streamlit App)
- UI, user input (instrument preferences), query to similarity engine, displays recommendations.
5. External Dependencies
- PyTorch, librosa, numpy, scikit-learn, pandas, Streamlit

b. Relationships & Interactions
- Data flows from Slakh2100 → step1 → step2 → step4 → step3 → storage.
- The trained U-Net model (step4 output) is loaded by prediction_funcs at inference time.
- Embedding matrix from step3 is loaded by the Streamlit app to compute top-N similar tracks per user query.
- Validation metrics saved in Metrics/ can be consumed by a monitoring or dashboard component.

c. Architectural patterns & design principles
- Pipeline pattern: clearly separated sequential ETL + training + embedding computation steps.
- Layered architecture: Data layer (raw & intermediate), Model layer (U-Net weights), Service layer (recommendation logic), Presentation layer (Streamlit UI).
- Single-process microservice for online recommendations (no distributed services yet).

d. Key technologies & frameworks
- Python 3.x orchestrates all steps.
- PyTorch for neural-network training.
- librosa for audio feature extraction.
- pandas/numpy for metadata and array manipulation.
- scikit-learn for similarity (cosine) calculations.
- Streamlit for web UI.
- YAML for parameter/config management.

##### Diagramming recommendations
- Use clear, concise labels for each component (e.g., “Step1: CSV Creation”, “Step4: U-Net Model Trainer”).
- Blue for data stores
- Green for processing/training steps
- Orange for the online service/UI
- Rectangles for computation modules
- Rounded rectangles for user interfaces

##### Detail—don’t omit any critical element
- Params.yaml and requirements.txt near the root as they drive reproducibility.
- Metrics/ as a feedback loop to the Experimentation component for continuous improvement.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Source
    Slakh[(“Slakh2100 Dataset”)]:::datastore

    %% Offline Pipeline
    subgraph "Offline Pipeline"
        direction TB
        Step0["Step0: Utility Functions"]:::process
        Step1["Step1: CSV Creation"]:::process
        Step2["Step2: Dataset Loading"]:::process
        Step4["Step4: U-Net Trainer"]:::process
        Step3["Step3: Similarity Computation"]:::process
        PredFuncs["Inference Utilities"]:::process
    end

    %% Storage
    subgraph "Storage Artifacts"
        direction TB
        CSV[(“Metadata CSV”)]:::datastore
        Cache[(“Processed Data Cache”)]:::datastore
        ModelWeights[(“U-Net Model Weights”)]:::datastore
        Embeddings[(“Instrument Embedding Matrix”)]:::datastore
        Metrics[(“Validation Metrics JSON”)]:::datastore
    end

    %% Online Service
    subgraph "Online Recommendation Service"
        direction TB
        App("Streamlit UI"):::ui
    end

    %% Experimentation
    Experimentation["Experimentation Notebooks"]:::notebook

    %% Config & Docs
    subgraph "Configuration & Documentation"
        direction TB
        Params["params.yaml"]:::config
        Requirements["requirements.txt"]:::config
        README["README.md"]:::config
        License["LICENSE"]:::config
        PDF["CS541FinalProject.pdf"]:::config
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch"]:::external
        Librosa["librosa"]:::external
        NumPy["NumPy"]:::external
        Pandas["pandas"]:::external
        Sklearn["scikit-learn"]:::external
        StreamlitLib["Streamlit"]:::external
        YAML["YAML"]:::external
    end

    %% Data Flow
    Slakh --> Step1
    Step1 --> Step2
    Step2 --> Step4
    Step4 --> Step3
    Step1 --> CSV
    Step2 --> Cache
    Step4 --> ModelWeights
    Step3 --> Embeddings
    Step3 --> Metrics
    Step0 --> Step1
    Step0 --> Step2
    Step0 --> Step4
    Step0 --> Step3

    %% Inference Flow
    App -->|loads| Embeddings
    App -->|loads| ModelWeights
    App --> PredFuncs
    PredFuncs --> ModelWeights

    %% Experimentation Feedback
    Metrics --> Experimentation

    %% Config & Docs Relations
    Params -.-> Step0
    Requirements -.-> Step0
    README -.-> Step0

    %% External Dependencies Usage
    PyTorch -.-> Step4
    Librosa -.-> Step2
    NumPy -.-> Step1
    Pandas -.-> Step1
    Sklearn -.-> Step3
    StreamlitLib -.-> App
    YAML -.-> Step0

    %% Click Events
    click Step0 "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/src/step0_utility_functions.py"
    click Step1 "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/src/step1_creating_csv.py"
    click Step2 "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/src/step2_DatasetLoading.py"
    click Step4 "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/src/step4_ModelTraining.py"
    click Step3 "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/src/step3_calculate_similarity_scores.py"
    click PredFuncs "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/src/prediction_funcs.py"
    click App "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/src/app.py"
    click Experimentation "https://github.com/shivamshinde123/instrument-based-music-recommendation/tree/main/Experimentation/"
    click Metrics "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/Metrics/validation_metrics.json"
    click Params "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/params.yaml"
    click Requirements "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/requirements.txt"
    click README "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/README.md"
    click License "https://github.com/shivamshinde123/instrument-based-music-recommendation/tree/main/LICENSE"
    click PDF "https://github.com/shivamshinde123/instrument-based-music-recommendation/blob/main/CS541FinalProject.pdf"

    %% Styles
    classDef datastore fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef process fill:#90EE90,stroke:#000,stroke-width:1px
    classDef ui fill:#FFA500,stroke:#000,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef notebook fill:#F0F0F0,stroke:#000,stroke-width:1px
```
