get_iplayer man page

get_iplayer — Stream Recording tool and PVR for BBC iPlayer

Synopsis

get_iplayer [<options>] [<regex|index> ...]

get_iplayer --get [<options>] <regex|index> ...
get_iplayer <url> [--type=<type> <options>]

get_iplayer <pid> [--type=<type> <options>]

get_iplayer --refresh [--type=<type> <options>]

Description

get_iplayer lists, searches and records BBC iPlayer TV and radio programmes.

get_iplayer has two modes: recording a complete programme for later playback, and as a Personal Video Recorder (PVR), subscribing to search terms and recording programmes automatically.

If given no arguments, get_iplayer updates and displays the list of currently available TV programmes. Use --type=radio for radio programmes Each available programme has an alphanumeric identifier (PID).

In PVR mode, get_iplayer can be called from cron to record programmes on a schedule.

Options

Search Options

--available-since <hours>

Limit search to programmes that have become available in the last <hours> hours

--before <hours>

Limit search to programmes added to the cache before <hours> hours ago

--category <string>

Narrow search to matched categories (comma-separated regex list).  Defaults to substring match.  Only works with --history.

--channel <string>

Narrow search to matched channel(s) (comma-separated regex list).  Defaults to substring match.

--exclude <string>

Narrow search to exclude matched programme names (comma-separated regex list).  Defaults to substring match.

--exclude-category <string>

Narrow search to exclude matched categories (comma-separated regex list).  Defaults to substring match.  Only works with --history.

--exclude-channel <string>

Narrow search to exclude matched channel(s) (comma-separated regex list).  Defaults to substring match.

--expires-before <hours>

Limit search to programmes that will expire in the next <hours> hours

--fields <field1>,<field2>,...

Searches only in the specified comma separated fields

--future

Additionally search future programme schedule if it has been indexed (refresh cache with: --refresh --refresh-future).

--history

Search/show recordings history

--long, -l

Additionally search in programme descriptions and episode names (same as --fields=name,episode,desc )

--search <search term>

GetOpt compliant way of specifying search args

--since <hours>

Limit search to programmes added to the cache in the last <hours> hours

--type <type>,<type>,...

Only search in these types of programmes: radio,tv,all (tv is default)

Display Options

--conditions

Shows GPLv3 conditions

--debug

Debug output

--dump-options

Dumps all options with their internal option key names

--help, -h

Intermediate help text

--helpbasic, --usage

Basic help text

--helplong

Advanced help text

--hide

Hide previously recorded programmes

--info, -i

Show full programme metadata and availability of modes and subtitles (max 40 matches)

--list <element>

Show a list of distinct element values (with counts) for the selected programme type(s) and exit.  Valid elements are: 'channel'

--listformat <format>

Display programme data based on a user-defined format string containing substitution parameters (such as <pid>, <name>, <episode>, etc.)

--long, -l

Show extended programme info

--manpage <file>

Create man page based on current help text

--nocopyright

Don't display copyright header

--page <number>

Page number to display for multipage output

--pagesize <number>

Number of matches displayed on a page for multipage output

--quiet, -q

Reduce logging output

--series

Display programme series names only with number of episodes

--show-cache-age

Display the age of the selected programme caches then exit

--show-options

Show options which are set and where they are defined

--silent

No logging output except PVR download report.  Cannot be saved in preferences or PVR searches.

--sort <fieldname>

Field to use to sort displayed matches

--sortreverse

Reverse order of sorted matches

--streaminfo

Returns all of the media stream URLs of the programme(s)

--terse

Only show terse programme info (does not affect searching)

--tree

Display programme listings in a tree view

--verbose, -v

Show additional output (useful for diagnosing problems)

--warranty

Displays warranty section of GPLv3

-V

Show get_iplayer version and exit.

Recording Options

--attempts <number>

Number of attempts to make or resume a failed connection.  --attempts is applied per-stream, per-mode.  Many modes have two or more streams available.

--exclude-supplier <supplier>,<supplier>,...

Comma-separated list of media stream suppliers to skip.  Possible values: akamai,limelight

--force

Ignore programme history (unsets --hide option also).  Forces a script update if used with -u

--fps50

Prefer 50 fps streams for TV programmes (not available for all video sizes).

--get, -g

Start recording matching programmes.  Search terms required unless --pid specified.  Use  --search=.* to force download of all available programmes.

--hash

Show recording progress as hashes

