https://github.com/aizhimou/pigeon-pod
Listen to YouTube. Anywhere.
https://github.com/aizhimou/pigeon-pod
listenbox mantine-v8 podcast podsync react self-hosted springboot3 youtube
Last synced: 10 days ago
JSON representation
Listen to YouTube. Anywhere.
- Host: GitHub
- URL: https://github.com/aizhimou/pigeon-pod
- Owner: aizhimou
- License: gpl-3.0
- Created: 2025-08-23T05:28:12.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-11-23T02:01:19.000Z (3 months ago)
- Last Synced: 2025-11-23T04:04:13.132Z (3 months ago)
- Topics: listenbox, mantine-v8, podcast, podsync, react, self-hosted, springboot3, youtube
- Language: Java
- Homepage: https://pigeonpod.cloud
- Size: 19.8 MB
- Stars: 588
- Watchers: 1
- Forks: 53
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
PigeonPod
Listen to YouTube & Bilibili. Anywhere.
If self-hosting isn't your thing, take a look at our upcoming online services:
PigeonPod
[](documents/readme/README-ZH.md) [](documents/readme/README-ES.md) [](documents/readme/README-PT.md) [](documents/readme/README-JA.md) [](documents/readme/README-DE.md) [](documents/readme/README-FR.md) [](documents/readme/README-KO.md)
## Screenshots
Channel list
Channel detail
## Core Features
- **🎯 Smart Subscription & Preview**: Paste any YouTube or Bilibili channel/playlist URL, auto-detect its type, and preview feed details before subscribing.
- **📻 Secure RSS for Any Client**: Generate standard, API-key-protected RSS links for channels and playlists that work in all podcast apps.
- **🤖 Auto Sync & History Backfill**: Periodically sync new uploads in the background, with configurable initial episodes and one-click backfill of historical videos.
- **🎦 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.
- **📦 Historical Episodes Batch Download**: Designed specifically for efficient back-catalog downloads, with search, pagination, per-item or per-page selection, and one-click submission.
- **📊 Download Dashboard & Bulk Actions**: Real-time dashboard for pending/downloading/completed/failed tasks, with detailed error logs and one-click bulk cancel/delete/retry.
- **🔍 Per-feed Filters & Retention**: Filter episodes by title/description keywords (include/exclude), minimum duration, and set per-feed sync and maximum episode limits.
- **⏱ Delayed Auto Download for New Episodes**: Configure per-feed auto-download delay windows to improve `--sponsorblock` success rates on newly published videos.
- **📈 YouTube API Usage Insights**: Monitor API quota usage and limits to plan sync jobs and avoid unexpected interruptions.
- **🎛 Customizable Feeds & Player**: Set per-feed custom title and cover art, and use the built-in web player for quick audio/video playback.
- **🔄 OPML Subscription Export**: Export all subscriptions as a standard OPML file for smooth migration between podcast clients.
- **🧩 Episode Management & Control**: Infinite-scrolling episode list with manual download, retry, cancel and delete actions that also manage downloaded files.
- **⬆️ In-app yt-dlp Updates**: Upgrade the built-in yt-dlp runtime with one click to keep extraction and download compatibility current.
- **🛠 Advanced yt-dlp Arguments**: Add custom yt-dlp arguments with standard syntax to fine-tune download behavior for advanced use cases.
- **🌐 Multilingual Responsive UI**: Fully localized interface (English, Chinese, Spanish, Portuguese, Japanese, French, German, Korean) with a responsive layout across devices.
- **📚 Podcasting 2.0 Chapters Support**: Generate standard `chapters.json` chapter files so more podcast clients can display rich episode chapter navigation.
## 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
```yml
version: '3.9'
services:
pigeon-pod:
image: 'ghcr.io/aizhimou/pigeon-pod:latest'
restart: unless-stopped
container_name: pigeon-pod
ports:
- '8834:8080'
environment:
- SPRING_DATASOURCE_URL=jdbc:sqlite:/data/pigeon-pod.db # set to your database path
volumes:
- data:/data
volumes:
data:
```
2. Start the service
```bash
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](https://github.com/aizhimou/pigeon-pod/releases)
2. Create data directory in the same directory as the JAR file.
```bash
mkdir -p data
```
3. Run the application
```bash
java -jar -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`**
## Storage Configuration
- PigeonPod supports `LOCAL` and `S3` storage modes.
- You can only enable one mode at a time.
- S3 mode supports MinIO, Cloudflare R2, AWS S3, and other S3-compatible services.
- Switching storage mode does not migrate historical media automatically. You must migrate files manually.
### Storage Quick Comparison
| Mode | Pros | Cons |
| --- | --- | --- |
| `LOCAL` | Easy setup, no external dependency | Uses local disk, harder to scale |
| `S3` | Better scalability, suitable for cloud deployment | Requires object storage setup and credentials |
## Documentation
- [How to get YouTube API Key](documents/how-to-get-youtube-api-key/how-to-get-youtube-api-key-en.md)
- [How to setup YouTube Cookies](documents/youtube-cookie-setup/youtube-cookie-setup-en.md)
- [How to get YouTube channel ID](documents/how-to-get-youtube-channel-id/how-to-get-youtube-channel-id-en.md)
## 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
```bash
git clone https://github.com/aizhimou/PigeonPod.git
cd PigeonPod
```
2. Configure database
```bash
# 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](https://console.cloud.google.com/)
- Enable YouTube Data API v3
- Create an API key
- Configure the API key in user settings
4. Start backend
```bash
cd backend
mvn spring-boot:run
```
5. Start frontend (new terminal)
```bash
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
[](https://www.star-history.com/#aizhimou/pigeon-pod&Timeline)
---
Made with ❤️ for podcast enthusiasts!
⭐ If you like PigeonPod, give us a star on GitHub!