git-annex/ tips/ downloading podcasts

You can use git-annex as a podcatcher, to download podcast contents. No additional software is required, but your git-annex must be built with the Feeds feature (run `git annex version` to check).

All you need to do is put something like this in a cron job:

`cd somerepo && git annex importfeed http://url/to/podcast http://other/podcast/url`

This downloads the urls, and parses them as RSS, Atom, or RDF feeds. All enclosures are downloaded and added to the repository, the same as if you had manually run `git annex addurl` on each of them.

git-annex will avoid downloading a file from a feed if its url has already been stored in the repository before. So once a file is downloaded, you can move it around, delete it, `git annex drop` its content, etc, and it will not be downloaded again by repeated runs of `git annex importfeed`. Just how a podcatcher should behave. (git-annex versions since 2015 also tracks the podcast `guid` values, as metadata, to help avoid duplication if the media file url changes; use `git annex metadata ...` to inspect.)

## templates

To control the filenames used for items downloaded from a feed, there's a --template option. The default is `--template='${feedtitle}/${itemtitle}${extension}'`

Other available template variables:
feedauthor, itemauthor, itemsummary, itemdescription, itemrights, itemid, itempubdate, author, title.

## catching up

To catch up on a feed without downloading its contents, use `git annex importfeed --relaxed`, and delete the symlinks it creates. Next time you run `git annex addurl` it will only fetch any new items.

## fast mode

To add a feed without downloading its contents right now, use `git annex importfeed --fast`. Then you can use `git annex get` as usual to download the content of an item.

## storing the podcast list in git

You can check the list of podcast urls into git right next to the files it downloads. Just make a file named feeds and add one podcast url per line.

Then you can run git-annex on all the feeds:

`xargs git-annex importfeed < feeds`

## recreating lost episodes

If for some reason git-annex refuses to download files you are certain are in the podcast, it is quite possible it is because they have already been downloaded. In any case, you can use `--force` to redownload them:

`git-annex importfeed --force http://example.com/feed`

## distributed podcatching

A nice benefit of using git-annex as a podcatcher is that you can run `git annex importfeed` on the same url in different clones of a repository, and `git annex sync` will sync it all up.

## centralized podcatching

You can also have a designated machine which always fetches all podcstas to local disk and stores them. That way, you can archive podcasts with time-delayed deletion of upstream content. You can also work around slow downloads upstream by podcatching to a server with ample bandwidth or work around a slow local Internet connection by podcatching to your home server and transferring to your laptop on demand.

## youtube channels

You can also use `git annex importfeed` on youtube channels. It will use yt-dlp to automatically download the videos.

You can either use `git-annex importfeed --scrape` with the url to the channel, or you can find the RSS feed for the channel, and `git-annex importfeed` that url (without `--scrape`).

Use of yt-dlp is disabled by default as it can be a security risk. See the documentation of annex.security.allowed-ip-addresses in git-annex for details.)

## metadata

As well as storing the urls for items imported from a feed, git-annex can store additional metadata, like the author, and itemdescription. This can then be looked up later, used in metadata driven views, etc.

To make all available metadata from the feed be stored: `git config annex.genmetadata true`

How do I switch on the 'feeds' feature?

Joey - your initial post said:

    git-annex must be built with the Feeds feature (run git annex version to check).

...but how do I actually switch on the feeds feature?

I install git-annex from cabal, so I do

    cabal update
    cabal install git-annex

which I did this morning and now `git annex version` gives me:

    git-annex version: 4.20130802
    build flags: Assistant Webapp Pairing Testsuite S3 WebDAV FsEvents XMPP DNS

