-
Notifications
You must be signed in to change notification settings - Fork 233
record
Click here for all recording options (Return to ToC)
- Recording basics
- Recording with episode URL
- Recording with episode PID
- Re-recording a programme
- Prevent recording a programme
- Recording alternate versions (incl. audiodescribed, signed)
- Recording an entire series/brand
- Recording only part of a programme
- Configuring recording quality
NOTE: get_iplayer does not support downloading news/sport videos, other embedded media, archive sites, special collections, educational material, programme clips or any content other than whole episodes of programmes broadcast on BBC linear services within the previous 30 days, plus episodes of BBC Three programmes posted within the same period. It may be possible to download other content such as red button programmes or iPlayer box sets directly via PID or URL (see below), but such use is not supported. get_iplayer DOES NOT support live recording from BBC channels.
In its simplest form, recording only requires you to add --get to your search commands to record the matching programmes. You can also record single programs by PID or URL (see below).
Record TV programme number 123 (index number from search results):
get_iplayer --get 123
Record radio programme number 10123 (index number from search results):
get_iplayer --get 10123
Record TV programme number 123 and save in /home/user/TV-files/:
get_iplayer --get 123 --output "/home/user/TV-files/"
Record radio programme number 30123 and TV programme number 324:
get_iplayer --get 30123 324
Record all radio programmes with "Bells on Sunday" in name:
get_iplayer --type=radio --get "Bells on Sunday"
Record all TV programmes with "blue peter" in name:
get_iplayer --get "blue peter"
Record all TV programmes with "blue peter" in the title, plus programme index 123:
get_iplayer --get "blue peter" 123
Record all programmes with 'hello' in the name, episode or description:
get_iplayer --long --get hello
If you cannot find a programme in get_iplayer search results, but it is available on the iPlayer site or iPlayer Radio site, you can download it directly using its episode URL (or episode PID - see below). The episode URL is the URL of the web page containing the media player for the specific episode of interest. In other words, it is the web page where you can actually play your programme.
Record a radio programme using its episode URL on the Sounds site:
get_iplayer https://www.bbc.co.uk/sounds/play/b07hfwrr
Record a radio programme using the episode URL from its programme website:
get_iplayer https://www.bbc.co.uk/programmes/b07hfwrr
Record a TV programme using its episode URL on the iPlayer site:
get_iplayer https://www.bbc.co.uk/iplayer/episode/b01sc0wf/Doctors_Series_15_Perfect
Record a TV programme using the episode URL from its programme website:
get_iplayer https://www.bbc.co.uk/programmes/b01sc0wf
get_iplayer detects that you have provided a URL, but you may also use the more explicit form with --url:
get_iplayer --url=https://www.bbc.co.uk/programmes/b07hfwrr
Recording multiple URLs requires --url:
get_iplayer --url=https://www.bbc.co.uk/programmes/b07hfwrr --url=https://www.bbc.co.uk/programmes/b07hfwxx
See BBC Programme Identifier for a description of PIDs.
You simply extract the PID from a programme's episode URL (see above):
get_iplayer --pid=b07hfwrr
get_iplayer --pid=b01sc0wf
You do not need to use --get with --pid.
There are several ways to download multiple PIDs. For programmes from the last 30 days catalogued in the local index cache, you can explicitly match against the pid field (ignored by default) in the cache:
get_iplayer --get --fields=pid b012h9yn b012hbg5
or you can use the pid: prefix to denote that your search terms are PIDs:
get_iplayer --get pid:b012h9yn pid:b012hbg5
You can also bypass the index cache and record multiple PIDs with the --pid option:
Comma-separated list
get_iplayer --pid=012h9yn,b012hbg5
Multiple --pid options
get_iplayer --pid=b012h9yn --pid=b012hbg5
When a programme is successfully recorded, it is logged in the download_history file in get_iplayer's profile directory ($HOME/.get_iplayer/options or %USERPROFILE%\.get_iplayer\options in Windows). If a programme is in the download history it cannot be re-downloaded unless you explicitly use the --force option, e.g.:
get_iplayer --pid=b01sc0wf --force
If an output file with exactly the same name already exists, --force will not overwrite it. You must also add the --overwrite option:
get_iplayer --pid b01sc0wf --force --overwrite
Exercise caution when overwriting files.
Use the --mark-downloaded option to prevent downloading programmes found in search results that you already have or do not want. This is done by inserting records for one or more programmes into the download history. These entries can still be overridden by --force. Examples:
$ get_iplayer troy
Matches:
7575: Troy: Fall of a City: Series 1 - Conditions, BBC One, b09tm9kv
7576: Troy: Fall of a City: Series 1 - Siege, BBC One, b09vf7c0
7577: Troy: Fall of a City: Series 1 - Spoils of War, BBC One, b09w375q
7578: Troy: Fall of a City: Series 1 - Hunted, BBC One, b09wzybb
INFO: 4 matching programmes
# use cache index for one or more episodes
$ get_iplayer --mark-downloaded 7575 7576
Matches:
7575: Troy: Fall of a City: Series 1 - Conditions, BBC One, b09tm9kv
7576: Troy: Fall of a City: Series 1 - Siege, BBC One, b09vf7c0
INFO: 2 matching programmes
INFO: Mark downloaded tv: 'Troy: Fall of a City: Series 1 - Conditions (b09tm9kv)'
INFO: Mark downloaded tv: 'Troy: Fall of a City: Series 1 - Siege (b09vf7c0)'
# marked episodes can be excluded from search results
$ get_iplayer --hide troy
Matches:
7577: Troy: Fall of a City: Series 1 - Spoils of War, BBC One, b09w375q
7578: Troy: Fall of a City: Series 1 - Hunted, BBC One, b09wzybb
INFO: 2 matching programmes
# can also use --pid or --url
$ get_iplayer --mark-downloaded --pid b09w375q
Episodes:
Troy: Fall of a City: Series 1 - Spoils of War, BBC One, b09w375q
INFO: 1 total programmes
INFO: Mark downloaded tv: 'Troy: Fall of a City: Series 1 - Spoils of War (b09w375q)'
# mark all matching episodes in search results
$ get_iplayer --mark-downloaded "Troy: Fall of a City: Series 1"
Matches:
7575: Troy: Fall of a City: Series 1 - Conditions, BBC One, b09tm9kv
7576: Troy: Fall of a City: Series 1 - Siege, BBC One, b09vf7c0
7577: Troy: Fall of a City: Series 1 - Spoils of War, BBC One, b09w375q
7578: Troy: Fall of a City: Series 1 - Hunted, BBC One, b09wzybb
INFO: 4 matching programmes
INFO: Mark downloaded tv: 'Troy: Fall of a City: Series 1 - Conditions (b09tm9kv)'
INFO: Mark downloaded tv: 'Troy: Fall of a City: Series 1 - Siege (b09vf7c0)'
INFO: Mark downloaded tv: 'Troy: Fall of a City: Series 1 - Spoils of War (b09w375q)'
INFO: Mark downloaded tv: 'Troy: Fall of a City: Series 1 - Hunted (b09wzybb)'
A single iPlayer programme episode may be available in several versions. For example, some TV programmes may be available with and without signing or audio description. Some programmes may be available in "original" and "editorial" versions, with the latter being edited after transmission. Some radio programmes may be available in "original" and "podcast" versions, with the latter having music clips removed or other edits made for podcast distribution. Multiple versions with the same base name will have a digit appended to the additional instance, e.g., "iplayer" and "iplayer2" versions. Use the --versions options to indicate the version you wish to download.
Download a TV programme with audio description, with no download if a version with audio description is not available:
get_iplayer --get 123 --versions=audiodescribed
Download a TV programme with signing, with no download if a version with signing is not available:
get_iplayer --get 123 --versions=signed
Multiple versions may be specified as a comma-delimited list, with values being processed from left to right. get_iplayer will attempt to download the first version found.
Download a TV programme without audio description if a version with audio description is not available
get_iplayer --get 123 --versions=audiodescribed,default
where "default" is used to indicate the first available version without audio description.
Sometimes only an audiodescribed version may be available, or a version without audio description may be mislabelled. Download a TV programme with audio description if a version without audio description is not available
get_iplayer --get 123 --versions=default,audiodescribed
Download the "original" version of a TV programme, but use the "editorial" version if the "original" version is not available:
get_iplayer --get 12345 --versions=original,editorial
Download the "podcast" version of a radio programme, but use the "original" version if the "podcast" version is not available:
get_iplayer --get 12345 --versions=podcast,original
For a TV programme with "iplayer" and "iplayer2" versions, prefer download of "iplayer2" ("iplayer" would be tried first otherwise):
get_iplayer --get 12345 --versions=iplayer2,iplayer
Unless you require TV programmes with audio description or signing, you are unlikely to need --versions. The default version determined by get_iplayer is nearly always what you want.
You can discover what versions of a programme are available by using the --info option:
get_iplayer --info 123
PIDs can also reference brands or series as well as individual programme episodes. You can find the relevant PID in the brand/series home page URL. For example, the brand home page for Casualty is:
https://www.bbc.co.uk/programmes/b006m8wd
so the brand PID is 'b006m8wd'. The brand home page can usually be accessed via the "Programme website" link on iPlayer episode pages for TV programmes or the "Home" link on iPlayer Radio episode pages for radio programmes. The series home page for Casualty Series 32 is:
https://www.bbc.co.uk/programmes/b092jkyg
so the series PID is 'b092jkyg'. The series home page can usually be accessed via the linked series name on an episode information page for both TV and radio programmes, e.g., "Series 32" on this page:
https://www.bbc.co.uk/programmes/b0b5ydb8
get_iplayer can use brand/series PIDs to recursively download all episodes in the brand or series:
get_iplayer --pid=b006m8wd --pid-recursive
The value for --pid is the brand/series PID and --pid-recursive instructs get_iplayer to examine the brand/series metadata to pick out the associated episode PIDs and download them. If you are using a brand/series PID, be aware that programme clips will not be downloaded. Recursive recording can be used for iPlayer box sets, stacked series, BBC Three programmes, or certain podcasts that are made available all at once. It can also be used for brands/series released over a period of time.
Recursive recording of a brand/series will first print a list of the enclosed episodes. If you want to record specific episodes and not the entire brand/series, use --pid-recursive-list to print the list of available episodes without attempting download:
get_iplayer --pid=b006m8wd --pid-recursive-list
You can then pick out the PID(s) for the desired episode(s) and use them with --pid
Previously downloaded episodes can be excluded with --hide:
get_iplayer --pid=b006m8wd --pid-recursive --hide
If a series contains a mix of TV and radio programmes, you can limit your downloads to only one programme type with --pid-recursive-type:
get_iplayer --pid b007r6vx --pid-recursive --pid-recursive-type=tv
Option value is not reflected in listings from --pid-recursive-list, nor is it applied when only downloading auxiliary resources (e.g., --metadata-only).
Use --start and --stop options to record only part of a programme. The values of --start and --stop can be expressed in seconds or in hh:mm:ss format:
get_iplayer --get 123 --start=00:15:30 --stop=01:30:45
get_iplayer --get 123 --start=930 --stop=5445
You can use --start without --stop, and vice versa.
iPlayer programmes are streamed in several formats and quality levels. However, you can also pick specific media streams or maximum quality levels for recording. See Recording quality for details.
With default settings, get_iplayer will download the best quality stream for your programme. "Best" means "largest video size" for TV programmes and "highest audio bit rate" for radio programmes. However, you may prefer to use lower quality streams to save bandwidth and disk space. For example, HD TV downloaded with default settings requires 2GB+ per hour of video, so if that is too much for your needs you may wish to configure get_iplayer to restrict the maximum quality of downloads. See Configuring recording quality for information.