hacker-podcast

Automatically fetches top stories from Hacker News API on a fixed daily schedule (23:30 UTC) using Cloudflare Workflows' cron trigger system. The scraper extracts article metadata (title, URL, score, comments) and stores raw content in Cloudflare KV for downstream processing. Uses exponential backoff retry logic built into the WorkflowEntrypoint pattern to handle transient failures without manual intervention.

Converts scraped Hacker News articles into Chinese-language podcast scripts using @ai-sdk/openai-compatible's generateText function with configurable LLM backends (OpenAI, Anthropic, or compatible APIs). The system generates structured dialogue between two hosts discussing each article, including summaries, key insights, and conversational transitions. Uses prompt engineering to enforce consistent speaker roles and Chinese language output, with fallback handling for API failures.

Implements a lightbox component for displaying and navigating episode cover art and related images using a modal overlay with keyboard navigation (arrow keys, Escape to close). Images are lazy-loaded from Cloudflare R2 CDN and displayed at full resolution with zoom and pan capabilities. The lightbox is triggered by clicking on episode cover art or related images and supports touch gestures on mobile (swipe to navigate).

Manages application configuration (API keys, provider selection, feature flags) through environment variables loaded from .env files and Cloudflare Workers secrets. Supports separate configurations for development (local), staging, and production environments without code changes. Configuration is validated at startup using TypeScript types, ensuring type safety and preventing runtime errors from missing or invalid settings. Implements fallback defaults for optional settings (e.g., TTS provider defaults to Edge TTS if not specified).

Converts podcast scripts into audio using pluggable TTS providers: Edge TTS (free, Microsoft-backed), Minimax HTTP API (Chinese-optimized), and Murf HTTP API (high-quality voices). Each provider is abstracted behind a common interface that accepts speaker-tagged script segments and returns per-speaker audio buffers. The system selects providers based on configuration and handles provider-specific audio format conversions (MP3, WAV, etc.) transparently.

Merges per-speaker audio segments into a single podcast episode using FFmpeg.js, a JavaScript port of FFmpeg compiled to WebAssembly. Runs entirely within the Cloudflare Worker browser runtime (no external FFmpeg binary required), concatenating speaker audio buffers with silence padding between segments and encoding the final output as MP3. Handles audio format normalization (sample rate, channels) and metadata embedding (ID3 tags with episode title, artist, date).

Stores generated podcast episodes in a two-tier storage system: Cloudflare KV holds episode metadata (title, date, summary, speaker names) as JSON documents with TTL-based expiration, while Cloudflare R2 (S3-compatible object storage) persists the final MP3 audio files with public CDN URLs. The system implements a caching layer in KV to avoid repeated metadata lookups and uses R2's built-in versioning for episode rollback. Metadata keys follow a date-based naming scheme (YYYY-MM-DD) for efficient pagination and retrieval.

Generates a standards-compliant RSS 2.0 feed with podcast-specific extensions (iTunes, Podtrac, Spotify) that enables distribution to Apple Podcasts, Spotify, YouTube, and 小宇宙 (Chinese podcast platform). The feed is dynamically generated from KV metadata on each request, including episode title, description, audio URL, publication date, and cover art. Implements caching headers (ETag, Cache-Control) to reduce regeneration overhead and uses RSS validation to ensure compatibility with podcast aggregators.

Renders a paginated homepage displaying podcast episodes in reverse chronological order (newest first) using Next.js App Router and React 19 components. Fetches episode metadata from Cloudflare KV in batches (e.g., 10 episodes per page) and implements client-side pagination controls with URL-based state (query parameters for page number). Each episode card displays title, publication date, summary, speaker names, and a link to the full episode page. Uses Tailwind CSS 4 and shadcn/ui components for responsive design.

Renders a dedicated page for each podcast episode (route: /episode/[date]) displaying full episode metadata (title, publication date, summary, speaker names), an embedded audio player powered by @vidstack/react, and related content links (original Hacker News articles, speaker bios). The page is server-side rendered using Next.js dynamic routes with date-based parameters, fetching episode data from Cloudflare KV and audio URL from R2. Implements Open Graph metadata for social sharing and structured data (JSON-LD) for search engine indexing.

Implements a HackerNewsWorkflow class extending Cloudflare Workflows' WorkflowEntrypoint, orchestrating the entire content pipeline (scrape → summarize → TTS → merge → store) as a sequence of steps with built-in error handling. Each step is idempotent and can be retried independently with exponential backoff (1s, 2s, 4s, 8s, etc.). Workflow state is persisted in Cloudflare Durable Objects, enabling recovery from transient failures without restarting the entire pipeline. Implements structured logging at each step for debugging and monitoring.

Builds a modern podcast web interface using React 19, Tailwind CSS 4, and shadcn/ui components with support for light/dark theme switching (stored in localStorage), multi-language support (English and Chinese via i18n configuration), and a command menu (Cmd+K) for quick navigation. The UI is fully responsive, adapting to mobile, tablet, and desktop viewports. Uses Next.js App Router for server-side rendering and client-side hydration, with Cloudflare Workers as the edge runtime.