TuneRipper/README.md

# TuneRipper - YouTube to MP3 Converter

A modern Blazor WebAssembly application with ASP.NET Core API for converting YouTube videos to MP3 files using yt-dlp.

## ?? Overview

TuneRipper is a full-stack web application that allows users to convert YouTube videos to MP3 format. It features a responsive Blazor WebAssembly frontend and a robust ASP.NET Core API backend with real-time progress monitoring.

## ??? Architecture

### Projects Structure
```
TuneRipper/
??? TuneRipper/                    # Blazor WebAssembly Client
??? TuneRipper.Api/                # ASP.NET Core API
??? TuneRipper.Shared/             # Shared Models & Configuration
??? DEPLOYMENT_GUIDE_IIS_Windows11.md
```

### Technology Stack
- **.NET 10** - Latest .NET framework
- **Blazor WebAssembly** - Modern SPA framework
- **ASP.NET Core API** - RESTful backend services
- **yt-dlp** - YouTube video processing
- **FFmpeg** - Audio conversion
- **IIS** - Production deployment platform

## ?? Quick Start

### Prerequisites
1. **.NET 10 SDK** installed
2. **yt-dlp.exe** (automatically placed in API wwwroot)
3. **FFmpeg** available in system PATH

### Development Setup

#### 1. Clone the Repository
```bash
git clone https://git.vrba.one/TuneRipper.git
cd TuneRipper
```

#### 2. Start the API
```bash
cd TuneRipper.Api
dotnet run
```
API will be available at:
- **HTTPS**: https://localhost:7160
- **HTTP**: http://localhost:5112

#### 3. Start the Blazor WebAssembly App
```bash
cd TuneRipper
dotnet run
```
App will be available at: https://localhost:7070

### Quick Testing
1. Navigate to the Blazor app
2. Enter a YouTube URL
3. Click "Download MP3"
4. Monitor real-time progress
5. Download the converted file

## ?? File Management System

### GUID-Based Naming
Downloaded files use the format: **`{jobId}_{title}.mp3`**

**Examples:**
- `550e8400-e29b-41d4-a716-446655440000_Rick_Astley_Never_Gonna_Give_You_Up.mp3`
- `6ba7b810-9dad-11d1-80b4-00c04fd430c8_How_to_Build_a_Web_API.mp3`

**Benefits:**
- ? **Unique Identification**: No filename conflicts
- ? **Direct Job Mapping**: Easy file lookup using GUID
- ? **User-Friendly Downloads**: Converted to readable names
- ? **Secure Access**: Job ID acts as access token

### File Storage
- **Location**: `TuneRipper.Api/wwwroot/downloads/`
- **Access**: Via API endpoints or direct static file serving
- **Cleanup**: Automated cleanup by job ID pattern

## ?? API Workflow

### 1. Start Processing
```http
POST /api/video/process
Content-Type: application/json

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "format": "mp3",
  "quality": "128"
}
```

### 2. Monitor Progress
```http
GET /api/video/status/{jobId}
```
Returns real-time progress with video details.

### 3. Download Result
```http
GET /api/download/{jobId}
```
Returns MP3 file with user-friendly filename.

## ?? Progress Monitoring

Real-time progress updates from yt-dlp processing:
- **5-15%**: Fetching video details
- **15-70%**: Downloading audio stream
- **70-85%**: Converting to MP3 format
- **85-95%**: Finalizing and cleanup
- **100%**: Ready for download

## ??? Development

### API Endpoints
- **Health Check**: `GET /api/health`
- **Process Video**: `POST /api/video/process`
- **Check Status**: `GET /api/video/status/{jobId}`
- **Get Result**: `GET /api/video/result/{jobId}`
- **Download File**: `GET /api/download/{jobId}`
- **List Jobs**: `GET /api/video/jobs`

### Configuration
Update `appsettings.json` for environment-specific settings:
```json
{
  "ApiSettings": {
    "BaseUrl": "https://localhost:7160",
    "TimeoutSeconds": 300,
    "EnableLogging": true
  }
}
```

### Testing
Use the provided HTTP test file:
```bash
# Open TuneRipper.Api/api-tests.http in VS Code or Visual Studio
```

## ?? Deployment

### IIS on Windows 11 (Recommended)
Follow the comprehensive deployment guide:
```bash
# See DEPLOYMENT_GUIDE_IIS_Windows11.md for detailed instructions
```

**Key Deployment Steps:**
1. Install .NET 10 Hosting Bundle for IIS
2. Enable IIS with ASP.NET Core support
3. Publish applications using Release configuration
4. Configure IIS sites and application pools
5. Set proper file permissions
6. Test end-to-end functionality

### Docker (Alternative)
```dockerfile
# Dockerfile examples available for containerized deployment
```

## ?? Configuration Details

### Required Tools
- **yt-dlp.exe**: Place in `TuneRipper.Api/wwwroot/`
- **FFmpeg**: Add to system PATH for audio conversion

### Environment Variables
- `ASPNETCORE_ENVIRONMENT`: Development/Production
- `ASPNETCORE_URLS`: Custom binding URLs

### CORS Configuration
API is configured to allow Blazor WebAssembly client access:
```csharp
builder.Services.AddCors(options =>
{
    options.AddPolicy("BlazorPolicy", policy =>
    {
        policy.AllowAnyOrigin()
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});
```

## ?? Troubleshooting

### Common Issues

#### API Not Starting
```bash
# Check .NET installation
dotnet --version

# Trust development certificates
dotnet dev-certs https --trust
```

#### yt-dlp Not Found
- Verify `yt-dlp.exe` is in `TuneRipper.Api/wwwroot/`
- Check file permissions
- Ensure downloads directory exists

#### FFmpeg Issues
```bash
# Verify FFmpeg installation
ffmpeg -version

# Add to PATH if needed
```

#### CORS Errors
- Verify API base URL configuration in Blazor app
- Check CORS policy settings
- Ensure API is running on expected port

### Debug Logging
Enable detailed logging in `appsettings.json`:
```json
{
  "Logging": {
    "LogLevel": {
      "TuneRipper.Api.Services.VideoService": "Debug"
    }
  }
}
```

## ?? Security Considerations

### Production Deployment
- **HTTPS Only**: Configure SSL certificates
- **CORS Restrictions**: Limit allowed origins
- **Rate Limiting**: Implement API rate limiting
- **File Cleanup**: Set up automated cleanup jobs
- **Access Control**: Consider authentication for production

### File Security
- Job IDs provide secure file access
- No directory traversal vulnerabilities
- Automatic cleanup prevents disk space issues

## ?? Performance Optimization

### Recommended Settings
- **Application Pool**: Configure for .NET 10
- **File Storage**: Consider cloud storage for scale
- **Caching**: Implement response caching where appropriate
- **Monitoring**: Set up application insights

### Scaling Considerations
- GUID-based naming supports distributed environments
- Stateless API design enables horizontal scaling
- Consider queue-based processing for high load

## ?? Maintenance

### Regular Tasks
- Update yt-dlp.exe for YouTube compatibility
- Monitor disk space in downloads directory
- Check for .NET 10 security updates
- Review and rotate log files

### Monitoring
- Application pool health
- File system usage
- API response times
- Error rates and patterns

## ?? Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## ?? License

This project is licensed under the MIT License - see the LICENSE file for details.

## ?? Related Files

- **Deployment Guide**: `DEPLOYMENT_GUIDE_IIS_Windows11.md`
- **API Tests**: `TuneRipper.Api/api-tests.http`
- **Project Files**: `*.csproj` in each project directory

---

**Built with ?? using .NET 10, Blazor WebAssembly, and modern web technologies.**