From 9ab5a08646d59b05de6837dc3a50a20b7e524422 Mon Sep 17 00:00:00 2001 From: Junwei Zhao Date: Mon, 3 Nov 2025 10:54:29 +1100 Subject: [PATCH] Clean up --- DOCKER_OPTIMIZATION.md | 5 +- PROJECT_SUMMARY.md | 326 +++++++++++++++++++++++++++++++++++++++++ STRUCTURE.md | 12 +- dev-stack.sh | 12 +- setup.sh | 32 ++-- 5 files changed, 356 insertions(+), 31 deletions(-) create mode 100644 PROJECT_SUMMARY.md diff --git a/DOCKER_OPTIMIZATION.md b/DOCKER_OPTIMIZATION.md index a826fd9..fb6b34b 100644 --- a/DOCKER_OPTIMIZATION.md +++ b/DOCKER_OPTIMIZATION.md @@ -453,7 +453,7 @@ docker build -t youmusic:slim -f Dockerfile.slim . โœ… All tests passed: - Application starts correctly -- Migrations run successfully +- Migrations run successfully - All API endpoints working - Frontend loads properly - Health checks passing @@ -516,7 +516,7 @@ docker run -p 8000:8000 youmusic:latest โœ… All tests passed: - Application starts correctly -- Migrations run successfully +- Migrations run successfully - All API endpoints working - Frontend loads properly - Health checks passing @@ -535,4 +535,3 @@ docker run -p 8000:8000 youmusic:latest --- **โœ… Production Ready** - The optimized Dockerfile provides excellent size reduction while maintaining full compatibility. - diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md new file mode 100644 index 0000000..ac9a8e8 --- /dev/null +++ b/PROJECT_SUMMARY.md @@ -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 diff --git a/STRUCTURE.md b/STRUCTURE.md index 9f094e0..e36e880 100644 --- a/STRUCTURE.md +++ b/STRUCTURE.md @@ -125,13 +125,13 @@ you-music/ - **session.py**: SQLAlchemy async engine and session management #### Models (`backend/app/models/`) -- **models.py**: +- **models.py**: - Music model (tracks, metadata) - Playlist model (user playlists) - Many-to-many relationship table #### Schemas (`backend/app/schemas/`) -- **schemas.py**: +- **schemas.py**: - Pydantic models for request/response - Validation schemas - Type hints for API @@ -143,11 +143,11 @@ you-music/ - **search.py**: Search external sources #### Services (`backend/app/services/`) -- **downloader.py**: +- **downloader.py**: - yt-dlp integration - Download logic from xiaomusic - Metadata extraction -- **search.py**: +- **search.py**: - YouTube search - Bilibili search - Result parsing @@ -180,7 +180,7 @@ you-music/ - **PlaylistsPage.tsx**: Playlist management UI #### API Client (`frontend/src/api/`) -- **client.ts**: +- **client.ts**: - Axios instance - API function definitions - Type-safe endpoints @@ -256,7 +256,7 @@ All frontend-backend communication uses REST APIs: # Backend cd backend && uvicorn main:app --reload -# Frontend +# Frontend cd frontend && npm run dev ``` diff --git a/dev-stack.sh b/dev-stack.sh index e049f35..4438d78 100755 --- a/dev-stack.sh +++ b/dev-stack.sh @@ -181,7 +181,7 @@ else echo "" echo -e "${BLUE}Press Ctrl+C to stop all services${NC}" echo "" - + # Cleanup function cleanup() { echo "" @@ -191,29 +191,29 @@ else echo -e "${GREEN}โœ… All services stopped${NC}" exit 0 } - + trap cleanup SIGINT SIGTERM - + # Start backend in background with output to console cd backend source .venv/bin/activate uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000 2>&1 | sed 's/^/backend | /' & BACKEND_PID=$! cd .. - + # Start frontend in background with output to console cd frontend npm run dev 2>&1 | sed 's/^/frontend | /' & FRONTEND_PID=$! cd .. - + echo -e "${GREEN}โœ… Services started${NC}" echo "" echo "Frontend: http://localhost:3000" echo "Backend: http://localhost:8000" echo "API Docs: http://localhost:8000/docs" echo "" - + # Wait for both processes wait fi diff --git a/setup.sh b/setup.sh index 6e94bb6..a3fe238 100755 --- a/setup.sh +++ b/setup.sh @@ -10,13 +10,13 @@ echo "=================" # Check if Docker is installed if command -v docker &> /dev/null; then echo "โœ… Docker found" - + echo "๐Ÿณ Building Docker image..." docker-compose build - + echo "๐Ÿš€ Starting YouMusic..." docker-compose up -d - + echo "" echo "โœจ YouMusic is running!" echo "๐Ÿ“ฑ Frontend: http://localhost:8000" @@ -24,22 +24,22 @@ if command -v docker &> /dev/null; then echo "" echo "To stop: docker-compose down" echo "To view logs: docker-compose logs -f" - + else echo "โš ๏ธ Docker not found. Installing manually..." - + # Check Python if ! command -v python3 &> /dev/null; then echo "โŒ Python 3 is required but not installed" exit 1 fi - + # Check Node.js if ! command -v node &> /dev/null; then echo "โŒ Node.js is required but not installed" exit 1 fi - + # Check FFmpeg if ! command -v ffmpeg &> /dev/null; then echo "โš ๏ธ FFmpeg not found. Please install it:" @@ -47,39 +47,39 @@ else echo " macOS: brew install ffmpeg" exit 1 fi - + echo "โœ… All dependencies found" - + # Backend setup echo "๐Ÿ”ง Setting up backend..." cd backend - + # Check if uv is installed if ! command -v uv &> /dev/null; then echo "Installing uv..." curl -LsSf https://astral.sh/uv/install.sh | sh export PATH="$HOME/.cargo/bin:$PATH" fi - + if [ ! -d ".venv" ]; then uv venv --python 3.13 fi - + uv sync - + # Create data directories mkdir -p ../data/music ../data/uploads ../data/temp - + # Frontend setup echo "๐ŸŽจ Setting up frontend..." cd ../frontend npm install npm run build - + # Copy frontend build to backend static mkdir -p ../backend/static cp -r dist/* ../backend/static/ - + echo "" echo "โœจ Setup complete!" echo ""