podfetch

The Podcast Transcript support feature enables PodFetch to parse <podcast:transcript> tags, archive transcript files, display transcripts in the player, enable full-text search, and generate missing transcripts using an OpenAI-compatible Whisper API.

Architecture Model

The implementation follows a hybrid storage approach: original files are archived, while normalized segments are stored in the database. It utilizes native database full-text search (SQLite FTS5 or Postgres tsvector) and a database-backed job queue with a Tokio worker for Whisper processing.

All components follow the established pattern:

1. Trait definition: in podfetch-domain
2. Diesel Repository: in podfetch-persistence (with adapters in adapters.rs)
3. Service layer: in podfetch-web/src/services/
4. Controller layer
5. React UI

Podfetch is a self-hosted podcast manager designed for downloading and listening to podcasts online.

Key features include:

• GPodder Integration: Allows users to sync and continue using their existing podcast applications.
• Podcasting 2.0 Support: Provides full-text search across episode transcripts.
• Transcript Generation: Can generate missing transcripts using any OpenAI-compatible Whisper API.
• Tech Stack: Built with Rust (backend) and React (frontend).

The podfetch-ui package provides the user interface for the Podfetch ecosystem. It is designed to allow users to interact with podcast content through a web-based or client-side interface.

Key features include:

• Search and download podcasts: Users can discover new content and initiate downloads.
• Listen to podcasts: Integrated playback capabilities for consuming podcast audio.

The Podfetch interface is organized into several primary views:

• Home Screen: The main landing area to access episodes and continue listening.
• Timeline View: A view for managing or viewing episode timelines.
• Info View: Detailed information pages for podcasts or episodes.
• Settings: Configuration for user preferences.
• Administration: Administrative controls and management interfaces.

PodFetch manages multiple transcript variants (e.g., JSON, VTT, SRT, HTML) per episode. It uses a preference system to decide which one to display and index. The is_preferred flag is recalculated whenever transcripts change.

Preference Rules:

1. Status Check: Only variants with status='parsed' are eligible. Non-parseable feed transcripts do not block the display or the Whisper fallback.
2. Source Priority: feed (from RSS) always takes precedence over generated (via Whisper).
3. Format Priority: Within the same source, the order is: JSON > VTT > SRT > HTML/Text.
4. Language Match: If formats are equal, the variant matching the podcast's language is chosen.
5. Fallback: If a new parseable feed transcript is discovered during a refresh, the preference switches from generated to the feed version, and segments are rebuilt accordingly.

The implementation of podcast transcript features relies on the following technology stack:

• Backend: Rust (Axum, Diesel sync, Tokio)
• HTTP Client: reqwest (requires the multipart feature enabled)
• Frontend: React 19, TypeScript, TanStack Query, Zustand
• Real-time: socketioxide
• Parsing: Custom-written VTT/SRT parsers (approximately 50 lines each) instead of external crates to ensure reliability and maintainability for these specific formats.

When a user has no stored SponsorBlock settings, the system applies the following default configuration:

• enabled: true
• skip_sponsor: true
• skip_selfpromo: true
• skip_interaction: false
• skip_intro: false
• skip_outro: false
• skip_preview: false
• skip_filler: false
• skip_music_offtopic: false

Chromecast devices are categorized by their visibility and ownership:

• chromecast_personal: Visible only to the user who owns them. Devices reported by an agent default to this type, owned by the user whose API key was used to authenticate the agent.
• chromecast_shared: Household devices visible to every user on the PodFetch instance. These are created when an admin promotes a personal device to shared status.

Session Ownership: When casting, you can select from your personal devices or any shared devices. Active sessions are owned by the user who initiated them. Only the owner can perform actions like pause, stop, or seek. If a different user starts a session on the same device, the previous session is implicitly stopped.

To ensure reliable E2E tests, the following patterns are used:

• Web-First Assertions: Avoid fixed sleep calls. Use Playwright's polling assertions like expect(...).toBeVisible() to handle asynchronous UI updates.
• Isolation: Use a fresh SQLite database in a temporary directory for every run to prevent cross-run state contamination.
• Network Binding: All mock servers are configured to bind strictly to 127.0.0.1.
• Authentication: The instance is configured to run without auth. If the UI requires a login, the global setup performs a single minimal login step and stores the resulting storage state for subsequent tests.