Podqueue - a simple podcast archiver, written in Python

podqueue is a simple Python script to archive your favourite podcasts.

Have you ever wanted to go back to listen to a great old episode, and it’s disappeared from the internet? Some podcasts only keep a few recent episodes in their feeds, or maybe the creator abandoned their project and no one paid for the web hosting. Whatever the reason, I want to keep my podcast queue archived. (Maybe I’m just finding excuses for upgrading my ZFS pool - who can say?) There are other solutions to this, but honestly, I was looking for a fun project and this seemed perfect.

Enter podqueue: an only briefly eponymous simple solution to download your entire subscription list to disk, with some nice features:

• Super simple configuration - all you need is an input (your subscription list) and an output (directory).
• Archive the show notes in simple JSON and cover art along with all the audio files.
• Portable - written in Python, podqueue is available on any platform.
• Set it and forget it - run podqueue on a cron or systemd timer, and (hopefully) never think about it again.

After it’s downloaded the back catalogue, you’ll get a directory structure like this, with one .json and one audio file (probably .mp3) per episode.

output/
├─ Accidental_Tech_Podcast/
├── episodes/
│──├── 2021-12-30_463_No_Indication_of_Progress.json
│──├── 2021-12-30_463_No_Indication_of_Progress.mp3
│──├── 2022-01-06_464_Monks_at_Drafting_Tables.json
│──├── 2022-01-06_464_Monks_at_Drafting_Tables.mp3
│──├── ...
├── Accidental_Tech_Podcast.png
├── Accidental_Tech_Podcast.json
├─ The_Pen_Addict/
├── episodes/
│──├── 2021-12-29_494_The_Centre_is_Twisty.json
│──├── 2021-12-29_494_The_Centre_is_Twisty.mp3
│──├── 2022-01-05_495_Parter_Jocker.json
│──├── 2022-01-05_495_Parter_Jocker.mp3
│──├── ...
├── The_Pen_Addict.png
├── The_Pen_Addict.json

Where do I get it?

Currently, podqueue is available in two places:

• https://github.com/tquin/podqueue
• https://pypi.org/project/podqueue

Installation can be done with Python’s pip:

python3 -m pip install --upgrade podqueue
python3 -m podqueue --help

Or you can just clone the git repo directly and run it that way:

git clone https://github.com/tquin/podqueue
cd podqueue/
python3 src/main.py --help

Alternatively, you can use Docker to containerise podqueue. This will use a docker volume to write the output files onto your host file system, so just specify that as <YOUR_OUTPUT_DIRECTORY> in the below commands.

git clone https://github.com/tquin/podqueue
cd podqueue/
nano example.opml # Replace this example with your subscription list
nano src/config.ini # Edit the config file with any changes you want
docker build --tag podqueue .
docker run -it -v <YOUR_OUTPUT_DIRECTORY>:/tmp/podqueue-output podqueue

Is my podcast app supported?

… Maybe. Most third-party, indie-developed apps support the OPML open standard, which is how you export your subscription list for podqueue to read. Apple and Google Podcasts both don’t have an official method, but there are some open source tools that might be able to help you. Spotify and Stitcher, though, because they use proprietary systems and not open standards, both don’t offer an export to OPML - you’ll need to copy your podcasts into an app that does and export that way.

Key: ✅ the good, ❌ the bad, and 🔨 the workaround

Icon	Podcast App	Supported	OPML Export Options
	Pocket Casts	✅	OPML export
	Overcast	✅	Option available in the app’s Settings page, or here on the web.
	Castro	✅	Export Subscriptions
	Downcast	✅	Exporting Podcast Subscriptions
	Podcast Addict	✅	How can I backup and restore my subscription & data?
	Castbox	✅	OPML Export
	Apple Podcasts	🔨	Not available in iOS app or macOS since Catalina. However, if you sync your podcasts to your Mac, there is an open-source workaround.
	Google Podcasts	🔨	Officially unavailable. There is a Gist by @telmen (I tested, seems to work) that can be run in your browser’s Devtools if you’re feeling lucky.
	Spotify	❌	Not available, since Spotify doesn’t use open Podcast standards. Community suggestion is ‘now reaching the internal teams at Spotify’, as of six months ago.
	Stitcher	❌	Not available.