record - get-iplayer/get_iplayer GitHub Wiki

Recording programmes

Click here for all recording options (Return to ToC)

NOTE: For information on how to configure file names and output directories for recorded programmes, see Filenames and Directories.

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

Recording basics

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. 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

Recording with episode URL

If you cannot find a programme in get_iplayer search results, but it is available on the iPlayer site or Sounds 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.

Only URLs in the forms shown below are valid. Note that all valid URLs contain the episode PID. get_iplayer requires the PID in order to download the associated episode.

https://www.bbc.co.uk/programmes/<pid>
https://www.bbc.co.uk/iplayer/episode/<pid>/...
https://www.bbc.co.uk/iplayer/cbbc/episode/<pid>/...
https://www.bbc.co.uk/iplayer/cbeebies/episode/<pid>/...
https://www.bbc.co.uk/radio/play/<pid>
https://www.bbc.co.uk/sounds/play/<pid>

Note also that some episode URLs found on the dedicated sites for CBBC and CBeebies will not work with get_iplayer because they do not contain episode PIDs. These URLs are in the forms:

https://www.bbc.co.uk/cbbc/watch/...
https://www.bbc.co.uk/cbeebies/watch/...

Search the iPlayer site or Sounds site to find valid URLs for such programmes (if they exist).

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

Recording with episode PID

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

Re-recording a programme

When a programme is successfully recorded, it is logged in the download_history file in get_iplayer's profile directory ($HOME/.get_iplayer or %USERPROFILE%\.get_iplayer 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. Also be aware that generated names for output files may change over time due to changes in BBC programme data or changes in get_iplayer settings. If you delete your download history or use --force, the --overwrite option is not guaranteed to prevent a duplicate download.

Prevent recording a programme

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)'

Recording alternate versions

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 radio programmes may be available in "podcast" and non-podcast versions, with the former having music clips removed or other edits made for podcast distribution. Use the --versions option to indicate the version(s) acceptable for 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. get_iplayer uses "default" as a pseudo-version that represents the first available version (that is not "audiodescribed" or "signed") found in programme metadata (as determined by built-in heuristics).

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.

Download a TV programme without signing if a version with signing is not available:

get_iplayer --get 123 --versions=signed,default

where "default" is used to indicate the first available version without signing.

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 "podcast" version of a radio programme, with fallback to non-podcast version:

get_iplayer --get 12345 --versions=podcast,default

Multiple versions with the same base name will have a digit appended to the additional instances, e.g., "audiodescribed" and "audiodescribed2". For a TV programme with "audiodescribed" and "audiodescribed2" versions, prefer download of "audiodescribed2" to "audiodescribed" ("audiodescribed" would be tried first otherwise), with fallback to other available version if necessary:

get_iplayer --get 12345 --versions=audiodescribed2,audiodescribed,default

Unless you require TV programmes with audio description or signing, or podcast edits for radio programmes, you are extremely 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

Recursive (full series/brand) recording

get_iplayer can download all episodes for a programme brand or for a single series within a brand. This is "recursive" recording.

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. To find the PID you need to download a brand or series, first locate an iPlayer/Sounds page where you can play any episode of that brand or series and follow the examples below.

With recursive recording, be aware that programme clips will not be downloaded. Recursive recording can be used for iPlayer box sets, stacked series, or certain podcasts that are made available all at once. It can also be used for brands/series released normally over a period of time.

TV Example: Doctor Who

Navigate to the iPlayer page for Doctor Who Series 1 Episode 1;

https://www.bbc.co.uk/iplayer/episode/b0074dlv/doctor-who-series-1-1-rose

Click the "Programme website" link near the bottom of the page, which will take you to the programmne information page for Doctor Who:

https://www.bbc.co.uk/programmes/b006q2x0

Click the "All Available Episodes" link in the "On iPlayer" section of the programme information page, which will take you to an episode list for all series of Doctor Who:

https://www.bbc.co.uk/iplayer/episodes/b006q2x0/doctor-who

Note the presence of "episodes" - plural - in the URL. This URL contains the PID you need for recursive recording of all episodes in all series of Doctor Who:

get_iplayer --pid b006q2x0 --pid-recursive [...]

CBBC/CBeebies: For CBBC/CBeebies programmes, the programme information page URL may look different. e.g., https://www.bbc.co.uk/cbeebies/shows/hey-duggee. Click "Choose an Episode" under "On iPlayer" to naviage to the full episode list.

In order to find the PID for a single series, e.g., Doctor Who Series 13, click the "Series 13" link on that page, which will take you to the episode list for Series 13:

https://www.bbc.co.uk/iplayer/episodes/b006q2x0/doctor-who?seriesId=m00116r6

Note the addition of a "seriesId" parameter to the URL. Use that parameter value as the PID for recording of all episodes in series 13:

get_iplayer --pid m00116r6 --pid-recursive [...]

NOTE: This method may not work for CBBC/CBeebies programmes.
NOTE: If a series link URL does not contain a seriesId parameter, click on a different series link, then click back to the original series link to add seriesId to the URL. If there is only one series available, a seriesId parameter value is not needed.

Radio Example: Sherlock Holmes

Navigate to the Sounds page for The Further Adventures of Sherlock Holmes Series 2 Episode 1:

https://www.bbc.co.uk/sounds/play/b007k4dc

Click the "Programme Website" link near the bottom of the page, which will take you to the programme information page for the episode:

https://www.bbc.co.uk/programmes/b007k4dc

Click "See all episodes from Sherlock Holmes" under "More Episodes" (alternative: click "Episodes" on the navigation bar), which will take you to an episode list for all series of Sherlock Holmes:

https://www.bbc.co.uk/programmes/b01j9gzs/episodes/player

Again, note the presence of "episodes" - plural - in the URL. This URL contains the PID you need for recursive recording of all episodes in all series of Sherlock Holmes:

get_iplayer --pid b01j9gzs --pid-recursive [...]

Alternative: Click "More Episodes" on the initial Sounds player page to navigate to an alternate episode list:

https://www.bbc.co.uk/sounds/brand/b01j9gzs

In order to find the PID for a single series, e.g., The Further Adventures of Sherlock Holmes Series 2, return to the programme information page:

https://www.bbc.co.uk/programmes/b007k4dc

Click the "The Further Adventures of Sherlock Holmes - Series 2" link under the episode title ("The Abergavenny Murder"), which will take you to the information page for Series 2:

https://www.bbc.co.uk/programmes/b007gfc2

Click "All Available Episodes" under "Available Now", which will take you to the episode list for Series 2:

https://www.bbc.co.uk/programmes/b007gfc2/episodes/player

This URL contains the PID you need for recursive recording of all episodes in Series 2:

get_iplayer --pid b007gfc2 --pid-recursive [...]

Notes on recursive recording

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

The --pid-recursive-type option is not applied to listings from --pid-recursive-list, nor is it applied when only downloading auxiliary resources (e.g., --metadata-only).

Recording only part of a programme

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.

Configuring recording quality

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 "highest video resolution” 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.