![](\"src/app/static/images/logos/logo_with_text.png\"){kind=logo}
\n\n\n\n\n
Ad-block for podcasts. Create an ad-free RSS feed.
\n\n \n ![\"Discord\"](\"https://img.shields.io/badge/discord-join-blue.svg?logo=discord&logoColor=white\"){kind=icon}
\n \n
![](\"docs/images/screenshot.png\")
\n\n## How To Run\n\nYou have a few options to get started:\n\n- [](https://railway.com/deploy/podly?referralCode=NMdeg5&utm_medium=integration&utm_source=template&utm_campaign=generic)\n - quick and easy setup in the cloud, follow our [Railway deployment guide](docs/how_to_run_railway.md). \n - Use this if you want to share your Podly server with others.\n- **Run Locally**: \n - For local development and customization, \n - see our [beginner's guide for running locally](docs/how_to_run_beginners.md). \n - Use this for the most cost-optimal & private setup.\n- **[Join The Preview Server](https://podly.up.railway.app/)**: \n - pay what you want (limited sign ups available)\n\n\n## How it works:\n\n- You request an episode\n- Podly downloads the requested episode\n- Whisper transcribes the episode\n- LLM labels ad segments\n- Podly removes the ad segments\n- Podly delivers the ad-free version of the podcast to you\n\n### Cost Breakdown\n*Monthly cost breakdown for 5 podcasts*\n\n| Cost | Hosting | Transcription | LLM |\n|---------|----------|---------------|--------|\n| **free**| local | local | local |\n| **$2** | local | local | remote |\n| **$5** | local | remote | remote |\n| **$10** | public (railway) | remote | remote |\n| **Pay What You Want** | [preview server](https://podly.up.railway.app/) | n/a | n/a |\n| **$5.99/mo** | https://zeroads.ai/ | production fork of podly | |\n\n\n## Contributing\n\nSee [contributing guide](docs/contributors.md) for local setup & contribution instructions.\n"
},
{
"path": "SECURITY.md",
"content": "# Security Policy\n\n## Supported Versions\n\nWe only support the latest on main & preview.\n\n## Reporting a Vulnerability\n\nPlease use the Private Vulnerability Reporting feature on GitHub:\n\n- Navigate to the Security tab of this repository.\n- Select \"Vulnerability reporting\" from the left-hand sidebar.\n- Click \"Report a vulnerability\" to open a private advisory.\n\nInclude as much detail as possible:\n\n- Steps to reproduce.\n- Potential impact.\n- Any suggested fixes.\n\nThis allows us to collaborate with you on a fix in a private workspace before the issue is made public.\n"
},
{
"path": "compose.dev.cpu.yml",
"content": "services:\n podly:\n container_name: podly-pure-podcasts\n image: podly-pure-podcasts\n volumes:\n - ./src/instance:/app/src/instance\n env_file:\n - ./.env.local\n build:\n context: .\n dockerfile: Dockerfile\n args:\n - BASE_IMAGE=${BASE_IMAGE:-python:3.11-slim}\n - CUDA_VERSION=${CUDA_VERSION:-12.4.1}\n - USE_GPU=${USE_GPU:-false}\n - USE_GPU_NVIDIA=${USE_GPU_NVIDIA:-false}\n - USE_GPU_AMD=${USE_GPU_AMD:-false}\n - LITE_BUILD=${LITE_BUILD:-false}\n ports:\n - \"5001:5001\"\n environment:\n - PUID=${PUID:-1000}\n - PGID=${PGID:-1000}\n - CUDA_VISIBLE_DEVICES=${CUDA_VISIBLE_DEVICES:--1}\n - SERVER_THREADS=${SERVER_THREADS:-1}\n restart: unless-stopped\n healthcheck:\n test:\n [\n \"CMD\",\n \"python3\",\n \"-c\",\n \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:5001/')\",\n ]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 10s\n\nnetworks:\n default:\n name: podly-pure-podcasts-network\n"
},
{
"path": "compose.dev.nvidia.yml",
"content": "services:\n podly:\n extends:\n file: compose.dev.cpu.yml\n service: podly\n env_file:\n - ./.env.local\n environment:\n - PUID=${PUID:-1000}\n - PGID=${PGID:-1000}\n - CUDA_VISIBLE_DEVICES=0\n - CORS_ORIGINS=*\n - SERVER_THREADS=${SERVER_THREADS:-1}\n deploy:\n resources:\n reservations:\n devices:\n - driver: nvidia\n count: 1\n capabilities: [gpu]\n\nnetworks:\n default:\n name: podly-pure-podcasts-network\n"
},
{
"path": "compose.dev.rocm.yml",
"content": "services:\n podly:\n extends:\n file: compose.dev.cpu.yml\n service: podly\n env_file:\n - ./.env.local\n devices:\n - /dev/kfd\n - /dev/dri\n environment:\n - PUID=${PUID:-1000}\n - PGID=${PGID:-1000}\n - CUDA_VISIBLE_DEVICES=${CUDA_VISIBLE_DEVICES:--1}\n - CORS_ORIGINS=*\n - SERVER_THREADS=${SERVER_THREADS:-1}\n # Don't ask me why this is needed for ROCM. See\n # https://github.com/openai/whisper/discussions/55#discussioncomment-3714528\n - HSA_OVERRIDE_GFX_VERSION=10.3.0\n security_opt:\n - seccomp=unconfined\n\nnetworks:\n default:\n name: podly-pure-podcasts-network\n# This would be ideal. Not currently supported, apparently. Or I just wasn't able to figure out the driver arg.\n# Tried: amdgpu, amd, rocm\n# deploy:\n# resources:\n# reservations:\n# devices:\n# - capabilities: [gpu]\n# driver: \"amdgpu\"\n# count: 1\n"
},
{
"path": "compose.yml",
"content": "services:\n podly:\n container_name: podly-pure-podcasts\n ports:\n - \"5001:5001\"\n image: ghcr.io/podly-pure-podcasts/podly-pure-podcasts:${BRANCH:-main-latest}\n volumes:\n - ./src/instance:/app/src/instance\n env_file:\n - ./.env.local\n environment:\n - PUID=${PUID:-1000}\n - PGID=${PGID:-1000}\n - CUDA_VISIBLE_DEVICES=${CUDA_VISIBLE_DEVICES:--1}\n - SERVER_THREADS=${SERVER_THREADS:-1}\n restart: unless-stopped\n healthcheck:\n test:\n [\n \"CMD\",\n \"python3\",\n \"-c\",\n \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:5001/')\",\n ]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 10s\n\nnetworks:\n default:\n name: podly-pure-podcasts-network\n"
},
{
"path": "docker-entrypoint.sh",
"content": "#!/bin/bash\nset -e\n\n# Check if PUID/PGID env variables are set\nif [ -n \"${PUID}\" ] && [ -n \"${PGID}\" ] && [ \"$(id -u)\" = \"0\" ]; then\n echo \"Using custom UID:GID = ${PUID}:${PGID}\"\n \n # Update user/group IDs if needed\n usermod -o -u \"$PUID\" appuser\n groupmod -o -g \"$PGID\" appuser\n \n # Ensure required directories exist\n mkdir -p /app/src/instance /app/src/instance/data /app/src/instance/data/in /app/src/instance/data/srv /app/src/instance/config /app/src/instance/db /app/src/instance/logs\n \n # Set permissions for all application directories\n APP_DIRS=\"/home/appuser /app/processing /app/src/instance /app/src/instance/data /app/src/instance/config /app/src/instance/db /app/src/instance/logs /app/scripts\"\n chown -R appuser:appuser $APP_DIRS 2>/dev/null || true\n \n # Ensure log file exists and has correct permissions in new location\n touch /app/src/instance/logs/app.log\n chmod 664 /app/src/instance/logs/app.log\n chown appuser:appuser /app/src/instance/logs/app.log\n\n # Run as appuser\n export HOME=/home/appuser\n exec gosu appuser \"$@\"\nelse\n # Run as current user (but don't assume it's appuser)\n exec \"$@\"\nfi "
},
{
"path": "docs/contributors.md",
"content": "# Contributor Guide\n\n### Quick Start (Docker - recommended for local setup)\n\n1. Make the script executable and run:\n\n```bash\nchmod +x run_podly_docker.sh\n./run_podly_docker.sh --build\n./run_podly_docker.sh # foreground with logs \n./run_podly_docker.sh -d # or detached\n```\n\nThis automatically detects NVIDIA GPUs and uses them if available.\n\nAfter the server starts:\n\n- Open `http://localhost:5001` in your browser\n- Configure settings at `http://localhost:5001/config`\n- Add podcast feeds and start processing\n\n## Usage\n\nOnce the server is running:\n\n1. Open `http://localhost:5001`\n2. Configure settings in the Config page at `http://localhost:5001/config`\n3. Add podcast RSS feeds through the web interface\n4. Open your podcast app and subscribe to the Podly endpoint (e.g., `http://localhost:5001/feed/1`)\n5. Select an episode and download\n\n## Transcription Options\n\nPodly supports multiple options for audio transcription:\n\n1. **Local Whisper (Default)**\n - Slower but self-contained\n2. **OpenAI Hosted Whisper**\n - Fast and accurate; billed per-feed via Stripe\n3. **Groq Hosted Whisper**\n - Fast and cost-effective\n\nSelect your preferred method in the Config page (`/config`).\n\n## Remote Setup\n\nPodly automatically detects reverse proxies and generates appropriate URLs via request headers.\n\n### Reverse Proxy Examples\n\n**Nginx:**\n\n```nginx\nserver {\n listen 443 ssl;\n server_name your-domain.com;\n\n location / {\n proxy_pass http://localhost:5001;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_set_header X-Forwarded-Host $host;\n }\n}\n```\n\n**Traefik (docker-compose.yml):**\n\n```yaml\nlabels:\n - \"traefik.enable=true\"\n - \"traefik.http.routers.podly.rule=Host(`your-domain.com`)\"\n - \"traefik.http.routers.podly.tls.certresolver=letsencrypt\"\n - \"traefik.http.services.podly.loadbalancer.server.port=5001\"\n```\n\n> **Note**: Most modern reverse proxies automatically set the required headers. No manual configuration is needed in most cases.\n\n### Built-in Authentication\n\nPodly ships with built-in authentication so you can secure feeds without relying on a reverse proxy.\n\n- Set `REQUIRE_AUTH=true` to enable protection. By default it is `false`, preserving existing behaviour.\n- When auth is enabled, Podly fails fast on startup unless `PODLY_ADMIN_PASSWORD` is supplied and meets the strength policy (≥12 characters with upper, lower, digit, symbol). Override the initial username with `PODLY_ADMIN_USERNAME` (default `podly_admin`).\n- Provide a long, random `PODLY_SECRET_KEY` so Flask sessions remain valid across restarts. If you omit it, the app generates a new key on each boot and all users are signed out.\n- On first boot with an empty database, Podly seeds an admin user using the supplied credentials. **If you are enabling auth on an existing install, start from a fresh data volume.**\n- After signing in, open the Config page to rotate your password and manage additional users. When you change the admin password, update the corresponding environment variable in your deployment platform so restarts continue to succeed.\n- Use the \"Copy protected feed\" button to generate feed-specific access tokens that are embedded in subscription URLs so podcast clients can authenticate without your primary password. Rate limiting is still applied to repeated authentication failures.\n\n## Ubuntu Service\n\nAdd a service file to /etc/systemd/system/podly.service\n\n```\n[Unit]\nDescription=Podly Podcast Service\nAfter=network.target\n\n[Service]\nUser=yourusername\nGroup=yourusername\nWorkingDirectory=/path/to/your/app\nExecStart=/usr/bin/pipenv run python src/main.py\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n```\n\nenable the service\n\n```\nsudo systemctl daemon-reload\nsudo systemctl enable podly.service\n```\n\n## Database Update\n\nThe database auto-migrates on launch.\n\nTo add a migration after data model change:\n\n```bash\npipenv run flask --app ./src/main.py db migrate -m \"[change description]\"\n```\n\nOn next launch, the database updates automatically.\n\n## Releases and Commit Messages\n\nThis repo uses `semantic-release` to automate versioning and GitHub releases. It relies on\nConventional Commits to determine the next version.\n\nFor pull requests, include **at least one** commit that follows the Conventional Commit format:\n\n- `feat: add new episode filter`\n- `fix(api): handle empty feed`\n- `chore: update dependencies`\n\nIf no Conventional Commit is present, the release pipeline will have nothing to publish.\n\n## Docker Support\n\nPodly can be run in Docker with support for both NVIDIA GPU and non-NVIDIA environments.\n\n### Docker Options\n\n```bash\n./run_podly_docker.sh --dev # rebuild containers for local changes\n./run_podly_docker.sh --production # use published images\n./run_podly_docker.sh --lite # smaller image without local Whisper\n./run_podly_docker.sh --cpu # force CPU mode\n./run_podly_docker.sh --gpu # force GPU mode\n./run_podly_docker.sh --build # build only\n./run_podly_docker.sh --test-build # test build\n./run_podly_docker.sh -d # detached\n```\n\n### Development vs Production Modes\n\n**Development Mode** (default):\n\n- Uses local Docker builds\n- Requires rebuilding after code changes: `./run_podly_docker.sh --dev`\n- Mounts essential directories (config, input/output, database) and live code for development\n- Good for: development, testing, customization\n\n**Production Mode**:\n\n- Uses pre-built images from GitHub Container Registry\n- No building required - images are pulled automatically\n- Same volume mounts as development\n- Good for: deployment, quick setup, consistent environments\n\n```bash\n# Start with existing local container\n./run_podly_docker.sh\n\n# Rebuild and start after making code changes\n./run_podly_docker.sh --dev\n\n# Use published images (no local building required)\n./run_podly_docker.sh --production\n```\n\n### Docker Environment Configuration\n\n**Environment Variables**:\n\n- `PUID`/`PGID`: User/group IDs for file permissions (automatically set by run script)\n- `CUDA_VISIBLE_DEVICES`: GPU device selection for CUDA acceleration\n- `CORS_ORIGINS`: Backend CORS configuration (defaults to accept requests from any origin)\n\n## FAQ\n\nQ: What does \"whitelisted\" mean in the UI?\n\nA: It means an episode is eligible for download and ad removal. By default, new episodes are automatically whitelisted (`automatically_whitelist_new_episodes`), and only a limited number of old episodes are auto-whitelisted (`number_of_episodes_to_whitelist_from_archive_of_new_feed`). Adjust these settings in the Config page (/config).\n\nQ: How can I enable whisper GPU acceleration?\n\nA: There are two ways to enable GPU acceleration:\n\n1. **Using Docker**:\n\n - Use the provided Docker setup with `run_podly_docker.sh` which automatically detects and uses NVIDIA GPUs if available\n - You can force GPU mode with `./run_podly_docker.sh --gpu` or force CPU mode with `./run_podly_docker.sh --cpu`\n\n2. **In a local environment**:\n - Install the CUDA version of PyTorch to your virtual environment:\n ```bash\n pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118\n ```\n\n## Contributing\n\nWe welcome contributions to Podly! Here's how you can help:\n\n### Development Setup\n\n1. Fork the repository\n2. Clone your fork:\n ```bash\n git clone https://github.com/yourusername/podly.git\n ```\n3. Create a new branch for your feature:\n ```bash\n git checkout -b feature/your-feature-name\n ```\n4. Create a pull request with a target branch of Preview\n\n#### Application Ports\n\nBoth local and Docker deployments provide a consistent experience:\n\n- **Application**: Runs on port 5001 (configurable via web UI at `/config`)\n - Serves both the web interface and API endpoints\n - Frontend is built as static assets and served by the backend\n- **Development**: `run_podly_docker.sh` serves everything on port 5001\n - Local script builds frontend to static assets (like Docker)\n - Restart `./run_podly_docker.sh` after frontend changes to rebuild assets\n\n#### Development Modes\n\nBoth scripts provide equivalent core functionality with some unique features:\n\n**Common Options (work in both scripts)**:\n\n- `-b/--background` or `-d/--detach`: Run in background mode\n- `-h/--help`: Show help information\n\n**Local Development**\n\n**Docker Development** (`./run_podly_docker.sh`):\n\n- **Development mode**: `./run_podly_docker.sh --dev` - rebuilds containers with code changes\n- **Production mode**: `./run_podly_docker.sh --production` - uses pre-built images\n- **Docker-specific options**: `--build`, `--test-build`, `--gpu`, `--cpu`, `--cuda=VERSION`, `--rocm=VERSION`, `--branch=BRANCH`\n\n**Functional Equivalence**:\nBoth scripts provide the same core user experience:\n\n- Application runs on port 5001 (configurable)\n- Frontend served as static assets by Flask backend\n- Same web interface and API endpoints\n- Compatible background/detached modes\n\n### Running Tests\n\nBefore submitting a pull request, you can run the same tests that run in CI:\n\nTo prep your pipenv environment to run this script, you will need to first run:\n\n```bash\npipenv install --dev\n```\n\nThen, to run the checks,\n\n```bash\nscripts/ci.sh\n```\n\nThis will run all the necessary checks including:\n\n- Type checking with mypy\n- Code formatting checks\n- Unit tests\n- Linting\n\n### Pull Request Process\n\n1. Ensure all tests pass locally\n2. Update the documentation if needed\n3. Create a Pull Request with a clear description of the changes\n4. Link any related issues\n\n### Code Style\n\n- We use black for code formatting\n- Type hints are required for all new code\n- Follow existing patterns in the codebase\n"
},
{
"path": "docs/how_to_run_beginners.md",
"content": "# How To Run: Ultimate Beginner's Guide\n\nThis guide will walk you through setting up Podly from scratch using Docker. Podly creates ad-free RSS feeds for podcasts by automatically detecting and removing advertisement segments.\n\n## Highly Recommend!\n\nWant an expert to guide you through the setup? Download an AI powered IDE like cursor https://www.cursor.com/ or windsurf https://windsurf.com/\n\nMost IDEs have a free tier you can use to get started. Alternatively, you can use your own [LLM API key in Cursor](https://docs.cursor.com/settings/api-keys) (you'll need a key for Podly anyways).\n\nOpen the AI chat in the IDE. Enable 'Agent' mode if available, which will allow the IDE to help you run commands, view the output, and debug or take corrective steps if necessary.\n\nPaste one of the prompts below into the chat box.\n\nIf you don't have the repo downloaded:\n\n```\nHelp me install docker and run Podly https://github.com/podly-pure-podcasts/podly_pure_podcasts\nAfter the project is cloned, help me:\n- install docker & docker compose\n- run `./run_podly_docker.sh --build` then `./run_podly_docker.sh -d`\n- configure the app via the web UI at http://localhost:5001/config\nBe sure to check if a dependency is already installed before downloading.\nWe recommend Docker because installing ffmpeg & local whisper can be difficult.\nThe Docker image has both ffmpeg & local whisper preconfigured.\nPodly works with many different LLMs, it does not require an OpenAI key.\nCheck your work by retrieving the index page from localhost:5001 at the end.\n```\n\nIf you do have the repo pulled, open this file and prompt:\n\n```\nReview this project, follow this guide and start Podly on my computer.\nBriefly, help me:\n- install docker & docker compose\n- run `./run_podly_docker.sh --build` and then `./run_podly_docker.sh -d`\n- configure the app via the web UI at http://localhost:5001/config\nBe sure to check if a dependency is already installed before downloading.\nWe recommend docker because installing ffmpeg & local whisper can be difficult.\nThe docker image has both ffmpeg & local whisper preconfigured.\nPodly works with many different LLMs; it does not need to work with OpenAI.\nCheck your work by retrieving the index page from localhost:5001 at the end.\n```\n\n## Prerequisites\n\n### Install Docker and Docker Compose\n\n#### On Windows:\n\n1. Download and install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)\n2. During installation, make sure \"Use WSL 2 instead of Hyper-V\" is checked\n3. Restart your computer when prompted\n4. Open Docker Desktop and wait for it to start completely\n\n#### On macOS:\n\n1. Download and install [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/)\n2. Drag Docker to your Applications folder\n3. Launch Docker Desktop from Applications\n4. Follow the setup assistant\n\n#### On Linux (Ubuntu/Debian):\n\n```bash\n# Update package index\nsudo apt update\n\n# Install Docker\nsudo apt install docker.io docker-compose-v2\n\n# Add your user to the docker group\nsudo usermod -aG docker $USER\n\n# Log out and log back in for group changes to take effect\n```\n\n#### Verify Installation:\n\nOpen a terminal/command prompt and run:\n\n```bash\ndocker --version\ndocker compose version\n```\n\nYou should see version information for both commands.\n\n### 2. Get an OpenAI API Key\n\n1. Go to [OpenAI's API platform](https://platform.openai.com/)\n2. Sign up for an account or log in if you already have one\n3. Navigate to the [API Keys section](https://platform.openai.com/api-keys)\n4. Click \"Create new secret key\"\n5. Give it a name (e.g., \"Podly\")\n6. **Important**: Copy the key immediately and save it somewhere safe - you won't be able to see it again!\n7. Your API key will look something like: `sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`\n\n> **Note**: OpenAI API usage requires payment. Make sure to set up billing and usage limits in your OpenAI account to avoid unexpected charges.\n\n## Setup Podly\n\n### Download the Project\n\n```bash\ngit clone https://github.com/normand1/podly_pure_podcasts.git\ncd podly_pure_podcasts\n```\n\n## Running Podly\n\n### Run the Application via Docker\n\n```bash\nchmod +x run_podly_docker.sh\n./run_podly_docker.sh --build\n./run_podly_docker.sh # foreground\n./run_podly_docker.sh -d # detached\n```\n\n### Optional: Enable Authentication\n\nThe Docker image reads environment variables from `.env` files or your shell. To require login:\n\n1. Export the variables before running Podly, or add them to `config/.env`:\n\n```bash\nexport REQUIRE_AUTH=true\nexport PODLY_ADMIN_USERNAME='podly_admin'\nexport PODLY_ADMIN_PASSWORD='SuperSecurePass!2024'\nexport PODLY_SECRET_KEY='replace-with-a-strong-64-char-secret'\n```\n\n2. Start Podly as usual. On first boot with auth enabled and an empty database, the admin account is created automatically. If you are turning auth on for an existing volume, clear the `sqlite3.db` file so the bootstrap can succeed.\n\n3. Sign in at `http://localhost:5001`, then visit the Config page to change your password, add users, and copy RSS URLs with the \"Copy protected feed\" button. Podly generates feed-specific access tokens and embeds them in the link so podcast players can subscribe without exposing your main password. Remember to update your environment variables whenever you rotate the admin password.\n\n### First Run\n\n1. Docker will download and build the necessary image (this may take 5-15 minutes)\n2. Look for \"Running on http://0.0.0.0:5001\"\n3. Open your browser to `http://localhost:5001`\n4. Configure settings at `http://localhost:5001/config`\n - Alternatively, set secrets via Docker env file `.env.local` in the project root and restart the container. See .env.local.example\n\n## Advanced Options\n\n```bash\n# Force CPU-only processing (if you have GPU issues)\n./run_podly_docker.sh --cpu\n\n# Force GPU processing\n./run_podly_docker.sh --gpu\n\n# Just build the container without running\n./run_podly_docker.sh --build\n\n# Test build from scratch (useful for troubleshooting)\n./run_podly_docker.sh --test-build\n```\n\n## Using Podly\n\n### Adding Your First Podcast\n\n1. In the web interface, look for an \"Add Podcast\" or similar button\n2. Paste the RSS feed URL of your podcast\n3. Podly will start processing new episodes automatically\n4. Processed episodes will have advertisements removed\n\n### Getting Your Ad-Free RSS Feed\n\n1. After adding a podcast, Podly will generate a new RSS feed URL\n2. Use this new URL in your podcast app instead of the original\n3. Your podcast app will now download ad-free versions!\n\n## Troubleshooting\n\n### \"Docker command not found\"\n\n- Make sure Docker Desktop is running\n- On Windows, restart your terminal after installing Docker\n- On Linux, make sure you logged out and back in after adding yourself to the docker group\n\n### Cannot connect to the Docker daemon. Is the docker daemon running?\n\n- If using docker desktop, open up the app, otherwise start the daemon\n\n### \"Permission denied\" errors\n\n- On macOS/Linux, make sure the script is executable: `chmod +x run_podly_docker.sh`\n- On Windows, try running Command Prompt as Administrator\n\n### OpenAI API errors\n\n- Double-check your API key in the Config page at `/config`\n- Make sure you have billing set up in your OpenAI account\n- Check your usage limits haven't been exceeded\n\n### Port 5001 already in use\n\n- Another application is using port 5001\n- **Docker users**: Either stop that application or modify the port in `compose.dev.cpu.yml` and `compose.yml`\n- **Native users**: Change the port in the Config page under App settings\n- To kill processes on that port run `lsof -i :5001 | grep LISTEN | awk '{print $2}' | xargs kill -9`\n\n### Out of memory errors\n\n- Close other applications to free up RAM\n- Consider using `--cpu` flag if you have limited memory\n\n## Stopping Podly\n\nTo stop the application:\n\nIf you have launched it in the foreground by omitting the `-d` parameter:\n1. In the terminal where Podly is running, press `Ctrl+C`\n2. Wait for the container to stop gracefully\n\nIf you have launched it in the background using the `-d` parameter:\n1. In the terminal where Podly is running, execute `docker compose down`\n2. Wait for the container to stop gracefully\n\nIn both cases this output should appear to indicate that it has stopped:\n\n```sh\n[+] Running 2/2\n ✔ Container podly-pure-podcasts Removed\n ✔ Network podly-pure-podcasts-network Removed\n```\n\n## Upgrading Podly\n\nTo upgrade the application while you are in the terminal where it is running:\n1. [Stop it](#stopping-podly)\n2. Execute `git pull`\n3. [Run it again](#running-podly)\n\n## Getting Help\n\nIf you encounter issues ask in our discord, we're friendly!\n\nhttps://discord.gg/FRB98GtF6N\n\n## What's Next?\n\nOnce you have Podly running:\n\n- Explore the web interface to add more podcasts\n- Configure settings in the Config page\n- Consider setting up automatic background processing\n- Enjoy your ad-free podcasts!\n"
},
{
"path": "docs/how_to_run_railway.md",
"content": "# How to Run on Railway\n\nThis guide will walk you through deploying Podly on Railway using the one-click template.\n\n## 0. Important! Set Budgets\n\nBoth Railway and Groq allow you to set budgets on your processing. Set a $10 (minimum possible, expect smaller bill) budget on Railway. Set a $5 budget for Groq.\n\n## 1. Get Free Groq API Key\n\nPodly uses Groq to transcribe podcasts quickly and for free.\n\n1. Go to [https://console.groq.com/keys](https://console.groq.com/keys).\n2. Sign up for a free account.\n3. Create a new API key.\n4. Copy the key and paste it into the `GROQ_API_KEY` field during the Railway deployment.\n\n## 2. Deploy Railway Template\n\nClick the button below to deploy Podly to Railway. This is a sponsored link that supports the project!\n\n[](https://railway.com/deploy/podly?referralCode=NMdeg5&utm_medium=integration&utm_source=template&utm_campaign=generic)\n\nIf you want to be a beta-tester, you can deploy the preview branch instead:\n\n[](https://railway.com/deploy/podly-preview?referralCode=NMdeg5&utm_medium=integration&utm_source=template&utm_campaign=generic)\n\n## 3. Configure Networking\n\nAfter the deployment is complete, you need to expose the service to the internet.\n\n1. Click on the new deployment in your Railway dashboard.\n2. Go to the **Settings** tab.\n3. Under **Networking**, find the **Public Networking** section and click **Generate Domain**.\n4. You can now access Podly at the generated URL.\n5. (Optional) To change the domain name, click **Edit** and enter a new name.\n\n\n\n## 4. Set Budgets & Expected Pricing\n\nSet a $10 budget on Railway and a $5 budget on Groq (or use the free tier for Groq which will slow processing).\n\nPodly is designed to run efficiently on Railway's hobby plan.\n\nIf you process a large volume of podcasts, you can check the **Config** page in your Podly deployment for estimated monthly costs based on your usage.\n\n## 5. Secure Your Deployment\n\nPodly now uses secure session cookies for the web dashboard while keeping HTTP Basic authentication for RSS feeds and audio downloads. Before inviting listeners, secure the app:\n\n1. In the Railway dashboard, open your Podly service and head to **Variables**.\n2. Add `REQUIRE_AUTH` with value `true`.\n3. Add a strong `PODLY_ADMIN_PASSWORD` (minimum 12 characters including uppercase, lowercase, digit, and symbol). Optionally set `PODLY_ADMIN_USERNAME`.\n4. Provide a long, random `PODLY_SECRET_KEY` so session cookies survive restarts. (If you omit it, Podly will generate a new key each deploy and sign everyone out.)\n5. Redeploy the service. On first boot Podly seeds the admin user and requires those credentials on every request.\n\n> **Important:** Enabling auth on an existing deployment requires a fresh data volume. Create a new Railway deployment or wipe the existing storage so the initial admin can be seeded.\n\nAfter signing in, use the Config page to change your password, add additional users, and copy RSS links via the \"Copy protected feed\" button. Podly issues feed-specific access tokens and embeds them in each URL so listeners can subscribe without knowing your main password. When you rotate passwords, update the corresponding Railway variables so restarts succeed.\n\n## 6. Using Podly\n\n1. Open your new Podly URL in a browser.\n2. Navigate to the **Feeds** page.\n3. Add the RSS feed URL of a podcast you want to process.\n4. Go to your favorite podcast client and subscribe to the new feed URL provided by Podly (e.g., `https://your-podly-app.up.railway.app/feed/1`).\n5. Download and enjoy ad-free episodes!\n"
},
{
"path": "docs/todo.txt",
"content": "- config audit & testing (advanced and basic)\n- move host/port/threads to docker config\nreaudit security + testing\nci.sh\ntest railway\nlogin for public facing\npodcast rss search\n\n'basic' config page - just put in groq api key + test + save on populate\nalso show if api key is set or blank\n\ntest hide 'local' whisper in lite build"
},
{
"path": "frontend/.gitignore",
"content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\npnpm-debug.log*\nlerna-debug.log*\n\nnode_modules\ndist\ndist-ssr\n*.local\n\n# Editor directories and files\n.vscode/*\n!.vscode/extensions.json\n.idea\n.DS_Store\n*.suo\n*.ntvs*\n*.njsproj\n*.sln\n*.sw?\n"
},
{
"path": "frontend/README.md",
"content": "# Podly Frontend\n\nThis is the React + TypeScript + Vite frontend for Podly. The frontend is built and served as part of the main Podly application.\n\n## Development\n\nThe frontend is integrated into the main Podly application and served as static assets by the Flask backend on port 5001.\n\n### Development Workflows\n\n1. **Docker (recommended)**: The Docker build compiles the frontend during image creation and serves static assets from Flask.\n\n2. **Direct Frontend Development**: You can run the frontend development server separately for advanced frontend work:\n\n ```bash\n cd frontend\n npm install\n npm run dev\n ```\n\n This starts the Vite development server on port 5173 with hot reloading and proxies API calls to the backend on port 5001.\n\n### Build Process\n\n- **Direct Development** (`npm run dev`): Vite dev server serves files with hot reloading on port 5173 and proxies API calls to backend on port 5001\n- **Docker**: Multi-stage build compiles frontend assets during image creation and copies them to the Flask static directory\n\n## Technology Stack\n\n- **React 18+** with TypeScript\n- **Vite** for build tooling and development server\n- **Tailwind CSS** for styling\n- **React Router** for client-side routing\n- **Tanstack Query** for data fetching\n\n## Configuration\n\nThe frontend configuration is handled through:\n\n- **Environment Variables**: Set via Vite's environment variable system\n- **Vite Config**: `vite.config.ts` for build and development settings\n - Development server runs on port 5173\n - Proxies API calls to backend on port 5001 (configurable via `BACKEND_TARGET`)\n- **Tailwind Config**: `tailwind.config.js` for styling configuration\n"
},
{
"path": "frontend/eslint.config.js",
"content": "import js from '@eslint/js'\nimport globals from 'globals'\nimport reactHooks from 'eslint-plugin-react-hooks'\nimport reactRefresh from 'eslint-plugin-react-refresh'\nimport tseslint from 'typescript-eslint'\n\nexport default tseslint.config(\n { ignores: ['dist'] },\n {\n extends: [js.configs.recommended, ...tseslint.configs.recommended],\n files: ['**/*.{ts,tsx}'],\n languageOptions: {\n ecmaVersion: 2020,\n globals: globals.browser,\n },\n plugins: {\n 'react-hooks': reactHooks,\n 'react-refresh': reactRefresh,\n },\n rules: {\n ...reactHooks.configs.recommended.rules,\n 'react-refresh/only-export-components': [\n 'warn',\n { allowConstantExport: true },\n ],\n },\n },\n)\n"
},
{
"path": "frontend/index.html",
"content": "\n\n \n \n \n \n Loading authentication…
\n![\"Podly\"](\"/images/logos/logo.webp\"){kind=logo}
\n {result.author}
\n )}\n {result.genres.length > 0 && (\n\n {result.genres.join(' · ')}\n
\n )}\n{result.feedUrl}
\n\n Episode • {formatTime(duration)}\n
\n\n {currentError\n ? 'An error occurred. You can report it with logs.'\n : 'Use this to collect logs for a bug report.'}\n
\n\n{recentEntries\n .map((e) => {\n const base = `[${formatTs(e.ts)}] ${e.level.toUpperCase()}: ${e.message}`;\n if (e.data === undefined) return base;\n try {\n return base + `\\n ${JSON.stringify(e.data)}`;\n } catch {\n return base;\n }\n })\n .join('\\n')}\n \n by {currentFeed.author}
\n )}\nby {currentFeed.author}
\n )}\n![\"Original](\"/rss-round-color-icon.svg\"){kind=icon}
\n Original RSS feed\n \n\n {requireAuth && isAdmin && isMember && (\n <>\n \n {currentFeed.description.replace(/<[^>]*>/g, '')}
\n\n Overrides the global setting. Global default: {autoWhitelistDefaultLabel}.\n
\n\n This feed exceeds your plan's allowance. New episodes will not be processed automatically until you upgrade your plan or leave other feeds.\n
\n\n Enabled episodes are processed by Podly to automatically detect and remove advertisements,\n giving you a clean, ad-free listening experience.\n
\n\n Disabled episodes are not processed and won't be available for download through Podly.\n This is useful for episodes you don't want to listen to.\n
\n\n Why whitelist episodes? Processing takes time and computational resources.\n Enable only the episodes you want to hear to keep your feed focused. This is useful when adding a new feed with a large back catalog.\n
\nFailed to load episodes
\nNo episodes found
\n\n {currentFeed.title}\n
\n\n {episode.description.replace(/<[^>]*>/g, '').substring(0, 300)}...\n
\n{pendingEpisode.title}
\n {isEstimating && (\n{estimateError}
\n )}\n {!isEstimating && processingEstimate && (\nEstimated minutes: {processingEstimate.estimated_minutes.toFixed(2)}
\n {!processingEstimate.can_process && (\nProcessing not available for this episode.
\n )}\nNo podcast feeds added yet.
\nClick \"Add Feed\" to get started.
\n\n No podcasts match "{searchTerm}"\n
\nby {feed.author}
\n )}\nFailed to load processing statistics
\n| ID | \nModel | \nSegment Range | \nStatus | \nTimestamp | \nRetries | \nActions | \n
|---|---|---|---|---|---|---|
| {call.id} | \n{call.model_name} | \n{call.segment_range} | \n\n \n {call.status}\n \n | \n{formatTimestamp(call.timestamp)} | \n{call.retry_attempts} | \n\n | \n
| \n \n {call.prompt && (\n \n \n \n )}\n {call.error_message && (\n Prompt:\n\n {call.prompt}\n \n \n \n )}\n {call.response && (\n Error Message:\n\n {call.error_message}\n \n \n \n )}\n Response:\n\n {call.response}\n \n | \n
| Seq # | \nTime Range | \nLabel | \nText | \n
|---|---|---|---|
| {segment.sequence_num} | \n\n {segment.start_time}s - {segment.end_time}s\n | \n\n \n {segment.primary_label === 'ad'\n ? (segment.mixed ? 'Ad (mixed)' : 'Ad')\n : 'Content'}\n \n | \n\n \n {segment.text}\n \n | \n
| ID | \nSegment ID | \nTime Range | \nLabel | \nConfidence | \nModel Call | \nText | \n
|---|---|---|---|---|---|---|
| {identification.id} | \n{identification.transcript_segment_id} | \n\n {identification.segment_start_time}s - {identification.segment_end_time}s\n | \n\n \n {identification.label === 'ad'\n ? (identification.mixed ? 'ad (mixed)' : 'ad')\n : identification.label}\n \n | \n\n {identification.confidence ? identification.confidence.toFixed(2) : 'N/A'}\n | \n{identification.model_call_id} | \n\n \n {identification.segment_text}\n \n | \n
\n Are you sure you want to reprocess this episode? This will delete the existing processed data and start fresh processing.\n
\n\n {/* Action Buttons */}\nWhen is Base URL used?
\n\n The Base URL is only used for models without a provider prefix. LiteLLM\n automatically routes provider-prefixed models to their respective APIs.\n
\n✅ Base URL is IGNORED for:
\ngroq/openai/gpt-oss-120b → Groq API\n anthropic/claude-3.5-sonnet → Anthropic\n API\n gemini/gemini-3-flash-preview → Google API\n gemini/gemini-2.0-flash → Google API\n ⚙️ Base URL is USED for:
\ngpt-4o\n For the default Groq setup, you don't need to set this.
\n\n These fields are controlled by environment variables. Update the referenced variables in your\n .env\n (or deployment secrets) to make the change persistent. Your manual change will be saved, but will be overwritten if you modify your environment variables in the future.\n
\n Managed by {meta.env_var}\n {meta?.value_preview && (\n ({meta.value_preview})\n )}\n {!meta?.value_preview && meta?.value && (\n ({meta.value})\n )}\n
Managed by deployment environment
\n )}\n{meta.env_var}\n );\n}\n"
},
{
"path": "frontend/src/components/config/shared/Field.tsx",
"content": "import type { ReactNode } from 'react';\nimport type { EnvOverrideEntry } from '../../../types';\nimport EnvVarHint from './EnvVarHint';\n\ninterface FieldProps {\n label: string;\n children: ReactNode;\n envMeta?: EnvOverrideEntry;\n labelWidth?: string;\n hint?: string;\n}\n\nexport default function Field({\n label,\n children,\n envMeta,\n labelWidth = 'w-60',\n hint,\n}: FieldProps) {\n return (\n \n );\n}\n"
},
{
"path": "frontend/src/components/config/shared/SaveButton.tsx",
"content": "interface SaveButtonProps {\n onSave: () => void;\n isPending: boolean;\n className?: string;\n}\n\nexport default function SaveButton({ onSave, isPending, className = '' }: SaveButtonProps) {\n return (\n gsk_) and paste it below.\n \n Based on the recommended models: whisper-large-v3-turbo and{' '}\n llama-3.3-70b-versatile\n
\n * Actual costs may vary based on podcast length, complexity, and token usage. Consider\n setting a $5-10/month billing limit for safety.\n
\nhttps://your-domain/api/auth/discord/callback\n Note: Environment variables (DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET, etc.) \n take precedence over values configured here.\n
\n\n Leave blank for unlimited; set to 0 to block new user creation. Applies only when authentication is enabled.\n
\n\n Pay what you want for the Starter Bundle (10 feeds).\n
\n\n Get 10 feeds for a monthly price of your choice (min ${minAmountDollars.toFixed(2)}).\n
\n \nError loading feeds. Please try again.
\nSelect a podcast from the list to view details and episodes.
\n\n Paste an RSS URL or search the catalog to find shows to follow.\n
\n\n {run\n ? hasActiveWork\n ? `Processing · Last update ${formatDateTime(run.updated_at)}`\n : `Idle · Last activity ${formatDateTime(run.updated_at)}`\n : 'Jobs Manager has not started yet.'}\n
\n\n {cleanupDisabled\n ? 'Cleanup is disabled while retention days are unset or zero.'\n : `Episodes older than ${retentionDays} day${retentionDays === 1 ? '' : 's'} will be removed.`}\n
\n\n {mode === 'active'\n ? 'Queued and running jobs, ordered by priority.'\n : 'All jobs ordered by priority (running/pending first).'}\n
\n\n Podly\n \n We're testing a self-hosted podcast ad removal system. Podly transcribes episodes, detects sponsor reads with an LLM, and generates clean RSS feeds that work in any podcast app.\n
\n\n {/* Live user count */}\nPodly grabs the feed, finds sponsorship blocks, and gives you a private RSS link so your own players stream the ad-free version.
\nListen anywhere
\nGetting started
\n\n \n \n \n {landingPageEnabled && (\n \n ← Back to home\n \n )}\n We've moved to a new and improved interface!
\nYou will be automatically redirected to our new UI in 5 seconds.
\n\n {% set redirect_url = \"http://\" + request.host.split(':')[0] + \":5001\" %}\n\n \n Go to New UI Now\n \n\nIf you are not redirected automatically, click the button above.
\n