Playtube/README.md

Playtube

Eigenstaendige Desktop-App für YouTube & YouTube Music (kein Browser-Fenster, keine Erweiterung) mit:

• Zwei Tabs – YouTube und YouTube Music laufen parallel, Musik spielt im Hintergrund weiter wenn du zu Videos wechselst.
• Login/Premium – eigenes, persistentes Profil (%APPDATA%\Playtube, im Entwicklungsmodus %APPDATA%\PlaytubeDev – bewusst getrennt, damit sich lokale Test-Builds nie mit einer installierten Version in die Quere kommen), einmal bei Google anmelden reicht fuer beide Dienste.
• Discord Rich Presence – zeigt Titel, Kanal/Interpret, Fortschrittsbalken und einen Link-Button in deinem Discord-Profil, sobald etwas laeuft.
• System-Tray – Fenster schliessen minimiert nur (Musik laeuft weiter), Rechtsklick aufs Tray-Icon zum Beenden, Play/Pause/Skip direkt aus dem Menue.
• Eigener Name – erscheint als "Playtube" im Taskmanager, Fenstertitel, Alt-Tab und (nach dem Packaging, siehe unten) im Lautstaerkemixer statt als "python".

Installation (Windows)

Lade auf der Releases-Seite Playtube-Setup-vX.Y.Z.exe herunter und starte sie. Der Installer

• installiert Playtube pro Benutzer nach %LOCALAPPDATA%\Programs\Playtube (keine Admin-Rechte noetig) und legt Startmenue-Eintrag (optional Desktop-Verknuepfung) an,
• ersetzt bei jeder spaeteren Ausfuehrung die vorhandene Installation an Ort und Stelle (feste Installer-ID) - es gibt also immer genau EINE installierte Version, nie mehrere nebeneinander,
• beendet dafuer ein noch laufendes Playtube selbst und raeumt den alten Programmordner auf, damit keine Reste alter Versionen uebrig bleiben,
• laesst Login und Einstellungen (%APPDATA%\Playtube) unangetastet; beim Deinstallieren ueber "Apps & Features" wird gefragt, ob sie mitgeloescht werden sollen.

Ab dann aktualisiert sich Playtube selbst (siehe "Automatische Updates") - die Setup-Datei wird dafuer nicht erneut von Hand gebraucht. Das ZIP-Paket (Playtube-vX.Y.Z-win64.zip) bleibt als portable Variante ohne Installation erhalten; Playtube bietet einer portablen Kopie beim naechsten Update automatisch an, in die regulaere Installation zu wechseln (danach kann der alte Ordner geloescht werden).

Schnellstart (Entwicklung)

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python main.py

Beim ersten Start meldest du dich einmal in einem der beiden Tabs mit deinem Google-Konto an (Symbol oben rechts auf youtube.com bzw. music.youtube.com) - der Login bleibt danach dauerhaft gespeichert.

Discord Rich Presence einrichten

Die Client-ID ist bereits in config.json eingetragen (discord.client_id). Falls du sie aendern oder eine eigene Anwendung nutzen willst:

1. Auf https://discord.com/developers/applications eine neue Application anlegen.
2. Die Application ID in config.json unter discord.client_id eintragen.
3. Optional, fuer eigene Icons: unter Rich Presence → Art Assets zwei Bilder mit den exakten Schluesseln youtube_logo und music_logo hochladen (Playtube nutzt genau diese Keys automatisch). Ohne hochgeladene Assets funktioniert die Presence trotzdem, nur ohne Bild.
4. Discord muss auf demselben Rechner laufen, damit die Presence angezeigt wird.

In config.json lassen sich zudem update_interval_seconds (Mindestabstand zwischen Updates) und show_idle_presence (Status anzeigen, wenn gerade nichts laeuft) anpassen.

App als eigenstaendige Playtube.exe packen

Fuer die volle Taskmanager-/Audiomixer-Markierung wird die App als eigene .exe gebaut (ein via python main.py gestarteter Prozess heisst in Windows immer "python.exe" - nur eine kompilierte .exe mit eigenem Namen und eigener Versionsinfo kann das aendern):

.venv\Scripts\pip install pyinstaller
powershell -ExecutionPolicy Bypass -File packaging\build.ps1

