mirror of
https://github.com/wahyd4/you-music.git
synced 2026-08-08 20:59:47 +10:00
Clean up
This commit is contained in:
@@ -535,4 +535,3 @@ docker run -p 8000:8000 youmusic:latest
|
||||
---
|
||||
|
||||
**✅ Production Ready** - The optimized Dockerfile provides excellent size reduction while maintaining full compatibility.
|
||||
|
||||
|
||||
@@ -0,0 +1,326 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user