cache - get-iplayer/get_iplayer GitHub Wiki

Indexing and caching

Click here for all config options (Return to ToC)

Cache basics

get_iplayer maintains a local cache of programme data indexed from channel schedule pages on the BBC web site. This is used for searching and support of PVR functionality. Key points to remember:

  • get_iplayer does NOT maintain a complete index of all programmes available on BBC iPlayer/Sounds. The primary function of the index cache is to support PVR functionality.
  • Indexing only covers programmes scheduled for broadcast on BBC linear services in the past 30 days. iPlayer exclusives, red button programmes, archives, special collections, podcasts, and similar items are not indexed since they do not appear in channel schedules. The get_iplayer cache will only ever contain a fraction of all programmes available via iPlayer/Sounds.
  • get_iplayer tops up its cache to 30 days of programme listings whenever the cache is updated. If you have not updated in several weeks, indexing will take longer. Initial updates after a fresh installation will also take much longer than normal.
  • Once the cache has been updated in the current week, the previous week(s) are no longer indexed. If you should need to re-index programmes from previous weeks, see Rebuilding the cache.
  • All programmes will be retained in the cache for 30 days even if they should expire sooner (availability information is not available from channel schedule pages). This means that unavailable programmes will appear in search results. Many of these are ephemeral programmes such as newscasts and weather forecasts, but some unavailable entertainment programmes and films will also be returned in search results. Always check the iPlayer/Sounds site for availability.
  • No programme is retained in the cache for longer than 30 days, regardless of how long it is available from the iPlayer/Sounds site.
  • Cache files are stored in your profile directory, which is typically $HOME/.get_iplayer for Unix/macOS and C:\Users\%USERNAME%\.get_iplayer for Windows. The files are named tv.cache and radio.cache.
  • Whenever a cache file is updated, the previous version is now saved in your profile directory with .old appended to the file name. If you encounter any problems, you can restore the previous cache file by copying the .old backup over the current version.

Programme types

By default, get_iplayer only indexes and searches for TV programmes. You can configure it to index and search both TV and radio programmes with:

get_iplayer --prefs-add --type=tv,radio

Or just radio programmes:

get_iplayer --prefs-add --type=radio

Refreshing the cache

The programme index cache is automatically updated whenever its files haven't been updated for the period of time defined by --expiry (default 4 hours).

Refresh the TV programme cache (or whatever you have defined for --type in preferences:

get_iplayer --refresh

Refresh the TV and radio programme caches:

get_iplayer --refresh --type=tv,radio

Alternative syntax to refresh the TV and radio caches:

get_iplayer --refresh --type=all

You can also use --refresh to force a cache update at any time. If you haven't updated for several weeks and don't want to backfill your cache up to its full 30 days, use an appropriate value for the --refresh-limit option to constrain programme indexing.

get_iplayer --refresh --refresh-limit=15 --type=tv,radio

Don't automatically update cache until it is at least a day old:

get_iplayer --get 123 --expiry=86400

Effectively suppress automatic cache update by setting --expiry to a huge number:

get_iplayer --get 123 --expiry=99999999

Filtering channels for indexing

You can greatly speed up indexing by configuring get_iplayer to ignore channels that are not of interest. Examples:

Exclude kiddie channels, but index all others:

get_iplayer --prefs-add --refresh-exclude="CBBC,CBeebies"

Index only kiddie channels:

get_iplayer --prefs-add --refresh-include="CBBC,CBeebies"

Index only Radio 4 and Radio 4 Extra (assumes --type in preferences includes "radio"). The string "Radio 4" will match both channels:

get_iplayer --prefs-add --refresh-include="Radio 4"

Index only Radio 4 (assumes --type in preferences includes "radio"). The regular expression "Radio 4$" will match only Radio 4:

get_iplayer --prefs-add --refresh-include="Radio 4$"

You can also exclude/include channels by group. There are three groups for both TV and radio: "national", "regional" and "local". The contents of the groups can be found here. Examples:

Except for short-lived local news bulletins, there are very few unique programmes on local BBC One variants. They can be ignored with:

get_iplayer --prefs-add --refresh-exclude-groups-tv="local"

If you are not interested in programmes on any local radio stations, they can be excluded with:

get_iplayer --prefs-add --refresh-exclude-groups-radio="local"

There is also a combined syntax to exclude the same group(s) for both TV and radio:

get_iplayer --prefs-add --refresh-exclude-groups="local"

Exclusion/inclusion of individual channels can layered onto group exclusions/inclusions. Examples:

To exclude all regional and local TV channels as well kiddie channels:

get_iplayer --prefs-add --refresh-exclude-groups-tv="regional,local" --refresh-exclude="CBBC,CBeebies"

To exclude all regional and local radio stations as well as news/talk radio:

get_iplayer --prefs-add --refresh-exclude-groups-radio="regional,local" --refresh-exclude="Radio 5 live,World Service"

To exclude all regional and local TV channels except BBC Two England and BBC One London:

get_iplayer --prefs-add --refresh-exclude-groups-tv="regional,local" --refresh-include="BBC Two England,BBC One London"

To exclude all regional and local radio stations except Radio Scotland and Radio Kent:

get_iplayer --prefs-add --refresh-exclude-groups-radio="regional,local" --refresh-include="Radio Scotland,Radio Kent"

Rebuilding the cache

If your cache should ever become corrupted, or you find that it is missing some programmes broadcast on the BBC within the past 30 days, you can rebuild it with:

get_iplayer --cache-rebuild --type=tv,radio

Omit the --type option to cache only TV programmes. You can also apply --refresh-exclude[-groups] and --refresh-include[-groups] options as you can with --refresh. Rebuilding your cache can be a slow process since it restores a full 30 days of programme listings.

You can rebuild only a portion of the cache by refreshing with --refresh-limit to specify the number of previous days to re-index:

get_iplayer --cache-rebuild --refresh-limit=15 --type=tv,radio