get_iplayer - Man Page

Limit search to programmes that became available before <hours> hours ago

Limit search to programmes that have become available in the last <hours> hours

Limit search to programmes added to the cache before <hours> hours ago

Narrow search to matched categories (comma-separated regex list).  Defaults to substring match.  Only works with --history.

Narrow search to matched channel(s) (comma-separated regex list).  Defaults to substring match.

Narrow search to exclude matched programme names (comma-separated regex list).  Defaults to substring match.

Narrow search to exclude matched categories (comma-separated regex list).  Defaults to substring match.  Only works with --history.

Narrow search to exclude matched channel(s) (comma-separated regex list).  Defaults to substring match.

Limit search to programmes that will expire after <hours> hours from now

Limit search to programmes that will expire before <hours> hours from now

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.

Additionally search future programme schedule if it has been indexed (refresh cache with: --refresh --refresh-future).

Search recordings history (requires search term)

Additionally search in programme descriptions and episode names (same as --fields=name,episode,desc )

GetOpt compliant way of specifying search args

Limit search to programmes added to the cache in the last <hours> hours

Only search in these types of programmes: tv,radio,all (tv is default)

Shows GPLv3 conditions

Debug output (very verbose and rarely useful)

Dumps all options with their internal option key names

Intermediate help text

Basic help text

Advanced help text

Hide previously recorded programmes

Show full programme metadata and availability of streams and subtitles (max 40 matches)

Show a list of distinct element values (with counts) for the selected programme type(s) and exit.  Valid elements are: 'channel'

Display search results with a custom format. Use substitution parameters in format string (see docs for list).

Show extended programme info

Create man page based on current help text

Don't display copyright header

Page number to display for multipage output

Number of matches displayed on a page for multipage output

Reduce logging output

Display programme series names only with number of episodes

Display the age of the selected programme caches then exit

Show options which are set and where they are defined

No logging output except PVR download report.  Cannot be saved in preferences or PVR searches.

Field to use to sort displayed matches

Reverse order of sorted matches

Returns all of the media stream URLs of the programme(s)

Only show terse programme info (does not affect searching)

Display programme listings in a tree view

Show additional output (useful for diagnosing problems)

Displays warranty section of GPLv3

Show get_iplayer version and exit.

Number of attempts to make or resume a failed connection.  --attempts is applied per-stream. Programmes have multiple streams available for each recording quality.

Only download audio stream for TV programme. Produces .m4a file. Implies --force.

Exit immediately if any stream fails to download. Use to avoid repeated failed download attempts if connection is dropped or access is blocked.

Comma-separated list of media stream formats to ignore when recording. Valid values: hls,dash.

Comma-separated list of media stream suppliers (CDNs) to skip. Possible values: akamai,limelight,bidi,cloudfront. Synonym: --exclude-cdn.

Ignore programme history (unsets --hide option also).

Start recording matching programmes. Search terms required.

Show recording progress as hashes

Comma-separated list of media stream to use when recording. Overrides --exclude-format. Valid values: hls,dash

Comma-separated list of media stream suppliers (CDNs) to use if not included by default or if previously excluded by --exclude-supplier. Possible values: akamai,limelight,bidi,cloudfront. Synonym: --include-cdn.

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 programmes in search results or specified with --pid/--url as downloaded by inserting records in download history.

Do not merge programme versions with same name and duration.

Ignore --proxy setting in preferences and/or http_proxy environment variable.

Do not resume partial HLS/DASH downloads.

Do not verify size of downloaded HLS/DASH file segments or file resize upon resume.

Overwrite recordings if they already exist

Only uses web proxy where absolutely required (try this extra option if your proxy fails).

Record arbitrary PIDs that do not necessarily appear in the index.

Update (if necessary) and use programme index cache with --pid. Cache is not searched for programme by default with --pid. Synonym: --pid-refresh.

Record all related episodes if value of --pid is a series or brand PID.  Requires --pid.

If value of --pid is a series or brand PID, list available episodes but do not download. Implies --pid-recursive. Requires --pid.

Download only programmes of <type> (radio or tv) with --pid-recursive. Requires --pid-recursive.

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.

TV and radio recording quality preference.  See --tv-quality and --radio-quality for available values and defaults. Default: default for programme type.

Radio recording quality preference (overrides --quality): high,std,med,low,default (Aliases: 320k,128k,96k,48k). Comma-delimited list in descending order of preference. Default: high,std,med,low.

