faq - get-iplayer/get_iplayer GitHub Wiki

get_iplayer FAQ List

Table of Contents

Basic functions

How do I install get_iplayer on Linux/BSD/macOS/Windows?

See: get_iplayer Installation

How do I get help with using get_iplayer?

See: get_iplayer Documentation

I'm a complete noob. Is there a step-by-step guide to using get_iplayer?

See: Tutorials

How do I start get_iplayer on Windows?

See: Windows installation

How do I enter get_iplayer commands on Windows?

See: Windows installation

How do I search for TV programmes with get_iplayer?

See: Searching for programmes

Also see: TV Guide

How do I record TV programmes with get_iplayer?

See: Recording programmes

Also see: TV Guide

How do I search for radio programmes with get_iplayer?

See: Searching for programmes

Also see: Radio Guide

How do I record radio programmes with get_iplayer?

See: Recording programmes

Also see: Radio Guide

How do I change the output directory for get_iplayer recordings?

See: Filenames and directories

Also see: TV Guide, Radio Guide

How do I record a programme using its episode URL?

See: Recording with episode URL

Also see: TV Guide, Radio Guide

How do I record a programme using its episode PID?

See: Recording with episode PID

Also see: TV Guide, Radio Guide

What is a PID?

See: Recording with episode PID

How do I record TV programmes with audio description?

See: Recording alternate versions

Also see: Audio Described Programmes Guide

How do I record TV programmes with signing?

See: Recording alternate versions

Also see: Signed Programmes Guide

How do I use the PVR functionality in get_iplayer?

See: PVR usage

Also see: PVR Guide

How do I find out which version of get_iplayer I have?

For the CLI, use get_iplayer -V. For the Web PVR Manager, the version is printed at the bottom of the page in the user interface.

How do I find out if a new version of get_iplayer is available?

Use:

get_iplayer --release-check

Alternate method:

Check your current version as described above, then check for new releases:

macOS: https://github.com/get-iplayer/get_iplayer_macos/releases

Windows: https://github.com/get-iplayer/get_iplayer_win32/releases

Other: https://github.com/get-iplayer/get_iplayer/releases

You can subscribe to the lists of releases with a feed reader by appending .atom to the URLs above.

If you use a version of get_iplayer packaged for your system, use your package management tools to check for updates.

How do I create a verbose log to attach to a bug report?

Create a verbose log as shown below. The syntax is the same on all platforms.

get_iplayer [...options...] --verbose > log.txt 2>&1

Troubleshooting - Searching

I can't find a programme with a get_iplayer search. What am I doing wrong?

  • Did you supply a search string? From v3.07, get_iplayer will no longer list all programmes when invoked without a search string. You must supply something to search for. To list all programmes, you must now explicitly specify a wildcard search: get_iplayer ".*" - note the quotes.

  • Did you correctly spell the programme name (or partial name) in your search string?

  • Are you searching for a string in the episode title? By default, get_iplayer only searches the programme (series) name. To search both, use --fields=name,episode.

  • Is the complete programme name a number (e.g., "2525")? You must use a regular expression for your search string. See: Programmes whose name is a number

  • Are you searching for a radio programme? If so, did you use --type=radio in your get_iplayer command? It is required for searching radio programmes.

  • Are you searching for a TV programme with audio description or signing? That search functionality is no longer available in get_iplayer, though you can still use --versions=audiodescribed or --versions=signed when downloading to select the desired version (if available).

  • Are you searching for programmes by category? That search functionality is no longer available in get_iplayer, though category information is still included in the metadata added to programmes after download.

  • Was the programme actually scheduled and broadcast on a BBC linear service? Box sets, iPlayer exclusives, archive programmes, red button programmes, special collections, and BBC podcasts are not indexed by get_iplayer and thus cannot be searched.

  • Was the programme broadcast within the past 30 days? get_iplayer only caches programme index entries for a maximum of 30 days.

  • Have you just installed get_iplayer for the first time? After your first installation of get_iplayer, you much refresh the programme index cache before searching. This should happen automatically, but you can force a refresh. See Indexing and caching.

  • Is the programme a film, newscast or weather forecast? Such programmes, among others, expire in less than 30 days. Films may expire after 1 week and newscasts may expire after 1 day. From v3.00, get_iplayer can no longer track expiry dates for programmes, so unavailable programmes will appear in search results.

  • Is the programme actually available on the iPlayer site? Not every programme will be available, or there may be a delay of up to several days before a programme is made available.

  • Some programmes lack the metadata get_iplayer needs for indexing. These programmes cannot be searched.

  • Is your programme index cache up-to-date? By default, search results won't include programmes that have become available since your last cache refresh.

  • If there was a problem with get_iplayer or with the BBC web site, there may be a gap in the programmes indexed in your cache and thus you may need to rebuild it. See: Rebuilding the cache.

  • When in doubt, use the programme episode PID or URL to download a programme directly (see above). All available programmes can be downloaded via PID or URL regardless of whether or not they are in the get_iplayer cache. In the Web PVR, paste the URL in the Quick URL box and click "Record".

