PigeonPod

Listen to YouTube. Anywhere.

If self-hosting isn't your thing, take a look at our upcoming online services: PigeonPod

Screenshots

Channel list

Channel detail

Core Features

• 🎯 Smart Subscription & Preview: Paste any YouTube channel or playlist URL, auto-detect its type, and preview feed details before subscribing.
• 🤖 Auto Sync & History Backfill: Periodically sync new uploads in the background, with configurable initial episodes and one-click backfill of historical videos.
• 📻 Secure RSS for Any Client: Generate standard, API-key-protected RSS links for channels and playlists that work in all podcast apps.
• 🔍 Per-feed Filters & Retention: Filter episodes by title/description keywords (include/exclude), minimum duration, and set per-feed sync and maximum episode limits.
• 📊 Download Dashboard & Bulk Actions: Real-time dashboard for pending/downloading/completed/failed tasks, with detailed error logs and one-click bulk cancel/delete/retry.
• 🧩 Episode Management & Control: Infinite-scrolling episode list with manual download, retry, cancel and delete actions that also manage downloaded files.
• 🎦 Flexible Audio/Video Output: Choose audio-only (AAC) or full video downloads with quality presets or selectable resolution/encoding, plus embedded metadata, chapters and artwork.
• 🍪 Restricted Content Support: Use YouTube Data API keys and uploaded cookies to access age-restricted and members-only content more reliably.
• 🎛 Customizable Feeds & Player: Set per-feed custom title and cover art, and use the built-in web player for quick audio/video playback.
• 🌐 Multilingual Responsive UI: Fully localized interface (English, Chinese, Spanish, Portuguese, Japanese, French, German, Korean) with a responsive layout across devices.

Deployment

Using Docker Compose (Recommended)

Make sure you have Docker and Docker Compose installed on your machine.

1. Use the docker-compose configuration file, modify environment variables according to your needs

version: '3.9'
services:
  pigeon-pod:
    image: 'ghcr.io/aizhimou/pigeon-pod:latest'
    restart: unless-stopped
    container_name: pigeon-pod
    ports:
      - '8834:8080'
    environment:
      - 'PIGEON_BASE_URL=https://pigeonpod.cloud' # set to your domain
      - 'PIGEON_AUDIO_FILE_PATH=/data/audio/' # set to your audio file path
      - 'PIGEON_COVER_FILE_PATH=/data/cover/' # set to your cover file path
      - 'SPRING_DATASOURCE_URL=jdbc:sqlite:/data/pigeon-pod.db' # set to your database path
    volumes:
      - data:/data

volumes:
  data:

2. Start the service

docker-compose up -d

3. Access the application Open your browser and visit http://localhost:8834 with default username: root and default password: Root@123

Run with JAR

Make sure you have Java 17+ and yt-dlp installed on your machine.

1. Download the latest release JAR from Releases

2. Create data directory in the same directory as the JAR file.

mkdir -p data

3. Run the application

java -jar -DPIGEON_BASE_URL=http://localhost:8080 \  # set to your domain
           -DPIGEON_AUDIO_FILE_PATH=/path/to/your/audio/ \  # set to your audio file path
           -Dspring.datasource.url=jdbc:sqlite:/path/to/your/pigeon-pod.db \  # set to your database path
           pigeon-pod-x.x.x.jar

4. Access the application Open your browser and visit http://localhost:8080 with default username: root and default password: Root@123

Documentation

• How to get YouTube API Key
• How to setup YouTube Cookies
• How to get YouTube channel ID

Tech Stack

Backend

• Java 17 - Core language
• Spring Boot 3.5 - Application framework
• MyBatis-Plus 3.5 - ORM framework
• Sa-Token - Authentication framework
• SQLite - Lightweight database
• Flyway - Database migration tool
• YouTube Data API v3 - YouTube data retrieval
• yt-dlp - Video download tool
• Rome - RSS generation library

Frontend

• Javascript (ES2024) - Core language
• React 19 - Application framework
• Vite 7 - Build tool
• Mantine 8 - UI component library
• i18next - Internationalization support
• Axios - HTTP client

Development Guide

Environment Requirements

• Java 17+
• Node.js 22+
• Maven 3.9+
• SQLite
• yt-dlp

Local Development

1. Clone the project

git clone https://github.com/aizhimou/PigeonPod.git
cd PigeonPod

2. Configure database

# Create data directory
mkdir -p data/audio

# Database file will be created automatically on first startup

3. Configure YouTube API

   • Create a project in Google Cloud Console
   • Enable YouTube Data API v3
   • Create an API key
   • Configure the API key in user settings

4. Start backend

cd backend
mvn spring-boot:run

5. Start frontend (new terminal)

cd frontend
npm install
npm run dev

6. Access the application

• Frontend dev server: http://localhost:5173
• Backend API: http://localhost:8080

Development Notes

1. Ensure yt-dlp is installed and available in command line
2. Configure correct YouTube API key
3. Ensure audio storage directory has sufficient disk space
4. Regularly clean up old audio files to save space

Star History

Made with ❤️ for podcast enthusiasts!

⭐ If you like PigeonPod, give us a star on GitHub!