cms.c2sgmbh/docs/plans/2026-02-14-youtube-thumbnail-download-design.md

YouTube Thumbnail Download — Design

Datum: 14.02.2026 Status: Approved

Ziel

Automatischer Download von YouTube-Video-Thumbnails und Kanalbildern als Payload Media, damit diese offline verfügbar sind und von Payload's Sharp-Pipeline optimiert werden.

Scope

• Video-Thumbnails: Auto-Download bei Sync + Bulk-Import für bestehende Einträge
• Kanalbilder: Profilbilder und Banner beim Channel-Sync
• Nicht im Scope: Kommentar-Autor-Avatare (bleiben als externe URLs)

Qualität

• YouTube-Thumbnails: hqdefault (480x360)
• Payload generiert daraus automatisch alle responsive Sizes (thumbnail, small, medium, etc.)

Architektur: Inline beim Sync

Download direkt im Sync-Flow integriert, kein separater Queue-Job.

1. Kern-Utility: downloadAndUploadImage()

Datei: src/lib/utils/media-download.ts

interface DownloadOptions {
  url: string
  filename: string
  alt?: string
  tenantId?: number
}

async function downloadAndUploadImage(
  payload: Payload,
  options: DownloadOptions
): Promise<number | null>

• Lädt Bild von URL herunter
• Erstellt Payload Media-Dokument (mit Tenant-Zuordnung)
• Sharp-Pipeline generiert alle 11 responsive Sizes automatisch
• Duplikat-Erkennung: Prüft ob Media mit gleichem Dateinamen + Tenant existiert
• Fehler → null (kein harter Fehler, Sync läuft weiter)

2. Integration in YouTube-Sync

YouTubeContent (beim Erstellen/Updaten):

• Wenn thumbnail-Feld leer → Download von https://img.youtube.com/vi/{videoId}/hqdefault.jpg
• Media-ID in thumbnail-Feld speichern
• Manuell hochgeladene Thumbnails werden nie überschrieben

YouTubeChannels (beim Channel-Sync):

• Profilbild und Banner aus YouTube API herunterladen (falls Felder leer)
• In entsprechende Media-Felder speichern

3. Bulk-Import Endpoint

Route: POST /api/youtube/thumbnails/bulk Auth: Super-Admin erforderlich

• Findet alle YouTubeContent-Einträge ohne Thumbnail
• Downloadet sequentiell mit 500ms Delay (Rate-Limit-Schutz)
• Response: { processed, downloaded, skipped, errors }
• Optional: ?dryRun=true

4. Fehlerbehandlung

Aspekt	Verhalten
Rate-Limiting	500ms Delay zwischen Downloads (Bulk)
Timeout	10s pro Download
Retry	Kein Retry (YouTube CDN zuverlässig)
404/Fehler	null zurückgeben, Sync fortsetzen
Duplikate	Existierendes Media zurückgeben
Manuelle Uploads	Nie überschreiben
Logging	Console.log (nicht AuditLogs)

Betroffene Dateien

Neu

• src/lib/utils/media-download.ts — Kern-Utility
• src/app/(payload)/api/youtube/thumbnails/bulk/route.ts — Bulk-Endpoint

Modifiziert

• YouTube-Sync-Services — Thumbnail-Download nach Content-Erstellung
• YouTubeChannels-Sync — Kanalbild-Download nach Channel-Update

Nicht-Ziele

• Keine Kommentar-Avatare herunterladen
• Kein Queue-basierter Download
• Keine automatische Aktualisierung bestehender Thumbnails