jaandrle/commafeed-podcasts

Fork 0

Files

T

jaandrle 0191347312

🎉

2026-04-24 14:03:17 +02:00

9.0 KiB

Raw Permalink Blame History

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

User Authentication: Securely store CommaFeed instance details, username, and password in the browser.
Category Management: Allow users to specify a category for storing podcast feeds.
Playlist Management: Use the "starred" category as a "to be listened" playlist.
Offline Listening: Download audio files for offline playback.
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:

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 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: 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.

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

Notes

Ensure compatibility with different browsers and devices.
Focus on user experience and accessibility.
Regularly update dependencies and ensure security patches are applied.

9.0 KiB Raw Permalink Blame History Unescape Escape