-
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 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 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). After your first installation of get_iplayer, you must refresh the programme index cache each calendar week for a month in order to build up 30 days of listings. Once that is done, the 30-day buffer will be maintained as long as you refresh once per calendar week.
BBC schedule data is 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.
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. The <pid> value is persistent across cache refreshes.
List all TV programmes (--type=tv is default):
get_iplayer
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.
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 since 24 hours ago:
get_iplayer --since=24
List all available radio channels:
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 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$"
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" --thumbnailonly
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" --thumbnailonly --skipdeleted