Podcastrr

A podcast management application similar to Sonarr but for podcasts, built with Python and Flask.

Features

• Search for Podcasts: Find podcasts from various sources
• Track Podcasts: Monitor your favorite podcasts for new episodes
• Download Management: Automatically download new episodes and manage storage
• Complete Podcast Archive: Download all episodes of a podcast with one click
• Custom Naming: Configure how downloaded files are named
• Tag/Label System: Organize podcasts into groups with tags
• Direct RSS Feed: Add podcasts using direct RSS feed URLs
• OPML Import/Export: Easily import and export podcast subscriptions
• Existing Episode Detection: Prevent re-downloading files if already present
• Web Interface: Manage everything through an intuitive web interface

Requirements

• Python 3.8+
• Dependencies listed in requirements.txt

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/podcastrr.git
   cd podcastrr
   

2. Create and activate a virtual environment:

   python -m venv .venv
   # On Windows
   .venv\Scripts\activate
   # On macOS/Linux
   source .venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create a .env file in the root directory with the following variables:

   FLASK_ENV=development
   SECRET_KEY=your_secret_key
   DATABASE_URI=sqlite:///podcastrr.db
   DOWNLOAD_PATH=/path/to/downloads
   

5. Initialize the database:

   python init_db.py
   

   This will create the database and run all necessary migrations.

6. If you're updating an existing installation and encounter database errors:

   python run_migrations.py
   

   This will apply any pending migrations to your database. See the Migration Guide for more details.

Usage

Local Development

Run the application:

python main.py

Then open your browser and navigate to http://localhost:5000.

Docker Deployment

The application can be deployed using Docker in two ways:

Option 1: Using the published Docker image from Forgejo registry (recommended for production)

1. Create a .env file with the following variables:

   FORGEJO_REGISTRY=your-forgejo-registry-url
   FORGEJO_USERNAME=your-username
   PORT=5000
   FLASK_ENV=production
   SECRET_KEY=your_secret_key
   DATABASE_URI=sqlite:///instance/podcastrr.db
   DOWNLOAD_PATH=/app/downloads
   

2. Run the application using docker-compose:

   docker-compose up -d
   

Option 2: Building from local Dockerfile (for development)

1. Modify the docker-compose.yml file to use the local build instead of the published image:

   • Comment out the image: line
   • Uncomment the build: section

2. Run the application using docker-compose:

   docker-compose up -d
   

The application will be available at http://localhost:5000 (or the port you specified in the .env file).

Development

1. Install development dependencies:

   pip install -r requirements-dev.txt
   

2. Run tests:

   pytest
   

3. Format code:

   black .