Automate the archiving of podcast feeds, including show notes and images.

These details have not been verified by PyPI

Project links

Project description

tquin/podqueue

Automate the archiving of podcast feeds, including show notes and images.

This Python project aims for a simple user interface - you just need to modify podqueue.conf with your inputs and outputs, and then schedule the program to run periodically.

What does my config file look like?

The default podqueue.conf looks like the below. You have two choices to run this app:

Edit this config file with your inputs and outputs, or
Overwrite these values with the CLI flags below.

[podqueue]
opml = podqueue.opml
dest = pq/
log_file = podqueue.log
# Please note, '%' in time_format must be escaped with '%%'
time_format = %%Y-%%m-%%d
verbose = False

CLI arguments

As mentioned, if any of these CLI arguments are specified, they will overwrite any values in the config file.

-o, --opml - Pass an OPML file that contains a podcast subscription list.
-d, --dest - The destination folder for downloads. Will be created if required, including sub-directories for each separate podcast.
-t, --time_format - Specify a time format string for JSON files. Defaults to '%Y-%m-%d' (2022-06-31) if not specified.
-v, --verbose - Prints additional debug information. If excluded, only errors are logged (no stdout for automation).
-l, --log_file - Specify the log file path. Defaults to ./podqueue.log

Where do I get my OPML?

This will depend on your podcast app, but most will be able to export your list of subscriptions into a common XML format.

If you use a different app that has a similar functionality, please let me know and I'll add it to this list.

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.

Your file should look something like this, with one line per podcast:

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<opml version="1.0">
  <head>
    <title>Pocket Casts Feeds</title>
  </head>
  <body>
    <outline text="feeds">
      <outline type="rss" text="Accidental Tech Podcast" xmlUrl="https://atp.fm/episodes?format=rss" />
      <outline type="rss" text="The Unmade Podcast" xmlUrl="https://www.unmade.fm/episodes?format=rss" />
      <outline type="rss" text="You Look Nice Today" xmlUrl="https://feeds.fireside.fm/youlooknicetoday/rss" />
      <outline type="rss" text="The Pen Addict" xmlUrl="https://www.relay.fm/penaddict/feed" />

      ... etc ...

    </outline>
  </body>
</opml>

How to install

Installation is done through Python's pip:

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

Alternatively, you can use Docker to containerise podqueue. This requires two volumes mounts, one for the output location to save podcast files to on the host, and the other to store the podqueue.opml config and log files.

Docker Compose:

services:
  podqueue:
    name: podqueue
    image: tquin/podqueue:latest
    user: "<YOUR UID>:<YOUR GUID>"
    restart: unless-stopped
    volumes:
      - "<YOUR_OUTPUT_DIRECTORY>:/data"
      - "<YOUR_CONFIG_DIRECTORY>:/config"

Docker CLI:

docker pull tquin/podqueue:latest
cat <YOUR_CONFIG_DIRECTORY>/podqueue.opml # Replace this example with your subscription list
docker run -it \
  -v <YOUR_OUTPUT_DIRECTORY>:/data \
  -v <YOUR_CONFIG_DIRECTORY>:/config \
  --restart unless-stopped \
  --user "<YOUR UID>:<YOUR GUID>" \
  tquin/podqueue:latest

Or you can just clone this repo directly:

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

Output

Executing the script will download each podcast into their own subdirectory, with episode metadata (shownotes, date, title, link) and show metadata (episode count, description, image) in each subdirectory. Episodes will be downloaded in default feed order - usually newest first, but it could depend on the podcast.

Example directory tree:

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

And a sample JSON file for an episode (note that description will often be HTML-formatted):

{
    "published_parsed": "2022-04-05",
    "title": "Episode 451: Minitel (Entry 791.IS4209)",
    "link": "https://pdst.fm/e/aphid.fireside.fm/d/1437767933/8658dd0c-baa7-4412-9466-918650a0013d/e373ca83-d5d9-4b8b-b03f-5fcd012ac9a2.mp3",
    "description": "In which a French-only precursor to the World Wide Web appears in the late 1970s in a wave of Gallic futurist fervor, and John may have been making long distance calls from a Parisian prison. Certificate #23054."
}

Todos

Distro packaging
Better config file location, eg $HOME/.config/podqueue.conf
Built-in systemd/cron timers
Option to only download after X date (--no-backlog or --earliest ?)

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

This version

0.1.9

Sep 4, 2023

0.1.8

Sep 4, 2023

0.1.6

Sep 4, 2023

0.1.4

Aug 12, 2023

0.1.3

May 8, 2023

0.1.2

May 4, 2022

0.1.1

Mar 22, 2022

0.1.0

Mar 21, 2022

0.0.9

Mar 21, 2022

0.0.6

Mar 21, 2022

0.0.5

Jan 8, 2022

0.0.4

Jan 7, 2022

0.0.3

Jan 7, 2022

0.0.2

Jan 7, 2022

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

podqueue-0.1.9.tar.gz (13.4 kB view details)

Uploaded Sep 4, 2023 Source

Built Distribution

podqueue-0.1.9-py3-none-any.whl (15.6 kB view details)

Uploaded Sep 4, 2023 Python 3

File details

Details for the file podqueue-0.1.9.tar.gz.

File metadata

Download URL: podqueue-0.1.9.tar.gz
Upload date: Sep 4, 2023
Size: 13.4 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for podqueue-0.1.9.tar.gz
Algorithm	Hash digest
SHA256	`b3929173546418040e5580e8f84ffbdaad377232144a5bcfde6f774c7f1fbbe7`
MD5	`c72626af40ffd59538527c8650d4f200`
BLAKE2b-256	`44defbbf293c99256ab3fb4da2e4232ff29a2fc1190ed5fc162d3bbeb803c6ad`

See more details on using hashes here.

File details

Details for the file podqueue-0.1.9-py3-none-any.whl.

File metadata

Download URL: podqueue-0.1.9-py3-none-any.whl
Upload date: Sep 4, 2023
Size: 15.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for podqueue-0.1.9-py3-none-any.whl
Algorithm	Hash digest
SHA256	`ac0aa24b9fa198a27a81533dcd41a883f6ff705960954d2c8101fe4c94c9315c`
MD5	`b5021e0414986f25af3148c212261357`
BLAKE2b-256	`2845cbfd07ba3b05eac755848cdd890c6580c0632dab23eec92bce38d6a08996`