CleanCast

Podcasting, purified
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Local Development
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

This is a GO Docker application that will take any podcast that is on Youtube and will generate a RSS feed with the audio only and all sponsored sections auto removed. The actual podcasts episodes are downloaded on demand from youtube when the user requests the specific episode then it is served to the user seamlessly.

(back to top)

Built With

• 

(back to top)

Getting Started

Below is a guide to get the application running

Prerequisites

1. Generate a Youtube api v3 key here
2. Install Docker
3. Need some podcasts you like

Running the App

1. Build out your Docker run command (For more Docker variables and compose examples go here)

   • docker run -p 8080:8080 -e GOOGLE_API_KEY=<api key here> -v /<audio download path here>:/config ikoyhn/clean-cast
     

2. Run the command to start the app up

3. Copy the properties.yml into your /config folder. In here you'll find settings such as NTFY notification setup.

4. Restart application after making any changes to properties.yml.

(back to top)

Usage

1. Find your ID

   • Playlist ID: To find this navigate to the channel and either click the podcast tab or playlist tab and click on the playlist you want to add. Ex TigerBelly the url you should see after clicking it will be www.youtube.com/playlist?list=PLbh0Jamvptwfp_qc439PLuyKJ-tWUt222` so the ID would be PLbh0Jamvptwfp_qc439PLuyKJ-tWUt222

   • Channel ID: If you want to create a podcast from all videos from a channel use this. You can get the channel ID using websites such as https://www.tunepocket.com/youtube-channel-id-finder/.

2. Build your URL

   • Playlist: If you are building a podcast URL using a playlist use the /rssendpoint. * Following the TigerBelly example where this app is running on http://localhost:8080 the url would be http://localhost:8080/rss/PLbh0Jamvptwfp_qc439PLuyKJ-tWUt222

   • Channel: If you are building a podcast URL using a channel ID use the /channel endpoint. An example would be http://localhost:8080/channel/UCoj1ZgGoSBoonNZqMsVUfAA

     • WARNING: When using the channel endpoint you can easily max your Youtube API v3 quota. To reduce the chance use the URL param date=MM-DD-YYYY, this will give you an RSS feed of all videos published AFTER the date. Example url would look like http://localhost:8080/channel/UCoj1ZgGoSBoonNZqMsVUfAA?date=06-01-2025

• NOTE: If you have the docker var -e TOKEN=<secure token> set you must add the token as a query param to this url. Ex: http://localhost:8080/rss/PLbh0Jamvptwfp_qc439PLuyKJ-tWUt222?token=secureToken

3. With this URL you can now add this to any of your favorite podcast apps that accept custom RSS feeds (Apple Podcasts app, VLC Media Player, etc)

IOS Users

Shortcut created by Noah Kiss can be found here in the discussions tab to allow for generating your RSS feeds easier. View the comments to ensure you are using the most up-to-date version of the shortcut. Please post any issues related to the shortcut in the discussion.

(back to top)

Issues Connecting Your Favorite Podcast App?

• If you are having issues using your favorite podcast client first check the Discussions to see if there is a guide to set it up already created, if there isn't please create an new Issue.
• If you have a guide you would like to write to help out others go ahead and create a new discussion with the title template of {app you are using} App - Setup Guide

Roadmap

• Playlists
• Channels
• Add UI for easier URL generation
  • Discovery Page of new podcasts based on Apple Podcast API
  • Managing saved podcasts
  • Allow user to set docker variables in UI
• Improve YT API Efficiency
  • Add user defined max videos to grab (by date)
  • Allow for multiple YT API keys
• Implement proper authenticaton (Username/Password)
• Implement Ntfy Notifications
• Create IOS App (stretch goal)
• Create Android App (stretch goal)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Running Locally

(NON-Windows only for now)

1. Install latest Golang version for your system
2. Install Delve
3. Create .env in root of the project a. Set GOOGLE_API_KEY and CONFIG_DIR in env. You can set more such as the properties from the yml for testing.
4. Run using launch.json

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

Top contributors:

License

Distributed under the MIT. See LICENSE.txt for more information.

(back to top)

Contact

Jared Lynch - jaredlynch13@gmail.com

(back to top)

Acknowledgments

• Irstanley/go-ytdlp for downloading Youtube videos (includes Sponsorblock for removing sponsored segments)
• google-api-go-client Used to get all information for Youtube Podcast

(back to top)