Playtube/README.md

Playtube Edge

Das ist die „Edge“-Variante von Playtube (Branch edge). Diese Version brauchst du, wenn du selbst hochgeladene Musik in YouTube Music hören willst. Die normale Playtube (Branch main) zeigt bei eigenen Uploads „Dieses Videoformat wird nicht unterstützt“, weil ihre Browser-Engine (QtWebEngine) kein AAC und kein H.264 abspielen kann. Playtube Edge rendert stattdessen mit der Microsoft-Edge-Engine (WebView2) – damit laufen auch Uploads.

• Download: Releases → Eintrag „Playtube Edge vX.Y.Z-edge“ → PlaytubeEdge-Setup-vX.Y.Z.exe. Voraussetzung: Windows 10/11 mit WebView2-Runtime (Windows 11: vorinstalliert).
• Läuft neben der normalen Playtube (eigener Ordner %APPDATA%\PlaytubeEdge, eigenes Login – beim ersten Start einmal bei Google anmelden).
• Updates kommen nur über die -edge-Releases (die normale Playtube sieht sie nie).
• Entwicklung: pip install -r requirements.txt, dann python main.py. Die WebView2-DLLs liegen in vendor/webview2 (Microsoft, NuGet Microsoft.Web.WebView2).

Der Rest dieser README beschreibt die gemeinsame Basis mit der normalen Playtube; wo dort „QtWebEngine“ steht, ist in dieser Variante WebView2 gemeint.

Eigenständige 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), einmal bei Google anmelden reicht für beide Dienste.
• Discord Rich Presence – zeigt Titel, Kanal/Interpret, Fortschrittsbalken und einen Link-Button in deinem Discord-Profil, sobald etwas läuft. Ist der Einstellungen-Tab offen, steht dort stattdessen „In den Einstellungen“ und welches Feld du gerade bearbeitest (z.B. „Discord Rich Presence › Client-ID“) - nur der Feldname, nie der Inhalt. Das folgt der Option „Status anzeigen, wenn gerade nichts läuft“ (aus = auch kein Einstellungs-Status). Discord übernimmt Änderungen höchstens alle 15 Sekunden, die Anzeige hinkt dem Klicken also etwas hinterher.
• Audioausgabe pro Tab – YouTube und YouTube Musik lassen sich in den Einstellungen auf verschiedene Ausgabegeräte legen (z.B. getrennte Sonar-Kanäle), siehe unten.
• System-Tray – Fenster schliessen minimiert nur (Musik läuft weiter), Rechtsklick aufs Tray-Icon zum Beenden, Play/Pause/Skip direkt aus dem Menü.
• Eigener Name – erscheint als "Playtube" im Taskmanager, Fenstertitel, Alt-Tab und (nach dem Packaging, siehe unten) im Lautstärkemixer statt als "python".

Installation (Windows)

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

• installiert Playtube pro Benutzer nach %LOCALAPPDATA%\Programs\Playtube (keine Admin-Rechte nötig) und legt Startmenü-Eintrag (optional Desktop-Verknüpfung) an,
• ersetzt bei jeder späteren Ausführung die vorhandene Installation an Ort und Stelle (feste Installer-ID) - es gibt also immer genau EINE installierte Version, nie mehrere nebeneinander,
• beendet dafür ein noch laufendes Playtube selbst und räumt den alten Programmordner auf, damit keine Reste alter Versionen übrig bleiben,
• lässt Login und Einstellungen (%APPDATA%\Playtube) unangetastet; beim Deinstallieren über "Apps & Features" wird gefragt, ob sie mitgelöscht werden sollen.

Ab dann aktualisiert sich Playtube selbst (siehe "Automatische Updates") - die Setup-Datei wird dafür 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 nächsten Update automatisch an, in die reguläre Installation zu wechseln (danach kann der alte Ordner gelöscht 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 ändern 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, für eigene Icons: unter Rich Presence → Art Assets zwei Bilder mit den exakten Schlüsseln 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 läuft) anpassen.

Audioausgabe pro Tab (YouTube / YouTube Musik)