Troubleshooting - Recording

What content can be recorded by get_iplayer?

get_iplayer supports downloading whole episodes of TV and radio programmes broadcast on BBC linear services within the previous 30 days and made available on the iPlayer site. get_iplayer does not support downloading news/sport videos, other embedded media, archive sites, special collections, educational material, programme clips or any other such content. It may be possible to download other content such as iPlayer box sets directly via PID or URL, but such use is not supported.

I can't record a programme with get_iplayer. What am I doing wrong?

  • If you are recording programmes individually, did you enter the correct episode URL or episode PID?

  • Is the programme actually available on the iPlayer site? Not every programme will be available, or there may be a delay of several days before a programme is made available.

  • Can you actually play the programme on the iPlayer site? Sometimes a programme may be listed on the iPlayer site but cannot be played. If a programme is not playable on the iPlayer site, it is probably also not available to get_iplayer.

  • In some cases, attempting to download a programme using its name or PID displayed in search results may generate a "No media streams found" warning because the corresponding programme was posted to the iPlayer site using a different PID than the one listed in the channel schedules (the source for the programme index cache). Find the correct episode URL or episode PID on the iPlayer site and use that instead.

  • Are you outside the UK? Only lower-quality radio programmes are available to international users. Even if you have a VPS, VPN, HTTP proxy or DNS proxy, you may still be blocked by the BBC.

How do I record an entire series?

If the series is still ongoing and episodes are available in get_iplayer search results, then catch up by downloading episodes normally. You can also use the PVR functionality to record an ongoing series. You can download episodes individually via PID or URL if they do not appear in search results. If the series is still available on iPlayer but the episodes have expired from the get_iplayer index cache, see Recursive (series/brand) recording for information on using --pid-recursive to download all episodes in a series. Recursive recording can be used for iPlayer box sets or stacked series.

Does get_iplayer support recording UHD 4K programmes?

No.

Does get_iplayer support live recording?

No.

How do I record FHD/1080p video for TV programmes?

get_iplayer does not record FHD/1080p video by default even if it is available for a TV programme. The resulting media files may be very large and the video quality may not be better than HD/720p. Use --tv-quality=fhd,hd,sd,web,mobile to prefer FHD video if available. See Recording quality for examples and more information on recording quality settings.

How do I record HD/720p video for TV programmes?

get_iplayer records HD/720p video by default if it is available for a TV programme. See Recording quality for examples and more information on recording quality settings.

I have a poor internet connection and I can't record HD video. How can I record lower-quality video?

Specify lower-quality recording. See Recording quality for examples and more information on recording quality settings. For example, to limit TV programmes to the best available non-HD quality, use --tv-quality=sd,web,mobile.

I only listen to speech radio programmes and I don't like 320kbps audio. How can I record lower-quality audio?

Specify lower-quality recording. See Recording quality for examples and more information on recording quality settings. For example, to limit radio programmes to no more than 128kbps, use --radio-quality=std,med,low.

What does it mean when I see the message "WARNING: No media streams found for requested programme versions and recording quality."?

  • Are you outside the UK? get_iplayer attempts to detect when the BBC is blocking you, but it doesn't always work. If not, get_iplayer will see that no streams are available, but it cannot know the reason, so only the above message will be displayed.

  • This message may appear if the requested programme was not made available via iPlayer for contractual or copyright reasons, as is the case for some films.

  • This message may appear if the requested programme has expired on the iPlayer site and thus is no longer available to get_iplayer.

  • In rare cases, this message may mean that the requested programme is listed on the iPlayer site, but the media streams used by get_iplayer are temporarily unavailable or have not been configured on the partner CDN sites.

