Documentation
* The full web based man page can be viewed here.
* For basic help run:
get_iplayer -h
* For Advanced and extended options run:
get_iplayer --long-help
* List all tv programmes (either from BBC site or cached):
get_iplayer
* List all tv programme names matching “News”:
get_iplayer news
* List all Radio programme names matching “News”:
get_iplayer --type=radio news
* List all Live TV and Radio channels/programmes:
get_iplayer --type=livetv,liveradio
* List all tv programmes with long descriptions:
get_iplayer --long
* List all tv programmes showing only ‘pid’, ‘name’ and ‘episode’
get_iplayer --listformat="<pid>: <name> - <episode>"
* Search all tv programmes for the word ‘hello’ in the ‘episode’ and ‘channel’ fields
get_iplayer --fields=episode,channel hello
* List all tv programmes with categories containing the word ‘News’ and on channel ‘BBC One’
get_iplayer --channel="BBC One" --category=News
* List all tv programmes added to the cache since 24 hours ago:
get_iplayer --since=24
* List all available categories for BBC Radio and BBC TV programmes:
get_iplayer --list=categories --type=tv,radio
* List all available radio channels:
get_iplayer --list=channel --type=radio
* List all BBC TV programmes and BBC podcasts
get_iplayer --type=podcast,tv
* List all programmes with categories not containing the string ‘child’ on BBC One:
get_iplayer --exclude-category=child --channel="bbc one"
* List all programme metadata and available streaming modes for programme with index number 123:
get_iplayer --info 123
Essentially, you can just add ‘—get’ to any of the above searches to record the matching programmes.
* Record programme number 123 (see index list):
get_iplayer --get 123
* Record Radio programme number 10123 (see index list):
get_iplayer --get 10123
* Record programme number 123 and save in ‘/home/user/tv-files/’:
get_iplayer --get 123 --output "/home/user/tv-files/"
* Record Radio programme number 10123 and tv programme number 324 (see index list):
get_iplayer --get 10123 324
* Record Podcasts matching ‘Moyles’:
get_iplayer --type=podcast --get "Moyles"
* Record all tv programmes with ‘blue peter’ in the title/episode:
get_iplayer --get "blue peter"
* Record all tv programmes with ‘blue peter’ in the title/episode, and programme index 123:
get_iplayer --get "blue peter" 123
* Record all programmes with URL that contains a programme ID (pid) b002a23a (i.e. the URL of the programme page on BBC iplayer):
get_iplayer "http://blah.blah.blah/b002a23a.shtml" get_iplayer --pid b002a23a
* Record a video from the BBC embedded media player such as Learning Zone, BBC Archive or the BBC News site (i.e. the URL of the page that contains the player):
get_iplayer "tv:http://news.bbc.co.uk/1/hi/uk_politics/8104086.stm" get_iplayer --type=tv "http://news.bbc.co.uk/1/hi/uk_politics/8104086.stm"
* Record all programmes with ‘comedy’ in the title, episode or long description:
get_iplayer --long --get comedy
* Record all programmes with categories containing ‘music’:
get_iplayer --get --category=music
* Using flvstreamer tool to get high or normal quality Flash version of a TV programme (—flvstreamer is not required of your options tell get_iplayer where flvstreamer is located)
get_iplayer --type=tv --get 123 --modes=flashstd --flvstreamer="/path/to/flvstreamer"
* Record a TV programme trying iphone, flashhigh and flashnormal modes in order until one succeeds. (use the —info option to see what modes are available for a programme).
get_iplayer --type=tv --get 123 --modes=iphone,flashhigh,flashstd --flvstreamer="/path/to/flvstreamer"
* Using flvstreamer tool to get high quality Flash version of a BBC Radio programme (—flvstreamer is not required of your options tell get_iplayer where flvstreamer is located). Note: Possible modes are (in order of quality): n95_3g, n95_wifi, flashlow, flashnormal, iphone, flashhigh, flashvhigh, flashhd. See this page for more details.
get_iplayer --type=radio --get 12345 --modes=flashaudio --flvstreamer="/path/to/flvstreamer"
* Record a radio programme trying iphone, flashaudio, flashaac then realaudio modes in order until one succeeds.
get_iplayer --type=radio --get 12345 --modes=iphone,flashaudio,flashaac,realaudio --flvstreamer="/path/to/flvstreamer"
Note: Please upgrade to flvstreamer 1.8 or later for reliable Live streaming.
* List LiveTV:
get_iplayer --type=livetv
* Record a Live BBC iPlayer TV programme (e.g. BBC2):
get_iplayer --type=livetv --get "BBC Two" get_iplayer --type=tv "http://www.bbc.co.uk/iplayer/playlive/bbc_two" get_iplayer --type=tv --pid="bbc_two"
* Record a High Quality Live BBC iPlayer Radio programme (e.g. BBC Radio 1):
get_iplayer --type=liveradio --get "Radio 1" get_iplayer --type=radio "http://www.bbc.co.uk/iplayer/playlive/bbc_radio_one" get_iplayer --type=radio --pid=bbc_radio_one
It is possible to index, search and queue recordings for specific programmes that have not yet been made available. This is currently only available on BBC TV and Radio modes and only searches for up to 13 days in advance. Note that some of the programmes in the BBC schedules are never released on iPlayer and therefore will never get recorded even if you can find them in the search results. Note that the refreshing can take quite a bit longer with —refresh-future specified.
* Refresh the cache with future schedules (e.g. for tv). You must do this otherwise you will not be able to search for future programmes:
get_iplayer --type=tv --refresh-future --refresh
* Save the refreshing of future programmes into your default settings (a good idea if you want the above to be automatic):
get_iplayer --add-prefs --refresh-future
* To search for a programme additionally in the future just use any of the usual search commands but adding ‘—future’:
get_iplayer 'Eastenders' --future
* You cannot record a programme in the future (!) but you can queue it in the PVR for recording when it becomes available (if at all). In this example the Index of the search results for a future episode of eastenders was ’123′:
get_iplayer --pvrqueue --type=tv 123
The recording history is a text database of the programmes you have recording since you started using get_iplayer. Its primary purpose is to prevent get_iplayer from downloading the same programme more than once. You can search the recordings history much like the normal programme types.
* Search for “Doctor Who” in the history
get_iplayer --history "Doctor Who"
* Show detailed programme metadata for all recorded programmes matching “Doctor Who” in the history
get_iplayer --history "Doctor Who" --info
* Download thumbnails for all recorded programmes matching “Doctor Who” in the history
get_iplayer --history "Doctor Who" --thumbnailonly
* Download thumbnails for all recorded programmes matching “Doctor Who” in the history and where the media file hasn’t been deleted.
get_iplayer --history "Doctor Who" --thumbnailonly --skipdeleted
* Refresh the tv programme cache (this happens after 4hrs automatically – see —expiry option):
get_iplayer --refresh
* Manually refresh the programme cache for all types:
get_iplayer --refresh --type=all
* Manually refresh the radio programme cache:
get_iplayer --refresh --type=radio
* Set the expiry of the caches (in seconds):
get_iplayer --add-prefs --expiry=3600
* Exclude adding matching channels to the programme cache (i.e. these channels won’t even be indexed and therefore indexing/refreshing will be faster):
get_iplayer --refresh-exclude="cbeebies,cbbc" --type=tv --refresh
* Check for Updates and Download new version of get_iplayer (also creates backup):
* Include these channels ONLY to the programme cache (i.e. these channels will only be indexed and therefore indexing/refreshing will be faster):
get_iplayer --refresh-include="bbc" --type=tv --refresh
Updating on Linux, OS X, Unix, cygwin, etc
* If you installed by simply downloading the get_iplayer script then you can just run:
get_iplayer --update
* Optionally force updating the script and the plugins:
get_iplayer --update --plugins-update --force
get_iplayer --update
* If you installed using a package manager then please see the Install page for further details:
Updating on Windows (Installer method)
* Download the latest Installer and re-run it. You can then uninstall the get_iplayer component and then re-install that component. The same goes for each of the other components if you so wish.
* Stream a programme in mplayer, or xine while recording it to disk (does not yet work in win32, does not work for flash based streams. Works for iphone, flash, podcast and realaudio modes):
get_iplayer --stdout --get 123 | mplayer -cache 3072 - get_iplayer --stdout --get 123 | xine stdin:/
* Stream a programme in mplayer/xine/vlc/ffplay while not recording it to disk:
get_iplayer --stream 123 --player="mplayer -cache 3072 -" get_iplayer --stream 123 --player="vlc -" get_iplayer --stream 123 --player="ffplay -" get_iplayer --stream 123 | mplayer -cache 3072 -
Note: Please upgrade to flvstreamer 1.8 or later for reliable Live streaming.
* Stream a Live BBC iPlayer TV programme to mplayer while not recording it to disk (e.g. BBC 2):
get_iplayer --stream --type=livetv "BBC Two" --player="mplayer -cache 512 -" get_iplayer --stream --type=tv "http://www.bbc.co.uk/iplayer/playlive/bbc_two" --player="mplayer -cache 512 -" get_iplayer --stream --type=tv "http://www.bbc.co.uk/iplayer/playlive/bbc_two" | mplayer -cache 512 - get_iplayer --stream --type=tv --pid="bbc_two" | mplayer -cache 512 -
* Stream a High Quality Live BBC iPlayer Radio programme to mplayer while not recording it to disk (e.g. BBC Radio 1):
get_iplayer --stream --type=liveradio "Radio 1" --player="mplayer -cache 64 -" get_iplayer --stream --type=radio "http://www.bbc.co.uk/iplayer/playlive/bbc_radio_one" | mplayer -cache 64 - get_iplayer --stream --pid='bbc_radio_one' | mplayer -cache 64 -
* If you are behind a web proxy you can use the following to specify it:
get_iplayer --proxy=http://[username:password@]<server>:<port>
* All modes other than iphone or http will not work through a web proxy. To make only the meta-data web requests go through the proxy add the —partial-proxy option. This will only work if your network allows direct access to the streaming port (e.g. port 1935).
Default user settings can be added, removed or changed as follows:
* Save or update proxy settings and verbose mode as user defaults (in ~/.get_iplayer/options or ‘USERPROFILE\.get_iplayer\options’ in ActivePerl/Windows):
get_iplayer --prefs-add --verbose --proxy=http://proxy.domain.com:3128
* Additionally save programme type settings (this will only update the specified options – existing options will be retained):
get_iplayer --prefs-add --type=radio,tv
* Remove a specific option from those saved (e.g. —proxy):
get_iplayer --prefs-del --proxy=http://proxy.domain.com:3128
* Show all saved default options:
get_iplayer --prefs-show
* Completely clear all saved default options:
get_iplayer --prefs-clear
* Options can also be saved in ‘/etc/get_iplayer/options’ on *nix/MaxOSX/cygwin platforms and ALLUSERSPROFILE\get_iplayer\options in Windows. The format is as follows:
<option key> <option value>
User defined groups of options can be added, removed or changed. They are referred to by the ‘preset name’ as follows:
* Save or update several options (—hide and —since) in the preset named ‘my_preset’ (in ~/.get_iplayer/presets/my_preset or ‘USERPROFILE\.get_iplayer\presets\my_preset’ in ActivePerl/Windows):
get_iplayer --preset=my_preset --prefs-add --hide --since=24
* Additionally save programme type for preset named ‘my_preset’ (this will only update the specified preset options – existing preset options will be retained):
get_iplayer --preset=my_preset --prefs-add --type=radio,tv
* Remove a specific option from those saved in the preset named ‘my_preset’ (e.g. —since=24):
get_iplayer --preset=my_preset --prefs-del --since=24
* Show all saved options in preset named ‘my_preset’:
get_iplayer --preset=my_preset --prefs-show
* Completely clear all saved options in preset named ‘my_preset’:
get_iplayer --preset=my_preset --prefs-clear
* Use the preset named ‘my_preset’ to search for items containing the name ‘News’:
get_iplayer --preset=my_preset News get_iplayer -z my_preset News
* Here is a more useful example. I would like to have a preset that shows me the BBC iPlayer TV programmes added to my cache in the last 24hrs, hide ones I’ve already downloaded, exclude some channels and exclude childrens’ and wales programme categories. So to add the preset I type:
get_iplayer --prefs-add --preset=last24 --type=tv --since=24 --hide --versionlist=default --exclude-category=child,wales --exclude-channel=alba,cbbc,cbeebies,parliament
* Now, to run the preset at any time I simply type:
get_iplayer --preset=last24 or get_iplayer -z last24
* Record programme number 123 with subtitles (if available) and optionally insert a
subtitle delay of 5 seconds:
get_iplayer --subtitles --suboffset 5000 --get 123
* (Re)download subtitles only (if available):
get_iplayer --subsonly --get 123
Programme Detailed Stream Information
* Display the Various stream URLs for programme index 123:
./get_iplayer --streaminfo 123
Full Program Information Display
* Display the programme metadata for index 123:
./get_iplayer --info 123
Metadata Files
* The programme metadata can be additionally downloaded using the —metadata=[TYPE] option. Where [TYPE] is one of xbmc, xbmc_movie, freevo, generic.
* Save all the metadata after a successful download into an xml file:
./get_iplayer --metadata=generic --get 123
* Save all the metadata ONLY for a specific search into an xml file (and don’t record the programme). This is useful if you forgot to get the metadata when recording.
./get_iplayer --metadata-only --metadata=generic 123
Thumbnails
* A programme thumbnail can be automatically downloaded using the —thumbnail option.
./get_iplayer --thumbnail --get 123
* Save all the thumbnail(s) ONLY for a specific search (and don’t record the programme). This is useful if you forgot to get the thumbnail when recording.
./get_iplayer --thumbnail-only 123
Update Your Entire Recording Collection with Thumbnails, Metadata and Subtitles
As long as your programmes remain in the directory they were originally recorded into you can retrospecitvely download the thumbnail, metadata or subtitles of the shows in your recordings history.
* Get all thumbnails for files that still exist (in this case for programmes matching ‘Doctor Who’):
./get_iplayer --thumbnail-only --history --skipdeleted "Doctor Who"
* Get all the metadata files (in generic format) for files that still exist:
./get_iplayer --metadata-only --metadata=generic --history --skipdeleted
* Get all subtitles for files that still exist (Note that you can only get subs if the programme is still available on iPlayer):
./get_iplayer --subs-only --history --skipdeleted
FIlenames
* Use a user defined filename-prefix format using substitution parameters:
--file-prefix="<name>-<episode>-<longname>-<version>-<pid>"
* Use a filename format using substitution parameters suited to XBMC, Boxee and MythTV:
--file-prefix="<nameshort>-<episodeshort>-<senum>-<pid>"
Valid Characters
Several options exist for controlling what characters are allowed in filenames.
* Allow use of spaces in filenames (by default these are converted to ‘_’).
--whitespace
* Use only filenames valid for DOS/Windows FAT filesystem.
--fatfilename
Recording to Specific Directories
* Use a specific directory for all programmes recorded:
--output="/home/user/recordings/"
* Override the above for all radio (or tv) programmes recorded:
--outputradio="/home/user/recordings-radio/" --outputtv="/home/user/recordings-tv/"
Subdirectories
* Use a subdirectory for each programme name:
--subdir
* Use a user-defined subdirectory format using substitution parameters:
--subdir-format="<nameshort>-<seriesnum>"
* Run a custom user command after a successful recording using substitution parameters:
get_iplayer --get 123 --command 'echo "<index> <filename> <name> <episode> <desc> <available> <longname> <duration> <versions> <version> <thumbnail> <channel> <categories> <type> <pid>"'
* Using the command option to background transcode your recorded video to mp4 format:
get_iplayer --get 123 --command "mencoder -ovc lavc -lavcopts vcodec=mpeg4 -oac lavc -lavcopts abitrate=128 -o <filename>.mp4 <filename> -quiet &"
The PVR functionality allows you to record any number of iPlayer programmes
using any combination of search terms that you would normally run on the
command line. The PVR searches are saved in ~/.get_iplayer/pvr/.
You can Add, Delete and List the PVR searches. This feature allows you to
run multiple batch recordings from a scheduler such as Unix crond (and possibly
the Windows scheduler). A tutorial is on how to setup and use the PVR is here.
* Add a new PVR search for a specific programme (i.e. ‘series link’):
get_iplayer --pvr-add=Top_Gear --type=tv "Top Gear"
* Add a new PVR search (using more search options):
get_iplayer --pvr-add=bbc1_comedy_tv_progs --category=comedy --type=tv --output=/path/to/my/pvr/recordings/ --channel="BBC One"
* Add a new One-Off recording PVR search. This will effectively queue the programmes for recording and delete the PVR search after completion:
get_iplayer --pvr-queue --type tv 123 231 32 "Blue Peter"
* Add a new One-Off recording PVR search for a specific PID:
get_iplayer --pvr-queue --pid=tv:b01a2b3c
* List the PVR searches already added:
get_iplayer --pvr-list
* Remove a PVR search:
get_iplayer --pvr-del=Top_Gear
* Disable a PVR search:
get_iplayer --pvr-disable=Top_Gear
* Re-enable a PVR search:
get_iplayer --pvr-enable=Top_Gear
* Run the PVR (this really should be added to your scheduler such as cron):
get_iplayer --pvr
* Add this line to add to user’s crontab (use ‘crontab -e’ to edit) – this will run all of the PVR jobs every hour:
0 * * * * /path/to/get_iplayer --pvr 2>>/tmp/get_iplayer.log
* Optionally, to notify by email when programme(s) have been recorded, add this to the top of your crontab (this will catch the stdout from the cron job and send to the specified email address):
MAILTO=me@mydomain.com
* Or, run the PVR Scheduler from the command line. This will fire off the PVR every hour as long as the command is running:
get_iplayer --pvrscheduler 3600
* On the latest installer there will be an entry in the Start menu to ‘Run PVR Scheduler Now’. This will start a command window which will fire off the PVR every 4 hours.
* Alternatively if you wish to use the Windows Scheduler see this guide for full instructions.
* The following substitutions may be available to certain options such as —command and —fileprefix. To see a list of all available parameters for a specific programme use the —info option.
<index> => index number <name> => programme short name <seriesnum> => Series number <nameshort> => programme name with series number stripped. <episode> => Episode info <episodenum> => Episode number <episodeshort> => programme episode with episode number stripped. <senum> => Series and Episode numbers in the s##e## format. <desc> => Long Description <descshort> => Short Description <descmedium> => Medium Description <versions> => comma separated list of versions <version> => selected version e.g 'signed' <thumbnail> => programme thumbnail url <web> => programme url <channel> => Programme channel <categories> => Categories <type> => Type: tv, podcast, or radio <mode> => Mode used to obtain programme <filename> => Filename of recorded file <filepart> => Filename of partially recorded file <dir> => Directory of file <fileprefix> => Filename Prefix of file <symlink> => Filename of any symlink file if specified <ext> => Filename Extension of file <duration> => duration in HH:MM:SS or seconds <available> => Date/Time made available or remaining <dldate> => Date when the file was obtained in YYYY-MM-DD format <dltime> => Time when the file was obtained in HH:MM:SS format <timeadded> => time when programme was added to cache (epoch format) <expiry> => time when programme will expire from web <expiryrel> => relative time when programme will expire from web <firstbcast> => time when programme was first broadcast <firstbcastrel> => relative time when programme was first broadcast <lastbcast> => time when programme was last broadcast <lastbcastrel> => relative time when programme was last broadcast
* Several external programs can be used by get_iplayer. The required programs for each mode and type are listed here. The following options are used to specify the exact path so that get_iplayer knows where they are. If they are already in the PATH then there is no need to specify them:
--mplayer --flvstreamer --atomicparsley --vlc --id3v2 --lame --ffmpeg
* e.g. to save the ffmpeg location to your default settings in Windows (you don’t need to do this if you use the get_iplayer installer):
get_iplayer --add-prefs --ffmpeg="C:\Program Files\get_iplayer\ffmpeg\bin\ffmpeg.exe"
* e.g. to save the ffmpeg location to your default settings in Linux/OS X (you don’t need to do this if the ffmpeg directory is in your $PATH):
get_iplayer --add-prefs --ffmpeg="/usr/bin/ffmpeg"
- The first time you run the script it will access the BBC website XML feeds and create an index of all programmes currently available.
- Sometimes you will not be able to record a programme listed due to BBC not encoding it yet for H.264 iPhone format (usually happens within 24hrs of airing).
- Also BBC don’t seem to create an iPhone H.264 version for some programmes at all. If this is the case look into using the rtmp recording modes.
- Windows/ActiveState Perl does not support fifos/named pipes and therefore any RealAudio radio recording will only be transcoded to mp3 after recording. Also none of the —stdout options will work with RealAudio radio.
* These still need documenting:
--multimode --email --series --tree --terse --thumbsize[cache] --hide --force --overwrite