--include-supplier <supplier>,<supplier>,...

Comma-separated list of media stream suppliers to use if not included by default.  Possible values: akamai,limelight,bidi

--log-progress

Force HLS/DASH download progress display to be captured when screen output is redirected to file.  Progress display is normally omitted unless writing to terminal.

--metadata-only

Create specified metadata info file without any recording or streaming (can also be used with thumbnail option).

--modes <mode>,<mode>,...

Recording modes.  See --tvmode and --radiomode (with --long-help) for available modes and defaults.  Shortcuts: tvworst,tvworse,tvgood,tvvgood,tvbetter,tvbest,radioworst,radioworse,radiogood,radiovgood,radiobetter,radiobest (default=default for programme type).

--no-proxy

Ignore --proxy setting in preferences

--no-resume

Do not resume partial HLS/DASH downloads.

--no-verify

Do not verify size of downloaded HLS/DASH file segments or file resize upon resume.

--overwrite

Overwrite recordings if they already exist

--partial-proxy

Only uses web proxy where absolutely required (try this extra option if your proxy fails).  If specified, value of http_proxy environment variable (if any) in parent process is retained and passed to child processes.

--pid <pid>,<pid>,...

Record arbitrary PIDs that do not necessarily appear in the index.

--pid-recursive

Record all related episodes if value of --pid is a series or brand PID.  Requires --pid.

--proxy, -p <url>

Web proxy URL e.g. 'http://USERNAME:PASSWORD@SERVER:PORT' or 'http://SERVER:PORT'.  Sets http_proxy environment variable for child processes (e.g., ffmpeg) unless --partial-proxy is specified.

--radiomode <mode>,<mode>,...

Radio recording modes (overrides --modes): dafhigh,dafstd,dafmed,daflow,hafhigh,hafstd,hafmed,haflow,hlsaacstd,hlsaaclow. Shortcuts: worst,worse,good,vgood,better,best,daf,haf,hlsaac (default=dafhigh,hafhigh,dafstd,hafstd,hlsaacstd,dafmed,hafmed,daflow,haflow,hlsaaclow).

--raw

Don't remux or change the recording in any way.  Saves output file in native container format (HLS->MPEG-TS, DASH->MP4)

--start <secs|hh:mm:ss>

Recording/streaming start offset (actual start may be several seconds earlier for HLS and DASH streams)

--stop <secs|hh:mm:ss>

Recording/streaming stop offset (actual stop may be several seconds later for HLS and DASH streams)

--suboffset <offset>

Offset the subtitle timestamps by the specified number of milliseconds

--subs-mono

Create monochrome titles, with leading hyphen used to denote change of speaker.

--subsraw

Additionally save the raw subtitles file

--subtitles

Download subtitles into srt/SubRip format if available and supported

--subtitles-only

Only download the subtitles, not the programme

--subtitles-required

Do not download TV programme if subtitles are not available.

--tag-only

Only update the programme metadata tag and not download the programme (can also be used with --history)

--tag-only-filename <filename>

Add metadata tags to specified file (ignored unless used with --tag-only)

--test, -t

Test only - no recording (will show programme type)

--thumb

Download Thumbnail image if available

--thumbnail-only

Only Download Thumbnail image if available, not the programme

--tvmode <mode>,<mode>,...

TV recording modes (overrides --modes): dvfhd,dvfsd,dvfxsd,dvfhigh,dvfxhigh,dvflow,hlshd,hlsvhigh,hlsstd,hlsxstd,hvfhd,hvfsd,hvfxsd,hvfhigh,hvfxhigh,hvflow. Shortcuts: worst,worse,vgood,better,best,dvf,hls,hvf (default=hlshd,hvfxsd,hlsvhigh,hvfxhigh,hlsstd,hlsxstd,hvflow).

--url <url>,<url>,...

Record the embedded media in the specified iPlayer episode URLs.  Use with --type.

--versions <versions>

Version of programme to record.  List is processed from left to right and first version found is downloaded.  Example: '--versions=audiodescribed,default' will prefer audiodescribed programmes if available.

Output Options

--command, -c <command>

Run user command after successful recording of programme using substitution paramaters such as <dir>, <fileprefix>, <filename>, etc.

--command-radio <command>

Run user command after successful recording of radio programme using substitution paramaters such as <dir>, <fileprefix>, <filename>, etc. Overrides --command.

--command-tv <command>

