downlink/docs/transcoding.md

Transcoding Feature

Overview

The transcoding feature converts downloaded YouTube videos and audio files into different formats. This allows users to download content in their preferred format (MP4, WebM, MP3, WAV, etc.) regardless of the original format.

Usage

Format Selection

Users can select from the following formats:

Video Formats:

• MP4 (most compatible)
• WebM (web-optimized)
• MKV (high quality)
• AVI (legacy support)

Audio Formats:

• MP3 (most compatible, compressed)
• WAV (uncompressed, high quality)
• M4A (Apple format, good quality)
• Opus (modern, efficient)

How It Works

1. User selects desired format from dropdown
2. System downloads best available format from YouTube
3. For audio formats (MP3, WAV), yt-dlp extracts audio and converts
4. For video formats, yt-dlp selects best matching format or transcodes if needed
5. Converted file is saved and served to user

Technical Details

Implementation

Audio Transcoding

Audio formats like MP3 and WAV require extraction and conversion:

• yt-dlp downloads best audio stream (usually M4A)
• Uses ffmpeg (via yt-dlp) to convert to requested format
• Command: yt-dlp -f "bestaudio" -x --audio-format mp3 --audio-quality 0

Video Transcoding

Video formats use format selection:

• yt-dlp attempts to find matching format
• Falls back to best available format if exact match not found
• May combine video and audio streams if needed

Code Location

• Format handling: lib/youtube.ts - downloadVideo() function
• Format selection logic determines yt-dlp command based on requested format

Format Mapping

// Video formats
mp4 → bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best
webm → bestvideo[ext=webm]+bestaudio[ext=m4a]/best[ext=webm]/best
mkv → bestvideo[ext=mkv]+bestaudio[ext=m4a]/best[ext=mkv]/best
avi → bestvideo[ext=avi]+bestaudio[ext=m4a]/best[ext=avi]/best

// Audio formats
mp3 → bestaudio[ext=m4a]/bestaudio + convert to MP3
wav → bestaudio[ext=m4a]/bestaudio + convert to WAV
m4a → bestaudio[ext=m4a]/bestaudio
opus → bestaudio[ext=opus]/bestaudio

Configuration

Audio Quality

Currently set to highest quality (--audio-quality 0). Can be adjusted:

• 0: Best quality (largest file)
• 5: Default quality
• 9: Lower quality (smaller file)

Video Quality

Currently downloads best available. Could be enhanced to allow:

• Resolution selection (720p, 1080p, etc.)
• Bitrate selection
• Codec preference

Examples

Transcoding Flow

// User requests MP3
{
  url: "https://youtube.com/watch?v=...",
  format: "mp3",
  formatType: "audio"
}

// System process:
// 1. Download best audio (M4A)
// 2. Extract audio stream
// 3. Convert to MP3 using ffmpeg
// 4. Save as .mp3 file

Dependencies

• yt-dlp: Handles format selection and basic conversion
• ffmpeg: Required for audio format conversion (MP3, WAV)

Limitations

• Transcoding happens server-side and can be CPU-intensive
• Large files may take significant time to process
• No progress indication during transcoding
• Quality settings are fixed (best quality)

Future Improvements

• Add quality/bitrate selection options
• Add resolution selection for video
• Add progress tracking for transcoding
• Add batch transcoding support
• Add preview/thumbnail generation
• Add custom ffmpeg parameters option