you-music/PROJECT_SUMMARY.md

YouMusic - Project Summary

📋 Project Overview

YouMusic is a modern, full-stack web music player with download capabilities, inspired by xiaomusic and spotube. It's designed with a mobile-first approach using React + shadcn/ui for the frontend and Python FastAPI for the backend.

✅ Implemented Features

1. Core Music Player ✓

• Play/pause controls
• Skip forward/backward
• Volume control with mute
• Progress bar with seeking
• Display current track info
• Queue management
• Auto-play next track

2. Music Library Management ✓

• View all downloaded music
• Search local library by name/artist
• Sort and filter options
• Metadata display (title, artist, album, duration)
• File scanning functionality
• Upload music files

3. Online Music Search ✓

• Search YouTube for music
• Search Bilibili for music
• Combined search across platforms
• Display thumbnails and metadata
• Filter by source (YouTube/Bilibili)

4. Download Functionality ✓

• Download from YouTube URLs
• Download from Bilibili URLs
• Download single tracks
• Download entire playlists
• Background download processing
• Automatic metadata extraction
• Progress tracking support

5. Playlist Management ✓

• Create custom playlists
• Add songs to playlists
• Remove songs from playlists
• Delete playlists
• Update playlist info
• Play entire playlists
• View playlist details

6. Music Sharing ✓

• Share via URL parameters (?music=id)
• Direct link to specific songs
• Auto-play shared music

7. Mobile-First UI ✓

• Responsive design
• Touch-friendly controls
• Mobile navigation
• Adaptive layouts
• Bottom player bar (mobile-friendly)

8. Additional Features ✓

• Search by artist (shows all tracks)
• Dark mode support (via shadcn/ui)
• Toast notifications
• Loading states
• Error handling
• API documentation (FastAPI Swagger)

🏗️ Architecture

Backend Stack

FastAPI (Python)
├── SQLAlchemy (ORM)
├── aiosqlite (Database)
├── yt-dlp (Downloader)
├── mutagen (Metadata)
├── aiohttp (HTTP client)
└── Pydantic (Validation)

Frontend Stack

React 18 + TypeScript
├── Vite (Build tool)
├── TanStack Query (Data fetching)
├── React Router (Navigation)
├── shadcn/ui (Components)
├── Tailwind CSS (Styling)
└── Axios (API client)

📁 Project Structure

you-music/
├── backend/
│   ├── app/
│   │   ├── api/          # API endpoints
│   │   ├── core/         # Configuration
│   │   ├── db/           # Database
│   │   ├── models/       # SQLAlchemy models
│   │   ├── schemas/      # Pydantic schemas
│   │   └── services/     # Business logic
│   ├── main.py           # FastAPI app
│   └── pyproject.toml    # Python deps (uv)
├── frontend/
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── api/          # API client
│   │   ├── hooks/        # Custom hooks
│   │   ├── lib/          # Utils
│   │   └── types/        # TypeScript types
│   └── package.json      # Node deps
├── data/                 # Runtime data
├── Dockerfile            # Container image
├── docker-compose.yml    # Docker setup
└── README.md             # Documentation

🔌 API Endpoints

Music

• GET /api/music/ - List all music
• GET /api/music/search - Search music
• GET /api/music/{id} - Get music details
• PUT /api/music/{id} - Update metadata
• DELETE /api/music/{id} - Delete music
• POST /api/music/upload - Upload file
• POST /api/music/scan - Scan directory

Playlists

• GET /api/playlists/ - List playlists
• POST /api/playlists/ - Create playlist
• GET /api/playlists/{id} - Get playlist
• PUT /api/playlists/{id} - Update playlist
• DELETE /api/playlists/{id} - Delete playlist
• POST /api/playlists/{id}/music/{music_id} - Add song
• DELETE /api/playlists/{id}/music/{music_id} - Remove song

Download

• POST /api/download/music - Download track
• POST /api/download/playlist - Download playlist
• GET /api/download/status - Download status

Search

• GET /api/search/ - Search all sources
• GET /api/search/youtube - Search YouTube
• GET /api/search/bilibili - Search Bilibili

🚀 Deployment

Using Docker

docker-compose up -d

Manual Deployment

# Backend
cd backend
uv venv --python 3.13
source .venv/bin/activate
uv sync
uvicorn main:app --host 0.0.0.0 --port 8000

# Frontend
cd frontend
npm install
npm run build

🎨 UI Components (shadcn/ui)

Implemented components:

• Button
• Input
• Slider
• Card (via Tailwind)
• Toast notifications (sonner)
• Navigation
• Player controls

📊 Database Schema

Music Table

• id, title, artist, album
• duration, file_path, file_size
• source_url, source_type
• thumbnail, lyrics
• created_at, updated_at

Playlist Table

• id, name, description
• thumbnail
• created_at, updated_at

playlist_music (Many-to-Many)

• playlist_id, music_id
• position, added_at

🔐 Security Features

• Input validation (Pydantic)
• SQL injection protection (SQLAlchemy)
• XSS protection (React)
• CORS configuration
• Safe file path handling
• URL validation

🎯 xiaomusic Integration

Adapted from xiaomusic:

1. Download Logic - Using yt-dlp similar to xiaomusic
2. Metadata Extraction - Using mutagen library
3. File Organization - Directory structure handling
4. Playlist Processing - Batch download support
5. FFmpeg Integration - Audio processing

🌟 Unique Features

Improvements over xiaomusic:

1. Modern React UI
2. Real-time search
3. Better mobile support
4. RESTful API
5. Database-backed library
6. Shareable links
7. Progressive Web App ready

📱 Mobile Optimizations

• Touch-friendly buttons (min 44px)
• Responsive grid layouts
• Mobile navigation
• Bottom player bar
• Swipe gestures support
• Viewport optimized

🔄 State Management

• TanStack Query for server state
• React useState for local state
• Audio ref for player state
• URL params for deep linking

🧪 Testing Ready

Structure supports:

• Backend: pytest
• Frontend: Vitest/Jest
• E2E: Playwright/Cypress
• API: FastAPI TestClient

📈 Performance

• Lazy loading
• Code splitting (Vite)
• Image optimization
• Database indexing
• Async operations
• Caching (TanStack Query)

🔮 Future Enhancements

Possible additions:

• User authentication
• Multi-user support
• Audio visualization
• Lyrics display
• Equalizer
• Podcast support
• Import from Spotify
• PWA offline mode
• WebSocket for real-time updates
• Recommendation engine

📦 Dependencies

Key Backend Packages

• fastapi==0.115.0
• uvicorn==0.30.6
• sqlalchemy==2.0.35
• yt-dlp==2024.10.7
• mutagen==1.47.0
• aiofiles==24.1.0

Key Frontend Packages

• react==18.3.1
• @tanstack/react-query==5.56.2
• react-router-dom==6.26.2
• tailwindcss==3.4.11
• lucide-react==0.441.0

🎓 Learning Resources

The project demonstrates:

• FastAPI async patterns
• React hooks usage
• TypeScript best practices
• Database modeling
• API design
• Docker containerization
• Component architecture
• State management

📄 License

MIT License - Free to use and modify

🙏 Acknowledgments

• xiaomusic - Download logic inspiration
• spotube - UI/UX inspiration
• shadcn/ui - Component library
• yt-dlp - Download engine
• FastAPI - Backend framework
• React - Frontend library

---

Status: ✅ Complete and Ready for Use Version: 1.0.0 Last Updated: 2024-10-30