PigeonPod

Listen to YouTube. Anywhere.

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

• 🎯 Smart Subscription: Quickly add and sync YouTube channels or playlists with one click.
• 🤖 Auto Sync Updates: Automatically check and sync latest channel content with incremental updates.
• 📻 RSS Podcast Subscription: Generate standard RSS subscription links, compatible with any podcast client.
• 🔍 Content Filtering: Support filtering by title and description keywords (include/exclude) and episode duration.
• 📊 Episode Management: View, delete, and retry failed episode downloads.
• 🎦 Video Support: Download video episodes with selectable resolutions and encodings; watch in podcast clients that support video.
• 🎚 Audio Quality Controls: Choose between 0–10 quality levels or keep the original track to balance fidelity and size.
• 💽 Chapters & Metadata: Automatically writes metadata and chapter markers to files for a better listening experience.
• ✨ Ad-free Listening: Automatically remove intro and mid-roll ads from episodes.
• 🍪 Custom Cookies: Supports subscription of age-restricted content and membership content by uploading cookies.
• 🌐 Multi-language Support: Complete support for English, Chinese, Spanish, Portuguese, Japanese, French, German, Korean interfaces.
• 📱 Responsive UI: Excellent experience on any device, anytime, anywhere.

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

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

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

• 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

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

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

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

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