Ergebnis liegt danach unter dist\Playtube\Playtube.exe. Ist Inno Setup 6 installiert (winget install --id JRSoftware.InnoSetup -e), baut das Skript daraus ausserdem den Installer dist\installer\Playtube-Setup-vX.Y.Z.exe (Skript: packaging/playtube.iss; mit -SkipInstaller ueberspringbar). Eine portable, nicht per Setup installierte .exe legt beim ersten Start automatisch eine Verknuepfung im Windows-Startmenue an - eine per Setup installierte Kopie hat den Eintrag bereits vom Installer.

Das Build-Skript benennt zusaetzlich den QtWebEngine-Hilfsprozess (der den eigentlichen Ton ausgibt) zu PlaytubeHelper.exe um, damit er im Taskmanager nicht als QtWebEngineProcess auftaucht. Fuer eine vollstaendige Umbenennung inkl. Icon/Versionsinfo dieses Hilfsprozesses (relevant fuer den Lautstaerkemixer) zusaetzlich rcedit als packaging\rcedit.exe ablegen - das Skript nutzt es automatisch, wenn vorhanden. Ohne rcedit funktioniert alles genauso, nur zeigt der Lautstaerkemixer fuer den Ton-Unterprozess je nach Windows-Version eventuell weiterhin "QtWebEngineProcess" statt "Playtube" (rein kosmetisch - Namensgebung von Chromium-Hilfsprozessen ist ein bekanntes, Windows-versionsabhaengiges Verhalten, das selbst grosse Electron-Apps nur mit rcedit o.ae. umgehen).

Automatische Updates

Playtube prueft beim Start und danach alle updates.check_interval_hours Stunden (Standard 6, im Einstellungen-Tab oder in config.json einstellbar) die GitHub Releases des Projekts. Im Einstellungen-Tab gibt es zusaetzlich einen "Jetzt nach Updates suchen"-Button mit Status-Anzeige und Fortschrittsbalken fuer den Download. Gibt es eine neuere Version, fragt ein Dialog, ob sie installiert werden soll:

• Windows, per Setup installiert (siehe "Installation"): laedt bevorzugt das kleine Patch-Paket herunter (nur die Playtube.exe mit unserem Anwendungscode, ca. 2-3 MB) und ueberschreibt damit die Datei im Installationsordner - der riesige PySide6/ QtWebEngine-Laufzeitordner (_internal/) bleibt unangetastet, da er sich zwischen normalen Patch-Releases nicht aendert. Die PySide6-Version steht im Dateinamen des Patches (...-pyside6.11.2-patch.play); weicht sie von der installierten Laufzeit ab, ist ein reines .exe-Patch nicht mehr passend und Playtube nimmt stattdessen den Setup-Installer, der alles (auch die Laufzeit) an Ort und Stelle erneuert und Playtube danach wieder startet. Der Versionseintrag in "Apps & Features" wird nach einem Patch ebenfalls nachgezogen.
• Windows, portable Kopie (aus dem ZIP entpackt, z.B. in Downloads): laedt den Setup-Installer und fuehrt ihn still aus. Playtube liegt danach in der regulaeren Installation - Startmenue-Eintrag und Dateizuordnung zeigen dorthin, die alte portable Kopie ist nicht mehr noetig (und kann geloescht werden). So entstehen nicht laenger versionierte Ordner nebeneinander. Gibt es (bei aelteren Releases) keinen Installer, wird wie frueher das volle ZIP ueber den vorhandenen Ordner kopiert.
• Linux (Playtube-Binary): Patch-Paket (nur das Binary) bzw. volles .tar.gz. Die App startet sich in allen Faellen danach selbst neu.
• Entwicklungsmodus (python main.py): fuehrt git pull + pip install -r requirements.txt aus und startet den Python-Prozess neu.

Auto-Update laesst sich im Einstellungen-Tab oder in config.json unter updates.enabled deaktivieren.

Nach einem erkannten Update wird beim naechsten Start automatisch der QtWebEngine- HTTP-Cache geleert (webprofile/cache) - alte Cache-Eintraege koennen sonst nicht mehr zum neuen Code passen (fruehere Ursache fuer fehlende Icons). Der Login bleibt davon unberuehrt, da Cookies/LocalStorage in einem komplett getrennten Ordner (webprofile/storage) liegen.

Patch-Dateien manuell installieren (.play)

