Skip to main content

Archive all episodes from your favorite podcasts

Project description

Podcast Archiver

Podcast Archiver Logo

version python downloads

Docker Build Tests pre-commit.ci

Maintainability codecov

ruff poetry pre-commit

A fast and simple command line client to archive all episodes from your favorite podcasts.

Podcast Archiver takes the feed URLs of your favorite podcasts and downloads all available episodes for you—even those "hidden" in paged feeds. You'll end up with a complete archive of your shows. The archiver also supports updating an existing archive, so that it lends itself to be set up as a cronjob.

Setup

Install via pipx:

pipx install podcast-archiver

Install via brew:

brew install janw/tap/podcast-archiver

Or use it via Docker:

docker run --tty --rm ghcr.io/janw/podcast-archiver --help

By default, the docker image downloads episodes to a volume mounted at /archive.

Usage

Run podcast-archiver --help for details on how to use it:

podcast-archiver --help

Example invocation

podcast-archiver -d ~/Music/Podcasts \
    -f http://logbuch-netzpolitik.de/feed/m4a \
    -f http://raumzeit-podcast.de/feed/m4a/ \
    -f https://feeds.lagedernation.org/feeds/ldn-mp3.xml

This way, you can easily add and remove feeds to the list and let the archiver fetch the newest episodes for example by adding it to your crontab.

Feeds can also be "fetched" from a local file:

podcast-archiver -f file:/Users/janw/downloaded_feed.xml

Continuous mode

When the --sleep-seconds option is set to a non-zero value, Podcast Archiver operates in continuous mode. After successfully populating the archive, it will not terminate but rather sleep for the given number of seconds until it refreshes the feeds again and downloads episodes that have been published in the meantime.

If no new episodes have been published, no download attempts will be made, and the archiver will go to sleep again. This mode of operation is ideal to be run in a containerized setup, for example using docker compose:

services:
  podcast-archiver:
    restart: always
    image: ghcr.io/janw/podcast-archiver
    volumes:
      - ./archive:/archive
    command:
      - --sleep-seconds=3600  # sleep for 1 hour between updates
      - --feed=https://feeds.feedburner.com/TheAnthropoceneReviewed
      - --feed=https://feeds.megaphone.fm/heavyweight-spot

Changing the filename format

Podcast Archiver has a --filename-template option that allows you to change the particular naming scheme of the archive. The default value for --filename-template. is shown in podcast-archiver --help, as well as all the available variables. The basic ones are:

  • Episode: episode.title, episode.subtitle, episode.author, episode.published_time, episode.original_filename
  • Podcast: show.title, show.subtitle, show.author, show.language

Note here that episode.published_time is a Python-native datetime, so its exact format can be adjusted further a la {episode.published_time:%Y-%m-%d %H%M%S} using strftime-placeholders. By default it uses %Y-%m-%d (e.g. 2024-12-31).

Examples

  • More precise published time

    {show.title}/{episode.published_time:%Y-%m-%d %H%M%S %Z} - {episode.title}.{ext}
    

    Results in …/That Show/2023-03-12 123456 UTC - Some Episode.mp3

  • Using the original filename (roughly equivalent to pre-1.0 --subdirs)

    {show.title}/{episode.original_filename}
    

    Results in …/That Show/ts001-episodefilename.mp3

  • Using the original filename (roughly equivalent to pre-1.0 --subdirs + --date-prefix)

    {show.title}/{episode.published_time} {episode.original_filename}
    

    Results in …/That Show/2023-03-12 ts001-episodefilename.mp3

Using a config file

Command line arguments can be replaced with entries in a YAML configuration file. An example config can be generated with

podcast-archiver --config-generate > config.yaml

After modifying the settings to your liking, podcast-archiver can be run with

podcast-archiver --config config.yaml

Alternatively (for example, if you're running podcast-archiver in Docker), you may point it to the config file using the PODCAST_ARCHIVER_CONFIG=path/to/config.yaml environment variable.

Using environment variables

Some settings of Podcast Archiver are available as environment variables, too. Check podcast-archiver --help for options with env var: … next to them.

Project details


Download files

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

Source Distribution

podcast_archiver-1.7.1.tar.gz (21.3 kB view details)

Uploaded Source

Built Distribution

podcast_archiver-1.7.1-py3-none-any.whl (24.4 kB view details)

Uploaded Python 3

File details

Details for the file podcast_archiver-1.7.1.tar.gz.

File metadata

  • Download URL: podcast_archiver-1.7.1.tar.gz
  • Upload date:
  • Size: 21.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for podcast_archiver-1.7.1.tar.gz
Algorithm Hash digest
SHA256 b04eabb7fb36b1bbe28e90633b2d1165b3cc9db3fcd3b1aa2a196a6f5c62af54
MD5 7d2f782992e406db219caded5b4bc364
BLAKE2b-256 2f808f94fd82d9e9c1777db499f81a688bbd91c62dd169013ea13f04a8d6d1b3

See more details on using hashes here.

Provenance

File details

Details for the file podcast_archiver-1.7.1-py3-none-any.whl.

File metadata

File hashes

Hashes for podcast_archiver-1.7.1-py3-none-any.whl
Algorithm Hash digest
SHA256 7f2a46b42395745aaab8802a43308255523cdd35b493fa30cd9f07b7240252a0
MD5 071c521ad4a2022cc3457ca63cce7bf2
BLAKE2b-256 6679d8a97b7e6098d8ccadcf63e4faff07cb5396a9c932381a0c3b998e130ea1

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page