🚀 Null — Free Music Player for Android

🎵 Millions of songs • 🚫 Zero ads • 📥 Offline • 🧬 Music DNA

🔥 Open Source • Free Forever • Built for Android

---

About Null

Null is a free, open-source music streaming player built for Android. Access millions of songs through a reliable, multi-source backend with intelligent fallback routing. No subscriptions, no ads, no tracking—just music.

Built with React + Vite on the front-end, Node.js + Express on the back-end, and Capacitor for native Android integration. Everything is designed to work offline, resume seamlessly, and handle network failures gracefully.

🔗 Visit Website • 📥 Download APK

---

Why Choose Null?

✨ No Ads, No Subscriptions
Stream unlimited music without paying. Ever.

🔒 Your Privacy Matters
Open-source code. Zero tracking. No data harvesting.

📱 Works Offline
Download tracks and listen anywhere, even without internet.

🚀 Fast & Reliable
Intelligent fallback routing ensures playback never stops.

🎯 Music Discovery
Personalized recommendations and Music DNA profiling.

💻 Built by the Community
Open-source on GitHub. Contribute and help shape the future.

---

Why Null Exists

Most music apps today:

• Interrupt your experience with ads
• Lock features behind subscriptions
• Track your behavior

Null was built to change that.

👉 A music player that is free, open, and respects users

🚀 Why People Love Null

• 🚫 No ads — ever
• ⚡ Fast and lightweight
• 📥 Works offline
• 🧬 Unique Music DNA feature
• 🔓 Fully open source

👉 Built for users, not profit

Features

Core Experience: Home, Search & Discovery, Queue Management

Home Screen	Search Interface	Queue Controls

Library & Playback: Personal Library, Full Playback Controls, Advanced Features

Library View	Playback Screen	Feature Highlights

Music DNA: Personalized Profiles & Insights

DNA Profile Overview	DNA Traits & Analysis	Animated DNA Helix

---

Features in Detail

🎵 Stream & Play Music

• Search Everything: Find songs, artists, albums, and playlists instantly
• Smart Playback: Queue management with shuffle, repeat, and insert controls
• Resume State: Pick up exactly where you left off every time
• Offline Downloads: Save tracks to your device and listen without internet
• Multi-Source Fallback: Intelligent routing ensures songs play even if one source fails
• Android Media Controls: Full integration with system player controls and notifications

📚 Organize Your Music

• Personal Favorites: Save love songs, artists, and playlists
• Smart Library: Recently Played, Most Played, and personalized Made For You sections
• Playlist Management: Create, edit, and organize custom collections
• Search Filters: Find exactly what you want with advanced filtering
• Sync Across Devices: Your library follows you everywhere

🎧 Listening Experience

• Integrated Lyrics: View lyrics while you listen
• Equalizer Hooks: Audio tuning controls for custom sound
• Data Saver Mode: Optimize streaming for limited connections
• Auto-Radio: Continuous playback with related track suggestions
• Theme Switching: Light and dark modes for day and night
• Mobile-First Design: Optimized layout for all screen sizes

👤 Account & Security

• Email/Phone Signup: Quick registration with OTP verification
• Secure Login: JWT-based sessions with refresh tokens
• Device Sync: Favorites and playlists sync automatically
• Privacy First: Request deletion and data download anytime
• Feedback & Support: Built-in issue reporting and help channels

🧬 Music DNA - Discover Your Sound

Null analyzes your listening history to create a personalized Music DNA profile:

• DNA Traits: Your unique energy, valence, acousticness, and danceability signature
• Genre Matrix: Visual breakdown of your favorite genres and decades
• Sonic Twins: AI-matched recommendations based on your listening patterns
• Shareable Profile: Export and share your DNA card on social media
• Animated Helix: Beautiful visualization of your music identity

---

Technology Stack

Layer	Technology	Purpose
Frontend	React 18 + Vite	Fast, modular UI
Mobile Shell	Capacitor 6	Native Android integration
Backend API	Node.js 22 + Express	Scalable server
Database	PostgreSQL	Persistent data storage
Stream Resolution	yt-dlp (with fallbacks)	Multi-source audio retrieval
Lyrics	LRCLIB API	Synchronized lyrics
Authentication	JWT + OTP	Secure user sessions

---

Project Structure

music-player/
├── src/               # React frontend (components, hooks, styles)
├── backend/           # Node.js server (API routes, auth, cache)
├── android/           # Capacitor & Android native code
├── tests/             # Unit and integration tests
├── scripts/           # Build and migration utilities
├── shared/            # Shared utilities and helpers
├── website/           # Marketing website assets
└── public/            # Static assets and service worker

Detailed architecture: See ARCHITECTURE.md

