feat: add KDE Plasma podcast plasmoid

2026-09-05 18:03:44 +02:00
commit 646033e16f
13 changed files with 1030 additions and 0 deletions
@@ -0,0 +1,82 @@
+# Il Post Podcasts — plasmoide KDE Plasma 6
+
+Plasmoide standalone per KDE Plasma 6 che visualizza gli episodi più recenti dei podcast de Il Post, mette i programmi preferiti in cima e permette di riprodurre gli episodi con un player KDE compatibile con MPRIS.
+
+> **Progetto derivato, non libreria upstream.** Questo repository **non è** il repository upstream originale clonato e non pretende di essere una nuova versione della libreria `thekoma/ilpostapi`. È un progetto separato, con scopo, struttura, UI e ciclo di rilascio propri, che integra e utilizza gli endpoint/API individuati nel progetto upstream.
+
+## Relazione con upstream
+
+- **Upstream di riferimento:** [`thekoma/ilpostapi`](https://github.com/thekoma/ilpostapi)
+- **Questo progetto:** [`enne2/ilpost-podcasts-plasmoid`](https://git.enne2.net/enne2/ilpost-podcasts-plasmoid)
+- Il repository upstream resta la sorgente di riferimento per gli endpoint non ufficiali de Il Post; questo plasmoide ne riusa il modello API senza incorporare il backend web upstream.
+- Gli aggiornamenti upstream non vengono importati automaticamente: vanno valutati e integrati manualmente quando cambiano endpoint o formato delle risposte.
+- Il client usa gli endpoint non ufficiali autenticati de Il Post (`/user/v1/auth/login` e `/podcast/v1/podcast`). Usarlo solo con un account autorizzato e nel rispetto dei Termini di servizio.
+
+## Funzionalità
+
+- Elenco degli episodi più recenti dei programmi disponibili.
+- Programmi preferiti selezionabili dalle impostazioni Plasma e mostrati con priorità.
+- Copertine asincrone con cache e icona di fallback se l'artwork non è disponibile.
+- Login dal widget; username, password e token vengono conservati in KWallet tramite `kwallet-query`, non in KConfig o nei file del progetto.
+- Riproduzione con Dragon Player, player KDE che espone MPRIS (`org.mpris.MediaPlayer2.dragonplayer`), con fallback al player predefinito tramite `xdg-open`.
+- Aggiornamento periodico configurabile e filtro “solo preferiti”.
+
+## Struttura
+
+```text
+package/
+  metadata.json
+  contents/config/       # impostazioni Plasma 6
+  contents/ui/            # interfaccia QML e catalogo programmi
+  contents/lib/           # plugin QML compilato durante la build
+src/                     # client API/KWallet e plugin QML C++
+CMakeLists.txt
+```
+
+Il codice è volutamente standalone: `package/` è il pacchetto Plasma, mentre `src/` contiene il bridge C++ per rete, autenticazione, KWallet e avvio del player.
+
+## Compilazione e installazione locale
+
+Dipendenze: Qt 6 Core/Network/Qml, `kwallet-query`, `kpackagetool6` e Dragon Player (oppure un handler audio compatibile).
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+cmake --build build --target install-plasmoid
+```
+
+Per una prima installazione:
+
+```bash
+kpackagetool6 -t Plasma/Applet -i package
+```
+
+Test rapido:
+
+```bash
+plasmawindowed org.enne2.ilpost.podcasts
+```
+
+Dopo l'installazione, aggiungere **Podcast de Il Post** al desktop e aprire **Configura** per scegliere preferiti, quantità e intervallo di aggiornamento. Le credenziali vanno inserite nei campi del widget, non nella shell o nei file Git.
+
+## Sviluppo upstream
+
+Il repository upstream può essere registrato come remoto di sola lettura:
+
+```bash
+git remote add upstream https://github.com/thekoma/ilpostapi.git
+git fetch upstream --prune
+```
+
+`origin` deve rimanere il repository Gitea del plasmoide. Prima di integrare modifiche upstream, verificare manualmente endpoint, autenticazione, campi JSON e Termini di servizio.
+
+## Sicurezza e limiti
+
+- Non committare credenziali, token, file `.env` o dump delle risposte API.
+- KWallet deve essere disponibile nella sessione KDE; se non lo è, il login non può salvare i segreti.
+- Le API usate non sono un contratto pubblico stabile e possono cambiare senza preavviso.
+- L'audio e le copertine possono mancare per alcuni episodi o dipendere dai permessi dell'account.
+
+## Licenza
+
+Il codice del plasmoide è distribuito con licenza GPL-3.0-or-later, come indicato nei metadati del pacchetto. L'attribuzione all'upstream resta esplicita sopra; verificare sempre gli obblighi applicabili prima di redistribuire o modificare il progetto.