So it is the latest version, but without Feeds. :-(

Comment by http://a-or-b.myopenid.com/ — Wed Oct 29 14:05:27 2025
comment 8
I've now made importfeed --force a bit smarter about reusing existing files.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
--force reload all URLs
Is it intentionally saving URLs with a prefixed 2_? I have sorted out all missing URLs and renamed it, so no harm done, but it has been a bit of a hassle to get there.
Comment by ckeen — Wed Oct 29 14:05:27 2025
use the force

The only way it can skip downloading a file is if its url has already been seen before. Perhaps you deleted them?

I've made `importfeed --force` re-download files it's seen before.

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Force a reload of a feed?
Currently I have my podcasts imported with --fast. For some reason there are podcast episodes missing. This has been done propably during my period of toying with the feature. If I retry on a clean annex I see all episodes. My suspicion is that git-annex has been interrupted during downloading a feed but now somehow thinks it's already there. How can I debug this situation and/or force git annex to retry all the links in a feed?
Comment by ckeen — Wed Oct 29 14:05:27 2025
comment 4

@nomeata, well, you can, but it has to download the files again.

When run without --fast, `importfeed` does use content based hashes, so if you run it in a temporary directory, it will download the content redundantly, hash it and see it's the same, and add the url to that hash. You can then delete the temporary directory, and the files hpodder had downloaded will have the url attached to them now. I don't know if this really buys you anything over deleting the hpodder files and starting over though.

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Great stuff!

Looking forward to seeing it in Debian unstable; where it will definitely replace my hpodder setup.

I guess there is no easy way to re-use the files already downloaded with hpodder? At first I thought that `git annex importfeed --relaxed` followed by adding the files to the git annex would work, but `importfeed` stores URLs, not content-based hashes, so it wouldn’t match up.

Comment by http://www.joachim-breitner.de/ — Wed Oct 29 14:05:27 2025
howto importfeed youtube playlists (not entire channels)
e.g. channel https://www.youtube.com/channel/UCzLPuKXYJxfwK6Vg7zuqjZQ has two playlists, e.g. one pointed to by https://www.youtube.com/playlist?list=PLIa3r7AIaTikMGfiZlIuArLujETxVfOKP. I had a question "What would be the importfeed url for that one?". Google into this youtube video and the fun is that it is the same approach but need `playlist_id` instead of `channel_id` in the `https://www.youtube.com/playlist?<query>` URL. My immediate problem was that it fetched only last videos... will need to resort to manual treat or alike to feed the rest
Comment by yarikoptic — Wed Oct 29 14:05:27 2025
Tracking GUIDs

@joey - thanks, that's prompt feature request fulfilment :-)

Looking more closely at the duplicates, it turns out that not everything got duplicated, just the "older" episodes. It turns out the newer episodes do have `guid` values saved (as `itemid` in the metadata) and the older episodes do not. I think this is most likely because I was running a fairly old git-annex until about October 2016, on a fairly old OS install, but then upgraded to a more recent one (now about 6 months old) which does track them. My assumption (without checking every file) is the episodes downloaded before October 2016 are ones that got duplicated.

I've edited the main page and added a note that GUIDs are tracked in versions since 2015, since I didn't obviously find that listed anywhere before.

Ewen

Comment by ewen — Wed Oct 29 14:05:27 2025
comment 26

@ewen importfeed already tracks guids, since 2015. Relevant commit is [[!commit f95a8c867223b2e17d036d0d3377bf0fc9d3adff]]

You may well have an older version of git-annex that didn't do that. But there are probably also feeds that lack a useful guid, or that even make a change that changes the guid of an existing item.

With `git annex metadata`, you can see the `itemid` which is where the guid is stored.

PS, please post in todo when you have a request..

Comment by joey — Wed Oct 29 14:05:27 2025
Track GUIDs to avoid duplicate downloads

While tracking podcast media URLs usually works to avoid duplicate downloads, when it fails it usually fails spectacularly. In particular if a podcast feed decides to update all the URLs (for old and new podcasts) to use a different URL scheme, then suddenly that looks like a huge volume of new URLs, and all of them get downloaded again -- even if the content has actually already been retrieved from a different URL (ie, older URL scheme). For instance the `acast.com` service has changed their URL scheme a couple of times in the last 1-2 years, rewriting all the historical URLs, so I have three copies of many of the episodes on podcasts on their service :-( (Many downloaded; some skipped once I caught the bulk download and stopped it/reran with `--fast` or `--relaxed` to make placeholders instead. `acast.com` seem to have managed to cause even more confusion by rewriting many of the older `mp3` files with new `id3` tags, thus changing the file size/hashes -- it definitely made cleaning up more complicated.)

Some (all?) podcast feeds also have a `guid` field, which specifies what should be a unique per-episode and unchanging, that other podcatchers use to track "seen this" content. In theory that `guid` value should be stable even across media URL changes -- at least if it isn't, then a podcaster changing the `guid` and media URL will almost certainly induce re-downloads in most podcatchers, and thus hopefully realise early on (eg, during testing) rather than in production.

Can `git-annex` be extended to track the `guid` values as well as the filenames, so `git annex importfeed` can avoid downloading episodes where it has already processed that `guid`, and instead just add the newly listed url as an alternate web URL for that specific episode (which has been my manual work around). Perhaps the episode `guid` could be stored as additional metadata, along with some sort of feed unique ID (link?), and then an index built/consulted when `importfeed` runs (although that "feed unique ID" would probably also have to be updatable by the user, to cope with "the feed URL has now changed from `http://` to `https://` which also seems to be happening a bunch at present.)

Ewen

PS: Apologies for duplicate partial comment; I think my browser decided some key combination meant "do default form action", which is post -- and I wasn't finished writing. I couldn't see a way to edit the comment, hence deleting/readding.

Comment by ewen — Wed Oct 29 14:05:27 2025
pubDate

@ewen, I tested that feed and it is able to get the pubDate from it and parses it ok.

Most likely, your version of git-annex is not built with a new enough version of the haskell feed library. Version 0.3.9 or newer is needed to be able to extract pubdates. For example, Debian stable doesn't have a new enough version.

Comment by joey — Wed Oct 29 14:05:27 2025
itempubdate

Using a `--template='${feedtitle}/${itempubdate}-${itemtitle}${extension}'` with a libsyn RSS feed (eg, Poly Weekly), I found that `itempubdate` was expanding to "none", even though there is a date with each entry in the RSS, eg,

    <pubDate>Fri, 26 Dec 2014 15:25:38 +0000</pubDate>

Maybe the date string cannot be parsed? But it does look like a fairly typical datestamp to me. If the cause is the mixed-case in the tag, could `pubDate` be supported in addition to `pubdate`? (AFAICT `pubDate` is the standardised mix of lower/upper case, but maybe not the most common, in which case supporting both `pubDate` and `pubdate` might help?) As seen with `git-annex version: 5.20141024~bpo70+1`, installed from Debian Backports; AFAICT it's still the latest release to make it to backports.

For now I'm just omitting "itempubdate" from my template.

Ewen

Comment by ewen — Wed Oct 29 14:05:27 2025
metadata

Good idea, Sazius!

I've made importfeed store the metadata, as long as annex.genmetadata is set in .git/config.

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
comment 21
For some podcast feeds I typically wish to view the description of the show before I decide to download it or not. Is there some way to perform that use case using git annex? I know `itemdescription` is something I can include in the template for the filename, but the descriptions can be really long... doesn't seem very elegant to have that in the file name. Could the description for example be included as metadata of the item?
Comment by Sazius — Wed Oct 29 14:05:27 2025
comment 20

The git-annex man page has a bit more to say about --relaxed and --fast. Their behavior when used with `importfeed` is the same as with `addurl`.

If the podcast feed provides an `itemid`, you can use that in the filename template. I don't know how common that is. Due to the way `importfeed` works, it cannot keep track of eg, an incrementing item number itself.

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
comment 2
@ckeen You seem to be using a filesystem that does not support filenames 150 characters long. This is unusual -- even windows and android can support a filename up to 255 characters in length. `git-annex addurl` already deals with this sort of problem by limiting the filename to 255 characters. If you'd like to file a bug report with details about your system, I can try to make git-annex support its limitations, I suppose.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
comment 19
I would expect user:pass@site.com to work if the site is using http basic auth. `importfeed` just runs `wget` (or `curl`) to do all downloads, and wget's documentation says that works. It also says you can use ~/.netrc to store the password for a site.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
--fast and --relaxed

Hi,

the explanations to --fast and --relaxed on this page could be extended a bit. I looked it up in the man page, but it is not yet clear to me when I would use one or the other with feeds. Also, does “Next time you run git annex addurl it will only fetch any new items.” really only apply to --relaxed, and not --fast?

Furthermore, it would be good if there were a template variable `itemnum` that I can use to ensure that `ls` prints the casts in the right order, even when the titles of the items are not helpful.

Greetings, Joachim

Comment by http://www.joachim-breitner.de/ — Wed Oct 29 14:05:27 2025
rss authentication
If a podcast requires authentication, is there a way to pass credentials through? I tried `http://user:pass@site.com/rss.xml` but it didn't work.
Comment by https://www.google.com/accounts/o8/id?id=AItOawlpKmTa1OPwy5Jk24pOoD8Vlo2jahzTPnw — Wed Oct 29 14:05:27 2025
comment 16
The filename extension is a known issue and already fixed in the development version, see http://git-annex.branchable.com/bugs/importfeed_uses___34____95__foo__34___as_extension/
Comment by arand — Wed Oct 29 14:05:27 2025
No file extension?
It seems git-annex is a bit overzealous when sanitizing the file extension, currently I get: "Nerdkunde/Let_s_go_to_the_D_M_C_A_m4a" from http://www.nerdkunde.de/episodes.m4a.rss with the default template and only "Nerdkunde/Let_s_go_to_the_D_M_C_A._m4a" if I add the "." in the template myself...
Comment by http://23.gs/ — Wed Oct 29 14:05:27 2025
comment 14
Yes, it did turn out to be as simple as my having forgotten that I have to manually add features to the version list.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
comment 13

So I ran `cabal install -v3` and looked at the output,

    Flags chosen: feed=True, tdfa=True, testsuite=True, android=False,
    production=True, dns=True, xmpp=True, pairing=True, webapp=True,
    assistant=True, dbus=True, inotify=True, webdav=True, s3=True

This looks like feed should be on.

There doesn't appear to be any errors in the compile either.

Is it as simple as a bug where this flag just doesn't show in the `git annex version` command?

Comment by http://a-or-b.myopenid.com/ — Wed Oct 29 14:05:27 2025
comment 12

-f-Feed will disable the feature. -fFeed will try to force it on.

You can probably work out what's going wrong using cabal install -v3

Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
comment 11

    $ cabal install feed
    Resolving dependencies...
    All the requested packages are already installed:
    feed-0.3.9.1
    Use --reinstall if you want to reinstall anyway.

Then I reinstalled `git-annex` but it still doesn't find the feeds flag.

    $ git annex version
    git-annex version: 4.20130802
    build flags: Assistant Webapp Pairing Testsuite S3 WebDAV FsEvents XMPP DNS

Do I need to do something like:

    cabal install git-annex --bindir=$HOME/bin -f"-assistant -webapp -webdav -pairing -xmpp -dns -feed"

...but what are the default flags to include in addition to `-feed`

Comment by http://a-or-b.myopenid.com/ — Wed Oct 29 14:05:27 2025
comment 10
`cabal install feed` should get the necessary library installed so that git-annex will build with feeds support.
Comment by http://joeyh.name/ — Wed Oct 29 14:05:27 2025
Filename too long

It seems that some of my feeds get stored into keys that generate a too long filename:

    podcasts/.git/annex/tmp/b1f_325_URL-s143660317--http&c%%feedproxy.google.com%~r%mixotic%~5%urTIRWQK2OQ%Mixotic__258__-__Michael__Miller__-__Galactic__Technolgies.mp3.log.web:
    openBinaryFile: invalid argument (File name too long)

Is there a way to work around this?

Comment by ckeen — Wed Oct 29 14:05:27 2025
Comments on this page are closed.