Windows-Patch-Pakete tragen die eigene Dateiendung .play statt .zip (technisch weiterhin ein ganz normales ZIP-Archiv). Playtube registriert .play beim ersten Start automatisch als Windows-Dateizuordnung - eine manuell heruntergeladene Playtube-vX.Y.Z-win64-patch.play (z.B. von der Releases-Seite) laesst sich also einfach per Doppelklick installieren, ohne dass Playtube selbst etwas herunterladen muss.

Eine neue Version veroeffentlichen

powershell -ExecutionPolicy Bypass -File packaging\release.ps1 -Version 1.1.0

Das Skript setzt die Versionsnummer, committet, erstellt Git-Tag v1.1.0 und pusht zu origin (dein Repo unter https://github.com/fojadrachi/Playtube). Der gepushte Tag loest automatisch die GitHub-Actions-Pipeline (.github/workflows/release.yml) aus, die sowohl eine Windows- als auch eine Linux-Version baut und beide als Assets an einem GitHub Release veroeffentlicht - Fortschritt unter https://github.com/fojadrachi/Playtube/actions.

Fuer Windows entstehen dabei drei Dateien: Playtube-Setup-vX.Y.Z.exe (Installer, fuer Neueinsteiger und volle Updates), Playtube-vX.Y.Z-win64.zip (portabel) und das kleine ...-pyside<Version>-patch.play (schnelles Update). Der Installer bekommt seine Versionsnummer aus playtube/__init__.py (das release.ps1 vor dem Tag setzt).

Alle Nutzer mit einer laufenden Playtube-Installation (Windows oder Linux) bekommen die neue Version danach automatisch angeboten.

Native Linux-Version

Playtube laeuft genauso unter Linux (gleicher Code, gleiches PySide6/QtWebEngine) und wird bei jedem Release automatisch als Playtube-vX.Y.Z-linux-x86_64.tar.gz unter https://github.com/fojadrachi/Playtube/releases mitgebaut.

Fertiges Release installieren (richtet Startmenue-Eintrag + Icon ein):

tar -xzf Playtube-vX.Y.Z-linux-x86_64.tar.gz
cd Playtube
sh install-linux.sh

Danach ist Playtube ueber das Anwendungsmenue oder den Befehl playtube startbar.

Aus dem Quellcode starten:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py

QtWebEngine benoetigt unter Linux ein paar System-Bibliotheken (auf Debian/Ubuntu): sudo apt install libxkbcommon0 libegl1 libnss3 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libasound2t64 libatk-bridge2.0-0 libcups2 (siehe auch die vollstaendige Liste in .github/workflows/release.yml).

Hinweise

• "Dieser Browser ist unter Umstaenden nicht sicher" beim Google-Login: Playtube setzt einen echten Chrome-User-Agent inkl. passender Sec-CH-UA-Header, damit Google das eingebettete Chromium (QtWebEngine) nicht als unsicheres WebView erkennt. Sollte die Meldung dennoch erscheinen: alle Playtube-Fenster/-Prozesse schliessen und neu starten (die Header greifen erst ab dem naechsten Prozessstart), notfalls einmal den Profilordner %APPDATA%\Playtube\webprofile (bzw. PlaytubeDev im Entwicklungsmodus) loeschen und neu anmelden.
• Auf YouTube/YouTube Music fehlen alle Icons (Play/Pause, Suche, Menue ...): Fast sicher laufen zwei Playtube-Prozesse gleichzeitig auf demselben Browser-Profil - die zweite Instanz rendert dann keine Icons mehr. Passiert leicht, weil das Schliessen des Fensters Playtube nur in den Tray minimiert: eine aeltere Version laeuft unsichtbar weiter, waehrend eine neu heruntergeladene zusaetzlich gestartet wird. Abhilfe: alle Playtube-Instanzen ueber das Tray-Icon (Rechtsklick -> Beenden) bzw. im Taskmanager beenden und nur EINE neu starten. Ab der Version mit playtube/single_instance.py verhindert Playtube den Doppelstart selbst (ein zweiter Start holt das laufende Fenster nach vorn); eine aeltere Instanz ohne diesen Schutz wird dabei nicht erkannt und muss einmalig manuell beendet werden.
• 4K/Premium-Videoqualitaet kann eingeschraenkt sein, da die Open-Source-Variante von QtWebEngine kein Widevine-DRM mitbringt (Standard-Qualitaeten funktionieren normal).
• Icon/Branding-Bilder liegen unter assets/ und wurden mit tools/generate_icon.py erzeugt (Pillow) - bei Bedarf einfach eigenes icon.ico/icon.png dort ersetzen.