# 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 ```bash docker-compose up -d ``` ### Manual Deployment ```bash # 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