get_iplayer 3.29 - 2022-02-08

get_iplayer 3.28 - 2021-12-08

get_iplayer 3.27 - 2021-02-15

get_iplayer 3.26 - 2020-06-28

get_iplayer 3.25 - 2020-02-01

get_iplayer 3.24 - 2019-12-29

get_iplayer 3.23 - 2019-11-29

get_iplayer 3.22 - 2019-08-19

get_iplayer 3.21 - 2019-07-14

get_iplayer 3.20 - 2019-02-25

There is a breaking change in this release

• Fixed bug that caused searches to fail when target episode title in cache contained vertical bar (|) characters. Vertical bars now converted to hyphens.

• Adjusted stream classification to accommodate BBC changes

  • 960x540@25 streams are apparently no longer provided for programmes first broadcast after approximately 2021-12-05. The are still available for older programmes, including recent repeats.
  • 960x540@25 streams for new programmes have been replaced by 960x540@50 streams with the same bit rate. get_iplayer now detects these lower-bitrate 50fps streams and classifies them appropriately. Use --tv-lower-bitrate to prefer those streams if they are available. The file sizes should be roughly the same as the previous 25fps streams. You do not need to change your preferences.

• Restored BBC Three schedules to the programme indexing to accomodate its return as a broadcast channel. Perform a full rebuild of the TV programme index cache if you want to ensure it includes all supported BBC Three programmes:

    get_iplayer --rebuild-cache
  

  Ignore these warnings, as there were no BBC Three schedule listings for that week:

    WARNING: Got 0 programmes for BBC Three schedule page (HTML): https://www.bbc.co.uk/schedules/p00fzl95/2022/w01
  
    WARNING: Failed to parse BBC Three schedule page: https://www.bbc.co.uk/schedules/p00fzl95/2022/w01
  

• Options related to recording quality have been changed

  • Some command iine parameters have been renamed:

    Old	New	Option Key
    --modes	--quality	modes
    --tv-mode	--tv-quality	tvmode
    --radio-mode	--radio-quality	radiomode
    --fps25	--tv-lower-bitrate	fps25

    The old command-line option names are scheduled for removal in the next release. The option keys (used in preferences, presets, and PVR searches) remain the same, so recording quality settings in existing preferences, presets, and PVR searches will continue to work.

  • The possible recording quality settings have been reduced to:

    Type	Quality Settings	Aliases	Default
    TV	fhd,hd,sd,web,mobile	1080p,720p,540p,396p,288p	hd,sd,web,mobile
    Radio	high,std,med,low	320k,128k,96k,48k	high,std,med,low

    In the next release, it will be a fatal error to enter an invalid quality setting on the command line. Aliases can be used interchangeably with their corresponding alphabetic codes. The two substantive changes are that TV "high" quality is now "web", and TV "low" quality is now "mobile". This makes TV and radio quality settings distinct sets that can be mixed unambiguously for --quality and the Web PVR Manager. All recording quality settings that cannot be translated into values from the lists above are discarded. See Recording Quality for further information. See below for more information about the "fhd" quality setting.

  • BREAKING CHANGE: Existing quality settings (or recording modes) saved in preferences, presets, and PVR searches will be translated into new quality settings in a backwards-compatible manner, with one exception. If your saved values have prefixes denoting stream format (hls,hvf,had,dash,dvf,daf), or numeric suffixes for specific streams, those prefixes and suffixes are now stripped and ignored. You should never use numeric suffixes since they are non-deterministic. In the unlikely event you need to restrict the stream formats to record, use the new --exclude-format option. --exclude-format=dash will exclude MPEG-DASH streams, and --exclude-format=hls will exclude HLS streams.

  • If you have not specifed at least one of sd,web,high with --tv-quality when downloading an audiodescribed programme, get_iplayer will now insert those quality settings to ensure a stream is available. HD is not available for audiodescribed programmes.

• Changes to programme metadata fields

  • No longer included in XML/JSON metadata files: durations, geoblocked, modes, modesizes, unavailable, verpids, versions. Use --info to see available version-dependent metadata values.
  • Now included in XML/JSON metadata files: quality, verpid
  • No longer displayed with --info unless --verbose is also specified: modes, modesizes
  • Now displayed with --info: qualities, qualitysizes

• Changes to application options

  • --purge-files has been removed.

  • --trim-history and --no-purge are now ignored and will be removed in the next release. You can remove them from your preferences with:

      get_iplayer --prefs-del --trim-history=0 --no-purge
    

    get_iplayer will no longer issue a warning to remove downloaded programmes more than 30 days old.

