GET_IPLAYER(1)

NAME
get_iplayer - Stream Recording tool and PVR for BBC iPlayer

SYNOPSIS
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>]

DESCRIPTION
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.

OPTIONS

  Search Options:

--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 recordings history (requires search term)

--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)

  Display Options:

--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.

  Recording Options:

--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,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>
    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.

  Output Options:

--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.

  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 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:

--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&..."

  External Program Options:

--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.

  Tagging Options:

--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.

  Misc Options:

--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

  Deprecated Options:

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

AUTHOR
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 <jmw@debian.org> for the Debian project (but may be used by others).

COPYRIGHT NOTICE
get_iplayer v3.17, 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.