🎵 Chameleon Tutor Studio

Turn study notes into full songs.
Chameleon Tutor Studio is a Streamlit-based app that transforms PDF study notes into catchy AI-generated lyrics, lays them over real instrumentals (from YouTube or reused beats), synthesizes vocals, and produces a polished final mix — all in one workflow.

✨ What It Does

📄 Upload PDFs (study notes, summaries, textbooks)

✍️ Generate English-only song lyrics using Groq LLMs

🎤 AI voice synthesis with adjustable speed

🎶 Instrumental extraction from YouTube using Demucs

🎚️ Audio mixing & effects (reverb, compression, delay)

💾 Save finished songs to a local library

▶️ Playlist playback inside the app

🧠 How It Works (High Level)

PDF → Lyrics

Extracts text from uploaded PDFs

Uses Groq’s LLaMA model to write catchy English-only lyrics

Automatically verifies lyrics for symbols / non-English characters

Beat Selection

Download audio from YouTube or

Reuse previously processed beats

Separates vocals & instrumentals using Demucs

Voice & Mixing

Generates vocals using Microsoft Edge TTS

Applies effects via Pedalboard

Mixes AI vocals + beat (+ optional ghost vocals)

Export

Renders a final MP3

Saves audio + lyrics into a reusable library

🛠️ Tech Stack

Frontend: Streamlit

LLM: Groq (LLaMA 3.3 70B)

TTS: edge-tts

Audio Processing:

Demucs (source separation)

Pydub

Pedalboard

YouTube Audio: yt-dlp

PDF Parsing: PyPDF

Environment Management: python-dotenv

📁 Project Structure
notes2song/
├── app.py
├── .env
├── temp_audio/          # Downloaded YouTube audio
├── separated/htdemucs/  # Vocal / instrumental stems
├── output/              # Intermediate + final renders
├── final_library/       # Saved songs + lyrics
└── README.md

🔐 Environment Setup
1. Clone the repo
git clone https://github.com/your-username/notes2song.git
cd notes2song

2. Create a virtual environment
python -m venv venv
source venv/bin/activate

3. Install dependencies
pip install -r requirements.txt

4. Add environment variables

Create a .env file:

GROQ_API_KEY=your_groq_api_key_here


⚠️ .env should never be committed to GitHub.

▶️ Running the App
streamlit run app.py


Then open the browser link Streamlit provides.

🎛️ Controls Overview

Mixer (Sidebar)

AI Voice Volume

Beat Volume

Ghost Vocal Volume

Voice Speed

Reverb

Echo

Main Actions

Refresh / Write Lyrics

Render Audio

Save to Library

💾 Library & Playlists

Saved songs are stored in final_library/

Each song includes:

.mp3 audio

.txt lyrics

Build playlists and loop them directly in the sidebar

⚠️ Notes & Limitations

Demucs runs on CPU by default (can be slow for long tracks)

YouTube downloads may require cookies for age/region-restricted videos

Large PDFs are truncated to avoid token limits

This app is intended for educational and personal use

🧪 Future Ideas

Multiple voice selection

Genre/style controls for lyric generation

GPU acceleration for Demucs

Cloud deployment

BPM matching & auto-chorus detection

❤️ Why This Exists

Studying doesn't have to be boring.
If your brain remembers lyrics better than notes — this is for you.