Im Einstellungen-Tab legst du unter „Audioausgabe“ getrennt fest, über welches Ausgabegerät der Ton von YouTube und von YouTube Musik läuft (Standard: Systemstandard). So kannst du z.B. YouTube auf „Sonar - Media“ und YouTube Musik auf „Sonar - Aux“ legen und beide getrennt regeln. Nach „Speichern“ gilt die Auswahl sofort, auch für bereits geöffnete Seiten (kein Neuladen nötig).

Wichtig zu wissen:

• Windows zeigt weiterhin einen Eintrag „Playtube“. Chromium (QtWebEngine) spielt den Ton beider Tabs über einen gemeinsamen Audio-Prozess ab, deshalb kann Windows (auch „App-Lautstärke und Geräteeinstellungen“) die Tabs nicht einzeln benennen oder routen. Getrennt wird stattdessen über das Gerät - in Sonar & Co. also über den gewählten Kanal/das gewählte Gerät.
• Freigabe der Gerätenamen: Chromium blendet Gerätenamen aus, solange die Seite keine Mikrofon-Berechtigung hat. Damit die Seite das gewählte Gerät findet, erteilt Playtube YouTube/YouTube Musik diese Freigabe - nur, solange mindestens ein Tab ein eigenes Gerät nutzt, nur für diese beiden Seiten und nur für die laufende Sitzung (sie wird nicht gespeichert und bei jedem Start neu erteilt). Es wird nichts aufgenommen.
• Ist das gewählte Gerät gerade nicht angeschlossen, bleibt die Auswahl (als „nicht verfügbar“) gespeichert und der Ton läuft solange über den Systemstandard.
• Technik: playtube/audio_routing.py legt per HTMLMediaElement.setSinkId die Medienelemente der Seite auf das Gerät (Suche über den Gerätenamen). In der Konfiguration stehen die Namen unter audio.youtube_output und audio.music_output (leer = Systemstandard).

Fernsteuerung (Stream Dock)

Playtube lässt sich lokal fernsteuern, z.B. über das Stream-Dock-Plugin com.fojadrachi.playtube.sdPlugin (Ajazz/Mirabox AKP153E & Co.). Dafür lauscht Playtube auf einer Named Pipe (\\.\pipe\Playtube.Remote.Playtube, im Entwicklungsmodus ...PlaytubeDev). Es gibt keinen Netzwerk-Port, verbinden darf nur der angemeldete Benutzer.

• Protokoll: eine JSON-Nachricht pro Zeile, z.B. {"id":1,"cmd":"play_pause","target":"auto"}, Antwort {"id":1,"ok":true}. Details in playtube/remote_control.py.
• Befehle: status, show, switch_tab, play_pause, play, pause, next, previous, seek, volume_change, set_volume, mute_toggle, like, dislike, shuffle, repeat, list_playlists, play_playlist. Es gibt eine feste Whitelist; beliebiges JavaScript oder URLs lassen sich nicht senden.
• target: "auto" steuert den Tab, der gerade abspielt, sonst den sichtbaren.
• Abschalten: in config.json "remote_control": {"enabled": false}.
• Tests: .venv\Scripts\python -m unittest discover -s tests -v

App als eigenständige Playtube.exe packen

Für 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 ändern):

.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 überspringbar). Eine portable, nicht per Setup installierte .exe legt beim ersten Start automatisch eine Verknüpfung im Windows-Startmenü an - eine per Setup installierte Kopie hat den Eintrag bereits vom Installer.

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

Automatische Updates

Playtube prüft beim Start und danach alle updates.check_interval_hours Stunden (Standard 6, im Einstellungen-Tab oder in config.json einstellbar) die Releases auf dem eigenen Gitea-Server (nur Tags -edge). Im Einstellungen-Tab gibt es zusätzlich einen "Jetzt nach Updates suchen"-Button mit Status-Anzeige und Fortschrittsbalken für den Download. Gibt es eine neuere Version, fragt ein Dialog, ob sie installiert werden soll:

