search - get-iplayer/get_iplayer GitHub Wiki
Click here for all search options (Return to ToC)
- Search basics
- Search examples
- Search strings as regular expressions
- Searching the Future Programme Schedule
- Searching the Recording History
get_iplayer can only search for programmes that were scheduled for broadcast on BBC linear services within the previous 30 days, even if some are available for more than 30 days on the iPlayer/Sounds site. Red button programmes, iPlayer box sets, iPlayer exclusives, and BBC podcasts are not searchable. Old programmes that are still available after 30 days must be located on the iPlayer/Sounds site and downloaded directly via PID or URL (see below).
get_iplayer performs searches against a local cache of the programme index it creates with data retrieved from BBC sites. (see Indexing and caching). The cache will automatically be updated with programmes from the past 30 days.
NOTE: 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.
BBC schedule pages are used for indexing programmes, which means:
- You cannot search for programmes by category
- You cannot search for audio described or signed programmes
- You cannot search for web-only (e.g., red button programmes)
- You cannot search for iPlayer box sets
- You cannot search for podcasts
Some programmes that appear in the programme index will not be available via iPlayer, and thus will not be available with get_iplayer. Always check the iPlayer/Sounds site for availability if a programme is not found by a get_iplayer search. By default, search results won't include programmes that have become available since your last cache refresh. You must refresh your cache to search for more recent programmes. See Refreshing the cache.
You may occasionally find that due to problems with get_iplayer or with the BBC web site, there may be a gap in the programmes indexed in your cache and thus search results may not include some recent programmes. In such cases, the solution is to rebuild your cache. See Rebuilding the cache.
Search output appears in this format:
...
208: Doctor Who: Series 7 Part 2 - 1. The Bells of Saint John, BBC One, b01rryzz
209: Doctor Who: Series 7 Part 2 - 2. The Rings Of Akhaten, BBC One, b01rx0lj
210: Doctor Who: Series 7 Part 2 - 3. Cold War, BBC One, b01s1cz7
...
default format = <index>: <name> - <episode>, <channel>, <pid>
The index number is intended as an easy-to-type way to indicate a programme to download (see Recording). However, index numbers are not persistent. They are regenerated every time the cache is updated. You can also use <pid> for recording with the --pid option. The <pid> value is persistent across cache refreshes.
List all TV programmes (--type=tv is default):
get_iplayer ".*"
You must supply a search string. If you wish to list all programmes, explicitly specify a wildcard search as shown above - note the quotes.
List all TV and radio programmes:
get_iplayer --type=tv,radio ".*"
By default, searching uses substring matches. For example, to list all TV programmes with names containing 'news':
get_iplayer --type=tv news
The --type=tv option may be used explicitly as well.
List all radio programmes with names containing 'news':
get_iplayer --type=radio news
List all TV programmes with names containing 'news', but hide programmes already recorded:
get_iplayer --hide news
Search terms containing white space and shell metacharacters must be enclosed in quotes. To list all TV programmes with names containing 'Lost & Found':
get_iplayer "Lost & Found"
The formatting of search results can be customised with the --listformat option. The option value is a format string containing substitution parameters (denoted by angle brackets) that are filled with the corresponding cache field value for that programme.
To list all TV programmes showing only pid, name and episode fields and using a custom format:
get_iplayer --listformat="<pid>: <name>-<episode>" ".*"
Available substitution parameters: <index> <pid> <name> <episode> <seriesnum> <episodenum> <desc> <channel> <available> <expires> <timeadded> <web> (<seriesnum> and <episodenum> are often not available)
Only the name field is searched by default, but searches can be applied to the episode and desc fields using the --fields option.
To search all TV programmes for the word 'hello' in the episode field:
get_iplayer --fields=episode hello
To search all TV programmes for the word 'hello' in the name or episode fields:
get_iplayer --fields=name,episode hello
This applies your search term against a space-delimited concatenation of the indicated fields in the order given (name followed by episode).
The --long option implicitly sets --fields=name,episode,desc. To search all TV programmes for the word 'hello' in the name, episode or desc fields, with expanded output:
get_iplayer --long hello
Because the fields specified with --fields are concatenated with spaces, your search term itself can span fields. Imagine a programme with name="Hello There" and episode="My name is Dolly". The search below would find such a programme:
get_iplayer --fields=name,episode "hello.*dolly"
To search for a particular episode PID:
get_iplayer --fields=pid b0b8rp1k
To search for a particular episode PID using alternative search term format:
get_iplayer pid:b0b8rp1k
Search results can be filtered by channel/station. To list all TV programmes from channel 'BBC One':
get_iplayer --channel="BBC One" ".*"
To exclude all TV programmes from CBBC and CBeebies:
get_iplayer --exclude-channel="CBBC,CBeebies" ".*"
Channel filters also employ substring matching by default. For example:
get_iplayer --type=radio --channel="6 Music" ".*"
can be used in lieu of:
get_iplayer --type=radio --channel="BBC Radio 6 Music" ".*"
Search results can also be filtered by excluding certain programmes by name, though this is rarely useful. For example:
get_iplayer --channel=CBBC Dengineers
returns a list of episodes from several series:
5888: The Dengineers: Series 1 - Football Den, CBBC, b06s614d
5889: The Dengineers: Series 2 - Community Den, CBBC, b0844sdq
5890: The Dengineers: Series 3 - Revisits Episode 1, CBBC, b09f4cd2
5891: The Dengineers: Series 3 - Revisits Episode 2, CBBC, b09g36b4
5892: The Dengineers: Series 3 - Observatory Den, CBBC, b09glkq2
5893: The Dengineers: Series 3 - Christmas Den, CBBC, b09k8q02
5894: The Dengineers: Series 3 - Witchcraft and Wizardry Den, CBBC, b09qjdxd
5895: The Dengineers: Series 4 - Revisits One, CBBC, p06m3qw0
5896: The Dengineers: Series 4 - Revisits Two, CBBC, p06m3r0f
If you already acquired Series 3 from a source other than get_iplayer, you can filter the results to exclude that series:
get_iplayer --channel=CBBC Dengineers --exclude="Series 3"
which returns:
5888: The Dengineers: Series 1 - Football Den, CBBC, b06s614d
5889: The Dengineers: Series 2 - Community Den, CBBC, b0844sdq
5895: The Dengineers: Series 4 - Revisits One, CBBC, p06m3qw0
5896: The Dengineers: Series 4 - Revisits Two, CBBC, p06m3r0f
Search results can be filtered according to when programmes were added to the cache, or according to when they became available via iPlayer.
List all TV programmes added to the cache in the past 24 hours:
get_iplayer --since=24 ".*"
List all BBC Four programmes that have become available in the past week (168 hours):
get_iplayer --available-since=168 --channel="BBC Four" ".*"
List all BBC Four programmes that have become available in the past week (168 hours), but no later than 3 days ago (72 hours):
get_iplayer --available-since=168 --available-before=72 --channel="BBC Four" ".*"
List all radio channels with programmes available (incl. counts):
get_iplayer --list=channel --type=radio ".*"
Search strings and filter criteria are interpreted as regular expressions. If you don't use any regular expression metacharacters in your search string, get_iplayer looks for a simple substring match. get_iplayer searches are case-insensitive.
For example, this search would find all TV programmes with 'east' anywhere in the name ("EastEnders", "East Midlands Today", "Minibeast Adventure", etc.):
get_iplayer "east"
whereas this search would only find TV programmes with 'east' at the beginning of their names (^ anchors match to beginning of string), followed by a whitespace character (represented by \s), which would match "East Midlands Today", but not "EastEnders"):
get_iplayer "^east\s"
Search strings for other fields are also interpreted as regular expressions. To search for all radio programmes on Radio 4 but not on Radio 4 Extra, use a regular expression to anchor a match for the channel name to the end of the string:
get_iplayer --type=radio --channel="Radio 4$" ".*"
You can use (or remove) anchors to make matches more (or less) specific. For example:
get_iplayer "^Bargain Hunt: Series 49$"
will match only episodes from series 49 of Bargain Hunt, while:
get_iplayer "^Bargain Hunt"
will match episodes from any series of Bargain Hunt
To search for a programme whose complete name is a number, use a regular expression to anchor a match at the beginning of the string. The regular expression differentiates the search string from an index number:
get_iplayer "^2012"
On the command line, always quote search strings containing regular expressions.
It is possible to index, search and queue recordings for specific programmes that have not yet been made available. This is currently only available for BBC TV and radio programmes up to 14 days in advance. Note that some of the programmes in the BBC schedules are never released on iPlayer and therefore will never get recorded even if you can find them in the search results. Note that indexing can take quite a bit longer with --refresh-future specified.
Refresh the cache with future schedules (e.g. for TV). You must do this otherwise you will not be able to search for future programmes:
get_iplayer --refresh-future --refresh
Save the refreshing of future programmes into your default settings (a good idea if you want the above to be automatic):
get_iplayer --add-prefs --refresh-future
To search for a programme additionally in the future just use any of the usual search commands but adding --future:
get_iplayer "Eastenders" --future
You cannot record a programme in the future but you can queue it in the PVR for recording when it becomes available (if at all). In this example the index of the search results for a future episode of Eastenders was '123′:
get_iplayer --pvr-queue 123
The recording history is a text database of the programmes you have recorded since you started using get_iplayer. Its primary purpose is to prevent get_iplayer from downloading the same programme more than once. You can search the recordings history much like the normal programme types. The history is stored in a file named download_history in your profile directory, which is typically $HOME/.get_iplayer for Unix/macOS and C:\Users\%USERNAME%\.get_iplayer for Windows.
Search for "Doctor Who" in the history
get_iplayer --history "Doctor Who""
Show detailed programme metadata for all recorded programmes matching “Doctor Who” in the history
get_iplayer --history "Doctor Who" --info
Download thumbnails for all recorded programmes matching “Doctor Who” in the history
get_iplayer --history "Doctor Who" --thumbnail-only
Download thumbnails for all recorded programmes matching “Doctor Who” in the history and where the media file hasn't been deleted.
get_iplayer --history "Doctor Who" --thumbnail-only --skipdeleted