Skip to main content

ADR 001: Use yt-dlp for Video Download

Status​

Accepted

Context​

The system needs to download videos from various platforms (YouTube, Vimeo, etc.) for processing. We need a reliable, maintained solution that supports:

  • Multiple video platforms
  • Audio extraction
  • Metadata extraction
  • Quality selection
  • Resume capability

Decision​

Use yt-dlp (YouTube-DL Plus) as the video download engine.

Consequences​

Positive​

  • Supports 1000+ video platforms
  • Active maintenance (unlike youtube-dl)
  • Built-in FFmpeg integration for audio extraction
  • Python API available
  • Rate limiting and retry logic built-in
  • Extracts metadata (title, description, duration)

Negative​

  • GPL license (must open-source derivatives)
  • Occasional breakages due to platform changes
  • Requires external FFmpeg installation

Alternatives Considered​

AlternativeProsCons
youtube-dlMatureStale maintenance
pytubePure PythonLimited platforms, fragile
Custom scrapersFull controlMaintenance burden
wget/curlSimpleNo platform support

Implementation​

import yt_dlp

ydl_opts = {
    'format': 'best',
    'outtmpl': '%(title)s.%(ext)s',
    'extract_audio': True,
    'audio_format': 'mp3',
}

Notes​

Monitor yt-dlp releases for platform-specific fixes.