• EXPERIMENTAL: Full HD streams (1080p)

  • Before anyone asks: UHD 4k streams are still not available to get_iplayer.

  • get_iplayer now attempts to generate 1920x1080@50 ("fhd") stream URLs for every programme that has 1280x720@50 ("hd") streams (so no audiodescribed programmes). The purpose of these 1080p streams is not known. They may be used for some smart TVs or set-top boxes, or they may be a BBC experiment.

  • It is not a bug if "fhd" streams are not available for a programme. Do not depend on the presence of these streams. They may disappear at any time. They are provided solely for you to experiment with if you find them useful. You may decide that the video quality of "fhd" streams does not justify their extra download and storage requirements.

  • The "fhd" streams are not included by default, nor are they included when expanding the obsolete "best" shortcut if it is saved in your preferences, presets, or PVR searches. You must request "fhd" downloads specifically with --tv-quality=fhd or --tv-quality=1080p. This is done in part to avoid resource shock for the presumed majority of users who don't read release notes and documentation, but also because the quality of "fhd" streams varies greatly. If you wish to include "fhd" in your default settings, save it in your preferences:

      get_iplayer --prefs-add --tv-quality=fhd,hd,sd,web,mobile
    

  • The bit rates for the "fhd" streams can vary quite a bit between programmes. The maximum appears to be around 10 Mb/s (though most are far lower), so output files could be up to ~90% larger than their "hd" equivalents, in the region of 3.8 GB/hr for video. Most will have far lower bit rates, sometimes lower than their "hd" equivalents, likely due to more sophisticated compression techniques being employed.

  • Because of the method used to access the "fhd" streams, get_iplayer can't estimate their actual bit rates, so it assumes 8 Mb/s, the value advertised in iPlayer metadata. Consequently, file size estimates and download progress reports may be quite far off.

  • It has been observed in initial testing that MPEG-DASH "fhd" downloads are much faster than HLS equivalents, so MPEG-DASH streams are tried first, while the opposite is true for non-"fhd" streams. This makes no difference to the output. The extra post-processing time required for MPEG-DASH is more than offset by the faster download. You can test the difference with --tv-quality=fhd --exclude-format=hls and --tv-quality=fhd --exclude-format=dash.

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Web PVR: Fixed wrapping of long lines in programme info page
• Fixed bug that caused some episodes to be skipped when using --pid-recursive with certain CBeebies/CBBC programmes
• Added support for "cloudfront" CDN. You can now use --exclude-supplier="cloudfront" if necessary.
• The modes and modesizes programme info fields are now shown in an abbreviated form. Individual streams are no longer listed, only available quality levels.
• The "vbidi" CDN is now excluded by default. It is inaccessible to get_iplayer and generates useless warnings derived from 403 responses to requests for HLS master playlists.

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Removed deprecated --tag-utf8 option
• For a programme downloaded multiple times, history search now returns the most recent entry with an extant media file instead of the oldest entry.
• Web PVR
  • Programme info pages and help page now open in new window/tab
  • Play* links now open in new window/tab
  • Play* links are no longer displayed for deleted files
  • Play Direct links should now work in Firefox, Chrome, Edge (but not Safari) With Remote Streaming type = Auto
  • Play Direct links are now only displayed where MP4/M4A files (or MP3 files from obsolete versions of get_iplayer) are available
  • Removed Quicktime, AVI streaming formats
  • Added MPEG-TS, Matroska, AAC, Vorbis streaming formats
• Windows: Fixed incorrect documentation link in installer finish screen
• macOS: get_iplayer should work on Apple Silicon systems via Rosetta 2, but this has not been verified. The developers do not have access to an Apple Silicon system.
• get_iplayer 3.27 or higher is required with Mojolicious 9.0+. Earlier releases of Mojolicious will continue to work with get_iplayer 3.27 or higher.

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Restored download of programme credits - broken by BBC changes.

• Restored channel names to --pid-recursive-list output - broken by BBC changes.

• Restored subtitle colours - broken by BBC changes.

• Media streams mislabelled as belonging to the defunct BBC Store are no longer ignored - a few may contain valid content.

• Fixed hash initialisation in Pvr class (@praxilian)

• Added new --cuesheet-offset option (synonym: --tracklist-offset) that can be used to apply a positive or negative offset to track times in cue sheet or track list. If you find track times off by a consistent amount after download, use --cuesheet-only with --cuesheet-offset=<n> or --tracklist-only with --tracklist-offset=<n> (where n = offset in seconds) to generate a new cue sheet or track list with adjusted track times.