• Windows, per Setup installiert (siehe "Installation"): lädt bevorzugt das kleine Patch-Paket herunter (nur die Playtube.exe mit unserem Anwendungscode, ca. 2-3 MB) und überschreibt damit die Datei im Installationsordner - der riesige PySide6/ QtWebEngine-Laufzeitordner (_internal/) bleibt unangetastet, da er sich zwischen normalen Patch-Releases nicht ändert. 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): lädt den Setup-Installer und führt ihn still aus. Playtube liegt danach in der regulären Installation - Startmenü-Eintrag und Dateizuordnung zeigen dorthin, die alte portable Kopie ist nicht mehr nötig (und kann gelöscht werden). So entstehen nicht länger versionierte Ordner nebeneinander. Gibt es (bei älteren Releases) keinen Installer, wird wie früher das volle ZIP über den vorhandenen Ordner kopiert.
• Linux (Playtube-Binary): Patch-Paket (nur das Binary) bzw. volles .tar.gz. Die App startet sich in allen Fällen danach selbst neu.
• Entwicklungsmodus (python main.py): führt git pull + pip install -r requirements.txt aus und startet den Python-Prozess neu.

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

Nach einem erkannten Update wird beim nächsten Start automatisch der QtWebEngine- HTTP-Cache geleert (webprofile/cache) - alte Cache-Einträge können sonst nicht mehr zum neuen Code passen (frühere Ursache für fehlende Icons). Der Login bleibt davon unberührt, 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) lässt sich also einfach per Doppelklick installieren, ohne dass Playtube selbst etwas herunterladen muss.

Eine neue Version veröffentlichen

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 Gitea unter https://git.fojadrachi.de/Fojadrachi/Playtube). Für Playtube Edge trägt der Tag den Zusatz -edge (z. B. v1.0.1-edge). Der gepushte Tag löst automatisch die Gitea-Actions-Pipeline (.gitea/workflows/release.yml) aus, die Playtube Edge für Windows baut und als Vorabversion auf dem Gitea veröffentlicht - Fortschritt unter https://git.fojadrachi.de/Fojadrachi/Playtube/actions.

Releases bauen (einmalige Einrichtung)

GitHub wird nirgends mehr benutzt. Die Pipeline braucht:

1. Einen Gitea-Actions-Runner unter Windows (act_runner, Label windows, Host-Modus) mit Python 3.12, git, PowerShell und Inno Setup 6. Registrierung z. B.: act_runner register --instance https://git.fojadrachi.de --token <Runner-Token> --labels windows:host
2. Ein Secret RELEASE_TOKEN im Repo (Einstellungen → Actions → Secrets): ein Zugriffstoken (Gitea → Einstellungen → Anwendungen) mit Schreibrecht auf das Repo.
3. In Gitea Actions für das Repo aktivieren (Einstellungen → Erweitert → Repository-Einheiten).

Ohne Runner kannst du selbst bauen und veröffentlichen:

powershell -ExecutionPolicy Bypass -File packaging\build.ps1
$env:GITEA_TOKEN = "<Zugriffstoken>"
powershell -ExecutionPolicy Bypass -File packaging\publish_release.ps1 -Tag v1.0.1-edge -Prerelease `
    -Files dist\installer\PlaytubeEdge-Setup-v1.0.1.exe -NotesFile packaging\release_notes.md

Für Windows entstehen dabei drei Dateien: Playtube-Setup-vX.Y.Z.exe (Installer, für 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

Hinweis: Playtube Edge nutzt WebView2 und läuft nur unter Windows. Die Linux-Beschreibung unten gehört zur normalen Playtube (Branch main, QtWebEngine); für Edge entstehen keine Linux-Pakete.

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

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

Danach ist Playtube über das Anwendungsmenü 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 benötigt 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.

Hinweise

• "Dieser Browser ist unter Umständen 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 nächsten Prozessstart), notfalls einmal den Profilordner %APPDATA%\Playtube\webprofile (bzw. PlaytubeDev im Entwicklungsmodus) löschen und neu anmelden.
• Auf YouTube/YouTube Music fehlen alle Icons (Play/Pause, Suche, Menü ...): 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 ältere Version läuft unsichtbar weiter, während eine neu heruntergeladene zusätzlich gestartet wird. Abhilfe: alle Playtube-Instanzen über 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 ältere Instanz ohne diesen Schutz wird dabei nicht erkannt und muss einmalig manuell beendet werden.
• 4K/Premium-Videoqualität kann eingeschränkt sein, da die Open-Source-Variante von QtWebEngine kein Widevine-DRM mitbringt (Standard-Qualitäten 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.