proginfo - get-iplayer/get_iplayer GitHub Wiki

Programme information

Click here for all display options (Return to ToC)

Click here for all output options (Return to ToC)

Programme metadata

Display the programme metadata for index 123:

get_iplayer --info 123

Display the programme metadata for PID b012hbg5:

get_iplayer --info --pid=b012hbg5

Metadata files

The programme metadata can be downloaded using the --metadata option. Use of --metadata alone is equivalent to --metadata=generic

Save the metadata after a successful download into an XML file in the output directory:

get_iplayer --metadata --get 123

Save only the metadata for a programme into an XML file (but don't record the programme). This is useful if you forgot to download the metadata when recording.

get_iplayer --metadata-only 123

Save the metadata after a successful download into a JSON file in the output directory:

get_iplayer --metadata=json --get 123

Save only the metadata for a programme into a JSON file (but don't record the programme). This is useful if you forgot to download the metadata when recording.

get_iplayer --metadata=json --metadata-only 123

See User Commands for examples of using metadata files during post-processing.

Thumbnail images

A programme thumbnail can be automatically downloaded using the --thumbnail option.

get_iplayer --thumbnail --get 123

Save only the thumbnail for a programme (but don't record the programme). This is useful if you forgot to get the thumbnail when recording.

get_iplayer --thumbnail-only 123

Use --thumbnail-size to specify the width of the image:

get_iplayer --thumbnail --thumbnail-size=1280 --get 123

See output options for supported image widths.

Use --thumbnail-square to retrieve a square version of the image:

get_iplayer --thumbnail --thumbnail-size=960 --thumbnail-square --get 123

Track lists

Use the --tracklist or --tracklist-only option to download music track lists available for some programmes.

get_iplayer --tracklist --get 123

get_iplayer --tracklist-only 123

Track lists are generally available for radio music programmes, but may exist for some TV programmes, such as Top of the Pops. The track list is downloaded to a plain text .tracks.txt file in your output directory.

  • Where available, track timings are included. Track timing data is usually only available for music programmes on national radio stations. The track timing data also may be incorrect at source.
  • When track timing data is available and --start and --stop are used with --tracklist, all tracks are included in the list, but only tracks between --start and --stop will have timings. With --tracklist-only, all tracks and timings are included.

Cue sheets

Use the --cuesheet or --cuesheet-only option to download music track information in the form of a cue sheet (.cue file).

get_iplayer --cuesheet --get 123

get_iplayer --cusheet-only 123

  • Applies to radio programmes only. Only useful with radio programmes that publish track lists on BBC site.

  • Cue sheets are inaccurate since track timing data is often wrong. You must correct cue sheets as needed if you use them to play back or edit downloaded programmes.

  • Cue sheets with erroneous track timings can be re-downloaded with an adjustment applied (specified in seconds, here +5 secs):

      get_iplayer --cuesheet-only --cuesheet-offset 5 123

  • Makes no attempt to identify track ends or air breaks between tracks. You must set track end times manually when editing 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).

  • When --start and --stop are used with --cuesheet, the cue sheet only includes track entries between --start and --stop. With --cuesheet-only, all track entries are included.

Programme credits

Use the --credits or --credits-only option to download programme credits.

get_iplayer --credits --get 123

get_iplayer --credits-only 123

Credits are available for many TV programmes, and a few radio programmes. The credits are downloaded to a plain text .credits.txt file in your output directory.

Update multiple files

As long as your programmes remain in the directory they were originally recorded, you can retrospectively download the thumbnail, metadata or subtitles of the shows using your recordings history, provided that the resources are still available from the iPlayer/Sounds site.

Get all thumbnails for files that still exist on your system (in this case for programmes matching 'Doctor Who'):

get_iplayer --thumbnail-only --history --skipdeleted "Doctor Who"

Get all the metadata (in 'generic' format) for "Doctor Who" files that still exist on your system:

get_iplayer --metadata-only --metadata=generic --history --skipdeleted  "Doctor Who"

Get all subtitles for "Doctor Who" files that still exist on your system:

get_iplayer --subtitles-only --history --skipdeleted "Doctor Who"

Media stream information

Display the various media stream URLs and related info for programme index 123:

get_iplayer --streaminfo 123