YouMusic - Modern Web Music Player

A fully-featured web music player with download capabilities, built with Python FastAPI backend and React frontend with shadcn/ui components. Inspired by xiaomusic and spotube.

Features

🎵 Core Features

• Modern, Mobile-First UI - Responsive design that works beautifully on both desktop and mobile
• Full-Featured Music Player - Play, pause, skip, volume control, progress seeking
• Local Music Library - Scan and play downloaded music files
• Online Music Search - Search YouTube and Bilibili for music
• Download Management - Download music from YouTube, Bilibili, and other platforms
• Playlist Management - Create, edit, and manage custom playlists
• Music Sharing - Share music links that open directly in the app

🔍 Search & Discovery

• Search by song name or artist
• Combined search across YouTube and Bilibili
• View artist discography (both downloaded and available online)
• Thumbnail previews for search results

📥 Download Capabilities

• Download individual tracks
• Download entire playlists
• Support for YouTube and Bilibili URLs
• Automatic metadata extraction
• Background download processing

🎼 Playlist Features

• Create custom playlists
• Add/remove songs from playlists
• Play entire playlists
• Playlist organization

Technology Stack

Backend

• FastAPI - Modern Python web framework
• SQLAlchemy - ORM for database management
• SQLite / PostgreSQL - Flexible database options (SQLite for local, PostgreSQL for production)
• asyncpg - High-performance async PostgreSQL driver
• yt-dlp - Universal video/audio downloader (supports YouTube, Bilibili, etc.)
• mutagen - Audio metadata extraction and editing
• aiosqlite - Async SQLite database
• aiohttp - Async HTTP client

Frontend

• React 18 - UI library
• TypeScript - Type safety
• Vite - Build tool
• TanStack Query - Data fetching and caching
• React Router - Routing
• shadcn/ui - Beautiful, accessible UI components
• Tailwind CSS - Utility-first styling
• Lucide React - Icon library

Installation

Quick Start - Local Development (Fastest)

For macOS/Linux developers:

# One-time setup
./dev-setup.sh

# Start development (both backend & frontend)
./dev.sh

# Visit http://localhost:3000

See LOCAL_DEV_GUIDE.md for detailed local development instructions.

Using Docker (Production/Easy Setup)

1. Clone the repository

git clone <your-repo-url>
cd you-music

2. Build and run with Docker Compose

docker-compose up -d

3. Access the application

• Frontend: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Manual Installation (Step by Step)

Backend Setup

1. Create Python virtual environment

cd backend
uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

2. Install dependencies

uv sync

3. Install system dependencies

• FFmpeg (for audio processing)

# Ubuntu/Debian
sudo apt-get install ffmpeg

# macOS
brew install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

4. Run the backend

cd backend
uvicorn main:app --reload

Frontend Setup

1. Install Node.js dependencies

cd frontend
npm install

2. Run development server

npm run dev

3. Build for production

npm run build

Usage

Basic Playback

1. Navigate to Library - View all downloaded music
2. Click Play - Start playing a song
3. Use Player Controls - Play/pause, skip, adjust volume

Searching & Downloading

1. Go to Search Tab
2. Enter search query - Song name, artist, or keywords
3. Browse results - From YouTube and Bilibili
4. Click Download - Downloads and adds to library

Managing Playlists

1. Go to Playlists Tab
2. Create Playlist - Click "New Playlist"
3. Add Songs - Browse library and add to playlist
4. Play Playlist - Click play on any playlist

Sharing Music

Music can be shared via URL:

http://localhost:8000/?music=<music_id>

When someone opens this link, the music will automatically load and play.

URL Download Support

The app supports downloading from:

• YouTube video URLs
• YouTube playlist URLs
• Bilibili video URLs
• Direct music file links

Simply paste the URL in the search/download section.

API Documentation

Once running, visit http://localhost:8000/docs for interactive API documentation.

Key Endpoints

Music

• GET /api/music/ - Get all music
• GET /api/music/search?q={query} - Search local music
• GET /api/music/{id} - Get specific music
• POST /api/music/upload - Upload music file
• DELETE /api/music/{id} - Delete music

Playlists

• GET /api/playlists/ - Get all playlists
• POST /api/playlists/ - Create playlist
• POST /api/playlists/{id}/music/{music_id} - Add music to playlist
• DELETE /api/playlists/{id}/music/{music_id} - Remove music from playlist

Download

• POST /api/download/music - Download single track
• POST /api/download/playlist - Download playlist

Search

• GET /api/search/?q={query} - Search all sources
• GET /api/search/youtube?q={query} - Search YouTube
• GET /api/search/bilibili?q={query} - Search Bilibili

Configuration

Database Configuration

YouMusic supports both SQLite (default, simple) and PostgreSQL (production, scalable):

