🎵 Roodio - Smart Mood-Based Music Streaming & Analysis Platform

📑 Table of Contents

1. Overview
2. Deployment & Architecture
3. 🚀 Web Application Features
4. 🧠 Machine Learning Engine
5. 💻 Local Setup & Testing (For Reviewers)
   • Prerequisites
   • Quick Start
   • Manual Setup
   • Local Environment Details
   • Test Accounts
   • Recommended Testing Order
6. Contributors
7. Disclaimer & License

---

📖 Overview

Roodio is a cutting-edge music streaming platform that integrates advanced Machine Learning to personalize the listening experience based on user mood and emotion. Unlike traditional streaming services, Roodio employs a dual-stack architecture combining a robust Laravel Web Application with a sophisticated Python-based Deep Learning Pipeline to analyze, classify, and recommend music that resonates with the user's current emotional state.

---

🏗️ Deployment & Architecture

Service	URL
Web Application	roodio.id
ML API (Hugging Face)	Roodio Predict API

Architecture Modules

1. 📱 Web Application (webApp): A full-stack Laravel application handling the user interface, music streaming, social features, and administrative controls.
2. 🧠 Machine Learning (machineLearning): A data science pipeline responsible for audio signal processing, lyric sentiment analysis, and multi-modal mood classification.

Production Infrastructure

Component	Technology
Cloud Server (VM)	Azure VM
File Storage	Azure Blob Storage
Database	MySQL 8.x
Email Service	Brevo (SMTP)
CDN & Security	Cloudflare
Domain	Hostinger

---

🚀 Web Application

The webApp serves as the core platform for users, admins, and super admins. It features a modern, responsive UI built with TailwindCSS and Livewire for seamless dynamic interactions.

✨ Key Features

• 🎧 Smart Audio Player: Real-time Beat Visualization, interactive vinyl record animation, and full-screen immersive mode with lyrics.
• 😊 Mood Tracking & Analytics: Daily/weekly mood logging, personalized analytics dashboard, and mood-based playlist generation.
• 👥 Social Community: Thread discussions, replies, reactions, and user networking.
• 🛡️ Role-Based Access Control:
  • User: Standard streaming and social features.
  • Admin: Manage songs (CRUD), playlists, and platform overviews.
  • Super Admin: Manage users, roles, and system-wide configurations.
• 🤖 MLOps Dashboard: Model accuracy monitoring, confidence tracking, and misprediction analysis.

🛠️ Tech Stack & Libraries

• Framework: Laravel 12.x | Livewire 3.7 | TailwindCSS 4.x | Alpine.js
• Database & Storage: MySQL 8.x | Azure Blob Storage
• UI Components: Flowbite, ApexCharts, Chart.js, FullCalendar, Tippy.js
• Animations: Matter.js (2D Physics), AOS, Canvas Particle Network

---

🧠 Machine Learning Engine

The machineLearning module uses a Hierarchical Multi-Modal Classification system that branches based on energy level, combining audio signal analysis with NLP-based lyric sentiment analysis.

🔥 Pipeline Architecture

The system uses a 3-stage hierarchical pipeline:

Audio Input
    │
    ▼
┌──────────────────────────────┐
│  Stage 1: Energy Classifier  │  PyTorch Neural Network
│  (YAMNet + RMS + ZCR)        │  → High Energy / Low Energy
└──────────┬───────────────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
┌──────────┐ ┌──────────┐
│ Stage 2A │ │ Stage 2B │
│ (Audio)  │ │ (Lyrics) │
│ RF + Meta│ │ BERT     │
│→Angry/   │ │→Sad/     │
│  Happy   │ │  Relaxed │
└──────────┘ └──────────┘

1. Stage 1 — Energy Classification (Audio):

• PyTorch NN (AudioClassifier) classifies songs into High Energy or Low Energy.
• Features: YAMNet embeddings (mean, std, max) + RMS + ZCR = 3,074-dimensional vector.

2. Stage 2A — High Energy Branch (Audio-only):

• Random Forest + Meta Classifier (stacking ensemble) to classify between Angry and Happy.

3. Stage 2B — Low Energy Branch (Lyrics-based):

• Fine-tuned BERT to classify between Sad and Relaxed.

*Libraries: torch, tensorflow_hub, transformers, librosa, scikit-learn, mlflow*

---

💻 Local Setup & Testing

A complete guide to running Roodio on your local machine. Intended for lecturers, reviewers, and developers who want to verify features locally.

1. Prerequisites

Make sure the following tools are installed on your machine:

Tool	Version	Notes (Windows Recommended)
PHP + MySQL + Composer	8.2+ / 8.x	Install Laragon. Required extensions: zip, mbstring, pdo_mysql, fileinfo, curl (enable in php.ini).
Node.js	20.19+ / 22.12+	Required by Laravel Vite. Download
Python	3.10+	Download
Git	Latest	Download

2. Quick Start (Automated)

Important

TERMINAL & DIRECTORY REQUIREMENTS:

• Laragon Users: You MUST use the built-in Laragon terminal (Click the Terminal button in the Laragon app). Navigate to the www folder.
• XAMPP Users: Open your preferred terminal and navigate to the htdocs folder.

Clone the repository:

git clone https://github.com/Xullfikar/roodio.git
cd roodio

Warning

CRITICAL: Before running the setup script, YOU MUST START YOUR MYSQL SERVER (e.g., click "Start All" in Laragon or XAMPP). If the database is off, the migration and seeding process will fail.

