Tarang

Run it  ·  Features  ·  Architecture  ·  Installation  ·  Reports

---

Tarang (तरङ्ग, "wave") is a music-first streaming web app. It is not a Spotify clone: it is an exploration of what a player feels like when glass surfaces, one shared motion language and a documented design system are treated as product decisions.

It plays demo audio and YouTube search results through a persistent floating player, with a full now-playing view, a queue, time-synced lyrics with translations, playlists and folders, moods, listening stats and simulated offline downloads. There is no backend, account system or required environment variable. The catalog is seed data in data/ and your state is kept in the browser.

Run it

git clone https://github.com/Samudra-GITHub/Tarang.git
cd Tarang && npm install && npm run dev

Then open http://localhost:3000, press Play Now, and click the floating player to expand it.

Features

Also: a living design-system reference at /design-system, an internal /dev-tools page, reduced-motion support, live-region announcements and global keyboard shortcuts.

Tech stack

Layer	Technology
Framework	Next.js 15 (App Router), React 19, TypeScript 5
Styling	Tailwind CSS 4, design tokens in styles/tokens.css, shadcn/ui, Radix UI
Motion	Framer Motion with shared variants in lib/motion.ts and lib/motion-variants.ts
State	Zustand with persist
Playback and search	HTML audio, YouTube IFrame Player API, Invidious API

Architecture

flowchart LR
    UI[Routes in app/] --> V[Feature views<br/>features/]
    V --> P[player-store<br/>Zustand]
    P --> A[HTML audio<br/>seed tracks]
    P --> Y[YouTube IFrame engine<br/>YouTube results]
    V --> S[(Seed data<br/>data/)]
    V --> L[(localStorage<br/>library · downloads · settings)]
    V --> I[Invidious search]

• The player store is the hub. lib/store/player-store.ts owns playback state and bridges events from both the native audio element and the YouTube IFrame wrapper (features/youtube/youtube-engine.ts), so the UI does not care which engine is playing.
• Thin routes, feature modules. Files in app/ stay small and render views from features/.
• Design system first. Tokens, typography, layout primitives and motion variants are shared by every route and documented in docs/design-system.md.

Known constraints: search relies on community-run Invidious instances that can go offline (the list is in features/youtube/invidious-client.ts), and artwork comes from picsum.photos with placeholder demo audio.

Tarang/
├── app/            Routes: album, artist, playlist, library, search, moods,
│                   downloads, stats, settings, design-system, dev-tools
├── components/     cards, charts, collection, decorative, layout, tracks, ui
├── features/       home, player, library, search, moods, stats, downloads, settings, youtube
├── hooks/          reduced motion, shortcuts, online status, dominant colour, tilt
├── lib/            motion, glass tokens, formatting, search, stats, store/
├── data/           Seed songs, albums, artists, playlists, moods, lyrics
├── styles/         tokens.css
└── docs/           Design system, reports, screenshots

Installation

Requires Node.js and npm.

npm install

Command	What it does
npm run dev	Start the dev server on port 3000
npm run build	Production build
npm run start	Serve the production build
npm run lint	Run ESLint

Environment

Nothing is required. Optionally set NEXT_PUBLIC_SITE_URL to the deployed origin so metadata, the sitemap and robots use the right URL (default http://localhost:3000).

Deploy

No deployment configuration is included. It is a standard Next.js app (npm run build, then npm run start).

Reports

The docs/ folder holds the project's own write-ups: the design system, an accessibility report, a performance report, the design-system migration status and the v3 release report.

Limitations

• Downloads are simulated, and there is no catalog or playback backend.
• Demo artwork and audio are placeholder content.

License

MIT.