SQLite (Default):

DB_TYPE=sqlite
# DATABASE_URL is auto-generated

PostgreSQL (Recommended for Production):

DB_TYPE=postgres
DB_POSTGRES_HOST=localhost
DB_POSTGRES_PORT=5432
DB_POSTGRES_DATABASE=you_music
DB_POSTGRES_USER=youmusic
DB_POSTGRES_PASSWORD=your_password

Benefits of PostgreSQL:

• ✅ Better concurrent performance
• ✅ Scale to multiple replicas in Kubernetes
• ✅ Connection pooling (20 + 10 overflow)
• ✅ Production-grade reliability

See POSTGRESQL.md for detailed PostgreSQL setup and migration guide.

Other Configuration

Create a .env file in the backend directory:

# Directories
MUSIC_DIR=/app/data/music
UPLOAD_DIR=/app/data/uploads
TEMP_DIR=/app/data/temp

# Download settings (optional)
PROXY=http://your-proxy:port
FFMPEG_LOCATION=ffmpeg

# YT-DLP settings
YT_DLP_FORMAT=bestaudio/best
YT_DLP_AUDIO_FORMAT=mp3
YT_DLP_AUDIO_QUALITY=0

See .env.example for all available options.

Architecture

Backend Structure

backend/
├── app/
│   ├── api/           # API endpoints
│   ├── core/          # Core configuration
│   ├── db/            # Database setup
│   ├── models/        # SQLAlchemy models
│   ├── schemas/       # Pydantic schemas
│   ├── services/      # Business logic
│   └── utils/         # Utility functions
└── main.py            # Application entry point

Frontend Structure

frontend/
├── src/
│   ├── components/    # React components
│   │   ├── ui/        # shadcn/ui components
│   │   ├── player/    # Music player
│   │   ├── search/    # Search functionality
│   │   └── playlist/  # Playlist management
│   ├── api/           # API client
│   ├── hooks/         # Custom React hooks
│   ├── lib/           # Utility functions
│   └── types/         # TypeScript types

Key Features Implementation

Music Download Logic (from xiaomusic)

The download functionality uses yt-dlp similar to xiaomusic:

# Download single music
async def download_music(url: str, output_name: str):
    cmd_args = [
        "yt-dlp",
        "--no-playlist",
        "-x",  # Extract audio
        "--audio-format", "mp3",
        "--audio-quality", "0",
        "--paths", music_dir,
        "-o", f"{output_name}.%(ext)s",
        url
    ]
    await asyncio.create_subprocess_exec(*cmd_args)

Mobile-First Design

The UI is optimized for mobile with:

• Touch-friendly controls
• Responsive grid layouts
• Mobile navigation
• Optimized player controls

Real-time Updates

Uses TanStack Query for:

• Automatic cache invalidation
• Background refetching
• Optimistic updates
• Loading states

Troubleshooting

FFmpeg not found

Ensure FFmpeg is installed and in your PATH:

ffmpeg -version

Port already in use

Change the port in docker-compose.yml or when running manually:

uvicorn main:app --port 8001

Database errors

If you encounter database errors, try the following:

With Migrations (Recommended):

# Check current migration status
cd backend
./migrate.sh current

# Apply pending migrations
./migrate.sh upgrade

# If needed, check migration history
./migrate.sh history

Reset Database (Dev only - DATA LOSS!):

# Delete database and restart (auto-migrates on startup)
rm data/youmusic.db
docker-compose restart

# Or for local development
./dev-stop.sh
rm backend/data/youmusic.db
./dev.sh

See MIGRATIONS.md for detailed migration documentation.

Development

Database Migrations

YouMusic uses Alembic for database migrations. This allows safe schema changes without data loss.

Common operations:

cd backend

# View current database version
./migrate.sh current

# Create a new migration after modifying models
./migrate.sh create "Add new field description"

# Apply migrations
./migrate.sh upgrade

# Rollback last migration
./migrate.sh downgrade

# View migration history
./migrate.sh history

Note: Migrations run automatically on app startup, so manual migration is only needed when developing new schema changes.

For complete migration documentation, see MIGRATIONS.md.

Running tests

# Backend
cd backend
pytest

# Frontend
cd frontend
npm test

Code formatting

# Backend
black .
isort .

# Frontend
npm run lint

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• xiaomusic - Inspiration for download logic
• spotube - UI/UX inspiration
• shadcn/ui - UI components
• yt-dlp - Download engine

Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation
• Review API docs at /docs

Roadmap

• Audio visualization
• Lyrics display
• Equalizer
• Queue management
• User authentication
• Multi-user support
• Song recommendations
• Import from Spotify/Apple Music
• Podcast support
• Offline mode (PWA)