How jathinlohi/emotion2playlist works
Project Type and Purpose
• This is a full-stack/utility tool project aimed at transforming text input into personalized Spotify playlists by using a fine-tuned BERT model for emotion detection.
• The README clearly outlines that the system uses a fine-tuned emotion classifier and integrates with Spotify’s API to recommend playlists.
Analyzing the File Structure
• The top-level files include the main application entry point (main.py), a Jupyter notebook for fine-tuning (“Fine-Tuning BERT.ipynb”), and a data directory (with songs.json) used in the pipeline.
• The model directory contains the core emotion classification logic (model/emotion_classifier.py).
• The utils directory includes a suite of helper modules:
• data_preprocessing.py: Handles text and data preprocessing.
• emotion_mapping.py and emotions_mood.py: Likely perform mapping of detected emotions to mood or playlist selection.
• inference.py: Orchestrates running the model for prediction.
• label_map.py: Contains mapping between numerical labels and emotion names.
• playlist_generator.py: Implements logic to generate playlists, probably by interacting with the Spotify API.
• spotify_utils.py: Provides integration functions with the Spotify API.
• save_dataset.py: Likely responsible for persisting datasets if needed.
• The presence of the requirements.txt file provides dependency information.
Core Components
a. Input Layer / UI:
• Although the UI is still under development, include a placeholder component for user input (where users enter text data).
b. Preprocessing:
• Component that handles data preprocessing (utils/data_preprocessing.py).
c. Emotion Classification:
• The fine-tuned BERT model housed in model/emotion_classifier.py. Also, include any components related to inference (utils/inference.py) used to run predictions.
d. Utility & Mapping Services:
• Emotion mapping layers using utils/emotion_mapping.py and utils/emotions_mood.py which translate detected emotions into mood-based decisions.
• The label map (utils/label_map.py) that provides emotion key-value pairing.
e. Playlist Generation & Spotify Integration:
• The playlist generator (utils/playlist_generator.py) and Spotify API utilities (utils/spotify_utils.py) that generate and retrieve playlist recommendations.
f. Data Storage / Dataset:
• The songs.json file contained in the data directory, which may act as a repository of song/playlist data.
Architectural Relationships & Interactions
• The input text is fed to the Preprocessing component, which cleans and prepares the data.
• Preprocessed text is passed to the Emotion Classification component where the fine-tuned BERT model (via emotion_classifier.py, orchestrated by inference.py) predicts emotion labels.
• The output of emotion detection is forwarded to the mapping components (emotion_mapping.py, emotions_mood.py, label_map.py) to determine suitable moods.
• The playlist generator then processes these results along with data from the songs.json and uses spotify_utils.py to interact with the Spotify API, returning a customized playlist recommendation.
• All of these interactions are coordinated within the main application entry point (main.py).
Architectural Patterns & Principles
• Separation of Concerns: The project clearly separates functionalities into modules (data processing, model inference, utility mapping, API integration).
• Modular Architecture: Use of dedicated directories for models and utilities makes it easy to maintain and test individual components.
• Pipeline Design: The flow from user input, through preprocessing, classification, mapping, and finally playlist generation follows a linear pipeline architecture.