you-music/README.md

# 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](https://github.com/hanxi/xiaomusic) and [spotube](https://github.com/KRTirtho/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
- **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:**

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

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

# Visit http://localhost:3000
```

See [LOCAL_DEV_GUIDE.md](LOCAL_DEV_GUIDE.md) for detailed local development instructions.

### Using Docker (Production/Easy Setup)

1. **Clone the repository**
```bash
git clone <your-repo-url>
cd you-music
```

2. **Build and run with Docker Compose**
```bash
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**
```bash
cd backend
uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```

2. **Install dependencies**
```bash
uv sync
```

3. **Install system dependencies**
- FFmpeg (for audio processing)
```bash
# Ubuntu/Debian
sudo apt-get install ffmpeg

# macOS
brew install ffmpeg

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

4. **Run the backend**
```bash
cd backend
uvicorn main:app --reload
```

#### Frontend Setup

1. **Install Node.js dependencies**
```bash
cd frontend
npm install
```

2. **Run development server**
```bash
npm run dev
```

3. **Build for production**
```bash
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

Create a `.env` file in the backend directory:

```env
# Database
DATABASE_URL=sqlite+aiosqlite:///./data/youmusic.db

# 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
```

## 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:

```python
# 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:
```bash
ffmpeg -version
```

### Port already in use
Change the port in docker-compose.yml or when running manually:
```bash
uvicorn main:app --port 8001
```

### Database errors
If you encounter database errors, try the following:

**With Migrations (Recommended):**
```bash
# 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!):**
```bash
# 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](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:**
```bash
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](MIGRATIONS.md).

### Running tests
```bash
# Backend
cd backend
pytest

# Frontend
cd frontend
npm test
```

### Code formatting
```bash
# 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](https://github.com/hanxi/xiaomusic) - Inspiration for download logic
- [spotube](https://github.com/KRTirtho/spotube) - UI/UX inspiration
- [shadcn/ui](https://ui.shadcn.com/) - UI components
- [yt-dlp](https://github.com/yt-dlp/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)