Update docs: new README, IIS guide, and production web.config
- Replaced README.md with a modern, production-focused version featuring quick start, architecture, workflow, troubleshooting, and security sections - Added DEPLOYMENT_GUIDE_IIS_Windows11.md with step-by-step IIS deployment instructions, including SSL, CORS, and permissions - Added version-controlled web.config files for API and Blazor app with HTTPS redirection, security headers, and SPA/static file support - Moved detailed yt-dlp integration notes to README_UPDATED.md for technical reference - Improves clarity, maintainability, and production readiness of documentation and deployment
This commit is contained in:
Michal Vrba
@@ -0,0 +1,298 @@
|
||||
# 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.**
|
||||
Reference in New Issue
Block a user