Run user command after successful recording of tv programme using substitution paramaters such as <dir>, <fileprefix>, <filename>, etc. Overrides --command.

--file-prefix <format>

The filename prefix (excluding dir and extension) using formatting fields. e.g. '<name>-<episode>-<pid>'

--limitprefixlength <length>

The maximum length for a file prefix.  Defaults to 240 to allow space within standard 256 limit.

--metadata <format>

Create metadata info file after recording.  Valid formats are: 'generic'

--output, -o <dir>

Recording output directory

--outputradio <dir>

Output directory for radio recordings (overrides --output)

--outputtv <dir>

Output directory for tv recordings (overrides --output)

--subdir, -s

Save recorded files into subdirectory.  Default: same name as programme.

--subdir-format <format>

The format to be used for subdirectory naming.  Use substitution parameters, e.g., '<nameshort>-<seriesnum>'

--thumb-ext <ext>

Thumbnail filename extension to use

--thumbsize <index|width>

Default thumbnail size/index to use for the current recording and metadata. index: 1-11 or width: 86,150,178,512,528,640,832,1024,1280,1600,1920

--whitespace, -w

Keep whitespace in file and directory names.  Default behaviour is to replace whitespace with underscores.

PVR Options

--comment <string>

Adds a comment to a PVR search

--pvr [pvr search name]

Runs the PVR using all saved PVR searches (intended to be run every hour from cron etc). The list can be limited by adding a regex to the command. Synonyms: --pvrrun, --pvr-run

--pvr-add <search name>

Save the named PVR search with the specified search terms. Search terms required unless --pid specified. Synonyms: --pvradd

--pvr-del <search name>

Remove the named search from the PVR searches. Synonyms: --pvrdel

--pvr-disable <search name>

Disable (not delete) a named PVR search. Synonyms: --pvrdisable

--pvr-enable <search name>

Enable a previously disabled named PVR search. Synonyms: --pvrenable

--pvr-exclude <string>

Exclude the PVR searches to run by search name (comma-separated regex list). Defaults to substring match. Synonyms: --pvrexclude

--pvr-list

Show the PVR search list. Synonyms: --pvrlist

--pvr-queue

Add currently matched programmes to queue for later one-off recording using the --pvr option. Search terms required unless --pid specified. Synonyms: --pvrqueue

--pvr-scheduler <seconds>

Runs the PVR using all saved PVR searches every <seconds>. Synonyms: --pvrscheduler

--pvr-single <search name>

Runs a named PVR search. Synonyms: --pvrsingle

Config Options

--cache-rebuild

Rebuild cache with full 30-day programme index. Use --refresh-limit to restrict cache window.

--cache-reset

Reset cache to retain only latest update and discard previous contents.

--expiry, -e <secs>

Cache expiry in seconds (default 4hrs)

--limit-matches <number>

Limits the number of matching results for any search (and for every PVR search)

--nopurge

Don't ask to delete programmes recorded over 30 days ago

--prefs-add

Add/Change specified saved user or preset options

--prefs-clear

Remove *ALL* saved user or preset options

--prefs-del

Remove specified saved user or preset options

--prefs-show

Show saved user or preset options

--preset, -z <name>

Use specified user options preset

--preset-list

Show all valid presets

--profile-dir <dir>

Override the user profile directory

--refresh, --flush, -f

Refresh cache

--refresh-abortonerror

Abort cache refresh for programme type if data for any channel fails to download.  Use --refresh-exclude to temporarily skip failing channels.

--refresh-exclude <channel>,<channel>,...

Exclude matched channel(s) when refreshing cache (comma-separated regex list).  Defaults to substring match.  Overrides --refresh-include-groups[-{tv,radio}] status for specified channel(s)

--refresh-exclude-groups <group>,<group>,...

Exclude channel groups when refreshing radio or TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

--refresh-exclude-groups-radio <group>,<group>,...

Exclude channel groups when refreshing radio cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

--refresh-exclude-groups-tv <group>,<group>,...

Exclude channel groups when refreshing TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

--refresh-future

Obtain future programme schedule when refreshing cache

--refresh-include <channel>,<channel>,...

Include matched channel(s) when refreshing cache (comma-separated regex list).  Defaults to substring match.  Overrides --refresh-exclude-groups[-{tv,radio}] status for specified channel(s)

--refresh-include-groups <group>,<group>,...

Include channel groups when refreshing radio or TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

--refresh-include-groups-radio <group>,<group>,...

