jaandrle/commafeed-podcasts
1
0
Fork 0
Code Issues Pull Requests Releases Activity

🎉

Browse Source
This commit is contained in:
Jan Andrle
2026-04-24 14:03:17 +02:00
commit 0191347312
31 changed files with 16354 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
changelog/PLAN.md
+189
View File
@@ -0,0 +1,189 @@
# CommaFeed Podcasts PWA Implementation Plan
## Overview
This plan outlines the implementation of a Progressive Web App (PWA) for managing and listening to podcasts using CommaFeed as the backend. The app will be built with Lit, providing a seamless experience for users to manage their podcast subscriptions, create playlists, and listen to episodes offline.
## Key Features
1. **User Authentication**: Securely store CommaFeed instance details, username, and password in the browser.
2. **Category Management**: Allow users to specify a category for storing podcast feeds.
3. **Playlist Management**: Use the "starred" category as a "to be listened" playlist.
4. **Offline Listening**: Download audio files for offline playback.
5. **Android Auto Integration**: Basic Bluetooth integration for media control.
## Implementation Steps
### 1. Setup and Configuration
- **Lit Project Setup**: Initialize a new Lit project with Lit or Open Web Components.
- **PWA Configuration**: Set up the PWA manifest and service worker.
- **State Management**: Implement @lit-labs/signals (Lit Labs) for state management.
- **Routing**: Set up @lit-labs/router (Lit Labs)
- **Service Worker**: Configure service worker to cache API requests and enable offline functionality.
### 2. User Authentication
- **Login Form**: Create a form to collect CommaFeed instance URL, username, and password.
- **Secure Storage**: Use the browser's Credential Management API (`navigator.credentials`) to securely store and retrieve credentials. This provides a more secure and user-friendly way to manage credentials compared to localStorage or sessionStorage.
- **API Integration**: Implement API calls to authenticate with the CommaFeed instance using Basic Auth. The authentication logic involves constructing an Authorization header using modern `TextEncoder` API with a fallback to `btoa` for broader compatibility. The implementation is as follows:
```javascript
const credentials = `${username}:${password}`;
const Authorization = `Basic ${toBase64(credentials)}`;
const headers = {
Authorization,
Accept: "application/json"
};
function toBase64(data) {
const existsTextEncoder= typeof TextEncoder !== 'undefined';
if (!existsTextEncoder)
return btoa(data);
const existsUint8ArrayToBase64= typeof Uint8Array.prototype.toBase64 === 'function';
if (existsUint8ArrayToBase64)
return new TextEncoder().encode(data).toBase64();
const binString= Array.from(new TextEncoder().encode(data))
.map(x=> String.fromCharCode(x)).join("");
return btoa(binString);
}
```
### 3. Category Management
- **Category Selection**: Allow users to select or create a category for storing podcast feeds.
- **API Integration**: Use CommaFeed API to fetch and manage categories.
### 4. Podcast Management
- **Feed Subscription**: Implement functionality to subscribe to podcast feeds.
- **Episode Listing**: Fetch and display episodes from subscribed feeds.
- **Filtering**: Filter episodes based on enclosure URL and type to identify podcasts.
#### Custom OPML import/export
CommaFeed API supports OPML import and export, but not category scoped. So we need to re-implement by ourself,
meaning reading/writing OPML files and using (un)subscribe API calls to manage subscriptions.
### 5. Playlist Management
- **Starred Category**: Use the "starred" category as a "to be listened" playlist.
- **Playlist Creation**: Allow users to create custom playlists using tags with a special naming convention (`playlist-name`).
- **Episode Management**: Add and remove episodes from playlists by managing tags.
- **Playback Tracking**: Use a special tag convention (`playing-timestamp`) to track the currently playing episode and its timestamp.
### 6. Offline Listening
- **Audio Download**: Implement functionality to download audio files for offline playback.
- **Auto download**: Automatically download audio files for when the use setup for wich playlist or “listen later” (`starred`) user setup in the config (page)
- **PWA Caching**: Use service worker to cache API requests and audio files for offline access.
### 7. Android Auto Integration
- **Media Session API**: Implement Media Session API for basic Bluetooth integration.
- **Media Control**: Ensure play/pause and skip functionality works through Bluetooth.
### 8. Docker Compose Setup
- **Configuration**: Research CommaFeed's official Docker setup for user provisioning and configure `docker-compose.yml` to set `COMMAFEED_HOST` environment variable.
- ideally there should be two options:
1. “all in one” with fixed commafeed instance (configured in the docker-compose.yml)
2. only frontend
- **PWA Application**: Set up Nginx to serve the PWA static files.
## UI considerations
- [All elements | Red Hat design system](https://ux.redhat.com/elements/) with web components:
- Audio player
- Alert
- Button, Call to action (link)
- Chip (Filter information or indicate that a selection was made)
- Dialog
- Scheme toggle
- Skip link
- Spinner
- Switch
- Tabs
- Tag
- Timestamp
- Video embed
- [Components | Web Awesome](https://webawesome.com/docs/components): I can use PRO web components
- Button, Button Group
- Dropdown
- Badge
- Callout
- Spinner
- Tag
- Toast
- inputs: Radio Group
- Icon
- Tab, Tab Group
- Format Bytes
- Format Date
- Format Number
- Include (Includes give you the power to embed external HTML files into the page.)
- Relative Time
## API Endpoints
See [./docs/CommaFeed API.md](./docs/CommaFeed API.md).
### Authentication
- **Basic Auth**: Use Basic Auth for authentication. The Authorization header is constructed using modern `TextEncoder` API with a fallback to `btoa` for broader compatibility.
### Categories
- `GET /rest/category/get`: Fetch all categories listed under the `children` key.
- `POST /rest/category/add`: Add a new category.
- `POST /rest/category/modify`: Modify an existing category.
- `POST /rest/category/delete`: Delete a category.
### Feeds
- `GET /rest/feed/get/{id}`: Get feed details.
- `POST /rest/feed/subscribe`: Subscribe to a feed.
- `POST /rest/feed/unsubscribe`: Unsubscribe from a feed.
- `GET /rest/feed/entries`: Get feed entries aka episodes for podcast app.
### Entries
- `GET /rest/entry/tags`: Get list of tags for the user.
- `POST /rest/entry/star`: Mark an entry as (un)starred.
- `POST /rest/entry/mark`: Mark an entry as read/unread.
### Playlist Management
- `GET /rest/category/entries?id=starred`: Get starred entries.
- `POST /rest/entry/star`: Star or unstar an entry.
- `GET /rest/entry/tags`: Get list of tags for the user.
- `POST /rest/entry/tag`: Add or remove tags from an entry.
- Use tags for playlist management (`playlist-name`).
- **Playback Tracking**: Use tags to track the currently playing episode and its timestamp (`playing-timestamp`).
## Data Storage
### Browser Storage
- **Credential Storage**: Use encryption to securely store credentials in the browser.
- **PWA** offline practices (cache)
- store audio(/video?) files
## Security Considerations
- **Credential Storage**: Use encryption to securely store credentials in the browser.
- **API Security**: Ensure all API calls are authenticated and use HTTPS.
- **Data Protection**: Protect user data and ensure compliance with privacy regulations.
## Testing
- **Unit Testing**: Write unit tests for components and utilities.
- **Integration Testing**: Test API integrations and data flow.
- **End-to-End Testing**: Test user flows and PWA functionality.
## Deployment
- **Docker Compose**: Use Docker Compose to deploy the application.
- verion “all in one”: use commafeed visible only to the web interface part, asking for host can be removed, needs to read commafeed docker setup docs (how to set up user automatically, probably via config)
- only frontend
- **CI/CD Pipeline**: Set up a CI/CD pipeline for automated testing and deployment.
## Timeline
- **Week 1-2**: Setup and Configuration
- **Week 3-4**: User Authentication and Category Management
- **Week 5-6**: Podcast Management and Playlist Management
- **Week 7-8**: Offline Listening and Android Auto Integration
- **Week 9-10**: Testing and Deployment
## Resources
- [Getting Started – Lit](https://lit.dev/docs/getting-started/)
- [Lit Labs – Lit](https://lit.dev/docs/libraries/labs/)
- [**Development: Generator: Open Web Components**](https://open-wc.org/docs/development/generator/)
- [CommaFeed API Documentation](https://www.commafeed.com/api-documentation/)
- [PWA Guide](https://web.dev/progressive-web-apps/)
- [Media Session API](https://developer.mozilla.org/en-US/docs/Web/API/MediaSession)
- [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
- [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API)
- [nudeps/nudeps: The DX of a bundler without the complexity of one. Experimentally soft-launched, try it and give us feedback!](https://github.com/nudeps/nudeps)
## Notes
- Ensure compatibility with different browsers and devices.
- Focus on user experience and accessibility.
- Regularly update dependencies and ensure security patches are applied.
changelog/TASK.md
+130
View File
@@ -0,0 +1,130 @@
---
created: 2026-03-28T14:24:51 (UTC +01:00)
tags: []
source: https://gemini.google.com/
author:
---
# Google Gemini
## Excerpt
> Ahoj, zvažuji, že bych naprogramoval PWA aplikaci pro podcasty, jako backend
> by sloužila (self-hodsted) instance commafeed (
> <https://www.commafeed.com/api-documentation/>) … hlavní věc, která mi u
> konkurečních řešení (kromně youtube music) chybí je vytváření playlistů,
> zároveň bych chtěl aby šlo na konkrétním zařízení zvolit automatické stahování
> audia pro daný playlist (pro offline poslech), chtěl bych aby aplikace šla
> používat i přes android auto … celé řešení by mělo být jednoduše nasazovatelné
> přes docker compose
- - -
Ahoj! To zní jako naprosto skvělý projekt. Spojit self-hosted RSS čtečku s
podcastovou aplikací dává obrovský smysl – podcasty jsou totiž v jádru jen RSS
feedy s audio přílohami (`\<enclosure>`). CommaFeed je na tohle super, protože
už za tebe řeší parsování feedů a synchronizaci přečtených/nepřečtených položek.
Pojďme si rozebrat, jak to postavit, kde jsou největší výzvy (hlavně to Android
Auto) a jak by mohl vypadat Docker Compose.
- - -
## 🛠️ Architektura a technologie
### 1\. Backend: CommaFeed
CommaFeed API ti poskytne všechno, co potřebuješ:
- Seznam odebíraných podcastů (feedy).
- Seznam epizod (záznamy ve feedu).
- Přílohy (URL na `.mp3` nebo `.m4a` soubory).
- Označení epizody jako "přehrané" (read/unread status).
### 2\. Frontend: PWA (React / Vue / Svelte)
Pro uložení audia pro offline poslech v PWA se používá kombinace dvou věcí v
prohlížeči:
- **IndexedDB:** Pro ukládání metadat (názvy playlistů, pozice v přehrávání,
seznam epizod).
- **Cache API:** Pro ukládání samotných velkých audio souborů (blobů).
> 💡 **Tip:** Pro stahování velkých souborů na pozadí (i když aplikaci zavřeš) se
> podívej na **Background Fetch API**. Pro správu Service Workera doporučuji
> knihovnu **Workbox** od Googlu, ušetří ti spoustu vrásek.
- - -
## 🚗 Ta záludná část: Android Auto
Tady tě musím jako parťák trochu varovat. **Čistá PWA v prohlížeči neumí nativně
vykreslit UI na obrazovce Android Auto.** Android Auto vyžaduje nativní integraci
přes Android Media3 knihovny. Máš ale tři možnosti, jak to vyřešit:
1. **Základní Bluetooth (Nejjednodušší):** V PWA implementuješ standardní `
Media Session API`. Auto sice neotevře speciální aplikaci na palubovce, ale
přes Bluetooth uvidíš název skladby, obal a bude fungovat tlačítko
pauza/přeskočit na volantu.
2. **TWA / Capacitor obal (Pokročilé):** Zabalíš PWA do Android balíčku (přes
Bubblewrap nebo Capacitor). To ti umožní přidat do aplikace kousek
nativního Kotlin/Java kódu, který se zaregistruje do Android Auto jako
přehrávač a bude komunikovat s tvou PWA.
3. **Využití prohlížeče v autě:** Novější auta s Android Automotive (AAOS) mají
Vivaldi nebo Chrome přímo v autě, kde by tvoje PWA běžela samostatně.
- - -
## 🐳 Docker Compose (vše v jednom)
Aby se to dalo nasadit jedním příkazem, můžeme propojit CommaFeed, jeho
databázi a tvou novou PWA aplikaci do jednoho souboru.
```
version: '3.8'
services:
# 1. Databáze pro CommaFeed
commafeed-db:
image: postgres:15-alpine
environment:
POSTGRES_DB: commafeed
POSTGRES_USER: commafeed
POSTGRES_PASSWORD: secret_password
volumes:
- cf-db-data:/var/lib/postgresql/data
restart: unless-stopped
# 2. CommaFeed Backend
commafeed:
image: athou/commafeed:latest
ports:
- "8082:8082"
environment:
- SPRING_DATASOURCE_URL=jdbc:postgresql://commafeed-db:5432/commafeed
- SPRING_DATASOURCE_USERNAME=commafeed
- SPRING_DATASOURCE_PASSWORD=secret_password
depends_on:
- commafeed-db
volumes:
- cf-config:/commafeed/config
restart: unless-stopped
# 3. Tvoje nová PWA aplikace (Nginx servírující statické soubory)
pwa-podcast-app:
image: nginx:alpine # Nebo tvůj vlastní build image
ports:
- "8080:80"
volumes:
- ./pwa-dist:/usr/share/nginx/html # Složka s tvou zbuilzenou PWA
restart: unless-stopped
volumes:
cf-db-data:
cf-config:
```
- - -
## ✨ Co dál?
Tenhle nápad má obrovský potenciál – chybějící playlisty štvou spoustu lidí a
self-hosted komunita takové věci miluje.
Kterou část bys chtěl rozlousknout jako první? **Můžeme se podívat na to, jak
přesně strukturovat ukládání audio souborů do Cache API v Service Workeru, nebo
jak namodelovat databázi pro ty playlisty?**