manpage

dinkypumpkin edited this page Aug 26, 2017 · 45 revisions

get_iplayer Unix Manual Page

(Return to ToC)

Table of Contents

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 comma separated fields

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

Display Options

--conditions : Shows GPLv3 conditions

--debug : Debug output

--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 programme data based on a user-defined format string containing substitution parameters (such as <pid>, <name>, <episode>, etc.)

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

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

--fps50 : Prefer 50 fps streams for TV programmes (not available for all video sizes).

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

--include-https : Allow HTTPS playlist/manifest/segment URLs for media streams.

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

--modes <mode>,<mode>,... : Recording modes. See --tvmode and --radiomode (with --long-help) for available modes and defaults. Shortcuts: tvworst,tvworse,tvgood,tvvgood,tvbetter,tvbest,radioworst,radioworse,radiogood,radiovgood,radiobetter,radiobest (default=default for programme type).

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

--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,hlsaacstd,hlsaaclow. Shortcuts: worst,worse,good,vgood,better,best,daf,haf,hlsaac (default=dafhigh,hafhigh,dafstd,hafstd,hlsaacstd,dafmed,hafmed,daflow,haflow,hlsaaclow).

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

--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,hlsvhigh,hlsstd,hlsxstd,hvfhd,hvfsd,hvfxsd,hvfhigh,hvfxhigh,hvflow. Shortcuts: worst,worse,vgood,better,best,dvf,hls,hvf (default=hlshd,hvfxsd,hlsvhigh,hvfxhigh,hlsstd,hlsxstd,hvflow).

--url <url>,<url>,... : Record the embedded media in the specified iPlayer episode URLs. Use with --type.

--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> : Run user command after successful recording of programme using substitution paramaters such as <dir>, <fileprefix>, <filename>, etc.

--command-radio <command> : Run user command after successful recording of radio programme using substitution paramaters such as <dir>, <fileprefix>, <filename>, etc. Overrides --command.

--command-tv <command> : Run user command after successful recording of tv programme using substitution paramaters such as <dir>, <fileprefix>, <filename>, etc. Overrides --command.

--file-prefix <format> : The filename prefix (excluding dir and extension) using formatting fields. e.g. '<name>-<episode>-<pid>'

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

--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. Default: same name as programme.

--subdir-format <format> : The format to be used for subdirectory naming. Use substitution parameters, e.g., '<nameshort>-<seriesnum>'

--suboffset <offset> : Offset the subtitle timestamps by the specified number of milliseconds

--subs-mono : Create monochrome titles, with leading hyphen used to denote change of speaker.

--subsraw : 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 (can also be used with --history)

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

--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. Default: 192

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

--cache-reset : Reset cache to retain only latest update and discard previous contents.

--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 ask to delete 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. Note that moov atom will be at end of output file if --no-tag used. Remuxing would be necessary to stream file.

--tag-format-show : Format template for programme name in tag metadata (use substitution parameters). Default: <name>

--tag-format-title : Format template for episode title in tag metadata (use substitution parameters). 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-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

--throttle <Mibit/s> : Bandwidth limit (in Mibit/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.02, 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.