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

Displays the age of the selected programme caches then exit

--show-options

Shows 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-delimited 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-delimited list of media stream suppliers to use if not included by default.  Possible values: level3,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 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,flashaachigh,flashaacstd,flashaaclow,hafhigh,hafstd,hafmed,haflow,hlsaacstd,hlsaaclow. Shortcuts: worst,worse,good,vgood,better,best,daf,flashaac,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 (RTMP->FLV, 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

--subsfmt <format>

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

--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,flashhd,flashvhigh,flashstd,flashxstd,hlshd,hlsvhigh,hlsstd,hlsxstd,hvfhd,hvfsd,hvfxsd,hvfhigh,hvfxhigh,hvflow. Shortcuts: worst,worse,vgood,better,best,dvf,flash,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>'

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

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

--whitespace, -w

Keep whitespace in file and directory names. Default behaviour is to replace whitespace with underscores unless --no-sanitise specified.

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

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-concurrent

Perform fork()-based concurrent (i.e., faster) indexing when web scraping TV schedules only. Requires --ybbcy and Parallel::ForkManager Perl module. Not supported on Windows.

--index-maxconn <number>

Maximum number of forks (connections) to use for concurrent indexing. Requires --index-concurrent. Default: 4 Max: 10

--no-scrape-versions

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

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

--ybbcy

Use alternate programme indexing and metadata retrieval if the BBC removes its XML data sources. TV programme indexing will be extremely slow. Some metadata will be missing or incorrect.

Deprecated Options

--check-duration

Print message showing recorded duration, expected duration and difference between them.

--rtmp-radio-opts <options>

Add custom options to rtmpdump for radio

--rtmp-tv-opts <options>

Add custom options to rtmpdump for tv

--rtmpdump <path>

Location of rtmpdump binary. Synonyms: --flvstreamer

--rtmpport <port>

Override the RTMP port (e.g. 443)

--swfurl <URL>

URL of Flash player used by rtmpdump for verification.  Only use if default Flash player URL is not working.

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

February 2017 Phil Lewis get_iplayer Manual