Skip to content

modesref

notnac edited this page Jul 13, 2019 · 40 revisions

Recording modes reference

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

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.

Shortcuts

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.

Stream types

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 levels

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 levels

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.

Recording mode options

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

Recording mode details

The characteristics for all recording modes are shown below for reference: TV Modes, Radio Modes

TV modes

"hlshd" mode

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.

Radio modes

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

Shortcut expansions

The tables below detail how recording mode shortcuts are expanded into lists of mode values.

TV shortcuts

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

Radio shortcuts

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

Recording modes and CDNs

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.

External programs

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) --- ---
You can’t perform that action at this time.