Recording/streaming start offset (actual start may be several seconds earlier for HLS and DASH streams)

Recording/streaming stop offset (actual stop may be several seconds later for HLS and DASH streams)

Do not download TV programme if subtitles are not available.

Test only - no recording (only shows search results with --pvr and --pid-recursive)

Prefer 25fps (or lower-bitrate 50fps) streams for TV programmes if available.

TV recording quality preference (overrides --quality): fhd,hd,sd,web,mobile,default (Aliases: 1080p,720p,540p,396p,288p). Comma-delimited list in descending order of preference. Default: hd,sd,web,mobile

Record the PIDs contained in the specified iPlayer episode URLs. Alias for --pid.

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. Versions: 'default,audiodescribed,signed,combined'. Default: 'default'.

User command to run after successful recording of programme. Use substitution parameters in command string (see docs for list).

User command to run after successful recording of radio programme. Use substitution parameters in command string (see docs for list). Overrides --command.

User command to run after successful recording of TV programme. Use substitution parameters in command string (see docs for list). Overrides --command.

Download programme credits, if available.

Only download programme credits, if available.

Create cue sheet (.cue file) for programme, if data available. Radio programmes only. Cue sheet will be very inaccurate and will required further editing. Cue sheet may require addition of UTF-8 BOM (byte-order mark) for some applications to identify encoding.

Offset track times in cue sheet and track list by the specified number of seconds. Synonym: --tracklist-offset

Only create cue sheet (.cue file) for programme, if data available. Radio programmes only.

The filename prefix template (excluding dir and extension). Use substitution parameters in template (see docs for list). Default: <name> - <episode> <pid> <version>

The maximum length for a file prefix.  Defaults to 240 to allow space within standard 256 limit.

Create metadata info file after recording. Valid values: generic,json. XML generated for 'generic', JSON for 'json'. If no value specified, 'generic' is used.

Create specified metadata info file without any recording or streaming.

Ensure raw audio and video files are re-muxed into MPEG-TS file regardless of stream format. Overrides --raw.

Do not create metadata info file after recording (overrides --metadata).

Do not sanitise output file and directory names. Implies --whitespace. Invalid characters for Windows ("*:<>?|) and macOS (:) will be removed.

Recording output directory

Output directory for radio recordings (overrides --output)

Output directory for tv recordings (overrides --output)

Don't remux or change the recording in any way.  Saves output file in native container format (HLS->MPEG-TS, DASH->MP4)

Save recorded files into subdirectory of output directory.  Default: same name as programme (see --subdir-format).

The format to be used for subdirectory naming.  Use substitution parameters in format string (see docs for list).

Offset the subtitle timestamps by the specified number of milliseconds.  Requires --subtitles.

Embed soft subtitles in MP4 output file. Ignored with --audio-only and --ffmpeg-obsolete. Requires --subtitles. Implies --subs-mono.

Create monochrome titles, with leading hyphen used to denote change of speaker. Requires --subtitles. Not required with --subs-embed.

Additionally save the raw subtitles file.  Requires --subtitles.

Download subtitles into srt/SubRip format if available and supported

Only download the subtitles, not the programme

Only update the programme metadata tag and not download the programme. Use with --history or --tag-only-filename.

Add metadata tags to specified file (ignored unless used with --tag-only)

Download thumbnail image if available

Thumbnail filename extension to use

Only download thumbnail image if available, not the programme

Force use of series/brand thumbnail (series preferred) instead of episode thumbnail

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: 1920 (1280 with --thumbnail-square)

Download square version of thumbnail image. Limits --thumbnail-size to 1280.

Create track list of music played in programme, if data available. Track times and durations may be missing or incorrect.

Only create track list of music played in programme, if data available.

Keep whitespace in file and directory names.  Default behaviour is to replace whitespace with underscores.

Adds a comment to a PVR search

Runs the PVR using all saved PVR searches (intended to be run periodically, e.g., from cron or Task Manager). The list can be limited by adding a regex to the command. Synonyms: --pvrrun, --pvr-run

Save the named PVR search with the specified search terms. Search terms required unless --pid specified. Synonyms: --pvradd

Remove the named search from the PVR searches. Synonyms: --pvrdel

Disable (not delete) a named PVR search. Synonyms: --pvrdisable

Enable a previously disabled named PVR search. Synonyms: --pvrenable

Exclude the PVR searches to run by search name (comma-separated regex list). Defaults to substring match. Synonyms: --pvrexclude

Show the PVR search list. Synonyms: --pvrlist

Add currently matched programmes to queue for later one-off recording using the --pvr option. Search terms required unless --pid specified. Synonyms: --pvrqueue

Runs the PVR using all saved PVR searches every <seconds>. Synonyms: --pvrscheduler

Create PVR search for each unique series name in search results. Search terms required. Synonyms: --pvrseries

Runs a named PVR search. Synonyms: --pvrsingle

Rebuild cache with full 30-day programme index. Use --refresh-limit to restrict cache window.

Cache expiry in seconds (default 4hrs)

Limits the number of matching results for any search (and for every PVR search)

Add/Change specified saved user or preset options

Remove *ALL* saved user or preset options

Remove specified saved user or preset options

Show saved user or preset options

Use specified user options preset

Show all valid presets

Override the user profile directory

Refresh cache

Abort cache refresh for programme type if data for any channel fails to download.  Use --refresh-exclude to temporarily skip failing channels.

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)