Run the Setup Script: If you are on Windows, you must allow scripts to run on your system first. Open your terminal (CMD or PowerShell) as Administrator and run:

# Windows Only: Allow script execution
Set-ExecutionPolicy Bypass -Scope Process -Force

Then, run the setup script:

# Windows
setup.bat

# Mac / Linux
bash setup.sh

The setup script automatically: checks extensions, installs Python/Composer/NPM dependencies, configures .env, runs migrations/seeders, creates storage symlinks, and builds frontend assets.

Start the Servers:

# Windows (Standard CMD/PowerShell)
start.bat

# Mac / Linux
bash start.sh

Three terminal windows will open handling the following local servers:

• Laravel Webapp: http://localhost:8000
• Flask ML API: http://localhost:7860
• Vite HMR Server: Running in the background for real-time frontend updates.

3. Manual Setup (Without Script)

If you prefer to set things up manually, follow these steps in 2 separate terminals (Remember to use Laragon's terminal if you are using Laragon):

Terminal 1 — ML API (Python)

# Ensure you are inside the roodio folder (www/roodio or htdocs/roodio)
cd machineLearning/api

# 1. Create a virtual environment (Recommended)
python -m venv venv     # Windows
python3 -m venv venv    # Mac/Linux

# 2. Activate the virtual environment
venv\Scripts\activate   # Windows
source venv/bin/activate # Mac/Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Start the Flask server
python app.py           # Windows
python3 app.py          # Mac/Linux

Terminal 2 — Laravel Webapp

# Ensure you are inside the roodio folder (www/roodio or htdocs/roodio)
cd webApp

# 1. Install dependencies
composer install
npm install && npm run build

# 2. Setup Environment
cp .env.example .env
php artisan key:generate

# 3. Setup Database (Ensure MySQL is running first, then configure DB credentials in .env)
php artisan migrate --seed

# 4. Create storage symlink
php artisan storage:link

# 5. Start the server
php artisan serve

4. Local Environment Details

• File Uploads: Stored locally in webApp/storage/app/public/ (no Azure credentials needed).
• Emails/OTP: Emails are NOT sent. OTP codes are logged in webApp/storage/logs/laravel.log.
• Database Initial State: Starts empty (no pre-loaded songs) to save local storage. Admin must upload songs to test the ML API.

5. Test Accounts

After the setup script finishes, use these seeded accounts:

Role	Username	Password
User	user	password
Admin	admin	password
SuperAdmin	superadmin	password

6. Recommended Testing Order

To fully test the application locally, follow this sequence:

1. Auth: Test Login, Register (check Laravel log for OTP), and Forgot Password.
2. Admin Songs: Login as admin, go to Songs, and upload a few MP3s. The Flask ML API will automatically predict the mood.
3. Admin Playlists: Create playlists using the uploaded songs.
4. User Features: Login as user. Test Home, Mood Filtering, Threads, Socials, and Profile updates.
5. SuperAdmin: Login as superadmin. Test User Management and Role assignments.
6. MLOps: Go back to Admin to check the Model Monitor and Feedback metrics.

---

🔧 Troubleshooting: ML API Errors

❌ Song Upload Returns an Error / Mood Prediction Fails

When uploading a song, the Laravel app calls the local Flask ML API at http://localhost:7860. If the mood prediction fails, the most common cause is a corrupted or incomplete model download cache.

The ML API uses pre-trained models (YAMNet via TensorFlow Hub, BERT via Hugging Face) that are downloaded and cached on first run. If the download was interrupted, the cached files can become corrupted and cause errors like:

OSError: Unable to load weights from checkpoint file
RuntimeError: PytorchStreamReader failed
tensorflow.python.framework.errors_impl.NotFoundError: ...

✅ Fix: Clear the Model Cache

Run the following commands in your terminal to delete the corrupted cache and force a fresh download on the next startup:

Windows (PowerShell or CMD):

# Clear TensorFlow Hub cache (YAMNet model)
Remove-Item -Recurse -Force "$env:TEMP\tfhub_modules" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\tfhub_modules" -ErrorAction SilentlyContinue

# Clear Hugging Face cache (BERT model)
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\huggingface" -ErrorAction SilentlyContinue

Mac / Linux (Bash):

# Clear TensorFlow Hub cache (YAMNet model)
rm -rf /tmp/tfhub_modules
rm -rf ~/.cache/tfhub_modules

# Clear Hugging Face cache (BERT model)
rm -rf ~/.cache/huggingface

After clearing the cache, restart the Flask ML API server and wait for the models to re-download completely before uploading a song:

# Inside machineLearning/api with venv activated:
python app.py   # Windows
python3 app.py  # Mac/Linux

Note

The first startup after clearing the cache may take several minutes depending on your internet speed, as the models (YAMNet ~200MB, BERT ~400MB) need to be fully re-downloaded. Do not interrupt the process.

---

👥 Contributors

• Andi Zulfikar - Backend Developer & ML Engineer
• William Pratama - Frontend Developer
• Agnes Gonxha Febriane Sukma - UI/UX Designer
• Felicia Wijaya - UI/UX Designer
• Yoyada Indrayudha - Quality Assurance

---

⚠️ Disclaimer

This project is intended for educational purposes only. It is not designed for commercial use, production environments, or widespread deployment. The codebase serves as a demonstration of technical concepts and should be used accordingly.

---

📝 License

This project is open-sourced software licensed under the MIT license.