-
Notifications
You must be signed in to change notification settings - Fork 231
search
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
NOTE: 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 site. BBC Three programmes, iPlayer exclusives, and BBC podcasts are not searchable. Old programmes that are still available after 30 days must be located on the iPlayer 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.
BBC schedule pages are used for indexing TV 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., BBC Three) and red button programmes
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 site for availability if a programme is not found by a get_iplayer search.
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
...
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
List all TV programmes with names containing 'Lost & Found':
get_iplayer "Lost & Found"
Search terms containing white space and shell metacharacters must be enclosed in quotes.
List all TV programmes showing only pid, name and episode fields and using a custom format:
get_iplayer --listformat="<pid>: <name>-<episode>" ".*"
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> <episode>). The other field that may be useful for searching is desc, the episode description.
Because the specified fields are concatenated with spaces, your search term 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"
Search all TV programmes for the word 'hello' in the name, episode or desc fields, with expanded output:
get_iplayer --long hello
The --long option implicitly sets --fields=name,episode,desc.
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" ".*"
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 ".*"
List all programme metadata and available recording modes for programme with index number 123:
get_iplayer --info 123
Search strings are interpreted as regular expressions. If you don't use any regular expression metacharacters in your search string, get_iplayer looks for a 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