options

notnac edited this page Sep 21, 2018 · 55 revisions

get_iplayer Options

(Return to ToC)

Table of Contents

Search Options

Command line Options file Description
--available-since <hours> availablesince <hours> Limit search to programmes that have become available in the last <hours> hours
--before <hours> before <hours> Limit search to programmes added to the cache before <hours> hours ago
--category <string> category <string> Narrow search to matched categories (comma-separated regex list). Defaults to substring match. Only works with --history.
--channel <string> channel <string> Narrow search to matched channel(s) (comma-separated regex list). Defaults to substring match.
--exclude <string> exclude <string> Narrow search to exclude matched programme names (comma-separated regex list). Defaults to substring match.
--exclude-category <string> excludecategory <string> Narrow search to exclude matched categories (comma-separated regex list). Defaults to substring match. Only works with --history.
--exclude-channel <string> excludechannel <string> Narrow search to exclude matched channel(s) (comma-separated regex list). Defaults to substring match.
--expires-before <hours> expiresbefore <hours> Limit search to programmes that will expire in the next <hours> hours
--fields <field1>,<field2>,... 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 future 1 Additionally search future programme schedule if it has been indexed (refresh cache with: --refresh --refresh-future).
--history history 1 Search recordings history (requires search term)
--long, -l long 1 Additionally search in programme descriptions and episode names (same as --fields=name,episode,desc )
--search <search term> search <search term> GetOpt compliant way of specifying search args
--since <hours> since <hours> Limit search to programmes added to the cache in the last <hours> hours
--type <type>,<type>,... type <type>,<type>,... Only search in these types of programmes: tv,radio,all (tv is default)

Display Options

Command line Options file Description
--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 1 Hide previously recorded programmes
--info, -i info 1 Show full programme metadata and availability of modes and subtitles (max 40 matches)
--list <element> 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> listformat <format> Display search results with a custom format. Use substitution parameters in format string (see docs for list).
--long, -l long Show extended programme info
--manpage <file> manpage <file> Create man page based on current help text
--nocopyright nocopyright 1 Don't display copyright header
--page <number> page <number> Page number to display for multipage output
--pagesize <number> pagesize <number> Number of matches displayed on a page for multipage output
--quiet, -q quiet 1 Reduce logging output
--series series 1 Display programme series names only with number of episodes
--show-cache-age showcacheage 1 Display the age of the selected programme caches then exit
--show-options showoptions 1 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> sortmatches <fieldname> Field to use to sort displayed matches
--sortreverse sortreverse 1 Reverse order of sorted matches
--streaminfo streaminfo 1 Returns all of the media stream URLs of the programme(s)
--terse terse 1 Only show terse programme info (does not affect searching)
--tree tree 1 Display programme listings in a tree view
--verbose, -v verbose 1 Show additional output (useful for diagnosing problems)
--warranty Displays warranty section of GPLv3
-V showver 1 Show get_iplayer version and exit.

Recording Options

