🎙️ Folder2Podcast RSS

Convert local audio folders to private podcast RSS feeds with one command - Zero intrusion, No side effects

Background

Podcast RSS is a powerful audio distribution standard that provides:

🔖 Complete playback progress tracking
🎯 Precise resume playback functionality
🔄 Cross-device listening history sync
📱 Multi-platform listening support
🎨 Rich media information display

Folder2Podcast RSS lets you easily convert local audio folders into private podcast RSS feeds, enjoying all the advanced features of professional podcast clients:

🎧 Listen using your favorite podcast apps (like Apple Podcasts, Pocket Casts)
📱 Continue from where you left off on any device
🔄 Automatically sync listening history across devices
📚 Systematically manage your audiobook library
🎯 Smart bookmarking for every audio file

Just one command to deploy, transforming your local audio into private podcast feeds instantly.

✨ Features

📱 Web Interface

The project provides a user-friendly web interface that allows users to:

View all available podcast sources
Copy subscription URLs with one click
One-click subscription support for multiple podcast clients:
- Apple Podcasts
- Overcast
- Pocket Casts
- Castro
- Moon FM
- More clients coming soon...

🎯 Other Features

Smart filename processing
Automatic serialization
Cover image management
Multi-device sync

For detailed information, please refer to Advanced Guide.

🚀 Quick Start

Docker Deployment (Recommended)

Preparation
- Install Docker
- Prepare audio directories (organized by podcast content)
- Standardize filename format (e.g., 01-Chapter1.mp3, Episode02.mp3)

⚠️ Important: BASE_URL Configuration

When deploying to a server, you must properly configure the BASE_URL environment variable, which affects:

Audio file links in RSS feed
Cover image links
All static resource access paths

Configuration examples:

# For local testing
BASE_URL=http://localhost:3000

# For server deployment (replace with your actual server IP or domain)
BASE_URL=http://192.168.55.222:3000
# or
BASE_URL=http://your-domain.com

Important notes:

