🎵 Ripify - Spotify Playlist Downloader (Web UI, Telegram Bot & CLI)

Ripify is a full-featured Python application designed to convert and download Spotify playlists and individual tracks into high-quality M4A (AAC) or MP3 files, complete with embedded HD album artwork and metadata tags.

The project features three flexible user interfaces:

1. 🌐 Streamlit Web App: A sleek UI with automatic browser file downloads and embedded audio playback.
2. 🤖 Telegram Bot (bot.py): Send a Spotify playlist link to your bot and receive high-quality audio files directly in chat (optimized for iOS & mobile!).
3. 💻 CLI Tool (spotify_downloader.py): Terminal workflow for batch downloads and automated scripting.

---

✨ Key Features

• 🔑 Works WITHOUT Spotify API Keys: Features an automatic Web Scraper fallback (__NEXT_DATA__) that extracts metadata from public playlists without requiring developer credentials.
• 🎯 YouTube Duration Tolerance Filter: Searches YouTube for matching audio and verifies duration within ±10% tolerance to eliminate wrong tracks or long remixes.
• 🏷️ HD Cover Art & ID3 / MP4 Tagging: Automatically embeds Title, Artist, Album, and HD Artwork into both .m4a (mutagen.mp4) and .mp3 (mutagen.id3) files.
• ⚡ Native iOS & Mobile Downloads: Default .m4a (AAC) format plays natively in Apple Music and saves straight to iPhone/iPad Files.
• 🛑 Robust Non-Blocking Pipeline: Handles rate-limiting gracefully and continues downloading remaining songs even if an isolated track fails.
• 🐳 Docker & Docker Compose Ready: Includes Dockerfile with pre-installed ffmpeg and multi-service orchestration.

---

🛠️ Prerequisites

• Python 3.11+ (Tested on Python 3.13)
• FFmpeg installed on your host system.

Installing FFmpeg:

• Ubuntu/Debian: sudo apt update && sudo apt install -y ffmpeg
• macOS: brew install ffmpeg
• Windows: winget install FFmpeg (or via Chocolatey / Scoop).

---

🚀 Installation & Setup

1. Clone the repository:

   git clone https://github.com/your-username/ripify.git
   cd ripify

2. Install Python dependencies:

   pip install -r requirements.txt

3. Configure Environment Variables: Copy .env.example to .env and adjust settings as needed:

   cp .env.example .env

   File contents of .env:

   # Spotify API Credentials (Optional - Fallback scraper activates if empty)
   SPOTIPY_CLIENT_ID=your_client_id
   SPOTIPY_CLIENT_SECRET=your_client_secret
   
   # Telegram Bot Token (Obtain from @BotFather)
   TELEGRAM_BOT_TOKEN=your_telegram_bot_token
   
   # Output Settings
   OUTPUT_DIR=./downloads
   AUDIO_FORMAT=m4a
   DURATION_TOLERANCE=0.10
   INTER_DOWNLOAD_DELAY=0.5

---

🖥️ Usage

1. Web Application (Streamlit)

Launch local web server:

streamlit run app.py

Open your browser at http://localhost:8501, paste a public Spotify playlist URL, and click ⚡ Prepare All Browser Downloads.

2. Telegram Bot

Start the bot runner:

python bot.py

Open Telegram, start a chat with your bot, and send any Spotify playlist link to receive audio files directly in chat!

3. CLI (Command Line Interface)

Run direct batch download from terminal:

python spotify_downloader.py

---

🐳 Docker Deployment

Run Ripify as a containerized stack in seconds:

docker compose up --build -d

This automatically launches both the Streamlit Web App (http://localhost:8501) and the Telegram Bot background service with pre-configured ffmpeg.

---

📁 Repository Structure

ripify/
├── app.py                   # Streamlit Web Application
├── bot.py                   # Telegram Bot service for mobile downloads
├── spotify_downloader.py    # Core extraction & audio downloader engine
├── requirements.txt         # Python package dependencies
├── Dockerfile               # Docker container specification
├── docker-compose.yml       # Docker Compose multi-service setup
├── .env.example             # Environment variables template
└── README.md                # Project documentation

---

⚠️ Disclaimer

This tool is developed strictly for educational and personal use only. Downloading copyrighted media from YouTube or Spotify may violate the Terms of Service of respective platforms. Please use this software responsibly and in compliance with your local copyright laws.

---

📄 License

Distributed under the MIT License. See LICENSE for more information.