GET_IPLAYER(1)get_iplayer Manual GET_IPLAYER(1)NAMEget_iplayer - Stream Recording tool and PVR for BBC iPlayer, BBC Pod‐
casts and more
SYNOPSISget_iplayer [<options>] [<regex|index> ...]
get_iplayer--get [<options>] <regex|index> ...
get_iplayer <url> --type=<type> [<options>]
get_iplayer <pid|url> [--type=<type> <options>]
get_iplayer--stream [<options>] <regex|index> | mplayer -cache 3072 -
get_iplayer--stream [<options>] --type=<type> <pid|url> | mplayer
-cache 3072 -
get_iplayer--stream [<options>] --type=livetv,liveradio <regex|index>
--player="mplayer -cache 128 -"
get_iplayer--refresh
DESCRIPTIONget_iplayer lists, searches and records BBC iPlayer TV/Radio, BBC Pod‐
cast programmes. Other 3rd-Party plugins may be available.
get_iplayer has three modes: recording a complete programme for later
playback, streaming a programme directly to a playback application,
such as mplayer; and as a Personal Video Recorder (PVR), subscribing to
search terms and recording programmes automatically. It can also stream
or record live BBC iPlayer output
If given no arguments, get_iplayer updates and displays the list of
currently available programmes. Each available programme has a numeri‐
cal identifier, pid. get_iplayer utilises the rtmpdump tool to record
BBC iPlayer programmes from RTMP flash streams at various qualities.
In PVR mode, get_iplayer can be called from cron to record programmes
to a schedule.
OPTIONS
Search Options:
--before
Limit search to programmes added to the cache before N hours ago
--category <string>
Narrow search to matched categories (regex or comma separated
values). Supported only for podcasts (not tv or radio pro‐
grammes).
--channel <string>
Narrow search to matched channel(s) (regex or comma separated
values)
--exclude <string>
Narrow search to exclude matched programme names (regex or comma
separated values)
--exclude-category <string>
Narrow search to exclude matched categories (regex or comma sep‐
arated values). Supported only for podcasts (not tv or radio
programmes).
--exclude-channel <string>
Narrow search to exclude matched channel(s) (regex or comma sep‐
arated values)
--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
Limit search to programmes added to the cache in the last N
hours
--type <type>
Only search in these types of programmes: livera‐
dio,livetv,radio,tv,all (tv is default)
--versions <versions>
Version of programme to search or record. List is processed
from left to right and first version found is downloaded. Exam‐
ple: '--versions signed,audiodescribed,default' will prefer
signed and audiodescribed programmes if available. Default:
'default,signed,audiodescribed'
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 sub‐
titles (max 50 matches)
--list <categories|channel>
Show a list of available categories/channels for the selected
type and exit
--listformat <format>
Display programme data based on a user-defined format string
(such as <pid>, <name> etc)
--listplugins
Display a list of currently available plugins or programme types
--long, -l
Show long 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
Verbose
--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. TV modes typically
have two streams available.
--bandwidth
In radio realaudio mode specify the link bandwidth in bps for
rtsp streaming (default 512000)
--check-duration
Print message showing recorded duration, expected duration and
difference between them.
--ddl-radio-opts <options>
Add custom options to ffmpeg DDL download re-muxing for radio
--exclude-supplier <suppliers>
Comma-delimited list of media stream suppliers to skip. Possi‐
ble values: akamai,limelight,level3,bidi
--ffmpeg-liveradio-opts <options>
Add custom options to ffmpeg re-muxing for liveradio
--ffmpeg-livetv-opts <options>
Add custom options to ffmpeg re-muxing for livetv
--ffmpeg-radio-opts <options>
Add custom options to ffmpeg re-muxing for radio
--ffmpeg-tv-opts <options>
Add custom options to ffmpeg re-muxing for tv
--force
Ignore programme history (unsets --hide option also). Forces a
script update if used with -u
--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
--hls-liveradio-opts <options>
Add custom options to ffmpeg HLS download re-muxing for livera‐
dio
--hls-livetv-opts <options>
Add custom options to ffmpeg HLS download encoding for livetv
--hls-radio-opts <options>
Add custom options to ffmpeg HLS download re-muxing for radio
--hls-tv-opts <options>
Add custom options to ffmpeg HLS download re-muxing for tv
--liveradio-intl
Force use of hard-coded international streams for HLS live
radio. Ignored for World Service
--liveradio-uk
Force use of hard-coded UK streams for HLS live radio (overrides
--liveradio-intl). Ignored for World Service
--liveradiomode <mode>,<mode>,..
Live Radio recording modes: hlsaachigh,hlsaac‐
std,hlsaacmed,hlsaaclow,shoutcastmp3std,shoutcastaachigh(R3
only, UK only). Shortcuts: default,good,bet‐
ter(=default),best,hls. ('default'=hlsaachigh,hlsaac‐
std,hlsaacmed,hlsaaclow)
--livetv-uk
Force use of hard-coded UK streams for HLS live tv
--livetvmode <mode>,<mode>,...
Live TV recording modes:
hlshd,hlssd,hlsvhigh,hlshigh,hlsstd,hlslow. Shortcuts:
default,good,better(=default),vbetter,best,hls.
('default'=hlsvhigh,hlshigh,hlsstd,hlslow)
--mediaselector <identifier>
Identifier of mediaselector API to use when searching for media
streams. One of: 4,5 Default: 5
--metadata-only
Create specified metadata info file without any recording or
streaming (can also be used with thumbnail option).
--mmsnothread
Disable parallel threaded recording for mms
--modes <mode>,<mode>,...
Recording modes. See --tvmode and --radiomode for available
modes and defaults. Shortcuts: default,good,bet‐
ter(=default),best. Use --modes=best to select highest quality
available (incl. HD TV).
--multimode
Allow the recording of more than one mode for the same programme
- WARNING: will record all specified/default modes!!
--no-proxy
Ignore --proxy setting in preferences
--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>
Record an arbitrary pid that does not necessarily appear in the
index.
--pid-recursive
When used with --pid record all the embedded pids if the pid is
a series or brand 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 speci‐
fied.
--radiomode <mode>,<mode>,...
Radio recording modes: flashaachigh,flashaacstd,flashau‐
dio,flashaaclow,wma. Shortcuts: default,good,bet‐
ter(=default),best,rtmp,flash,flashaac.
('default'=flashaachigh,flashaacstd,flashaudio,flashaaclow)
--raw Don't transcode or change the recording/stream in any way (i.e.
radio/realaudio, rtmp/flv)
--rtmp-liveradio-opts <options>
Add custom options to rtmpdump for liveradio
--rtmp-livetv-opts <options>
Add custom options to rtmpdump for livetv
--rtmp-radio-opts <options>
Add custom options to rtmpdump for radio
--rtmp-tv-opts <options>
Add custom options to rtmpdump for tv
--rtmpport <port>
Override the RTMP port (e.g. 443)
--shoutcast-liveradio-opts <options>
Add custom options to ffmpeg Shoutcast download re-muxing for
liveradio
--start <secs|hh:mm:ss>
Recording/streaming start offset (rtmp and realaudio only)
--stop <secs|hh:mm:ss>
Recording/streaming stop offset (can be used to limit live rtmp
recording length) rtmp and realaudio only
--suboffset <offset>
Offset the subtitle timestamps by the specified number of mil‐
liseconds
--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 sup‐
ported
--subtitles-only
Only download the subtitles, not the programme
--subtitles-required
Do not download TV programme if subtitles are not available.
--swfurl <URL>
URL of Flash player used by rtmpdump for verification. Only use
if default Flash player URL is not working.
--tag-only
Only update the programme tag and not download the programme
(can also be used with --history)
--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: flashhd,flashvhigh,flashhigh,flashstd,flash‐
normal,flashlow. Shortcuts: default,good,bet‐
ter(=default),best,rtmp,flash. (Use 'best' for HD TV.
'default'=flashvhigh,flashhigh,flashstd,flashnormal,flashlow)
--url "<url>"
Record the embedded media player in the specified URL. Use with
--type=<type>.
--wav In radio realaudio mode output as wav and don't transcode to mp3
Output Options:
--aactomp3
Transcode AAC audio to MP3 with ffmpeg/avconv (CBR 128k unless
--mp3vbr is specified). Applied only to radio programmes. (Syn‐
onyms: --mp3)
--avi Output video in AVI container instead of MP4. There is no meta‐
data tagging support for AVI output.
--command, -c <command>
Run user command after successful recording using args such as
<pid>, <name> etc
--email <address>
Email HTML index of matching programmes to specified address
--email-password <password>
Email password
--email-port <port number>
Email port number (default: appropriate port for --email-secu‐
rity)
--email-security <TLS|SSL>
Email security TLS, SSL (default: none)
--email-sender <address>
Optional email sender address
--email-smtp <hostname>
SMTP server IP address to use to send email (default: localhost)
--email-user <username>
Email username
--fatfilename
Remove FAT forbidden characters in file and directory names.
Always applied on Windows. Overrides --punctuation.
--file-prefix <format>
The filename prefix (excluding dir and extension) using format‐
ting fields. e.g. '<name>-<episode>-<pid>'
--fxd <file>
Create Freevo FXD XML of matching programmes in specified file
--hfsfilename
Remove colons in file and directory names. Prevents OS X Finder
displaying colon as forward slash. Always applied on OS X. Over‐
rides --punctuation.
--html <file>
Create basic HTML index of matching programmes in specified file
--isodate
Use ISO8601 dates (YYYY-MM-DD) in filenames and subdirectory
paths
--keep-all
Keep whitespace, all possible punctuation and non-ASCII charac‐
ters in file and directory names. Shortcut for: --whitespace
--non-ascii --punctuation.
--metadata <type>
Create metadata info file after recording. Valid types are: xbmc
(or kodi), xbmc_movie (or kodi_movie), freevo, generic
--mkv Output video in MKV container instead of MP4. There is no meta‐
data tagging support for MKV output.
--mp3vbr
Set LAME VBR mode to N (0 to 9) for AAC transcoding. 0 = target
bitrate 245 Kbit/s, 9 = target bitrate 65 Kbit/s (requires
--aactomp3). Applied only to radio programmes.
--mythtv <file>
Create Mythtv streams XML of matching programmes in specified
file
--non-ascii, --na
Keep non-ASCII characters in file and directory names. Default
behaviour is to remove all non-ASCII characters.
--nowrite, -n
No writing of file to disk (use with -x to prevent a copy being
stored on disk)
--output, -o <dir>
Recording output directory
--outputliveradio <dir>
Output directory for live radio recordings (overrides --output)
--outputlivetv <dir>
Output directory for live tv recordings (overrides --output)
--outputlocalfiles <dir>
Output directory for localfiles recordings (overrides --output)
--outputpodcast <dir>
Output directory for podcast recordings (overrides --output)
--outputradio <dir>
Output directory for radio recordings (overrides --output)
--outputtv <dir>
Output directory for tv recordings (overrides --output)
--player '<command> <options>'
Use specified command to directly play the stream
--punctuation, --pu
Keep punctuation characters and symbols in file and directory
names, with ellipsis always replaced by underscore. Default be‐
haviour is to remove all punctuation and symbols except under‐
score, hyphen and full stop. Overridden by --fatfilename and
--hfsfilename.
--stdout, -x
Additionally stream to STDOUT (so you can pipe output to a
player)
--stream
Stream to STDOUT (so you can pipe output to a player)
--subdir, -s
Put Recorded files into Programme name subdirectory
--subdir-format <format>
The format to be used for the subdirectory naming using format‐
ting fields. e.g. '<nameshort>-<seriesnum>'
--symlink <file>
Create symlink to <file> once we have the header of the record‐
ing
--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.
--xml-alpha
Create freevo/Mythtv menu sorted alphabetically by programme
name
--xml-channels
Create freevo/Mythtv menu of channels -> programme names ->
episodes
--xml-names
Create freevo/Mythtv menu of programme names -> episodes
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. Use --search=.* to force download of all
available programmes. 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 (regex or comma
separated values). 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. Use --search=.* to force download of all avail‐
able programmes. Synonyms: --pvrqueue
--pvr-scheduler <seconds>
Runs the PVR using all saved PVR searches every <seconds>. Syn‐
onyms: --pvrscheduler
--pvr-single <search name>
Runs a named PVR search. Synonyms: --pvrsingle
Config Options:
--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)
--localfilesdirs <dir>[,dir,]
Directories/Folders to scan for new files
--nopurge
Don't ask to delete programmes recorded over 30 days ago
--packagemanager <string>
Tell the updater that we were installed using a package manager
and don't update (use either: apt,rpm,deb,yum,disable)
--plugins-update
Update get_iplayer plugins to the latest versions. get_iplayer
main script also will be updated if a newer version is avail‐
able.)
--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/folder
--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 <string>
Exclude matched channel(s) when refreshing cache (regex or comma
separated values)
--refresh-exclude-groups
Exclude channel groups when refreshing radio or tv cache
(comma-separated values). Valid values: 'national', 'regional',
'local'
--refresh-exclude-groups-radio
Exclude channel groups when refreshing radio cache (comma-sepa‐
rated values). Valid values: 'national', 'regional', 'local'
--refresh-exclude-groups-tv
Exclude channel groups when refreshing tv cache (comma-separated
values). Valid values: 'national', 'regional', 'local'
--refresh-feeds <string>
Alternate source for programme data. Valid values:
'ion','ion2','schedule'
--refresh-feeds-radio <string>
Alternate source for radio programme data. Valid values:
'ion','ion2','schedule'
--refresh-feeds-tv <string>
Alternate source for TV programme data. Valid values:
'ion','ion2','schedule'
--refresh-future
Obtain future programme schedule when refreshing cache (between
7-14 days)
--refresh-include <string>
Include matched channel(s) when refreshing cache (regex or comma
separated values)
--refresh-limit <integer>
Number of days of programmes to cache. Only applied with
--refresh-feeds=schedule. Makes cache updates VERY slow.
Default: 7 Min: 1 Max: 30
--refresh-limit-radio <integer>
Number of days of radio programmes to cache. Only applied with
--refresh-feeds=schedule. Makes cache updates VERY slow.
Default: 7 Min: 1 Max: 30
--refresh-limit-tv <integer>
Number of days of TV programmes to cache. Only applied with
--refresh-feeds=schedule. Makes cache updates VERY 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/sub‐
sonly/thumbonly.
--update, -u
Update get_iplayer if a newer version is available. If so, plug‐
ins also will be updated if newer versions available.
--webrequest <urlencoded string>
Specify all options as a urlencoded string of
"name=val&name=val&..."
External Program Options:
--atomicparsley <path>
Location of AtomicParsley tagger binary
--ffmpeg <path>
Location of ffmpeg or avconv binary. Synonyms: --avconv
--ffmpeg-obsolete
Indicates you are using an obsolete version of ffmpeg (<0.7)
that does not support the -loglevel option, so --quiet, --ver‐
bose and --debug will not be applied to ffmpeg. Synonym:
--avconv-obsolete
--id3v2 <path>
Location of id3v2 or id3tag binary
--lame <path>
Location of lame binary
--mplayer <path>
Location of mplayer binary
--rtmpdump <path>
Location of rtmpdump binary. Synonyms: --flvstreamer
--vlc <path>
Location of vlc or cvlc binary
Tagging Options:
--no-artwork
Do not embed thumbnail image in output file. All other metadata
values will be written.
--no-tag
Do not tag downloaded programmes
--tag-cnid
Use AtomicParsley --cnID argument (if supported) to add catalog
ID used for combining HD and SD versions in iTunes
--tag-fulltitle
Prepend album/show title to track title
--tag-hdvideo
AtomicParsley accepts --hdvideo argument for HD video flag
--tag-id3sync
Save ID3 tags for MP3 files in synchronised form. Provides work‐
around for corruption of thumbnail images in Windows. Has no
effect unless using MP3::Tag Perl module.
--tag-isodate
Use ISO8601 dates (YYYY-MM-DD) in album/show names and track
titles
--tag-longdesc
AtomicParsley accepts --longdesc argument for long description
text
--tag-longdescription
AtomicParsley accepts --longDescription argument for long
description text
--tag-longepisode
Use <episode> (incl. episode number) instead of <episodeshort>
for track title
--tag-longtitle
Prepend <series> (if available) to track title. Ignored with
--tag-fulltitle.
--tag-podcast
Tag downloaded radio and tv programmes as iTunes podcasts
(requires MP3::Tag module for AAC/MP3 files)
--tag-podcast-radio
Tag only downloaded radio programmes as iTunes podcasts
(requires MP3::Tag module for AAC/MP3 files)
--tag-podcast-tv
Tag only downloaded tv programmes as iTunes podcasts
--tag-shortname
Use <nameshort> instead of <name> for album/show title
--tag-utf8
AtomicParsley accepts UTF-8 input
Misc Options:
--encoding-console-in <name>
Character encoding for standard input (currently unused). Encod‐
ing 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 out‐
put. 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. Encod‐
ing 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
--no-scrape-versions
Do not scrape episode web pages as extra measure to find
audiodescribed/signed versions (only applies with
--playlist-metadata).
--playlist-metadata (IGNORED)
Force use of playlists (XML and JSON) for programme metadata
instead of /programmes data endpoints.
--trim-history <# days to retain>
Remove download history entries older than number of days speci‐
fied in option value. Cannot specify 0 - use 'all' to com‐
pletely delete download history
AUTHORget_iplayer was written by Phil Lewis <iplayer2 (at sign) linuxcen‐
tre.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).
COPYRIGHT NOTICEget_iplayer v2.94, Copyright (C) 2008-2010 Phil Lewis
This program comes with ABSOLUTELY NO WARRANTY; for details use
--warranty.
This is free software, and you are welcome to redistribute it under
certain
conditions; use --conditions for details.
Phil Lewis June 2015 GET_IPLAYER(1)