Should I be concerned when I see a message similar to "non-existing SPS 0 referenced in buffering period" or "SPS unavailable in decode_picture_timing" in get_iplayer output?

These messages comes from the H.264 video decoder in ffmpeg and are printed when re-muxing MPEG-TS files to MP4. As far as is known, the conditions flagged by ffmpeg do not have any effect on get_iplayer re-muxing, so you can ignore these messages.

Why does the download progress display show a percentage complete noticeably less than 100% just before a download finishes?

The file sizes and bit rates provided in media stream metadata may not match the actual sizes and bit rates of the media streams themselves. Therefore, the calculated percentage complete will be <100% when the actual size is less than the size estimated from metadata. As long as the downloaded file is complete you can ignore this.

What does it mean when I see a message similar to "WARNING: File segment not available from server (99) https://..."?

This means that the server was unable to locate a segment of the requested programme - it is not a get_iplayer problem. It does not mean get_iplayer failed to download that segment - it is a server error. Segments are typically missing from only one particular stream, so downloading with different recording quality may provide a workaround. You can also wait a few days to see if the missing segments are restored.

What does it mean when I see a message similar to "ERROR: Failed to download file segment (99) https://..."?

This means that get_iplayer, after several retries, was unable to download a segment of the requested programme. This may be due to server problems or upstream connectivity problems - it is not a get_iplayer problem. These problems are usually transient, so delete any partial download and retry your download at a later time.

What does it mean when I see a message similar to "WARNING: Unexpected size for file segment [99]"?

This means a segment of the requested programme was incomplete. get_iplayer will make several attempts to re-download the segment. This may be due to server problems or upstream connectivity problems - it is not a get_iplayer problem. These problems are usually transient, so delete any partial download and retry your download at a later time.

Troubleshooting - Installation

What do I do if my anti-virus software identifies the get_iplayer Windows installer, or one of its components, as being infected?

Some anti-virus software may flag the installer itself, the generated uninstaller (uninstall.exe) or other components as infected, and thus may quarantine or auto-delete those files. Historically, these have always been false positives, but you must check with your anti-virus vendor to be certain. Do not install get_iplayer if you are at all unsure about the contents of its Windows installer.

Why does sudo apt-get install get-iplayer install an obsolete version of get_iplayer on Ubuntu/Mint?

The get-iplayer packages in old Ubuntu/Mint repositories usually include obsolete and partially broken versions of get_iplayer. You must remove any get_iplayer installed from Ubuntu repositories and perform a manual installation. Also see Ubuntu section in Linux/BSD package installation.

Why do I get an error message when attempting to download with --pid where the programme PID begins with 'm'?

Your get_iplayer is years out of date. Upgrade to the latest release.

Troubleshooting - Web PVR Manager

I can't find a programme with a Web PVR search. What am I doing wrong?

See Troubleshooting - Searching above. Also note that you must click "Refresh Cache" after you open the Web PVR to update get_iplayer's cache with recent programmes. Programmes must be in the cache to be searchable.

Why don't any of the links in the Web PVR Manager work in Google Chrome, Opera or Firefox?

Google Chrome 53, Opera 40 and Firefox 49 implemented a change in the WHATWG HTML specification that broke most of the links in the Web PVR Manager interface. Upgrade to get_iplayer 2.97 or higher to restore functionality in those browser versions (or higher).

Why do I get an "Unknown File Type" warning dialog when launching Web PVR Manager on Windows?

Windows update KB3185319 (2016-09-13) changes the handling of internet shortcut (.url) files in certain locations. The get_iplayer installation directory is one such location, so the internet shortcut used to launch the Web PVR Manager in your browser generates an "Unknown File Type". warning dialog. You can simply click "Open" in the warning dialog to launch the Web PVR Manager as normal. Upgrade to get_iplayer 2.97 or higher to avoid the warning dialog altogether.

On Windows, after I auto-run my PVR list (using the PVR Run tab) for an extended period, the WPM dies with the error Cannot fork at line xxx. What can I do to prevent that?

Upgrade to get_iplayer 2.96 or higher.

When I run my PVR list, the progress information for each programme isn't displayed until the entire programme has been downloaded. Why don't I see a progress bar for each download?

Upgrade to get_iplayer 2.96 or higher.

How do I delete entries from the Recordings tab?

The Recordings tab contains your download history. When you select entries in the Recordings tab and click "Delete", the associated media files are deleted from disk and the entries are greyed out. However, the entries are not removed from your download history. This prevents you from re-downloading a programme you already downloaded. There is generally no need to remove entries from your download history. If you wish to force a deleted programme to be re-downloaded, use the "Force Recording" option. If you really can't abide the presence of old entries in the Recordings tab, you must edit the download history file directly to remove them. The file is typically located at $HOME/.get_iplayer/download_history (Unix/macOS) or C:\Users\%USERNAME%\.get_iplayer\download_history (Windows).

Using outside UK or with VPN/proxy

I am outside the UK and I can't record a programme. What can I do?

Use of get_iplayer outside the UK is not supported, with the exception of downloading lower-quality (96k and 48k) radio programmes that are available to international users. Do not ask for help downloading TV programmes or higher-quality (320k and 128k) radio programmes from outside the UK. Do not discuss methods to circumvent BBC geoblocking in get_iplayer forums. It doesn't matter what VPN/VPS/proxy you use - you may find yourself blocked by the BBC, and get_iplayer can do nothing about it.

I am in the UK, but I am using a VPN, VPS, HTTP proxy or DNS proxy and I can't record a programme. What can I do?

Use of get_iplayer with any VPN/VPS/proxy - even if you are in the UK - is not supported. If the BBC has blocked your VPN/VPS/proxy even though you are in the UK, there is nothing get_iplayer can do about it. If your VPN/VPS/proxy is causing download problems, there is nothing get_iplayer can do to work around them.

Converting files

How do I convert a radio programme into an MP3 file?

The best solution is to use a separate media converter utility on your downloaded files. Also see some related user command examples in documentation.

How do I repackage audio and video from a TV programme into an MKV file?

The best solution is to use a separate media converter utility on your downloaded files. Also see user command examples in documentation.

How do I repackage audio and video from a TV programme into an AVI file?

The best solution is to use a separate media converter utility on your downloaded files. Also see user command examples in documentation.

Advanced topics

My programme index cache doesn't appear to be updating, so searches for recent programmes do not return any results. How can I rebuild the cache?

Rebuild it with get_iplayer --cache-rebuild. Add --type=tv,radio to rebuild both TV and radio caches. See: Rebuilding the cache

Why does it take so long to update the programme index cache?

From v3.00, programme indexing relies on BBC schedule pages, and get_iplayer employs the Mojolicious Perl module to speed up indexing. If you do not install that module, indexing will be very slow. If Mojolicious is installed, you will see the message INFO: Indexing tv programmes (concurrent). If not, you will see INFO: Indexing tv programmes (sequential). Similar messages appear when indexing radio programmes.

How do I create .nfo files for Kodi?

See user command examples in documentation.

Where are preferences stored?

Preferences are stored in a file named options in your profile directory, which is typically $HOME/.get_iplayer for Unix/macOS and C:\Users\%USERNAME%\.get_iplayer for Windows.

Where is the download history stored?

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

Where are the programme index cache files stored?

Cache files are stored in in your profile directory, which is typically $HOME/.get_iplayer for Unix/macOS and C:\Users\%USERNAME%\.get_iplayer for Windows. The files are named tv.cache and radio.cache. The previous versions of those files from before the most recent refresh are found in tv.cache.old and radio.cache.old.

Where are the pvr searches stored?

The pvr searches are stored in a subdirectory named pvr in your profile directory, which is typically $HOME/.get_iplayer for Unix/macOS and C:\Users\%USERNAME%\.get_iplayer for Windows. Each file in that pvr subdirectory contains a single pvr search. If you create pvr searches with the CLI, the files have the names you specified for --pvr-add. Filenames beginning with "ONCE" are for one-off downloads created with --pvr-queue in the CLI or "Queue" links in the Web PVR . Filenames for searches created from the Web PVR are auto-generated from search criteria and have names like _eastenders_name_tv or musical_talent_desc_radio. Filenames can be changed in the Web PVR by editing the value of the pvrsearch field.

Can I run multiple instances of get_iplayer?

Yes. You can open multiple command prompts and run get_iplayer in each one. This may make better use of your available bandwidth. But - this does NOT work with pvr functionality. Only one instance of get_iplayer --pvr (or the Web PVR Manager) can be run.