Command line Options file Description
--attempts <number> 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 audioonly 1 Only download audio stream for TV programme. 'hls' recording modes are not supported and ignored. Produces .m4a file. Implies --force.
--download-abortonfail downloadabortonfail 1 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>,... excludesupplier <supplier>,<supplier>,... Comma-separated list of media stream suppliers to skip. Possible values: akamai,limelight,bidi
--force force 1 Ignore programme history (unsets --hide option also).
--fps25 fps25 1 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 hash 1 Show recording progress as hashes
--hls-hq-audio hlshqaudio 1 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>,... includesupplier <supplier>,<supplier>,... Comma-separated list of media stream suppliers to use if not included by default. Possible values: akamai,limelight,bidi
--log-progress logprogress 1 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>,... 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 nodashremux 1 Do not perform additional remux to ensure DASH downloads are compatible with iTunes, Windows Media Player, and some others.
--no-proxy noproxy 1 Ignore --proxy setting in preferences and/or http_proxy environment variable.
--no-resume noresume 1 Do not resume partial HLS/DASH downloads.
--no-verify noverify 1 Do not verify size of downloaded HLS/DASH file segments or file resize upon resume.
--overwrite overwrite 1 Overwrite recordings if they already exist
--partial-proxy partialproxy 1 Only uses web proxy where absolutely required (try this extra option if your proxy fails).
--pid <pid>,<pid>,... pid <pid>,<pid>,... Record arbitrary PIDs that do not necessarily appear in the index.
--pid-recursive pidrecursive 1 Record all related episodes if value of --pid is a series or brand PID. Requires --pid.
--pid-recursive-list pidrecursivelist 1 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> proxy <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>,... radiomode <mode>,<mode>,... Radio recording modes (overrides --modes): dafhigh,dafstd,dafmed,daflow,hafhigh,hafstd,hafmed,haflow,hlastd,hlalow. Shortcuts: best,better,good,worst,haf,daf,hls,dash,high,std,med,low (default=hafhigh,dafhigh,hafstd,hlastd,dafstd,hafmed,dafmed,haflow,hlalow,daflow).
--start <secs|hh:mm:ss> 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> stop <secs|hh:mm:ss> Recording/streaming stop offset (actual stop may be several seconds later for HLS and DASH streams)
--stream-http streamhttp 1 Use HTTP (instead of HTTPS) media stream playlist URLs.
--subtitles-required subsrequired 1 Do not download TV programme if subtitles are not available. Implies --subtitles.
--test, -t test 1 Test only - no recording (will show programme type)
--tvmode <mode>,<mode>,... 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>,... url <url>,<url>,... Record the PIDs contained in the specified iPlayer episode URLs.
--versions <versions> versionlist <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 line Options file Description
--command, -c <command> command <command> User command to run after successful recording of programme. Use substitution parameters in command string (see docs for list).
--command-radio <command> commandradio <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> commandtv <command> User command to run after successful recording of TV programme. Use substitution parameters in command string (see docs for list). Overrides --command.
--credits credits 1 Download programme credits, if available.
--credits-only creditsonly 1 Only download programme credits (if available), not programme.
--file-prefix <format> fileprefix <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> limitprefixlength <length> The maximum length for a file prefix. Defaults to 240 to allow space within standard 256 limit.
--metadata metadata Create metadata info file after recording.
--metadata-only metadataonly 1 Create specified metadata info file without any recording or streaming.
--no-metadata nometadata 1 Do not create metadata info file after recording (overrides --metadata).
--no-sanitise nosanitise 1 Do not sanitise output file and directory names. Implies --whitespace. Invalid characters for Windows ("*:<>?|) and macOS (:) will be removed.
--output, -o <dir> output <dir> Recording output directory
--outputradio <dir> outputradio <dir> Output directory for radio recordings (overrides --output)
--outputtv <dir> outputtv <dir> Output directory for tv recordings (overrides --output)
--raw raw 1 Don't remux or change the recording in any way. Saves output file in native container format (HLS->MPEG-TS, DASH->MP4)
--subdir, -s subdir 1 Save recorded files into subdirectory of output directory. Default: same name as programme (see --subdir-format).
--subdir-format <format> subdirformat <format> The format to be used for subdirectory naming. Use substitution parameters in format string (see docs for list).
--suboffset <offset> suboffset <offset> Offset the subtitle timestamps by the specified number of milliseconds
--subs-embed subsembed 1 Embed soft subtitles in MP4 output file. Ignored with --audio-only and --ffmpeg-obsolete. Implies --subtitles.
--subs-mono subsmono 1 Create monochrome titles, with leading hyphen used to denote change of speaker. Implies --subtitles.
--subs-raw subsraw 1 Additionally save the raw subtitles file. Implies --subtitles.
--subtitles subtitles 1 Download subtitles into srt/SubRip format if available and supported
--subtitles-only subsonly 1 Only download the subtitles, not the programme
--tag-only tagonly 1 Only update the programme metadata tag and not download the programme. Use with --history or --tag-only-filename.
--tag-only-filename <filename> tagonlyfilename <filename> Add metadata tags to specified file (ignored unless used with --tag-only)
--thumb thumb 1 Download thumbnail image if available
--thumb-ext <ext> thumbext <ext> Thumbnail filename extension to use
--thumbnail-only thumbonly 1 Only download thumbnail image if available, not the programme
--thumbnail-series thumbseries 1 Force use of series/brand thumbnail (series preferred) instead of episode thumbnail
--thumbnail-size <width> thumbsize <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 thumbsquare 1 Download square version of thumbnail image.
--tracklist tracklist 1 Download track list of music played in programme, if available. Track times and durations may be missing or incorrect.
--tracklist-only tracklistonly 1 Only download track list of music played in programme (if available), not programme.
--whitespace, -w whitespace 1 Keep whitespace in file and directory names. Default behaviour is to replace whitespace with underscores.

PVR Options

Command line Options file Description
--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

Config Options

Command line Options file Description
--cache-rebuild Rebuild cache with full 30-day programme index. Use --refresh-limit to restrict cache window.
--expiry, -e <secs> expiry <secs> Cache expiry in seconds (default 4hrs)
--limit-matches <number> limitmatches <number> Limits the number of matching results for any search (and for every PVR search)
--nopurge nopurge 1 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 1 Refresh cache
--refresh-abortonerror refreshabortonerror 1 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>,... refreshexclude <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>,... refreshexcludegroups <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>,... refreshexcludegroupsradio <group>,<group>,... Exclude channel groups when refreshing radio cache (comma-separated values). Valid values: 'national', 'regional', 'local'
--refresh-exclude-groups-tv <group>,<group>,... refreshexcludegroupstv <group>,<group>,... Exclude channel groups when refreshing TV cache (comma-separated values). Valid values: 'national', 'regional', 'local'
--refresh-future refreshfuture 1 Obtain future programme schedule when refreshing cache
--refresh-include <channel>,<channel>,... refreshinclude <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>,... refreshincludegroups <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>,... refreshincludegroupsradio <group>,<group>,... Include channel groups when refreshing radio cache (comma-separated values). Valid values: 'national', 'regional', 'local'
--refresh-include-groups-tv <group>,<group>,... refreshincludegroupstv <group>,<group>,... Include channel groups when refreshing TV cache (comma-separated values). Valid values: 'national', 'regional', 'local'
--refresh-limit <days> refreshlimit <days> Minimum number of days of programmes to cache. Makes cache updates slow. Default: 7 Min: 1 Max: 30
--refresh-limit-radio <days> refreshlimitradio <days> Number of days of radio programmes to cache. Makes cache updates slow. Default: 7 Min: 1 Max: 30
--refresh-limit-tv <days> refreshlimittv <days> Number of days of TV programmes to cache. Makes cache updates slow. Default: 7 Min: 1 Max: 30
--skipdeleted skipdeleted 1 Skip the download of metadata/thumbs/subs if the media file no longer exists. Use with --history & --metadataonly/subsonly/thumbonly.
--webrequest <urlencoded string> webrequest <urlencoded string> Specify all options as a urlencoded string of "name=val&name=val&..."

External Program Options

Command line Options file Description
--atomicparsley <path> atomicparsley <path> Location of AtomicParsley binary
--ffmpeg <path> ffmpeg <path> Location of ffmpeg binary. Assumed to be ffmpeg 3.0 or higher unless --ffmpeg-obsolete is specified.
--ffmpeg-force ffmpegforce 1 Bypass version checks and assume ffmpeg is version 3.0 or higher
--ffmpeg-loglevel <level> ffmpegloglevel <level> Set logging level for ffmpeg. Overridden by --quiet and --silent. Default: 'fatal'
--ffmpeg-obsolete ffmpegobsolete 1 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

Command line Options file Description
--no-artwork noartwork 1 Do not embed thumbnail image in output file. Also removes existing artwork. All other metadata values will be written.
--no-tag notag 1 Do not tag downloaded programmes.
--tag-credits tag_credits 1 Add programme credits (if available) to lyrics field.
--tag-format-show tag_formatshow Format template for programme name in tag metadata. Use substitution parameters in template (see docs for list). Default: <name>
--tag-format-title tag_formattitle Format template for episode title in tag metadata. Use substitution parameters in template (see docs for list). Default: <episodeshort>
--tag-isodate tag_isodate 1 Use ISO8601 dates (YYYY-MM-DD) in album/show names and track titles
--tag-podcast tag_podcast 1 Tag downloaded radio and tv programmes as iTunes podcasts
--tag-podcast-radio tag_podcast_radio 1 Tag only downloaded radio programmes as iTunes podcasts
--tag-podcast-tv tag_podcast_tv 1 Tag only downloaded tv programmes as iTunes podcasts
--tag-tracklist tag_tracklist 1 Add track list of music played in programme (if available) to lyrics field.
--tag-utf8 tag_utf8 1 Use UTF-8 encoding for non-ASCII characters in AtomicParsley parameter values (Linux/Unix/macOS only). Use only if auto-detect fails.

Misc Options

Command line Options file Description
--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> indexmaxconn <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> throttle <Mb/s> Bandwidth limit (in Mb/s) for media file download. Default: unlimited. Synonym: --bw
--trim-history <# days to retain> trimhistory <# 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

Command line Options file Description
--no-index-concurrent noindexconcurrent 1 Do not use concurrent indexing to update programme cache. Cache updates will be very slow.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.