♪  ♫  ♩  ♬  ♪  ♫  ♩  ♬  ♪  ♫  ♩  ♬  ♪  ♫  ♩  ♬  ♪  ♫  ♩  ♬

Soundwave is a sleek, full-featured web music player that streams audio
directly from YouTube — no API keys, no login, no subscriptions. Just search
and play, wrapped in a gorgeous animated UI.

✨ Features · 🖼️ Screenshots · ⚡ Quick Start · 🏗️ Architecture · 🤝 Contributing

---

✨ Features

🎵 Playback Multi-fallback audio engine — tries yt-dlp direct, Flask proxy, Invidious, and Piped in sequence for maximum reliability Seek support with Range request proxying Shuffle & Repeat modes Prev / Next track navigation 4-minute stream URL caching for snappy replays	🔍 Discovery Instant YouTube search — no API key required, scrapes ytInitialData Trending feed on home screen Global search bar with recent history & live suggestions Time-aware greeting (Morning / Afternoon / Evening)
💜 Library Liked Songs — persisted to localStorage Queue view — see what's playing next Sidebar library with liked song quick-launch Keyboard shortcut L to like the current track instantly	🎨 UI / UX Animated particle canvas background with connected-dot physics Floating gradient orbs in the background scene Responsive — full mobile layout with slide-out sidebar Skeleton loaders while content fetches Toast notifications for user actions

---

🖼️ Screenshots

Home — Trending Feed	Now Playing	Queue & Library
(animated orb bg + card grid)	(player bar with seek + controls)	(sidebar + liked songs)

Live demo screenshots coming soon — run locally and see for yourself!

---

⚡ Quick Start

Prerequisites

Tool	Version
Python	3.9 +
pip	latest
yt-dlp	latest (auto-installed)

1 — Clone & Install

# Clone the repository
git clone https://github.com/im-aswajith/soundwave.git
cd soundwave

# Install dependencies
pip install -r requirements.txt

requirements.txt contains:

flask
yt-dlp

2 — Run

python app.py

3 — Open

http://localhost:5000

That's it. No .env files, no API keys, no database setup. 🎉

---

🏗️ Architecture

soundwave/
│
├── app.py                  # Flask backend — search, stream, proxy
├── requirements.txt
│
├── templates/
│   └── index.html          # Single-page app shell
│
└── static/
    ├── css/
    │   └── style.css       # Full design system (orbs, player, cards)
    └── js/
        └── app.js          # State machine, audio engine, UI logic

How Streaming Works

Browser                Flask (app.py)              YouTube / CDN
   │                        │                           │
   │  GET /api/stream/:id   │                           │
   │ ─────────────────────► │                           │
   │                        │  yt-dlp (subprocess)      │
   │                        │ ──────────────────────────►
   │                        │◄── signed CDN URL ────────│
   │◄─── { url, mime } ─────│                           │
   │                        │                           │
   │  (if CORS fails)       │                           │
   │  GET /api/proxy/:id    │                           │
   │ ─────────────────────► │  Range-aware proxy        │
   │                        │ ──────────────────────────►
   │◄═══ chunked audio ═════│◄══════ audio bytes ═══════│

Fallback chain (client-side, in order):

1. yt-dlp direct CDN URL
2. /api/proxy/:id — Flask streams bytes (fixes CORS)
3. Invidious instance A
4. Invidious instance B
5. Piped API

If every strategy fails, an error is shown. The player never auto-skips — user intent is always respected.

---

🎛️ API Reference

Endpoint	Method	Description
/	GET	Serves the SPA
/api/search?q=...	GET	YouTube search → JSON { results: [...] }
/api/trending	GET	Top music hits → JSON { results: [...] }
/api/stream/:video_id	GET	Returns { url, content_type } via yt-dlp
/api/proxy/:video_id	GET	Range-aware audio proxy (CORS bypass)

Result object shape

{
  "id":        "dQw4w9WgXcQ",
  "title":     "Never Gonna Give You Up",
  "channel":   "Rick Astley",
  "duration":  "3:32",
  "views":     "1.5B views",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
  "url":       "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
}

---

⌨️ Keyboard Shortcuts

Key	Action
Space	Play / Pause
→	Next track
←	Previous track
L	Like / Unlike current track

---

🔧 Configuration

Soundwave works out of the box, but you can tweak these constants in app.py:

# Stream URL cache lifetime (seconds)
CACHE_TTL = 240      # 4 minutes

# Default search result limit
RESULT_LIMIT = 24

# Request timeout for YouTube scraping
FETCH_TIMEOUT = 12   # seconds

# yt-dlp subprocess timeout
YTDLP_TIMEOUT = 25   # seconds

---

🛠️ Tech Stack

Layer	Technology
Backend	Python · Flask
Audio Extraction	yt-dlp
Search	YouTube ytInitialData scraping (no API key)
Frontend	Vanilla JS · CSS3
Fonts	Syne · DM Sans (Google Fonts)
Storage	localStorage (liked songs, search history)
Animation	Canvas API (particles) · CSS keyframes (orbs)

---

Good first issues

• 🎨 Custom theme / color scheme support
• 📱 PWA / install-to-homescreen support
• 🌐 Additional Invidious/Piped fallback instances
• 🔊 Volume memory across sessions

---

⚠️ Disclaimer

Soundwave is a personal project built for educational purposes. It does not store, redistribute, or host any audio files. All audio is streamed in real time directly from YouTube's CDN via publicly available URLs extracted by yt-dlp.

Please respect YouTube's Terms of Service and your local copyright laws.

---

📄 License

Distributed under the MIT License. See LICENSE for details.

---

Made with 💜 and a lot of music

⭐ If Soundwave made your day better, please consider starring the repo!