• The default value of the --thumbnail-size option is now 1920, which downloads a 1920x1080 image. The previous default was 192, which downloaded a 192x108 image. This larger default size should work better on TVs and larger devices, but it will still scale down for smaller devices and media manager software.

  • If you have added --thumbnail-size to your preferences, it will continue to be used.

  • This change will add ~200KB to the size of tagged output files, compared to the previous default.

  • If you wish to restore the previous default thumbnail size:

      get_iplayer --prefs-add --thumbnail-size=192
    

• Thumbnail size is now automatically limited to 1280 when --thumbnail-square is used, in order to avoid distorted images.

• The @wrt atom in metadata tags (iTunes: Composer field) is now set to "BBC Sounds" for radio programmes. The value is still set to "BBC iPlayer" for TV programmes.

• The --tag-utf8 option is now ignored and will be removed in the next release. It hasn't served any useful purpose for some time. To remove it from your preferences if necessary:

    get_iplayer --prefs-del --tag-utf8
  

• The minimum version of Perl nominally required for get_iplayer is now 5.16, in line with recent changes in requirements for the Mojolicious module. This requirement is not yet enforced in get_iplayer code since some combinations of older Perl and Mojolicious versions will still work. This only concerns Linux users doing manual installations, and who for some reason attempt to install new versions of Mojolicious with obsolete versions of Perl, so it is unlikely to apply to you.

• get_iplayer previously allowed a PVR run to continue even if the previous run might still be active, as long as 12 hours had elapsed since the previous run was launched, on the presumption that after 12 hours the previous run must be hung. That is no longer the case.

  • If an invalid (e.g., due to disk write error) PVR lockfile is found, get_iplayer deletes the lockfile and exits with an error and an instruction for you to check if get_iplayer PVR is already running before restarting.
  • If a valid PVR lockfile is found and the previous run is still active, get_iplayer will now always exit with an error regardless of whether or not 12 hours has elapsed. It now prints the process ID associated with the running PVR so that you can check the process status if necessary.
  • get_iplayer is not prone to hanging as it sometimes was when it relied on rtmpdump and ffmpeg for downloading, so this change should have little effect on you. One possible exception is if you try to use get_iplayer in Windows Subsystem for Linux v1 (WSL 1), where AtomicParsley always hangs and thus hangs every PVR run. Don't use get_iplayer on WSL 1. AtomicParsley does work with WSL 2.

• Ubuntu/Mint (and other Ubuntu-based distros) only: The Ubuntu PPA is dead, long live the Ubuntu PPA

  • Shortly after the release of v3.26, the PPA formerly at launchpad.net/~jon-hedgerows/+archive/ubuntu/get-iplayer was deleted by its maintainer.
  • A new third-party PPA has been provided. See: Linux/BSD package installation for upgrade information.

• Raspbian/Raspberry PI only: The Raspbian repository is dead, long live the Raspbian repository

  • Shortly after the release of v3.26, the repository previously at packages.hedgerows.org.uk was deleted by its maintainer.
  • A new third-party repository has been provided. See: Linux/BSD package installation for upgrade information.

• Windows only: Metadata tagging changes

  • Metadata tags are now encoded as Unicode (UTF-8) by default, equivalent to the behaviour on other platforms. This requires workarounds for Windows Perl limitations and a customised version of AtomicParsley (provided with Windows installer). This change will make your files a bit more portable to other platforms and may save a bit of post-download tag editing.
  • If you encounter problems with the new Unicode tagging, it can be bypassed with the new --tag-no-unicode option.
  • If Unicode tagging fails or is bypassed with --tag-no-unicode, get_iplayer falls back to the previous non-Unicode method that converts tags to a single-byte encoding. The "cp1252" encoding (Windows code page 1252) is used by default, which should be appropriate for all programmes supported by get_iplayer.
  • The new --tag-encoding option can be used to set an alternate character encoding for single-byte conversion, but you shouldn't need to use it for any programme supported by get_iplayer. This option has been included for testing and as future-proofing against any edge cases.
  • If Unicode tagging fails or is bypassed with --tag-no-unicode, characters that cannot be converted to the single-byte encoding are no longer removed from metadata tags, but are replaced with XML character references, e.g., "знали" becomes знали. This should only occur in rare cases where the default encoding is used and metadata contains text in a non-Roman script, e.g., a Cyrillic song title in a programme track list that was added to metadata tags via --tag-tracklist.
    • Before converting XML character references, first load the file into Mp3tag and use its "Convert codepage" action to convert the metadata tags back to Unicode (there may be other methods to accomplish this). The XML character references will remain in the converted metadata.
    • You should then be able to copy and paste XML character references into an online editor that renders HTML (e.g., Dillinger) and then copy the rendered UTF-8 characters back into your file using Mp3tag (or equivalent). Desktop applications that can render HTML should be able to perform the same function (e.g., the HTML view in MediaInfo).
    • The expansion of unencoded characters into XML character references may lead to tag values that are too long and are thus truncated during tagging (you may see warnings issued by AtomicParsley). This should only be a problem when most or all of the metadata tags are in a non-Roman script, which is not the case for programmes supported by get_iplayer. If you download such programmes and Unicode tagging does not work for some reason, be sure to set the proper encoding with --tag-encoding, e.g., "cp1251" (Windows code page 1251) for metadata tags in Cyrillic.
  • NOTE: In a future release, metadata tagging on Windows will be Unicode-only. The options for single-byte encoding will be removed. They have been provided as a fallback should problems arise in this initial implementation.

• Windows only: 64-bit version available

  • There is now a 64-bit version of get_iplayer for Windows (Intel/AMD only).
  • A 32-bit version is still available, and it will still work on 64-bit systems.

• macOS only: Initial release broken

  • The initial 3.26.0 version of the macOS installer package, released on 2020-06-28, was broken and was withdrawn on 2020-06-29. The installed get_iplayer script couldn't locate the bundled version of ffmpeg, so downloaded files were not converted to MP4 and metadata tags were not applied. You will see the message "WARNING: Required ffmpeg utility not found - not converting .ts file(s)" for each download.

  • To correct this problem, all users should install the updated 3.26.1 version:

    https://github.com/get-iplayer/get_iplayer_macos/releases/tag/3.26.1

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Restored track list and cue sheet generation broken by BBC changes.

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Restored 25fps HLS streams omitted from v3.23.
• Removed --hls-lq-audio option. It will now generate an error if used.
• Added --mpeg-ts option. If MPEG-TS is your preferred output format (e.g., for device compatibility), use this option to ensure output files are in proper MPEG-TS format regardless of the stream format (HLS or DASH). This is identical to --raw for HLS streams, but the DASH raw format is different. If you have been using --raw to generate MPEG-TS output, switch to --mpeg-ts (which overrides --raw).

Users of macOS 10.15 (Catalina) and higher should not use the --tag-podcast, --tag-podcast-radio and --tag-podcast-tv options if also using the new Music, Podcasts, and TV apps from Apple. Those options may prevent get_iplayer output files from being imported into the new apps. Users of Windows and older macOS releases, which have the old unitary iTunes app, can continue to use those options.

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Adapted for BBC changes that caused "403 Forbidden" errors when attempting to download HLS streams (the default).
  • The --hls-lq-audio option is now ignored and will be removed in the next release. 320k audio for TV programmes is no longer available, so the option has no effect.
  • 320k/96k HLS streams (hafhigh and hafmed recording modes) for radio programmes are no longer available, except for 96k HLS streams for some World Service programmes. DASH streams are still available for those bit rates. Some older programmes may still have 320k/96k HLS streams available, but they should eventually disappear. EDIT: 320k HLS streams (hafhigh mode) have since returned, though they may only be available for the podcast versions of World Service programmes.
  • If you use default settings for download quality (which should be the case for most users), you do not need to change anything. The best quality available will still be downloaded by default.
  • If you don't use default settings, you may need to adjust your recording modes for radio programmes. The hafhigh and hafmed modes will still be accepted, but they likely will have no effect. Recording modes for TV programmes should not need changes.
• Added CBeebies Radio to programme indexing
• Radio button labels in Web PVR Manager are now clickable (@hintswen)
• Fixed a bug that caused get_iplayer to fail with Perl 5.16 (@llewelld)
• Fixed a bug that caused PVR searches for Proms programmes to download both TV and radio episodes even if --type=radio was specified.

Windows 7 and 8 are no longer formally supported. In practice this means that should get_iplayer or any of its dependencies become incompatible with Windows 7 or 8, no fix will be supplied. It also means that any Windows-related bug reports will only be evaluated on the latest version of Windows 10, since the developers will no longer have access to Windows 7 or 8. However, get_iplayer should continue to run on Windows 7 and 8 for the time being.

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Fixed schedule page parsing used for cache updates. This was broken by BBC changes and manifested as a series of “WARNING: Got 0 programmes...” messages during cache updates. Your cache will not update without this fix. If you find that some programmes are still missing from your cache, use --cache-rebuild to perform a full rebuild.
• get_iplayer now recognises previously-unknown programme versions (e.g., "legal") when the "default" pseudo-version is specified in the value of the --versionlist option.
• The --pid-recursive-type option is now applied when only downloading auxiliary resources (e.g., --subtitles-only).
• Fixed programme title extraction with --pid-recursive to prevent unwanted extra text being appended to title in episode listing (e.g., for Proms programmes).

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Added --release-check option to check for new releases
  • If used on the command line (get_iplayer --release-check) an immediate check is made.
  • If added to preferences (get_iplayer --prefs-add --release-check) a weekly check is made. The modification time on the "release_check" file in your profile directory is used to determine when a check is due.
  • Accesses release feeds from GitHub repositories.
  • get_iplayer is NOT automatically updated with --release-check . It only prints a message notifying you that a new release is available.
• Added --cuesheet and --cuesheet-only options to download track information in the form of a cue sheet (.cue file).
  • Applies to radio programmes only. Only useful with radio programmes that publish track lists on BBC site.
  • You cannot assume cue sheets to be accurate since track data is often wrong. You must correct cue sheets as needed if you use them to play back or edit downloaded programmes.
  • get_iplayer makes no attempt to identify air breaks between tracks. You must set track end times manually if you use cue sheets to edit downloaded programmes.
  • You will need to add a UTF-8 BOM (byte order mark) to cue sheets so that non-ASCII characters are displayed properly in some applications, e.g., foobar2000. This can be done with any capable text editor, or in the Notepad "Save" dialog with Encoding = "UTF-8 with BOM" (Windows 10) or Encoding = "UTF-8" (Windows 7).
• --subs-embed now implies --subs-mono. If you use --subs-embed, you no longer need to use --subs-mono.
  • Embedded subtitles are rendered in a single colour, so this change ensures that embedded subtitles have leading hyphens to denote changes of speaker.
  • This change also ensures that the external SRT file is formatted the same as the embedded subtitles. If you wish to create an external SRT file with colour subtitles along with embedded subtitles, use --subtitles-only --no-subs-embed --no-subs-mono --overwrite to re-download colour subtitles and replace the SRT file.
• Added --metadata=json option to create metadata file in JSON format (.json file). Content is the same as default XML-format metadata files (produced by --metadata without format value specified).
• Added --pid-recursive-type option to limit recursive downloads to programmes of specified type (radio or tv) when series includes both radio and TV programmes. Option value is not reflected in listings from --pid-recursive-list, nor is it applied when only downloading auxiliary resources (e.g., --metadata-only). Requires --pid-recursive.
• Added <sesortx> substitution parameter. See definition in Substitution Parameters. This parameter provides an additional option for constructing sortable file names with --file-prefix.
• The --pid option can no longer be saved in the default options file, where it could break subsequent downloads. It can still be saved in presets and used with --pvr-queue.
• The installer-supplied wrapper script that launches a standalone Web PVR Manager server has been renamed from get_iplayer.cgi to get_iplayer_cgi (macOS) and from get_iplayer.cgi.cmd to get_iplayer_cgi.cmd (Windows).
• Implemented a workaround for a deficiency in Windows Perl that caused "Wide character in print" warnings.
• Implemented a workaround to avoid Can't locate object method "subtitles_available" error when using --pid-recursive with --subtitles or --subtitles-only with mixed TV/radio series.
• Fixed a bug that caused the channel name to be tagged as "BBC iPlayer" when downloading individual programmes with --pid.
• Fixed a bug that caused downloads to fail when using default settings if the only available version of a radio programme was "podcastX" (where X = 2,3,...).

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki

• Fixed a bug in v3.19 that caused a "Can't use an undefined value as an ARRAY reference" error when using --pid-recursive or --pid-recursive-list with programmes that have no available episodes

• Fixed a bug in v3.19 that prevented Windows users from viewing and editing PVR searches in the Web PVR Manager.

• EDIT: If you find that BBC Scotland programmes of interest are missing from search results, force all available BBC Scotland programmes to be indexed and cached with (ignore any 404 errors):

    get_iplayer --refresh --refresh-include="BBC Scotland" --refresh-limit=30
  

v3.20 was released soon after v3.19, which was withdrawn. See the get_iplayer 3.19 release notes for other recent changes.

See: https://github.com/get-iplayer/get_iplayer/wiki/installation

See: https://github.com/get-iplayer/get_iplayer/wiki