Exclude channel groups when refreshing radio or TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

Exclude channel groups when refreshing radio cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

Exclude channel groups when refreshing TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

Obtain future programme schedule when refreshing cache

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)

Include channel groups when refreshing radio or TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

Include channel groups when refreshing radio cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

Include channel groups when refreshing TV cache (comma-separated values).  Valid values: 'national', 'regional', 'local'

Minimum number of days of programmes to cache. Default: 7 Min: 1 Max: 30

Number of days of radio programmes to cache. Default: 7 Min: 1 Max: 30

Number of days of TV programmes to cache. Default: 7 Min: 1 Max: 30

Skip the download of metadata/thumbs/subs if the media file no longer exists.  Use with --history & --metadataonly/subsonly/thumbonly.

Specify all options as a urlencoded string of "name=val&name=val&..."

Location of AtomicParsley binary

Location of ffmpeg binary. Assumed to be ffmpeg 3.0 or higher unless --ffmpeg-obsolete is specified.

Bypass version checks and assume ffmpeg is version 3.0 or higher

Set logging level for ffmpeg. Overridden by --quiet and --silent. Default: 'fatal'

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.

Do not embed thumbnail image in output file. Also removes existing artwork. All other metadata values will be written.

Do not tag downloaded programmes.

Add programme credits (if available) to long description field.

(Windows only) Single-byte character encoding for non-ASCII characters in metadata tags. Encoding name must be known to Perl Encode module. Unicode (UTF* or UCS*) character encodings are not supported. Default: active code page or cp1252 (Windows code page 1252)

Format template for programme name in tag metadata. Use substitution parameters in template (see docs for list). Default: <name>

Format template for episode title in tag metadata. Use substitution parameters in template (see docs for list). Default: <episodeshort>

Use ISO8601 dates (YYYY-MM-DD) in album/show names and track titles

(Windows only) Do not attempt to perform Unicode tagging and use single-byte character encoding instead (see --tag-encoding)

Tag downloaded radio and tv programmes as iTunes podcasts (incompatible with Music/Podcasts/TV apps on macOS 10.15 and higher)

Tag only downloaded radio programmes as iTunes podcasts (incompatible with Music/Podcasts/TV apps on macOS 10.15 and higher)

Tag only downloaded tv programmes as iTunes podcasts (incompatible with Music/Podcasts/TV apps on macOS 10.15 and higher)

Add track list of music played in programme (if available) to lyrics field.

Character encoding for standard input (currently unused).  Encoding name must be known to Perl Encode module.  Default (only if auto-detect fails): Linux/Unix/macOS = UTF-8, Windows = cp850

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/macOS = UTF-8, Windows = cp850

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

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/macOS = UTF-8, Windows = cp1252

Character encoding used to encode commands sent from Web PVR.  Encoding name must be known to Perl Encode module.  Default = UTF-8

Maximum number of connections to use for concurrent programme indexing.  Default: 5 Min: 1 Max: 10

Forces check for new release if used on command line. Checks for new release weekly if saved in preferences.

Bandwidth limit (in Mb/s) for media file download. Default: unlimited. Synonym: --bw

Do not use concurrent indexing to update programme cache.  Cache updates will be very slow.