-
Notifications
You must be signed in to change notification settings - Fork 225
modesref
STOP: Most users only need to configure maximum recording quality, and then only if the defaults are not acceptable. Read the Recording quality document first and configure your maximum recording quality as described there. Only refer to this document if you need to know specifics for a particular recording mode or shortcut.
Click here for all recording options (Return to ToC)
- Recording modes
- Shortcuts
- Recording mode options
- Recording mode details
- Shortcut expansions
- Recording modes and CDNs
- External programs
BBC iPlayer makes programmes available in different streaming formats at multiple levels of video and audio quality. get_iplayer represents each combination of format and quality with an alphanumeric code, referred to as a "mode". The mode value is a combination of a stream type prefix and bit rate/video size suffix. You may have seen references to these: "hvf" + "hd" = "hvfhd", "daf" + "high" = "dafhigh", etc. You can find details of available recording modes below, though in general you will not need to use them directly. Use shortcuts instead.
get_iplayer uses a system of recording mode shortcuts that should work for most users. A shortcut can be a stream type, a quality level, or a combination of the two. A shortcut is expanded into a list of recording modes for get_iplayer to use in selecting which media stream to record. See below for details of how shortcuts are expanded into mode lists.
The mode shortcuts are used for the --modes, --tvmode and --radiomode options of the get_iplayer CLI (command-line interface), the modes, tvmode and radiomode options in your preferences or the Recording Modes field in the get_iplayer WPM (Web PVR Manager). Multiple shortcuts can be specified as a comma-delimited list, with values being processed from left to right. NOTE: Do not insert spaces between mode values.
| Prefix | Description | Usage |
|---|---|---|
| hvf | HLS (Apple HTTP Live Streaming) | TV |
| dvf | MPEG-DASH (Dynamic Adaptive Streaming over HTTP) | TV |
| tv | Combined hvf + dvf | TV (default) |
| haf | HLS (Apple HTTP Live Streaming) | radio |
| hla | HLS (Apple HTTP Live Streaming) | radio (legacy) |
| daf | MPEG-DASH (Dynamic Adaptive Streaming over HTTP) | radio |
| radio | Combined haf + hla + daf | radio (default) |
Maximum quality level can be one of four possible values, in decreasing order of bit rate (radio) or video resolution (TV):
- best
- better
- good
- worst
Maximum quality levels should be prefixed with "tv" or "radio" as appropriate for use with --modes or in the Web PVR.
If you specify only a stream type prefix for one of the mode options (e.g., --radiomode=daf), you will download the best available quality for that stream type. If you specify only a quality level for the value of one of the mode options (e.g., --tvmode=good), you will download the best available quality - up to the level specified - in the default mode list for the given programme type. If a stream at the specified maximum quality level is not available, the best available lower-quality version is used.
Single quality level can be one of several values, in decreasing order of bit rate (radio) or video resolution (TV):
TV
- hd (not available for audiodescribed programmes or with --fps25)
- sd
- high
- low
Radio
- high (not available for some World Service programmes)
- std (not available for some World Service programmes)
- med
- low
Single quality levels should be prefixed with "tv" or "radio" as appropriate for use with --modes or in the Web PVR. Single quality levels can be combined. If no streams at the specified quality level(s) are found, download fails.
The recording quality for programmes is set by one of the mode options shown in the following table. It is recommended that you set separate modes for radio and TV if you do not use the default values. If no type-specific mode (--tvmode, --radiomode) is defined, the --modes option (if supplied) will be used. If you use the --modes option, take care to supply recording modes and shortcuts appropriate to the type(s) of programmes you are downloading. For example, using --modes=hvfhd or --modes=tvgood in a command to download a radio programme will prevent the download from succeeding.
Mode values are supplied as a comma-separated list of values which get_iplayer processes from left to right, e.g., --tvmode=hvfhd,hvfsd,hvfhigh will first try hvfhd, then hvfsd, and so on. The first mode found that matches an available media stream will be used for the download. If the download for the first mode fails, subsequent modes will be tried.
You can determine the recording modes available for a programme with get_iplayer --info <index> or get_iplayer --info --pid <pid>. The listing of available modes will look like:
modes: original: hvfhd1,hvfhd2,hvfhd3,dvfhd1,dvfhd2,hvfsd1,hvfsd2,hvfsd3,dvfsd1,dvfsd2,hvfxsd1,hvfxsd2,hvfxsd3,dvfxsd1,dvfxsd2,hvfhigh1,hvfhigh2,hvfhigh3,dvfhigh1,dvfhigh2,hvfxhigh1,hvfxhigh2,hvfxhigh3,dvfxhigh1,dvfxhigh2,hvflow1,hvflow2,hvflow3,dvflow1,dvflow2,subtitles1,subtitles2
modesizes: original: hvfhd1=1286MB,hvfhd2=1286MB,hvfhd3=1286MB,dvfhd1=1119MB,dvfhd2=1119MB,hvfsd1=747MB,hvfsd2=747MB,hvfsd3=747MB,dvfsd1=620MB,dvfsd2=620MB,hvfxsd1=459MB,hvfxsd2=459MB,hvfxsd3=459MB,dvfxsd1=354MB,dvfxsd2=354MB,hvfhigh1=451MB,hvfhigh2=451MB,hvfhigh3=451MB,dvfhigh1=346MB,dvfhigh2=346MB,hvfxhigh1=274MB,hvfxhigh2=274MB,hvfxhigh3=274MB,dvfxhigh1=182MB,dvfxhigh2=182MB,hvflow1=181MB,hvflow2=181MB,hvflow3=181MB,dvflow1=96MB,dvflow2=96MB,subtitles1=67kB,subtitles2=67kB [estimated sizes only]
NOTE: The modesizes values are only estimates generated from programme metadata and may be quite inaccurate. The actual file sizes cannot be discovered before download.
Recording modes are configured using the options below.
| Options file | Command line | Description |
|---|---|---|
| modes | --modes <mode>,<mode>,... | Recording modes. See --tvmode and --radiomode (with --long-help) for available modes and defaults. Shortcuts: tvworst,tvgood,tvbetter,tvbest,radioworst,radiogood,radiobetter,radiobest (default=default for programme type). |
| radiomode | --radiomode <mode>,<mode>,... | Radio recording modes (overrides --modes): dafhigh,dafstd,dafmed,daflow,hafhigh,hafstd,hafmed,haflow,hlahigh,hlastd,hlamed,hlalow. Shortcuts: best,better,good,worst,haf,hla,daf,hls,dash,high,std,med,low (default=hafhigh,hlahigh,dafhigh,hafstd,dafstd,hafmed,hlamed,dafmed,haflow,hlalow,daflow). |
| tvmode | --tvmode <mode>,<mode>,... | TV recording modes (overrides --modes): dvfhd,dvfsd,dvfxsd,dvfhigh,dvfxhigh,dvflow,hlshd,hvfhd,hvfsd,hvfxsd,hvfhigh,hvfxhigh,hvflow. Shortcuts: best,better,good,worst,dvf,hvf,dash,hls,hd,sd,high,low. 50fps streams (if available) preferred unless --fps25 specified (default=hvfhd,dvfhd,hvfsd,dvfsd,hvfxsd,dvfxsd,hvfhigh,dvfhigh,hvfxhigh,dvfxhigh,hvflow,dvflow). |
The characteristics for all recording modes are shown below for reference: TV Modes, Radio Modes
Prior to April 2018, the BBC made most TV programmes available in an additional HLS format, which get_iplayer denoted with modes using the "hls" prefix. In particular, this included a 1280x720@25fps format, known as "hlshd" mode in get_iplayer. That format is no longer provided for new TV programmes, and the "hls" modes - except for "hlshd" - have been removed for both TV and radio. The "hlshd" mode may still be available for some repeats and box sets. However, the "hlshd" mode is not contained in any shortcut expansions, so it must be specified separately in --modes or --tvmode option values.
Below are representative values for recordings made with each of the TV recording modes.
| Recording Mode | Stream Format | Video Codec | Video Size | Video FPS | Video Bit Rate | Audio Codec | Audio Bit Rate | Overall Bit Rate |
|---|---|---|---|---|---|---|---|---|
| hvfhd | HLS | H.264 | 1280 x 720 | 50 | 4852 kbps | AAC | 320 or 128 kbps(*) | 4991 kbps |
| hvfsd | HLS | H.264 | 960 x 540 | 50 | 2648 kbps | AAC | 320 or 128 kbps(*) | 2787 kbps |
| hvfxsd | HLS | H.264 | 960 x 540 | 25 | 1542 kbps | AAC | 320 or 96 kbps(*) | 1646 kbps |
| hvfhigh | HLS | H.264 | 704 x 396 | 50 | 1481 kbps | AAC | 320 or 128 kbps(*) | 1604 kbps |
| hvfxhigh | HLS | H.264 | 704 x 396 | 25 | 810 kbps | AAC | 320 or 96 kbps(*) | 914 kbps |
| hvflow | HLS | H.264 | 512 x 288 | 25 | 413 kbps | AAC | 320 or 96 kbps(*) | 518 kbps |
| dvfhd | MPEG-DASH | H.264 | 1280 x 720 | 50 | 4852 kbps | AAC | 128 kbps | 4991 kbps |
| dvfsd | MPEG-DASH | H.264 | 960 x 540 | 50 | 2648 kbps | AAC | 128 kbps | 2787 kbps |
| dvfxsd | MPEG-DASH | H.264 | 960 x 540 | 25 | 1542 kbps | AAC | 96 kbps | 1646 kbps |
| dvfhigh | MPEG-DASH | H.264 | 704 x 396 | 50 | 1481 kbps | AAC | 128 kbps | 1604 kbps |
| dvfxhigh | MPEG-DASH | H.264 | 704 x 396 | 25 | 810 kbps | AAC | 96 kbps | 914 kbps |
| dvflow | MPEG-DASH | H.264 | 512 x 288 | 25 | 413 kbps | AAC | 96 kbps | 518 kbps |
| hlshd | HLS | H.264 | 1280 x 720 | 25 | 2280 kbps | AAC | 96 kbps | 2379 kbps |
(*)Audio bit rate depends on available streams and whether or not --hls-lq-audio option is used.
Below are representative values for recordings made with each of the radio recording modes.
| Recording Mode | Stream Format | Audio Codec | Audio Bit Rate | Notes |
|---|---|---|---|---|
| hafhigh | HLS | AAC | 320 kbps | UK only |
| hafstd | HLS | AAC | 128 kbps | UK only |
| hafmed | HLS | AAC | 96 kbps | UK and Intl |
| haflow | HLS | AAC | 48 kbps | UK and Intl |
| hlahigh | HLS | AAC | 320 kbps | UK only (legacy) |
| hlastd | HLS | AAC | 128 kbps | UK only (legacy) |
| hlamed | HLS | AAC | 96 kbps | UK and Intl (legacy) |
| hlalow | HLS | AAC | 48 kbps | UK and Intl (legacy) |
| dafhigh | MPEG-DASH | AAC | 320 kbps | UK only |
| dafstd | MPEG-DASH | AAC | 128 kbps | UK only |
| dafmed | MPEG-DASH | AAC | 96 kbps | UK and Intl |
| daflow | MPEG-DASH | AAC | 48 kbps | UK and Intl |
The tables below detail how recording mode shortcuts are expanded into lists of mode values.
TV shortcut expansions depend on whether or not you use the --fps25 option, which limits downloading to 25fps streams (HD video not available). Without --fps25, 50fps streams (where available) are tried first, with fallback to 25fps streams.
| Shortcut | Modes |
|---|---|
| best | synonym for tvbest |
| better | synonym for tvbetter |
| good | synonym for tvgood |
| worst | synonym for tvworst |
| hd | synonym for tvhd |
| sd | synonym for tvsd |
| high | synonym for tvhigh |
| low | synonym for tvlow |
| Without --fps25 | (default) |
| tvbest | hvfhd,dvfhd,hvfsd,dvfsd,hvfxsd,dvfxsd,hvfhigh,dvfhigh,hvfxhigh,dvfxhigh,hvflow,dvflow |
| tvbetter | hvfsd,dvfsd,hvfxsd,dvfxsd,hvfhigh,dvfhigh,hvfxhigh,dvfxhigh,hvflow,dvflow |
| tvgood | hvfhigh,dvfhigh,hvfxhigh,dvfxhigh,hvflow,dvflow |
| tvworst | hvflow,dvflow |
| tvhd | hvfhd,dvfhd |
| tvsd | hvfsd,dvfsd,hvfxsd,dvfxsd |
| tvhigh | hvfhigh,dvfhigh,hvfxhigh,dvfxhigh |
| tvlow | hvflow,dvflow |
| hvf | synonym for hvfbest |
| hvfbest | hvfhd,hvfsd,hvfxsd,hvfhigh,hvfxhigh,hvflow |
| hvfbetter | hvfsd,hvfxsd,hvfhigh,hvfxhigh,hvflow |
| hvfgood | hvfhigh,hvfxhigh,hvflow |
| hvfworst | hvflow |
| dvf | synonym for dvfbest |
| dvfbest | dvfhd,dvfsd,dvfxsd,dvfhigh,dvfxhigh,dvflow |
| dvfbetter | dvfsd,dvfxsd,dvfhigh,dvfxhigh,dvflow |
| dvfgood | dvfhigh,dvfxhigh,dvflow |
| dvfworst | dvflow |
| With --fps25 | |
| tvbest | hvfxsd,dvfxsd,hvfxhigh,dvfxhigh,hvflow,dvflow |
| tvbetter | hvfxsd,dvfxsd,hvfxhigh,dvfxhigh,hvflow,dvflow |
| tvgood | hvfxhigh,dvfxhigh,hvflow,dvflow |
| tvworst | hvflow,dvflow |
| tvhd | not available |
| tvsd | hvfxsd,dvfxsd |
| tvhigh | hvfxhigh,dvfxhigh |
| tvlow | hvflow,dvflow |
| hvf | synonym for hvfbest |
| hvfbest | hvfxsd,hvfxhigh,hvflow |
| hvfbetter | hvfxsd,hvfxhigh,hvflow |
| hvfgood | hvfxhigh,hvflow |
| hvfworst | hvflow |
| dvf | synonym for dvfbest |
| dvfbest | dvfxsd,dvfxhigh,dvflow |
| dvfbetter | dvfxsd,dvfxhigh,dvflow |
| dvfgood | dvfxhigh,dvflow |
| dvfworst | dvflow |
| Shortcut | Modes |
|---|---|
| best | synonym for radiobest |
| better | synonym for radiobetter |
| good | synonym for radiogood |
| worst | synonym for radioworst |
| high | synonym for radiohigh |
| std | synonym for radiostd |
| med | synonym for radiomed |
| low | synonym for radiolow |
| radiobest | hafhigh,dafhigh,hafstd,dafstd,hafmed,dafmed,haflow,daflow |
| radiobetter | hafstd,dafstd,hafmed,dafmed,haflow,daflow |
| radiogood | hafmed,dafmed,haflow,daflow |
| radioworst | haflow,daflow |
| radiohigh | hafhigh,dafhigh |
| radiostd | hafstd,dafstd |
| radiomed | hafmed,dafmed |
| radiolow | haflow,daflow |
| daf | synonym for dafbest |
| dafbest | dafhigh,dafstd,dafmed,daflow |
| dafbetter | dafstd,dafmed,daflow |
| dafgood | dafmed,daflow |
| dafworst | daflow |
| haf | synonym for hafbest |
| hafbest | hafhigh,hafstd,hafmed,haflow |
| hafbetter | hafstd,hafmed,haflow |
| hafgood | hafmed,haflow |
| hafworst | haflow |
| hla | synonym for hlabest |
| hlabest | hlahigh,hlastd,hlamed,hlalow |
| hlabetter | hlastd,hlamed,hlalow |
| hlagood | hlamed,hlalow |
| hlaworst | hlalow |
BBC iPlayer programmes may be available from more than one content distribution network (CDN). A CDN is an external provider of media streaming services and infrastructure. get_iplayer internally differentiates between available CDNs with a number appended to recording modes. The metadata for a radio programme might show the following:
modes: original: hafhigh1,hafhigh2,hafstd1,hafstd2,hafmed1,hafmed2,haflow1,haflow2
This indicates that the "haf" streams are available from two CDNs. Some programmes may only be available from a single CDN:
modes: original: hafstd1,haflow1
The CDNs that correspond to the "1" and "2" may be different for each invocation of get_iplayer. It is not possible to predict which CDN will be be used for a given recording. In general it is not necessary to specifically designate a CDN when recording a programme. If, for example, get_iplayer cannot download the hafhigh1 stream, it will roll over to the hafhigh2 stream and retry the download.
There may be times when the #1 CDN is not responding properly or rejecting connections. You can force the use of the #2 (higher) CDN by explicitly setting your recording modes with the number appended. An example:
get_iplayer --get 123 --tvmode=hvfhd2,hvfhigh2
Be aware that the #2 CDN in your second attempt may correspond to the problematic #1 CDN from the previous download attempt, so a few retries may be required to get a connection to the working CDN.
If one of the iPlayer CDNs is unavailable or performing poorly, you can exclude its streams using the --exclude-supplier option. This option currently supports three possible values: akamai, limelight and bidi. The bidi CDN is TV-only. Use --info --verbose to see which CDNs serve particular streams (modes) for a programme. Look for lines in the output beginning with "INFO: Found mode". The CDN identifiers are at the ends of those lines. As mentioned above, be aware that the mapping between CDNs and modes may change between invocations of get_iplayer.
The table below shows the external programmes required to convert and tag files produced from each combination of recording mode and output format used by get_iplayer.
NOTE: ffmpeg 3.0 or higher is required to remux dvf downloads. avconv and earlier versions of ffmpeg will not work.
NOTE: ffmpeg 2.5 or higher is required to remux hvf downloads. avconv and earlier versions of ffmpeg will not work.
| Type | Modes | Format | ffmpeg | atomicparsley |
|---|---|---|---|---|
| TV | hlshd, hvfhd, hvfsd, hvfxsd, hvfhigh, hvfxhigh, hvflow | mp4 (h264/aac) | X | X |
| TV | hlshd, hvfhd, hvfsd, hvfxsd, hvfhigh, hvfxhigh, hvflow (with --raw) | mpegts (h264/aac) | --- | --- |
| TV | dvfhd, dvfsd, dvfxsd, dvfhigh, dvfxhigh, dvflow | mp4 (h264/aac) | X | X |
| TV | dvfhd, dvfsd, dvfxsd, dvfhigh, dvfxhigh, dvflow (with --raw) | fragmented m4v/m4a (separate h264/aac files) | --- | --- |
| Radio | hafhigh, hafstd, hafmed, haflow | m4a (aac) | X | X |
| Radio | hafhigh, hafstd, hafmed, haflow (with --raw) | mpegts (aac) | --- | --- |
| Radio | hlaahigh, hlastd, hlamed, hlalow | m4a (aac) | X | X |
| Radio | hlahigh, hlastd, hlamed, hlalow (with --raw) | mpegts (aac) | --- | --- |
| Radio | dafhigh, dafstd, dafmed, daflow | m4a (aac) | X | X |
| Radio | dafhigh, dafstd, dafmed, daflow (with --raw) | fragmented m4a (aac) | --- | --- |