README.md

---
title: Copyright Purpose Song Recommender
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.24.0
app_file: app.py
pinned: false
short_description: AI-powered song recommendation engine for copyright purpose.
---

# 🎧 AI-Powered Song Recommender for Creative Projects

Welcome to the **Copyrighted-Purpose Song Recommender** — an intelligent assistant that helps you find the perfect song for your project using natural language.

Whether you're working on:
- 🎬 a cinematic scene
- 📱 a viral social media video
- 📢 a brand campaign
- 💔 an emotional film
- etc etc

This app will analyze your needs and recommend songs using real music intelligence powered by:
- **Spotify audio features** (valence, energy, tempo, danceability, etc.)
- **YouTube metadata** (likes, comments, views)
- **LLM parsing** (DeepSeek LLM for production, and still on research for compatible CPU model in HF demo.)

---

## 💡 How It Works

1. **Describe your project** in natural language (e.g. _"I want a sad, emotional breakup song for a scene for a K-drama"_).
2. The system **extracts structured intent** like mood, tempo, genre, etc.
3. Songs are recommended from our catalog based on matching features.
4. ✅ You can give feedback (👍/👎) and export the results.
5. As an overview of the outcome, go to notebook.ipynb -> 4.2 Temporary result
![alt text](https://github.com/shavirazh/copyright-purpose-song-recommender/blob/main/result_overview.png?raw=true)

---

## ✨ Features

- 🎼 **Valence + Danceability mood filtering**
- 🔁 **Reference song similarity matching**
- 📊 **YouTube popularity sorting**
- 🧠 **LLM-powered input parsing**
- 💬 **Feedback logging with export**
- 📁 **Downloadable CSV for results & feedback**

---

## 🚀 Try It Now

1. Enter a description of your scene or campaign
2. Click **🔍 Recommend Songs**
3. Optionally give feedback or export results

---

## 🛠️ Built With

- `Gradio` – UI
- `Transformers` – LLM model loading
- `LangChain` – for prompt templates and parsing
- `Pandas` – data filtering and exporting
- `DeepSeek LLM 7B Chat` – for input parsing (production)
- This space is using compatible model for CPU, yet still on research the best model.

---

## 📂 About the Dataset

- The song catalog includes audio features from Spotify and engagement stats from YouTube.
- You can modify or expand this dataset in your fork.

---

## 🙏 Credits

Developed by Shavira Z (personal project), for use in music publishing song user/clients.

---

## 📬 Feedback or Suggestions?

Feel free to reach out or leave an issue. We’re happy to collaborate or improve this experience!

Email: [email protected]

LinkedIn: https://linkedin.com/in/shavirazh

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference