01Overview

Downloader Studio is a desktop application written in Python, using PyQt5 for the GUI and yt-dlp as the extraction/download engine. It lets users search for media, queue it up, and download audio or video with FFmpeg post-processing for format conversion.

Key points

• Sidebar-tabbed interface: Search, Queue, Settings, Logs.
• Minimal floating mode toggled with Ctrl+M.
• Dark and light themes applied globally via a Python-generated Qt stylesheet.
• UI translated into 4 languages (FR, EN, DE, ES), rebuilt dynamically on language change.
• Settings persisted as JSON in the user data directory.

02Project architecture

File tree

downloader-studio/
├── main.py                        # Entry point (QApplication, splash screen)
├── config.py                      # Global constants (version, paths, languages)
├── requirements.txt                # Runtime dependencies
├── app/
│   ├── signals.py                  # Global SignalManager (e.g. language_changed)
│   ├── core/
│   │   ├── download_engine.py      # Queue + yt-dlp integration
│   │   └── update_checker.py       # Update check via GitHub Releases
│   ├── ui/
│   │   ├── main_window.py          # Main window, sidebar, themes, settings
│   │   ├── minimal_window.py        # Compact floating mode (Ctrl+M)
│   │   └── pages/
│   │       ├── search_page.py      # Search + results + add to queue
│   │       ├── queue_page.py       # Queue, progress, history
│   │       ├── settings_page.py    # Language, theme, sources, formats, quality
│   │       └── logs_page.py        # Activity log + export
│   └── utils/
│       ├── icons.py                # SVG icons generated on the fly (QIcon)
│       └── resources.py            # Path resolution (dev / PyInstaller / Inno)
├── i18n/
│   ├── __init__.py                 # Facade: t(), set_language(), get_translator()
│   └── translations.py             # TRANSLATIONS dict + Translator class
├── assets/                         # Logo, icons, visual assets
├── docs/                           # This site (landing page + documentation)
├── packaging/
│   ├── build_exe.py                 # Full build script (PyInstaller + Inno Setup)
│   └── Downloader_Studio.iss        # Inno Setup script (Windows installer)

Separation of concerns

The app follows a classic UI / business-logic split:

• UI (app/ui/): PyQt5 widgets, layout, themes, user events. No direct download logic.
• Core (app/core/): DownloadEngine manages the queue and drives DownloadWorker instances (QThread) that call yt-dlp. No dependency on PyQt Widgets, only on QThread/pyqtSignal for thread-safe UI communication.
• i18n (i18n/): centralized string dictionary, no UI string is hardcoded in widgets.
• Utils (app/utils/): stateless cross-cutting helpers (icons, path resolution).

Path resolution (resources.py)

resource_path() handles three different execution contexts so the code behaves identically in dev and once packaged:

03How it works

Download lifecycle

Supported sources

The UI exposes two search checkboxes: YouTube and SoundCloud. The engine also recognizes Twitch and TikTok by pasting a direct URL (no keyword search for these two); detection is done via domain matching in search_page.py.

Embedded player resolution (iframe)

Some "portal" sites don't expose a page yt-dlp can read directly: the real video lives inside an <iframe>. When yt-dlp fails with Unsupported URL, resolve_embedded_media_url() downloads the HTML page, looks for the first iframe src that looks like a player, then retries the download on that resolved URL.

Formats and quality

Minimal mode

Ctrl+M switches to minimal_window.py: a compact floating window that keeps the essentials (paste a URL, start the download, open the output folder) without showing the full interface.

Settings persistence

On close, save_app_settings() writes a JSON file with the theme, language, output folder, enabled sources, enabled formats, and quality preferences. It's read back on startup by load_app_settings().

04Internationalization (i18n)

Every displayed string goes through i18n/translations.py. The Translator class loads a per-language dictionary from TRANSLATIONS and exposes a global t(key) function used throughout the UI.

# i18n/translations.py
TRANSLATIONS = {
    "fr": { "search": "Recherche", "queue": "File d'attente", ... },
    "en": { "search": "Search", "queue": "Queue", ... },
    "de": { ... },
    "es": { ... },
}

class Translator:
    def get(self, key, default=None): ...
    def set_language(self, language): ...

def t(key, default=None):
    return _translator.get(key, default)

When the language changes (Settings page), a global signal signal_manager.language_changed (app/signals.py) is emitted. Each subscribed page rebuilds its text widgets to avoid keeping labels in the old language.

05Dependencies

Runtime dependencies (requirements.txt)

Non-Python external dependency

Build-time dependencies (not in requirements.txt)

06Build & release

Local build (Windows)

py -3.13 -m venv .venv-build
.\.venv-build\Scripts\python -m pip install --upgrade pip
.\.venv-build\Scripts\python -m pip install -r requirements.txt pyinstaller

# Full build: PyInstaller + FFmpeg + Inno Setup installer
.\.venv-build\Scripts\python packaginguild_exe.py

# From Git Bash
./build.sh

packaging/build_exe.py runs, in order:

1. Python version validation (3.10–3.13 final).
2. PyInstaller build in onedir mode (see why below).
3. FFmpeg retrieval (local cache, system install, or download).
4. Installer compilation with Inno Setup 6 (if detected).

Why onedir instead of onefile

onefile mode extracts Python into %TEMP%\_MEI... on every launch. An antivirus or permission policy can block or delete python313.dll at that moment, causing Failed to load Python DLL. onedir mode keeps the Python runtime, Qt DLLs, and FFmpeg next to the installed executable, so launching no longer depends on a temporary extraction.

Multiplatform build (GitHub Actions CI)

.github/workflows/release.yml triggers on a v*.*.* tag and builds all three platforms in parallel, then publishes everything to a GitHub Release:

# Trigger a full release
git tag v2.17.0
git push origin v2.17.0

Automatic updates

app/core/update_checker.py queries the GitHub Releases API (/releases/latest) on startup. It compares the remote version against APP_VERSION (config.py), then selects the asset matching the current OS (sys.platform) via filename suffix matching, with a generic fallback if no platform-specific asset is found.

07Configuration

config.py centralizes the app's global constants.

08Limitations & disclaimers

• Downloader Studio is not affiliated with any platform it queries (YouTube, SoundCloud, Twitch, TikTok).
• Downloading fully depends on yt-dlp: any change on the target sites can break extraction until the dependency is updated.
• Respect each platform's terms of service and the copyright of downloaded content.
• Release builds require CPython 3.10–3.13; any other version is intentionally blocked.

← Back to the site

01Überblick

Downloader Studio ist eine Desktop-Anwendung in Python, mit PyQt5 für die Oberfläche und yt-dlp als Extraktions-/Download-Engine. Nutzer können Medien suchen, in eine Warteschlange stellen und als Audio oder Video herunterladen, mit FFmpeg-Nachbearbeitung für Formatkonvertierung.

Wichtige Punkte

• Seitenleisten-Oberfläche: Suche, Warteschlange, Einstellungen, Logs.
• Minimalistischer Schwebemodus, umschaltbar mit Strg+M.
• Helles und dunkles Design, global über ein in Python erzeugtes Qt-Stylesheet angewendet.
• Oberfläche in 4 Sprachen (FR, EN, DE, ES), bei Sprachwechsel dynamisch neu aufgebaut.
• Einstellungen als JSON im Benutzerdatenordner gespeichert.

02Projektarchitektur

Dateibaum

downloader-studio/
├── main.py                        # Einstiegspunkt (QApplication, Splashscreen)
├── config.py                      # Globale Konstanten (Version, Pfade, Sprachen)
├── requirements.txt                # Laufzeitabhängigkeiten
├── app/
│   ├── signals.py                  # Globaler SignalManager (z. B. language_changed)
│   ├── core/
│   │   ├── download_engine.py      # Warteschlange + yt-dlp-Integration
│   │   └── update_checker.py       # Update-Prüfung über GitHub Releases
│   ├── ui/
│   │   ├── main_window.py          # Hauptfenster, Seitenleiste, Designs, Einstellungen
│   │   ├── minimal_window.py        # Kompakter Schwebemodus (Strg+M)
│   │   └── pages/
│   │       ├── search_page.py      # Suche + Ergebnisse + zur Warteschlange hinzufügen
│   │       ├── queue_page.py       # Warteschlange, Fortschritt, Verlauf
│   │       ├── settings_page.py    # Sprache, Design, Quellen, Formate, Qualität
│   │       └── logs_page.py        # Aktivitätsprotokoll + Export
│   └── utils/
│       ├── icons.py                # Zur Laufzeit erzeugte SVG-Icons (QIcon)
│       └── resources.py            # Pfadauflösung (Dev / PyInstaller / Inno)
├── i18n/
│   ├── __init__.py                 # Fassade: t(), set_language(), get_translator()
│   └── translations.py             # TRANSLATIONS-Dict + Translator-Klasse
├── assets/                         # Logo, Icons, visuelle Assets
├── docs/                           # Diese Website (Landing Page + Dokumentation)
├── packaging/
│   ├── build_exe.py                 # Vollständiges Build-Skript (PyInstaller + Inno Setup)
│   └── Downloader_Studio.iss        # Inno-Setup-Skript (Windows-Installer)

Trennung der Zuständigkeiten

Die App folgt einer klassischen UI/Geschäftslogik-Trennung:

• UI (app/ui/): PyQt5-Widgets, Layout, Designs, Benutzerereignisse. Keine direkte Download-Logik.
• Core (app/core/): DownloadEngine verwaltet die Warteschlange und steuert DownloadWorker-Instanzen (QThread), die yt-dlp aufrufen. Keine Abhängigkeit von PyQt-Widgets, nur von QThread/pyqtSignal für Thread-sichere UI-Kommunikation.
• i18n (i18n/): zentrales String-Wörterbuch, keine UI-Zeichenkette ist fest in Widgets kodiert.
• Utils (app/utils/): zustandslose Querschnittshilfen (Icons, Pfadauflösung).

Pfadauflösung (resources.py)

resource_path() behandelt drei verschiedene Ausführungskontexte, damit der Code in der Entwicklung und nach dem Packaging identisch funktioniert:

03Funktionsweise

Download-Lebenszyklus

Unterstützte Quellen

Die Oberfläche bietet zwei Such-Kontrollkästchen: YouTube und SoundCloud. Die Engine erkennt zusätzlich Twitch und TikTok durch direktes Einfügen einer URL (keine Stichwortsuche für diese beiden); die Erkennung erfolgt über Domain-Übereinstimmung in search_page.py.

Auflösung eingebetteter Player (iframe)

Manche "Portal"-Seiten stellen keine direkt von yt-dlp lesbare Seite bereit: Das eigentliche Video steckt in einem <iframe>. Wenn yt-dlp mit Unsupported URL fehlschlägt, lädt resolve_embedded_media_url() die HTML-Seite herunter, sucht nach der ersten iframe-src, die wie ein Player aussieht, und versucht den Download erneut mit dieser aufgelösten URL.

Formate und Qualität

Minimalmodus

Strg+M wechselt zu minimal_window.py: ein kompaktes Schwebefenster, das nur das Wesentliche behält (URL einfügen, Download starten, Zielordner öffnen), ohne die vollständige Oberfläche anzuzeigen.

Speicherung der Einstellungen

Beim Schließen schreibt save_app_settings() eine JSON-Datei mit Design, Sprache, Zielordner, aktivierten Quellen, aktivierten Formaten und Qualitätspräferenzen. Sie wird beim Start von load_app_settings() wieder eingelesen.

04Internationalisierung (i18n)

Jede angezeigte Zeichenkette läuft über i18n/translations.py. Die Klasse Translator lädt ein sprachspezifisches Wörterbuch aus TRANSLATIONS und stellt eine globale Funktion t(key) bereit, die überall in der UI verwendet wird.

# i18n/translations.py
TRANSLATIONS = {
    "fr": { "search": "Recherche", "queue": "File d'attente", ... },
    "en": { "search": "Search", "queue": "Queue", ... },
    "de": { ... },
    "es": { ... },
}

class Translator:
    def get(self, key, default=None): ...
    def set_language(self, language): ...

def t(key, default=None):
    return _translator.get(key, default)

Bei Sprachwechsel (Einstellungsseite) wird ein globales Signal signal_manager.language_changed (app/signals.py) ausgelöst. Jede abonnierte Seite baut ihre Text-Widgets neu auf, um Beschriftungen in der alten Sprache zu vermeiden.

05Abhängigkeiten

Laufzeitabhängigkeiten (requirements.txt)

Externe Nicht-Python-Abhängigkeit

Build-Abhängigkeiten (nicht in requirements.txt)

06Build & Veröffentlichung

Lokaler Build (Windows)

py -3.13 -m venv .venv-build
.\.venv-build\Scripts\python -m pip install --upgrade pip
.\.venv-build\Scripts\python -m pip install -r requirements.txt pyinstaller

# Vollständiger Build: PyInstaller + FFmpeg + Inno-Setup-Installer
.\.venv-build\Scripts\python packaginguild_exe.py

# Über Git Bash
./build.sh

packaging/build_exe.py führt der Reihe nach aus:

1. Prüfung der Python-Version (3.10–3.13 final).
2. PyInstaller-Build im onedir-Modus (siehe unten, warum).
3. Beschaffung von FFmpeg (lokaler Cache, Systeminstallation oder Download).
4. Kompilierung des Installers mit Inno Setup 6 (falls erkannt).

Warum onedir statt onefile

Der onefile-Modus extrahiert Python bei jedem Start nach %TEMP%\_MEI.... Ein Antivirenprogramm oder eine Rechterichtlinie kann python313.dll in diesem Moment blockieren oder löschen, was zu Failed to load Python DLL führt. Der onedir-Modus behält die Python-Laufzeit, Qt-DLLs und FFmpeg neben der installierten Executable, sodass der Start nicht mehr von einer temporären Extraktion abhängt.

Plattformübergreifender Build (GitHub Actions CI)

.github/workflows/release.yml wird bei einem Tag v*.*.* ausgelöst und baut alle drei Plattformen parallel, um dann alles in einer GitHub Release zu veröffentlichen:

# Eine vollständige Release auslösen
git tag v2.17.0
git push origin v2.17.0

Automatische Updates

app/core/update_checker.py fragt beim Start die GitHub-Releases-API (/releases/latest) ab. Es vergleicht die entfernte Version mit APP_VERSION (config.py) und wählt dann das zum aktuellen Betriebssystem passende Asset (sys.platform) über eine Dateinamen-Suffix-Übereinstimmung aus, mit generischem Fallback, falls kein plattformspezifisches Asset gefunden wird.

07Konfiguration

config.py zentralisiert die globalen Konstanten der App.

08Einschränkungen & Hinweise

• Downloader Studio ist nicht mit den abgefragten Plattformen verbunden (YouTube, SoundCloud, Twitch, TikTok).
• Der Download hängt vollständig von yt-dlp ab: Änderungen an den Zielseiten können die Extraktion brechen, bis die Abhängigkeit aktualisiert wird.
• Beachte die Nutzungsbedingungen der Plattformen und das Urheberrecht der heruntergeladenen Inhalte.
• Release-Builds erfordern CPython 3.10–3.13; jede andere Version wird absichtlich blockiert.

← Zurück zur Website

01Visión general

Downloader Studio es una aplicación de escritorio escrita en Python, con PyQt5 para la interfaz gráfica y yt-dlp como motor de extracción/descarga. Permite buscar medios, encolarlos y descargarlos en audio o video, con post-procesamiento FFmpeg para la conversión de formato.

Puntos clave

• Interfaz con pestañas laterales: Búsqueda, Cola, Configuración, Logs.
• Modo flotante minimalista activable con Ctrl+M.
• Temas claro y oscuro aplicados globalmente mediante una hoja de estilos Qt generada en Python.
• Interfaz traducida a 4 idiomas (FR, EN, DE, ES), reconstruida dinámicamente al cambiar de idioma.
• Configuración persistida en JSON en el directorio de datos del usuario.

02Arquitectura del proyecto

Árbol de archivos

downloader-studio/
├── main.py                        # Punto de entrada (QApplication, splash screen)
├── config.py                      # Constantes globales (versión, rutas, idiomas)
├── requirements.txt                # Dependencias en tiempo de ejecución
├── app/
│   ├── signals.py                  # SignalManager global (ej. language_changed)
│   ├── core/
│   │   ├── download_engine.py      # Cola + integración con yt-dlp
│   │   └── update_checker.py       # Verificación de actualizaciones vía GitHub Releases
│   ├── ui/
│   │   ├── main_window.py          # Ventana principal, barra lateral, temas, configuración
│   │   ├── minimal_window.py        # Modo flotante compacto (Ctrl+M)
│   │   └── pages/
│   │       ├── search_page.py      # Búsqueda + resultados + agregar a la cola
│   │       ├── queue_page.py       # Cola, progreso, historial
│   │       ├── settings_page.py    # Idioma, tema, fuentes, formatos, calidad
│   │       └── logs_page.py        # Registro de actividad + exportación
│   └── utils/
│       ├── icons.py                # Íconos SVG generados al vuelo (QIcon)
│       └── resources.py            # Resolución de rutas (dev / PyInstaller / Inno)
├── i18n/
│   ├── __init__.py                 # Fachada: t(), set_language(), get_translator()
│   └── translations.py             # Diccionario TRANSLATIONS + clase Translator
├── assets/                         # Logo, íconos, recursos visuales
├── docs/                           # Este sitio (landing page + documentación)
├── packaging/
│   ├── build_exe.py                 # Script de compilación completo (PyInstaller + Inno Setup)
│   └── Downloader_Studio.iss        # Script de Inno Setup (instalador de Windows)

Separación de responsabilidades

La aplicación sigue una separación clásica de UI / lógica de negocio:

• UI (app/ui/): widgets de PyQt5, diseño, temas, eventos de usuario. Sin lógica de descarga directa.
• Core (app/core/): DownloadEngine gestiona la cola y coordina instancias de DownloadWorker (QThread) que llaman a yt-dlp. Sin dependencia de PyQt Widgets, solo de QThread/pyqtSignal para comunicación segura entre hilos con la UI.
• i18n (i18n/): diccionario de cadenas centralizado, ninguna cadena de la UI está escrita directamente en los widgets.
• Utils (app/utils/): utilidades transversales sin estado (íconos, resolución de rutas).

Resolución de rutas (resources.py)

resource_path() gestiona tres contextos de ejecución distintos para que el código funcione igual en desarrollo y una vez empaquetado:

03Funcionamiento

Ciclo de vida de la descarga

Fuentes compatibles

La interfaz expone dos casillas de búsqueda: YouTube y SoundCloud. El motor también reconoce Twitch y TikTok pegando directamente una URL (sin búsqueda por palabra clave para estas dos); la detección se hace por coincidencia de dominio en search_page.py.

Resolución de reproductores incrustados (iframe)

Algunos sitios "portal" no exponen directamente una página legible por yt-dlp: el video real vive dentro de un <iframe>. Cuando yt-dlp falla con Unsupported URL, resolve_embedded_media_url() descarga la página HTML, busca el primer src de iframe que parezca un reproductor y reintenta la descarga con esa URL resuelta.

Formatos y calidad

Modo minimalista

Ctrl+M cambia a minimal_window.py: una ventana flotante compacta que conserva lo esencial (pegar una URL, iniciar la descarga, abrir la carpeta de salida) sin mostrar la interfaz completa.

Persistencia de la configuración

Al cerrar, save_app_settings() escribe un archivo JSON con el tema, el idioma, la carpeta de salida, las fuentes activadas, los formatos activados y las preferencias de calidad. Se vuelve a leer al iniciar mediante load_app_settings().

04Internacionalización (i18n)

Todas las cadenas mostradas pasan por i18n/translations.py. La clase Translator carga un diccionario por idioma desde TRANSLATIONS y expone una función global t(key) usada en toda la UI.

# i18n/translations.py
TRANSLATIONS = {
    "fr": { "search": "Recherche", "queue": "File d'attente", ... },
    "en": { "search": "Search", "queue": "Queue", ... },
    "de": { ... },
    "es": { ... },
}

class Translator:
    def get(self, key, default=None): ...
    def set_language(self, language): ...

def t(key, default=None):
    return _translator.get(key, default)

Cuando cambia el idioma (página de Configuración), se emite una señal global signal_manager.language_changed (app/signals.py). Cada página suscrita reconstruye sus widgets de texto para evitar mantener etiquetas en el idioma anterior.

05Dependencias

Dependencias en tiempo de ejecución (requirements.txt)

Dependencia externa no Python

Dependencias de compilación (no incluidas en requirements.txt)

06Compilación y publicación

Compilación local (Windows)

py -3.13 -m venv .venv-build
.\.venv-build\Scripts\python -m pip install --upgrade pip
.\.venv-build\Scripts\python -m pip install -r requirements.txt pyinstaller

# Compilación completa: PyInstaller + FFmpeg + instalador Inno Setup
.\.venv-build\Scripts\python packaginguild_exe.py

# Desde Git Bash
./build.sh

packaging/build_exe.py ejecuta, en orden:

1. Validación de la versión de Python (3.10–3.13 final).
2. Compilación con PyInstaller en modo onedir (ver por qué abajo).
3. Obtención de FFmpeg (caché local, instalación del sistema o descarga).
4. Compilación del instalador con Inno Setup 6 (si se detecta).

Por qué onedir en lugar de onefile

El modo onefile extrae Python en %TEMP%\_MEI... en cada inicio. Un antivirus o una política de permisos puede bloquear o eliminar python313.dll en ese momento, provocando Failed to load Python DLL. El modo onedir mantiene el runtime de Python, las DLL de Qt y FFmpeg junto al ejecutable instalado, por lo que el inicio ya no depende de una extracción temporal.

Compilación multiplataforma (CI de GitHub Actions)

.github/workflows/release.yml se activa con una etiqueta v*.*.* y compila las tres plataformas en paralelo, luego publica todo en una GitHub Release:

# Activar una release completa
git tag v2.17.0
git push origin v2.17.0

Actualizaciones automáticas

app/core/update_checker.py consulta la API de GitHub Releases (/releases/latest) al iniciar. Compara la versión remota con APP_VERSION (config.py) y luego selecciona el activo correspondiente al sistema operativo actual (sys.platform) mediante coincidencia de sufijo de nombre de archivo, con reserva genérica si no se encuentra un activo específico de la plataforma.

07Configuración

config.py centraliza las constantes globales de la aplicación.

08Límites y avisos

• Downloader Studio no está afiliado a ninguna de las plataformas que consulta (YouTube, SoundCloud, Twitch, TikTok).
• La descarga depende totalmente de yt-dlp: cualquier cambio en los sitios de destino puede romper la extracción hasta que se actualice la dependencia.
• Respeta los términos de uso de las plataformas y los derechos de autor del contenido descargado.
• El build de release requiere CPython 3.10–3.13; cualquier otra versión se bloquea intencionalmente.

← Volver al sitio