Include channel groups when refreshing radio cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

--refresh-include-groups-tv <group>,<group>,...

Include channel groups when refreshing TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

--refresh-limit <days>

Minimum number of days of programmes to cache.  Makes cache updates slow.  Default: 7 Min: 1 Max: 30

--refresh-limit-radio <days>

Number of days of radio programmes to cache.  Makes cache updates slow.  Default: 7 Min: 1 Max: 30

--refresh-limit-tv <days>

Number of days of TV programmes to cache.  Makes cache updates slow.  Default: 7 Min: 1 Max: 30

--skipdeleted

Skip the download of metadata/thumbs/subs if the media file no longer exists.  Use with --history & --metadataonly/subsonly/thumbonly.

--webrequest <urlencoded string>

Specify all options as a urlencoded string of "name=val&name=val&..."

External Program Options

--atomicparsley <path>

Location of AtomicParsley binary

--ffmpeg <path>

Location of ffmpeg binary. Assumed to be ffmpeg 3.0 or higher unless --ffmpeg-obsolete is specified.

--ffmpeg-force

Bypass version checks and assume ffmpeg is version 3.0 or higher

--ffmpeg-obsolete

Indicates you are using an obsolete version of ffmpeg (<1.0) that may not support certain options. Without this option, MP4 conversion may fail with obsolete versions of ffmpeg.

--ffmpeg-verbose

Show verbose (-loglevel verbose) output from ffmpeg

Tagging Options

--no-artwork

Do not embed thumbnail image in output file. Also removes existing artwork. All other metadata values will be written.

--no-tag

Do not tag downloaded programmes. Note that moov atom will be at end of output file if --no-tag used. Remuxing would be necessary to stream file.

--tag-format-show

Format template for programme name in tag metadata (use substitution parameters). Default: <name>

--tag-format-title

Format template for episode title in tag metadata (use substitution parameters). Default: <episodeshort>

--tag-isodate

Use ISO8601 dates (YYYY-MM-DD) in album/show names and track titles

--tag-podcast

Tag downloaded radio and tv programmes as iTunes podcasts

--tag-podcast-radio

Tag only downloaded radio programmes as iTunes podcasts

--tag-podcast-tv

Tag only downloaded tv programmes as iTunes podcasts

--tag-utf8

Use UTF-8 encoding for non-ASCII characters in AtomicParsley parameter values (Linux/Unix/macOS only). Use only if auto-detect fails.

Misc Options

--encoding-console-in <name>

Character encoding for standard input (currently unused).  Encoding name must be known to Perl Encode module.  Default (only if auto-detect fails): Linux/Unix/OSX = UTF-8, Windows = cp850

--encoding-console-out <name>

Character encoding used to encode search results and other output.  Encoding name must be known to Perl Encode module.  Default (only if auto-detect fails): Linux/Unix/OSX = UTF-8, Windows = cp850

--encoding-locale <name>

Character encoding used to decode command-line arguments.  Encoding name must be known to Perl Encode module.  Default (only if auto-detect fails): Linux/Unix/OSX = UTF-8, Windows = cp1252

--encoding-locale-fs <name>

Character encoding used to encode file and directory names.  Encoding name must be known to Perl Encode module.  Default (only if auto-detect fails): Linux/Unix/OSX = UTF-8, Windows = cp1252

--index-maxconn <number>

Maximum number of connections to use for concurrent programme indexing.  Default: 5 Min: 1 Max: 10

--trim-history <# days to retain>

Remove download history entries older than number of days specified in option value.  Cannot specify 0 - use 'all' to completely delete download history

Deprecated Options

--no-index-concurrent

Do not use concurrent indexing to update programme cache.  Cache updates will be very slow.

--no-scrape-versions

Do not scrape episode web pages as extra measure to find audiodescribed/signed versions.

--subsfmt <format>

Subtitles format.  One of: default, compact.  Default: 'default'

--thumbsizecache <index|width>

Default thumbnail size/index to use when building cache. index: 1-11 or width: 86,150,178,512,528,640,832,1024,1280,1600,1920

Author

get_iplayer was written by Phil Lewis <iplayer2 (at sign) linuxcentre.net> and is now maintained by the contributors at http://www.infradead.org/get_iplayer/html/get_iplayer.html

This manual page was originally written by Jonathan Wiltshire <jmw@debian.org> for the Debian project (but may be used by others).

Info

May 2017 Phil Lewis get_iplayer Manual