-
Notifications
You must be signed in to change notification settings - Fork 231
manpage
get_iplayer - Stream Recording tool and PVR for BBC iPlayer
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>]
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.
--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 fields. The fields are concatenated with spaces in the order specified and the search term is applied to the resulting string.
--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: tv,radio,all (tv is default)
--conditions : Shows GPLv3 conditions
--debug : Debug output (very verbose and rarely useful)
--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 search results with a custom format. Use substitution parameters in format string (see docs for list).
--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.
--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.
--audio-only : Only download audio stream for TV programme. 'hls' recording modes are not supported and ignored. Produces .m4a file. Implies --force.
--download-abortonfail : Exit immediately if stream for any recording mode fails to download. Use to avoid repeated failed download attempts if connection is dropped or access is blocked.
--exclude-supplier <supplier>,<supplier>,... : Comma-separated list of media stream suppliers to skip. Possible values: akamai,limelight,bidi
--force : Ignore programme history (unsets --hide option also).
--fps25 : Use only 25fps streams for TV programmes (HD video not available).
--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-hq-audio : Attempt to download higher-quality audio for 'hlshd' mode (TV only). Output file may require editing to sync audio and video.
--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.
--mark-downloaded : Mark programmes in search results or specified with --pid/--url as downloaded by inserting records in download history.
--modes <mode>,<mode>,... : Recording modes. See --tvmode and --radiomode (with --long-help) for available modes and defaults. Shortcuts: tvbest,tvbetter,tvgood,tvworst,radiobest,radiobetter,radiogood,radioworst (default=default for programme type).
--no-dash-remux : Do not perform additional remux to ensure DASH downloads are compatible with iTunes, Windows Media Player, and some others.
--no-proxy : Ignore --proxy setting in preferences and/or http_proxy environment variable.
--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).
--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.
--pid-recursive-list : If value of --pid is a series or brand PID, list available episodes but do not download. Implies --pid-recursive. Requires --pid.
--proxy, -p <url> : Web proxy URL, e.g., http://username:password@server:port or http://server:port. Value of http_proxy environment variable (if present) will be used unless --proxy is specified. Used for both HTTP and HTTPS. Overridden by --no-proxy.
--radiomode <mode>,<mode>,... : Radio recording modes (overrides --modes): dafhigh,dafstd,dafmed,daflow,hafhigh,hafstd,hafmed,haflow. Shortcuts: best,better,good,worst,haf,daf,hls,dash,high,std,med,low (default=hafhigh,dafhigh,hafstd,dafstd,hafmed,dafmed,haflow,daflow).
--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)
--stream-http : Use HTTP (instead of HTTPS) media stream playlist URLs.
--subtitles-required : Do not download TV programme if subtitles are not available.
--test, -t : Test only - no recording (will show programme type)
--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).
--url <url>,<url>,... : Record the PIDs contained in the specified iPlayer episode URLs.
--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.
--command, -c <command> : User command to run after successful recording of programme. Use substitution parameters in command string (see docs for list).
--command-radio <command> : User command to run after successful recording of radio programme. Use substitution parameters in command string (see docs for list). Overrides --command.
--command-tv <command> : User command to run after successful recording of TV programme. Use substitution parameters in command string (see docs for list). Overrides --command.
--credits : Download programme credits, if available.
--credits-only : Only download programme credits (if available), not programme.
--file-prefix <format> : The filename prefix template (excluding dir and extension). Use substitution parameters in template (see docs for list). Default: <name> - <episode> <pid> <version>
--limitprefixlength <length> : The maximum length for a file prefix. Defaults to 240 to allow space within standard 256 limit.
--metadata : Create metadata info file after recording.
--metadata-only : Create specified metadata info file without any recording or streaming.
--no-metadata : Do not create metadata info file after recording (overrides --metadata).
--no-sanitise : Do not sanitise output file and directory names. Implies --whitespace. Invalid characters for Windows ("*:<>?|) and macOS (:) will be removed.
--output, -o <dir> : Recording output directory
--outputradio <dir> : Output directory for radio recordings (overrides --output)
--outputtv <dir> : Output directory for tv recordings (overrides --output)
--raw : Don't remux or change the recording in any way. Saves output file in native container format (HLS->MPEG-TS, DASH->MP4)
--subdir, -s : Save recorded files into subdirectory of output directory. Default: same name as programme (see --subdir-format).
--subdir-format <format> : The format to be used for subdirectory naming. Use substitution parameters in format string (see docs for list).
--suboffset <offset> : Offset the subtitle timestamps by the specified number of milliseconds
--subs-embed : Embed soft subtitles in MP4 output file. Ignored with --audio-only and --ffmpeg-obsolete.
--subs-mono : Create monochrome titles, with leading hyphen used to denote change of speaker.
--subs-raw : 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
--tag-only : Only update the programme metadata tag and not download the programme. Use with --history or --tag-only-filename.
--tag-only-filename <filename> : Add metadata tags to specified file (ignored unless used with --tag-only)
--thumb : Download thumbnail image if available
--thumb-ext <ext> : Thumbnail filename extension to use
--thumbnail-only : Only download thumbnail image if available, not the programme
--thumbnail-series : Force use of series/brand thumbnail (series preferred) instead of episode thumbnail
--thumbnail-size <width> : Thumbnail size to use for the current recording and metadata. Specify width: 192,256,384,448,512,640,704,832,960,1280,1920. Invalid values will be mapped to nearest available. Default: 192
--thumbnail-square : Download square version of thumbnail image.
--tracklist : Download track list of music played in programme, if available. Track times and durations may be missing or incorrect.
--tracklist-only : Only download track list of music played in programme (if available), not programme.
--whitespace, -w : Keep whitespace in file and directory names. Default behaviour is to replace whitespace with underscores.
--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-series : Create PVR search for each unique series name in search results. Search terms required. Synonyms: --pvrseries
--pvr-single <search name> : Runs a named PVR search. Synonyms: --pvrsingle
--cache-rebuild : Rebuild cache with full 30-day programme index. Use --refresh-limit to restrict cache window.
--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 show warning about 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&..."
--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-loglevel <level> : Set logging level for ffmpeg. Overridden by --quiet and --silent. Default: 'fatal'
--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.
--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.
--tag-credits : Add programme credits (if available) to lyrics field.
--tag-format-show : Format template for programme name in tag metadata. Use substitution parameters in template (see docs for list). Default: <name>
--tag-format-title : Format template for episode title in tag metadata. Use substitution parameters in template (see docs for list). 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-tracklist : Add track list of music played in programme (if available) to lyrics field.
--tag-utf8 : Use UTF-8 encoding for non-ASCII characters in AtomicParsley parameter values (Linux/Unix/macOS only). Use only if auto-detect fails.
--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
--purge-files : Delete downloaded programmes more than 30 days old
--throttle <Mb/s> : Bandwidth limit (in Mb/s) for media file download. Default: unlimited. Synonym: --bw
--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
--no-index-concurrent : Do not use concurrent indexing to update programme cache. Cache updates will be very slow.
get_iplayer was written by Phil Lewis <iplayer2 (at sign) linuxcentre.net> and is now maintained by the contributors at https://github.com/get-iplayer/get_iplayer
This manual page was originally written by Jonathan Wiltshire <[email protected]> for the Debian project (but may be used by others).
get_iplayer v3.16, 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.