🎛️ MediaForge - FastAPI Media Processing Service Context

Overview

MediaForge is a FastAPI-based media processing service that offers:

• Metadata editing and inspection
• Audio and video transformation
• YouTube video/audio downloading
• Output storage in a MinIO server
• Real-time dashboard for logs and job status
• External webhook support for job updates

All processing is handled by FFmpeg and yt-dlp, and outputs are managed via MinIO.

---

🔧 Features

1. 📦 Metadata Handling

• View metadata (title, artist, date, etc.)
• Edit/remove metadata
• Add custom tags/descriptions

2. 🔊 Audio Processing

• Format conversion (MP3, WAV, FLAC, AAC, etc.)
• Extract audio from video
• Merge/mix audio with video
• Volume adjustment and normalization
• Remove or isolate audio tracks
• Modify bitrate, sample rate, or channels

3. 🎞️ Video Processing

• Format conversion (MP4, MKV, MOV, AVI, etc.)
• Resize, crop, pad, rotate, flip
• Trim/cut video sections
• Merge/concatenate videos
• Adjust frame rate (FPS)
• Add overlays/logos/watermarks
• Apply visual filters (blur, sharpen, grayscale)
• Extract frames/images

4. 📥 YouTube Downloader

• Download via yt-dlp
• Extract audio only (optional)
• Auto-convert on download

---

💾 MinIO Integration

• Save all output files to a defined MinIO bucket
• Files organized into folders (/audio/, /video/, /images/)
• Presigned URLs returned after processing

---

🖥️ Web Dashboard (Logs & Job Progress)

• UI dashboard to:
  • Track jobs (Queued, Processing, Completed, Failed)
  • View FFmpeg logs and commands
  • Filter by job type
• Real-time updates via WebSocket or polling
• Built with HTMX, Vue, or React (optional)

---

🔔 External Webhook Notifications

• Allow clients to provide a webhook_url with their job
• On job completion (success/failure), send a POST request to the webhook URL with:
  • Job ID
  • Status
  • Output URL(s)
  • Log (optional)
  • Timestamp

Example webhook payload:

{
  "job_id": "abc123",
  "status": "completed",
  "output_urls": ["https://media.example.com/audio/abc123.mp3"],
  "log_summary": "FFmpeg finished successfully",
  "completed_at": "2025-06-22T14:30:00Z"
}

---

📁 Folder Structure

/app
  ├── main.py
  ├── routers/
  │   ├── metadata.py
  │   ├── audio.py
  │   ├── video.py
  │   ├── youtube.py
  │   └── dashboard.py
  ├── services/
  │   ├── ffmpeg_utils.py
  │   ├── minio_client.py
  │   ├── job_tracker.py
  │   └── webhook_notifier.py
  └── models/
      └── schemas.py

---

🧰 Dependencies

• FastAPI
• Uvicorn
• ffmpeg / ffprobe
• yt-dlp
• minio SDK
• python-multipart
• aiofiles
• websockets / sse-starlette
• httpx (for async webhook calls)

---

🗃️ Environment Variables

MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=media-files
FFMPEG_PATH=/usr/bin/ffmpeg
FFPROBE_PATH=/usr/bin/ffprobe

---

📌 Notes

• Supports both file uploads and remote media URLs
• Webhooks and dashboard are optional but supported
• Async-first design for scalability and responsiveness
• Ready for future job queuing (Celery, RQ, etc.)