BASE_URL must include protocol prefix (http:// or https://)
Include port number if using custom port
Don't add trailing slash '/'
Ensure the address is accessible from client devices (like podcast apps)

Launch Service

Option 1: Direct Docker command

docker run -d \
  -p 3000:3000 \
  -v /path/to/audiobooks:/podcasts \
  -e PORT=3000 \
  -e BASE_URL=http://your-server-ip:3000 \
  -e PUID=$(id -u) \
  -e PGID=$(id -g) \
  yaotutu/folder2podcast

Option 2: Using Docker Compose (Recommended)

# docker-compose.yml
version: '3.8'
services:
  folder2podcast:
    image: yaotutu/folder2podcast
    ports:
      - "3000:3000"
    volumes:
      - ./audiobooks:/podcasts:ro  # Mount in read-only mode
    environment:
      - PORT=3000
      - AUDIO_DIR=/podcasts
      - BASE_URL=http://your-server-ip:3000
      - PUID=1000  # Replace with your user ID
      - PGID=1000  # Replace with your group ID
    restart: unless-stopped

Permission Note:

Sometimes Docker container might have trouble accessing your audio files

In such cases, you need to set PUID and PGID environment variables

These values should match the owner ID of your audio folder

On Mac/Linux, simply run id -u and id -g in terminal to get these values

Once set correctly, the app will be able to access your audio files normally

Verify Deployment
- Visit http://localhost:3000/podcasts to confirm service is running
- Check if podcast list displays correctly
- Test audio file access

Docker Image Tags

yaotutu/folder2podcast:main - Development version, synced with main branch, includes latest features
yaotutu/folder2podcast:latest - Stable version, tested and released, recommended for production

📦 Directory Structure

Each podcast folder can contain its own podcast.json configuration file to customize that podcast's presentation and behavior. This design allows different settings for each podcast series.

Configuration File Location

audiobooks/
├── podcast-series-1/
│   ├── 01-chapter1.mp3
│   └── podcast.json    # Independent config for series 1
└── podcast-series-2/
    ├── 01.intro.mp3
    └── podcast.json    # Independent config for series 2

⚙️ Configuration

Environment Variables

The system supports multiple environment variables for customization. Here's the complete list:

Variable	Description	Default	Example
`AUDIO_DIR`	Audio files root directory	`./audio`	`/path/to/audiobooks`
`PORT`	Server listening port	`3000`	`8080`
`BASE_URL`	Server base URL for RSS feed links	`http://localhost:PORT`	`http://192.168.55.222:3000`
`TITLE_FORMAT`	Episode title display format	`full`	`clean` or `full`
`PUID`	Audio folder owner ID	`1000`	Run `id -u` to get
`PGID`	Audio folder group ID	`1000`	Run `id -g` to get

Detailed description:

AUDIO_DIR
- Purpose: Specify root directory for audio files
- Default: audio folder in current directory
- Note: Directory must have read permissions
PORT
- Purpose: Specify server listening port
- Default: 3000
- Note: Service won't start if port is occupied
BASE_URL
- Purpose: Generate URLs in RSS feed
- Default: http://localhost:port
- Importance: Must be set correctly to ensure audio files are accessible
- Format: Must include protocol (http/https)
TITLE_FORMAT
- Purpose: Control episode title display format
- Default: full (keep complete filename)
- Options:
  - full: Keep complete filename (without extension)
  - clean: Remove number prefix and separators

Usage example:

# Docker run example
docker run -d \
  -p 3000:3000 \
  -v /audiobooks:/podcasts \
  -e AUDIO_DIR=/podcasts \
  -e PORT=3000 \
  -e BASE_URL=http://192.168.55.222:3000 \
  -e TITLE_FORMAT=full \
  yaotutu/folder2podcast

Configuration priority:

Environment variables > Default values
podcast.json config > Environment variables (for specific podcasts)

podcast.json Configuration

{
  "title": "Podcast Title",
  "description": "Podcast Description",
  "author": "Author Name",
  "email": "author@example.com",
  "language": "en-us",
  "category": "Technology",
  "explicit": false,
  "websiteUrl": "https://example.com",
  "titleFormat": "clean",
  "episodeNumberStrategy": "first",  // Episode number extraction strategy: prefix (default), suffix, first, last, or { pattern: "regex" }
  "useMTime": false  // Whether to use file creation time as publish date, defaults to false
}

📝 Time Management Note:

When useMTime is false (default):

Files with numbers use number-based publish dates

Files without numbers use file creation time

When useMTime is true:

All files use file creation time as publish date

Ignores number information in filenames

For detailed information, refer to Advanced Guide

🎨 Advanced Features

📱 Client Support

Supported Podcast Clients

Almost all podcast clients that support custom RSS feeds work:

Apple Podcasts (iOS, Mac)
Pocket Casts (All platforms)
Overcast (iOS)
Castro (iOS)
Google Podcasts (Android, Web)
AntennaPod (Android)

Usage Flow

Get Subscription Link
- Visit http://your-server:3000/podcasts
- Find the podcast series you want to subscribe to
- Copy the corresponding RSS Feed URL
Add to Podcast Client
- Open your preferred podcast client
- Find "Add Podcast" or "Add RSS Feed"
- Paste your Feed URL
- Wait for content to sync
Start Using
- All episodes will automatically sync to the client
- Listening progress syncs across devices
- Supports background download and offline playback
- Can add chapter notes (supported by some clients)

RSS Best Practices

Content Organization
- Use clear folder structure
- Maintain consistent file naming
- Add high-quality cover images (recommended 1400x1400px)
Performance Optimization
- Control the number of audio files per folder
- Use mp3 format for best compatibility
- Configure correct BASE_URL to ensure accessibility

Troubleshooting

📋 Support & Feedback

Found a bug? Submit Issue
Have suggestions? Join Discussion
Want to contribute? Submit PR

Changelog

View complete update history in CHANGELOG.md

👆 Scan QR code to join our WeChat group for beta testing!

1. Podcast List API

Access /podcasts to get all available podcasts
Returns detailed information including title, description, subscription URLs
Feed URLs include complete access addresses ready for subscription

2. Resource Access

Podcast cover: /audio/podcast-name/cover.jpg
Audio files: /audio/podcast-name/episode.mp3
Default resources: /image/default-cover.jpg

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.en.md

README.en.md

🎙️ Folder2Podcast RSS

Table of Contents

Background

✨ Features

📱 Web Interface

🎯 Other Features

🚀 Quick Start

Docker Deployment (Recommended)

Docker Image Tags

📦 Directory Structure

Configuration File Location

⚙️ Configuration

Environment Variables

podcast.json Configuration

🎨 Advanced Features

📱 Client Support

Supported Podcast Clients

Usage Flow

RSS Best Practices

Troubleshooting

📋 Support & Feedback

Changelog

1. Podcast List API

2. Resource Access

Files

README.en.md

Latest commit

History

README.en.md

File metadata and controls

🎙️ Folder2Podcast RSS

Table of Contents

Background

✨ Features

📱 Web Interface

🎯 Other Features

🚀 Quick Start

Docker Deployment (Recommended)

Docker Image Tags

📦 Directory Structure

Configuration File Location

⚙️ Configuration

Environment Variables

podcast.json Configuration

🎨 Advanced Features

📱 Client Support

Supported Podcast Clients

Usage Flow

RSS Best Practices

Troubleshooting

📋 Support & Feedback

Changelog

1. Podcast List API

2. Resource Access