A full-stack music and lyrics web application — search songs, view synchronized lyrics, and stream audio, all in one place.
Lyricalize is a modern music player web app that lets you search for songs, read lyrics, and listen to tracks — all from a clean, responsive interface. It fetches real-time music data and lyrics via API, plays audio at the best available quality (up to 320kbps), and presents everything in a polished editor-style UI with dark mode support.
- Song Search — Find tracks instantly with a fast, real-time search experience
- Lyrics Viewer — Read synced lyrics for any searched track in the built-in editor panel
- Audio Playback — Stream songs at the highest available quality (12kbps → 320kbps with auto best-quality selection)
- Music Panel UI — Sidebar-style music panel with track info, player controls, and queue management
- Dark Mode — Full dark/light theme support powered by Tailwind CSS
- Serverless Backend — API routes handled by a Cloudflare Worker, keeping the backend fast and scalable
- Responsive Design — Works seamlessly across desktop and mobile browsers
| Technology | Role |
|---|---|
| React 18 + TypeScript | Core UI framework |
| Vite | Build tool & dev server |
| React Router v6 | Client-side routing |
| TanStack React Query | Data fetching & caching |
| Tailwind CSS | Styling & theming |
| shadcn/ui + Radix UI | Accessible component primitives |
| Zustand | Global audio/track state management |
| Technology | Role |
|---|---|
| Cloudflare Workers | Serverless API compute |
| Hono | Lightweight API routing framework |
| Wrangler CLI | Local dev & deployment tooling |
- Bun — Fast package manager & runtime
- ESLint — TypeScript-aware linting
- PostCSS + Autoprefixer — CSS processing
- Bun (recommended) or Node.js 18+
- A Cloudflare account (for deployment)
git clone https://github.com/SKS-WEBDEV/lyricalize.git
cd lyricalize
bun installStart the local development server (React frontend + Cloudflare Worker API):
bun run devThe app will be available at http://localhost:3000 with hot module replacement enabled.
# Build for production
bun run build
# Preview production build locally
bun run previewlyricalize/
├── src/ # React frontend
│ ├── components/
│ │ └── editor/
│ │ └── MusicPanel.tsx # Music player UI panel
│ ├── hooks/
│ │ └── useAudioEngine.ts # Audio playback engine
│ ├── lib/
│ │ └── api.ts # API client & data fetching
│ ├── pages/ # Route-level page components
│ └── main.tsx # App entry & routing
├── worker/
│ ├── index.ts # Cloudflare Worker entry point
│ └── userRoutes.ts # Custom API route definitions
├── public/ # Static assets
├── prompts/ # AI prompt files
├── wrangler.jsonc # Cloudflare Worker configuration
├── vite.config.ts # Vite build configuration
└── tailwind.config.js # Tailwind theme & design system
- Search — User searches for a song; the API returns tracks with validated download URL arrays
- Select — Clicking a track stores it in Zustand global state
- URL Selection — The audio engine picks the best available quality:
- 🥇 Highest bitrate (preferred)
- 🥈 320kbps
- 🥉 160kbps
- 🔁 Fallback to lowest available
- Playback — The audio element (mounted in the DOM for full browser compatibility) loads and plays the track
- Events — Browser fires
loadstart → loadeddata → canplay → playingin sequence
{
"downloadUrl": [
{ "quality": "12kbps", "url": "https://..." },
{ "quality": "48kbps", "url": "https://..." },
{ "quality": "96kbps", "url": "https://..." },
{ "quality": "160kbps", "url": "https://..." },
{ "quality": "320kbps", "url": "https://..." }
]
}All API endpoints are defined in worker/userRoutes.ts and mounted under /api/*.
// Example custom route
app.get('/api/hello', (c) => c.json({ message: 'Hello from Workers!' }));Built-in routes include health checks and client error reporting.
# Authenticate with Cloudflare (first time only)
bunx wrangler login
# Build and deploy
bun run deployUpdate wrangler.jsonc with your Worker name, routes, and any environment variables before deploying.
| What to change | Where |
|---|---|
| UI Components | src/components/ or add new shadcn/ui components |
| Theme & Colors | tailwind.config.js and src/index.css |
| Frontend Routes | src/main.tsx |
| API Routes | worker/userRoutes.ts |
| App Sidebar | src/components/app-sidebar.tsx |
Open DevTools (F12) and check the console for these logs:
[AudioEngine] 🔧 Audio element created. crossOrigin=anonymous
[AudioEngine] 📍 Audio element added to DOM
[AudioEngine] 🎵 Track Change
[AudioEngine] 📥 Setting audio src and calling load()...
[AudioEngine] 🔗 audio.src confirmed: https://...
[MusicPanel] Track selected: {...}
If audio doesn't play, verify:
- The browser console for errors
- Network tab to confirm audio URLs are being fetched
- Browser audio permissions are enabled
- Audio file format compatibility (MP4 is broadly supported)
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/my-feature) - Commit your changes (
git commit -m 'Add my feature') - Push to the branch (
git push origin feature/my-feature) - Open a Pull Request
For major changes, please open an issue first to discuss what you'd like to change.
Please read carefully before using, deploying, or contributing to this project.
Lyricalize is an open-source project intended strictly for educational and personal, non-commercial use. It was built to demonstrate the integration of modern web technologies including React, Cloudflare Workers, and third-party music APIs.
- Lyricalize does not host, store, distribute, or own any music, audio files, or lyrics content.
- All audio streams and lyrics data are fetched in real-time from third-party public APIs. The availability and legality of such content is governed entirely by those third-party services.
- Song titles, album artwork, artist names, and lyrics are the intellectual property of their respective rights holders — including but not limited to record labels, music publishers, and artists.
- Streaming or downloading copyrighted music without the explicit authorization of the rights holder may violate copyright law in your jurisdiction, including but not limited to the DMCA (USA), the EU Copyright Directive, and equivalent legislation worldwide.
This project is not affiliated with, endorsed by, or connected to any music streaming service, record label, publisher, or any third-party API provider it may consume.
Users and contributors who deploy this application are solely responsible for ensuring their usage of any third-party APIs complies with those services' Terms of Service. The project maintainers accept no liability for misuse of upstream APIs.
This software is provided "as is", without warranty of any kind, express or implied. The authors and contributors shall not be held liable for any claim, damages, or other liability arising from the use of this software or any content accessed through it.
If you are a rights holder and believe your content is being accessed or surfaced inappropriately through this application, please open a GitHub issue or contact the repository owner directly. We will respond promptly.
This project is licensed under the MIT License — see the LICENSE file for details.
- Live App: lyricalize.vercel.app
- Repository: github.com/SKS-WEBDEV/lyricalize