---

Getting Started

Requirements

• Node.js 22+ (download)
• npm 10+ (included with Node.js)
• Java 21+ (JDK)
• Android SDK (for device builds; included with Android Studio)

Quick Start (Web)

# Clone the repository
git clone https://github.com/adit-ya15/music-player.git
cd music-player

# Install dependencies
npm install

# Start development server
npm run dev          # Web UI on http://localhost:5173
npm run server       # Backend on http://localhost:3000 (in another terminal)

Build & Test

# Lint code for style issues
npm run lint

# Run test suite
npm test

# Build for production (web)
npm run build

Android Development

Debug APK (for testing on device)

npm run build                    # Build web assets
npx cap sync android             # Sync to Android project
cd android
./gradlew assembleDebug          # Build debug APK
# Output: app/build/outputs/apk/debug/app-debug.apk

Release APK (for distribution)

npm run build
npx cap sync android
cd android
./gradlew assembleRelease        # Requires keystore (see below)
# Output: app/build/outputs/apk/release/app-release.apk

Keystore Setup: See RELEASE_AND_UPDATE_GUIDE.md for signing and release configuration.

---

Documentation & Resources

Document	Contents
ARCHITECTURE.md	System design, data flow, and component architecture
SECURITY.md	Security practices, rate limiting, and threat model
PRIVACY.md	Data handling, privacy policy, and user rights
CONTRIBUTING.md	How to contribute, coding standards, and pull request process
CODE_OF_CONDUCT.md	Community values and conduct guidelines
ROADMAP.md	Planned features, milestones, and community requests
CHANGELOG.md	Release notes and version history
RELEASE_AND_UPDATE_GUIDE.md	Build, sign, and publish process for new versions
OPEN_SOURCE_RELEASE_CHECKLIST.md	Pre-release QA and verification steps

---

Configuration

Environment Variables

Create .env for local development:

DATABASE_URL=postgresql://user:pass@localhost:5432/null
JWT_SECRET=your-secret-key
PORT=3000

Never commit .env files to Git. Use .env.example as a template.

Sensitive files to ignore:

• .env and .env.*.local
• android/keystore.properties
• android/local.properties
• .DS_Store

---

How to Contribute

Contributions are welcome! Whether it's code, bug reports, design feedback, or translations—we'd love your help.

To contribute:

1. Fork the repository on GitHub
2. Clone your fork locally
3. Create a feature branch (git checkout -b feature/your-feature)
4. Make your changes, following the style guide
5. Test thoroughly (npm test, npm run lint)
6. Commit with clear messages
7. Push to your fork
8. Open a Pull Request with detailed description

See CONTRIBUTING.md for detailed guidelines, architecture decisions, and code standards.

---

Getting Help

• 📖 Documentation: Check ARCHITECTURE.md and SECURITY.md
• 🐛 Report Bugs: Open an issue on GitHub with reproduction steps
• 💬 Discuss Features: Start a discussion for ideas and feedback
• ❤️ Community: See CODE_OF_CONDUCT.md

---

Support & Sponsor Development

Null is free and always will be. If you love the app and want to support development:

• UPI (India): aditya262701@okicici
• Support Page: null-music.netlify.app/#support
• Star the Repository: Give us a ⭐ on GitHub

Every contribution—financial or otherwise—helps us keep the music player free and ad-free for everyone.

---

License & Legal

Null is released under the MIT License. See LICENSE for the full text.

• Copyright: Aditya
• License: MIT
• Open Source: Yes, forever

---

Frequently Asked Questions

Q: Is Null really free?
A: Yes. Forever. No ads, no paywalls, no surprises.

Q: How is Null free without ads?
A: It's open-source software maintained by volunteers and supported by optional sponsorships.

Q: Does Null track me?
A: No. All code is open-source and auditable. Check PRIVACY.md.

Q: Will Null work offline?
A: Yes. Download tracks in advance, and they'll play without internet.

Q: How can I contribute?
A: Code, bug reports, translations, and design feedback are all welcome. See CONTRIBUTING.md.

Q: Can I build Null myself?
A: Absolutely. Clone the repo and follow the Getting Started guide.

---

Credits & Acknowledgments

• Built by: Aditya
• Community: All contributors who've helped shape Null
• Technologies: React, Node.js, Capacitor, yt-dlp, LRCLIB, and more
• Inspired by: Open-source community values and user privacy advocacy

---

⭐ Support the Project

If you believe in:

• Free software
• No ads
• Open source

👉 Give this repo a ⭐ — it helps more than anything

👉 Share it with friends — help it grow 🚀

_{Made with ❤️ for music lovers. Open-source. Ad-free. Forever.}