GET_IPLAYER(1)
💖 GET_IPLAYER 💖
okay bestie, sit down, hydrate, because this is the manual page for get_iplayer — the get_iplayer(1) page, your one-stop shop for grabbing BBC stuff. It's giving very much "I have a spreadsheet and I'm not afraid to use it". Let's go. 🫶
✨ NAME ✨
get_iplayer — Stream Recording tool and PVR for BBC iPlayer and BBC Sounds
so yeah, it's a recorder and a PVR. two modes, one icon. 💅
✨ 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 BBC Sounds radio programmes. literally all of it. ✨
ngl it has two modes, and they're both iconic in their own way:
- recording a complete programme so you can watch/listen later
- being a Personal Video Recorder (PVR) — it subscribes to your search terms and records programmes automatically like the little overachiever it is 🎀
so if you hand it the regex ".*" (yes, incl. quotes, the quotes are not optional bestie), it updates and displays the list of currently available TV programmes. want radio instead? use --type=radio. every available programme has an alphanumeric identifier called a PID. that's its little name tag. 🏷️
and in PVR mode, get_iplayer can be called from cron to record programmes on a schedule — set it and forget it, main character energy fr fr 👑
✨ OPTIONS ✨
quick housekeeping before we dive in: Boolean options can be negated by adding a "no-" prefix, e.g., --no-subtitles or --no-whitespace. and yes, this applies even if the base option name already begins with "no-", e.g., --no-no-tag or --no-no-artwork. double negative? she said yes. 💀
🔍 Search Options 🔍
--available-before <hours>— only look at programmes that became available before<hours>hours ago--available-since <hours>— only look at programmes that became available in the last<hours>hours--before <hours>— only look at programmes that were added to the cache before<hours>hours ago--category <string>— narrow the search to matched categories (comma-separated regex list). defaults to substring match. and heads up: this only works with--history--channel <string>— narrow the search to matched channel(s) (comma-separated regex list). defaults to substring match--exclude <string>— narrow the search by excluding matched programme names (comma-separated regex list). defaults to substring match. bye felicia 👋--exclude-category <string>— narrow the search by excluding matched categories (comma-separated regex list). defaults to substring match. only works with--history--exclude-channel <string>— narrow the search by excluding matched channel(s) (comma-separated regex list). defaults to substring match--expires-after <hours>— only look at programmes that will expire after<hours>hours from now--expires-before <hours>— only look at programmes that will expire before<hours>hours from now--fields <field1>,<field2>,...— searches only in the fields you name. the fields get concatenated with spaces in the order you specified, and then your search term is applied to the resulting string. string go brrr 🧵--future— also search the future programme schedule, if it's been indexed (refresh that cache with:--refresh --refresh-future)--history— search your recordings history (requires a search term)--long,-l— also search in programme descriptions and episode names (same as--fields=name,episode,desc)--search <search term>— the GetOpt-compliant way of specifying search args--since <hours>— only look at programmes added to the cache in the last<hours>hours--type <type>,<type>,...— only search in these types of programmes:tv,radio,all(tvis the default)
🖥️ Display Options 🖥️
--conditions— shows the GPLv3 conditions 📜--debug— debug output (very verbose and rarely useful — she said what she said)--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 streams and subtitles (max 40 matches)--list <element>— show a list of distinct element values (with counts) for the selected programme type(s), then exit. valid elements are:'channel'--listformat <format>— display search results with a custom format. use substitution parameters in the format string (see docs for list)--long,-l— show extended programme info--manpage <file>— create a man page based on the current help text (meta, honestly)--nocopyright— don't display the 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 the 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 the PVR download report. cannot be saved in preferences or PVR searches. ✨--sort <fieldname>— field to use to sort displayed matches--sortreverse— reverse the 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 the warranty section of GPLv3-V— showget_iplayerversion and exit
🎬 Recording Options 🎬
--attempts <number>— number of attempts to make or resume a failed connection.--attemptsis applied per-stream. programmes have multiple streams available for each recording quality. she's persistent 💪--audio-only— only download the audio stream for a TV programme. produces an.m4afile. implies--force--download-abort-onfail— exit immediately if any stream fails to download. use this to avoid repeated failed download attempts if your connection is dropped or access is blocked--exclude-format <format>,<format>,...— comma-separated list of media stream formats to ignore when recording. valid values:hls,dash--exclude-supplier <supplier>,<supplier>,...— comma-separated list of media stream suppliers (CDNs) to skip. possible values:akamai,limelight,bidi,cloudfront. synonym:--exclude-cdn--force— ignore programme history (this also unsets the--hideoption)--get,-g— start recording matching programmes. search terms required.--hash— show recording progress as hashes##########🔥--include-format <format>,<format>,...— comma-separated list of media stream to use when recording. overrides--exclude-format. valid values:hls,dash--include-supplier <supplier>,<supplier>,...— comma-separated list of media stream suppliers (CDNs) to use if they're not included by default, or if they were previously excluded by--exclude-supplier. possible values:akamai,limelight,bidi,cloudfront. synonym:--include-cdn--log-progress— force HLS/DASH download progress display to be captured when screen output is redirected to a file. normally the progress display is omitted unless you're writing to a terminal--mark-downloaded— mark programmes in search results, or ones specified with--pid/--url, as downloaded by inserting records in the download history--no-merge-versions— do not merge programme versions with the same name and duration--no-proxy— ignore the--proxysetting in preferences and/or thehttp_proxyenvironment variable--no-resume— do not resume partial HLS/DASH downloads--no-verify— do not verify the size of downloaded HLS/DASH file segments, or the file resize upon resume--overwrite— overwrite recordings if they already exist--partial-proxy— only uses the web proxy where absolutely required (try this extra option if your proxy fails)--pid <pid>,<pid>,...— record arbitrary PIDs that don't necessarily appear in the index--pid-index— update (if necessary) and use the programme index cache with--pid. the cache is not searched for the programme by default with--pid. synonym:--pid-refresh--proxy,-p <url>— web proxy URL, e.g.,http://username:password@server:portorhttp://server:port. the value of thehttp_proxyenvironment variable (if present) will be used unless--proxyis specified. used for both HTTP and HTTPS. overridden by--no-proxy--quality <quality>,<quality>,...— TV and radio recording quality preference. see--tv-qualityand--radio-qualityfor available values and defaults. default:defaultfor programme type--radio-quality <quality>,<quality>,...— 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--start <secs|hh:mm:ss>— recording/streaming start offset (heads up: the actual start may be several seconds earlier for HLS and DASH streams)--stop <secs|hh:mm:ss>— recording/streaming stop offset (heads up: the actual stop may be several seconds later for HLS and DASH streams)--subtitles-required— do not download a TV programme if subtitles are not available. no subs no service 🎀--test,-t— test only, no recording (only shows search results with--pvrand--pid-recursive)--tv-lower-bitrate,--tvlbr— prefer 25fps (or lower-bitrate 50fps) streams for TV programmes, if available--tv-quality <quality>,<quality>,...— 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--url <url>,<url>,...— record the PIDs contained in the specified iPlayer episode URLs. alias for--pid--versions <versions>— version of programme to record. the list is processed from left to right and the first version found is downloaded. example:'--versions=audiodescribed,default'will prefer audiodescribed programmes if available. versions:'default,audiodescribed,signed,combined'. default:'default'
okay that's the first chunk bestie, we're not done yet — more coming, don't go anywhere 💖
🌀 Recursive Recording Options
--pid-recursive— bestie, this is the "gimme the WHOLE show" button 🍓 If the value you passed to--pidis a series PID or a brand PID, it records every related episode. Needs--pidto be there, no exceptions.--pid-recursive-channel <channel>[,<channel>,...]— filters that episode list down to only the programmes where<channel>shows up in the channel name.<channel>can be a regex or a comma-separated list of substrings. Requires--pid-recursive.--pid-recursive-exclude <exclude>[,<exclude>,...]— the bouncer 🚫 kicks out every programme where<exclude>(regex, or comma-separated list of substrings) appears in the series name or the episode title. Requires--pid-recursive.--pid-recursive-exclude-channel <channel>[,<channel>,...]— same bouncer energy, but it looks at the channel name. Anything where<channel>(regex or comma-separated list of substrings) appears in the channel name gets excluded. Requires--pid-recursive.--pid-recursive-list— if your--pidis a series or brand PID, this lists the available episodes and does not download a single one. It implies--pid-recursive. Requires--pid.--pid-recursive-search <search>[,<searchl>,...]— only keeps programmes where<search>(regex, or comma-separated list of substrings) appears in the series name or episode title. Requires--pid-recursive.--pid-recursive-type <type>— narrows the episode list to programmes of type<type>(which isradioortv). Requires--pid-recursive.
💾 Output Options
--command,-c <command>— a user command to run after a programme records successfully 🎀 drop substitution parameters right into the command string (the docs have the list).--command-radio <command>— user command that runs after a radio programme records successfully. Same substitution-parameter situation (docs, list, go look). This one overrides--command.--command-tv <command>— user command that runs after a TV programme records successfully. Substitution parameters again (docs, list). Also overrides--command.--credits— downloads the programme credits, if they're available 💅--credits-only— downloads only the programme credits, if available. No programme, just the credits.--cuesheet— makes a cue sheet (a.cuefile) for the programme, if the data's there. Radio programmes only. Heads up though: the cue sheet will be very inaccurate and will need further editing. Also it may need a UTF-8 BOM (byte-order mark) added before some applications will recognise the encoding. 😭--cuesheet-offset [-]<offset>— shifts the track times in the cue sheet and the track list by however many seconds you say. Synonym:--tracklist-offset.--cuesheet-only— only makes the cue sheet (.cuefile) for the programme, if data's available. Radio programmes only.--file-prefix <format>— the filename prefix template (and nope, this is excluding the directory and the extension). Use substitution parameters in the template (docs, list). Default:<name> - <episode> <pid> <version>.--limitprefixlength <length>— the max length for a file prefix. Defaults to240, which leaves room inside the standard256limit ✨--metadata— creates a metadata info file after recording. Valid values:generic,json. XML gets generated for'generic', JSON for'json'. If you don't specify a value,'generic'is used.--metadata-only— creates the specified metadata info file with no recording and no streaming at all. Just the metadata, bestie.--mpeg-ts— forces raw audio and video files to be re-muxed into an MPEG-TS file no matter what the stream format is. Overrides--raw.--no-metadata— don't create a metadata info file after recording. This overrides--metadata.--no-sanitise— don't sanitise the output file and directory names. Implies--whitespace. Invalid characters for Windows ("*:<>?|) and macOS (:) will be removed.--output,-o <dir>— the recording output directory 📁--output-radio <dir>— output directory specifically for radio recordings (overrides--output).--output-tv <dir>— output directory specifically for TV recordings (overrides--output).--raw— don't remux or change the recording in any way, periodt. Saves the output file in its native container format (HLS->MPEG-TS,DASH->MP4).--subdir,-s— saves recorded files into a subdirectory of the output directory. Default: same name as the programme (peep--subdir-format).--subdir-format <format>— the format used for naming that subdirectory. Use substitution parameters in the format string (docs, list).--suboffset <offset>— offsets the subtitle timestamps by however many milliseconds you give it. Requires--subtitles.--subs-embed— embeds soft subtitles in the MP4 output file. Ignored with--audio-onlyand--ffmpeg-obsolete. Requires--subtitles. Implies--subs-mono.--subs-mono— creates monochrome titles, with a leading hyphen used to show when the speaker changes. Requires--subtitles. Not required with--subs-embed.--subs-raw— additionally saves the raw subtitles file. Requires--subtitles.--subtitles— downloads subtitles intosrt/SubRip format, if they're available and supported 🦋--subtitles-only— only downloads the subtitles. Not the programme. Just the subs.--tag-only— only updates the programme metadata tag and does not download the programme. Use it with--historyor--tag-only-filename.--tag-only-filename <filename>— adds metadata tags to the specified file (this gets ignored unless you're using it with--tag-only).--thumb— downloads the thumbnail image, if available 🎀--thumb-ext <ext>— the thumbnail filename extension to use.--thumbnail-only— only downloads the thumbnail image if available, not the programme.--thumbnail-series— forces use of the series/brand thumbnail (series preferred) instead of the episode thumbnail.--thumbnail-size <width>— the 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 the nearest available one. Default:1920(1280with--thumbnail-square).--thumbnail-square— downloads the square version of the thumbnail image. Limits--thumbnail-sizeto1280.--tracklist— creates a track list of the music played in the programme, if the data's available. Fair warning: the track times and durations may be missing or incorrect 💀--tracklist-only— only creates the track list of music played in the programme, if the data's available.--whitespace,-w— keeps 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 <search name>— runs the PVR using all the saved PVR searches (this is meant to be run periodically, like from cron or Task Manager). You can limit the list by adding a regex to the command. Synonyms:--pvrrun,--pvr-run.--pvr-add <search name>— saves the named PVR search with the search terms you specified. Search terms are required unless--pidis specified. Synonyms:--pvradd.--pvr-del <search name>— removes the named search from the PVR searches. Synonyms:--pvrdel.--pvr-disable <search name>— disables (does not delete) a named PVR search. Synonyms:--pvrdisable.--pvr-enable <search name>— re-enables a named PVR search that you previously disabled. Synonyms:--pvrenable.--pvr-exclude <string>— excludes PVR searches from running, by search name (comma-separated regex list). Defaults to substring match. Synonyms:--pvrexclude.--pvr-list— shows the PVR search list. Synonyms:--pvrlist.--pvr-queue— adds the currently matched programmes to the queue for a later one-off recording using the--pvroption. Search terms required unless--pidis specified. Synonyms:--pvrqueue.--pvr-scheduler <seconds>— runs the PVR using all saved PVR searches every<seconds>. Synonyms:--pvrscheduler.--pvr-series— creates a PVR search for each unique series name in the search results. Search terms required. Synonyms:--pvrseries.--pvr-single <search name>— runs a named PVR search. Synonyms:--pvrsingle.
⚙️ Config Options
--cache-rebuild— rebuilds the cache with the full 30-day programme index. Use--refresh-limitto restrict the cache window.--expiry,-e <secs>— cache expiry in seconds (default4hrs).--limit-matches <number>— limits the number of matching results for any search (and for every PVR search too).--prefs-add— add/change the specified saved user or preset options.--prefs-clear— remove ALL saved user or preset options. Yes, all of them, bestie 🙈--prefs-del— remove the specified saved user or preset options.--prefs-show— show the saved user or preset options.--preset,-z <name>— use the specified user options preset.--preset-list— show all valid presets ✨--profile-dir <dir>— overrides the user profile directory.--refresh— refreshes the cache.--refresh-abort-onerror— aborts the cache refresh for a programme type if the data for any channel fails to download. Use--refresh-excludeto temporarily skip the failing channels.--refresh-exclude <channel>,<channel>,...— excludes the matched channel(s) when refreshing the cache (comma-separated regex list). Defaults to substring match. Overrides--refresh-include-groups[-{tv,radio}]status for the specified channel(s).--refresh-exclude-groups <group>,<group>,...— excludes channel groups when refreshing the radio or TV cache (comma-separated values). Valid values:'national','regional','local'.--refresh-exclude-groups-radio <group>,<group>,...— excludes channel groups when refreshing the radio cache (comma-separated values). Valid values:'national','regional','local'.--refresh-exclude-groups-tv <group>,<group>,...— excludes channel groups when refreshing the TV cache (comma-separated values). Valid values:'national','regional','local'.--refresh-future— obtains the future programme schedule when refreshing the cache.--refresh-include <channel>,<channel>,...— includes the matched channel(s) when refreshing the cache (comma-separated regex list). Defaults to substring match. Overrides--refresh-exclude-groups[-{tv,radio}]status for the specified channel(s).--refresh-include-groups<group>,<group>,...— when you're refreshing the radio or TV cache, this is where you say which channel groups you actually want, comma-separated obvs. Valid values:'national','regional','local'✨--refresh-include-groups-radio<group>,<group>,...— same energy but radio-cache-only bestie. Comma-separated values, valid ones are'national','regional','local'🎀--refresh-include-groups-tv<group>,<group>,...— and this one's the TV-only twin. Comma-separated values:'national','regional','local'💖--refresh-limit<days>— the minimum number of days of programmes to cache. Default:7, Min:1, Max:30. keep it in the range bestie 🌸--refresh-limit-radio<days>— how many days of radio programmes to cache. Default:7, Min:1, Max:30📻--refresh-limit-tv<days>— how many days of TV programmes to cache. Default:7, Min:1, Max:30📺--skipdeleted— literally just skips downloading metadata/thumbs/subs when the media file isn't there anymore. Use it with--history&--metadataonly/--subsonly/--thumbonly🫶--webrequest<urlencoded string>— drop all your options in as one urlencoded string shaped like"name=val&name=val&..."👑
✨ External Program Options ✨
okay so these are the "where do I find the other program" options, iconic behaviour tbh
--atomicparsley<path>— the location of the AtomicParsley binary 💅--ffmpeg<path>— location of the ffmpeg binary. Unless you pass--ffmpeg-obsolete, it's assumed to be ffmpeg3.0or higher 🌈--ffmpeg-force— bypass the version checks and just assume ffmpeg is version3.0or higher. living dangerously, love that for you 🔥--ffmpeg-loglevel<level>— sets the logging level for ffmpeg. Heads up:--quietand--silentoverride this. Default:'fatal'💜--ffmpeg-obsolete— for when you're on an obsolete version of ffmpeg (<1.0) that might not support certain options. No cap: without this option, MP4 conversion may fail with obsolete versions of ffmpeg. You've been warned bestie 😭
🎀 Tagging Options 🎀
--no-artwork— don't embed the thumbnail image in the output file. It also removes existing artwork. All the other metadata values still get written tho 💖--no-tag— don't tag downloaded programmes. periodt ✋--tag-credits— adds programme credits (if available) into the long description field 🫶--tag-encoding<name>— (Windows only) single-byte character encoding for non-ASCII characters in metadata tags. The encoding name has to be known to the Perl Encode module. Unicode (UTF*orUCS*) character encodings are not supported. Default: the active code page orcp1252(Windows code page 1252) 🪟--tag-format-show— format template for the programme name in tag metadata. Use substitution parameters in the template (see docs for the list). Default:<name>⭐--tag-format-title— format template for the episode title in tag metadata. Use substitution parameters in the template (see docs for the list). Default:<episodeshort>✨--tag-isodate— use ISO8601 dates (YYYY-MM-DD) in album/show names and track titles 📅--tag-no-unicode— (Windows only) don't attempt Unicode tagging, use single-byte character encoding instead (see--tag-encoding) 💅--tag-podcast— tags downloaded radio and tv programmes as iTunes podcasts. Just so you know: incompatible with Music/Podcasts/TV apps on macOS10.15and higher 💀--tag-podcast-radio— tags only downloaded radio programmes as iTunes podcasts (also incompatible with Music/Podcasts/TV apps on macOS10.15and higher) 📻--tag-podcast-tv— tags only downloaded tv programmes as iTunes podcasts (and yeah, incompatible with Music/Podcasts/TV apps on macOS10.15and higher) 📺--tag-tracklist— adds the track list of music played in the programme (if available) to the lyrics field 🎵
🌸 Misc Options 🌸
--encoding-console-in<name>— character encoding for standard input (currently unused, so it's giving placeholder energy). The encoding name must be known to the Perl Encode module. Default (only if auto-detect fails): Linux/Unix/macOS =UTF-8, Windows =cp850🦋--encoding-console-out<name>— character encoding used to encode search results and other output. Encoding name must be known to the Perl Encode module. Default (only if auto-detect fails): Linux/Unix/macOS =UTF-8, Windows =cp850💖--encoding-locale<name>— character encoding used to decode command-line arguments. Encoding name must be known to the 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 the Perl Encode module. Default (only if auto-detect fails): Linux/Unix/macOS =UTF-8, Windows =cp1252📁--encoding-webrequest<name>— character encoding used to encode commands sent from Web PVR. Encoding name must be known to the Perl Encode module. Default =UTF-8🌐--index-maxconn<number>— maximum number of connections to use for concurrent programme indexing. Default:5, Min:1, Max:10🔥--release-check— forces a check for a new release if you use it on the command line. If it's saved in preferences instead, it checks for a new release weekly 👑--throttle<Mb/s>— bandwidth limit (in Mb/s) for media file download. Default: unlimited. Synonym:--bw🐌
💀 Deprecated Options 💀
--no-index-concurrent— do not use concurrent indexing to update the programme cache. Lowkey a warning bestie: cache updates will be very slow. like, painfully 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.36
Copyright (C) 2008-2010 Phil Lewis, 2010- get_iplayer contributors
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.and that's a wrap on the whole page bestie 💖 this lil' manual is from get_iplayer v3.36, dated May 2025, and it's page GET_IPLAYER(1) — go forth and download responsibly, mwah 💅✨
📦 where this page comes from
- fedora 43: get_iplayer 3.36-2.fc43 · GPL-3.0-or-later
- fedora 44: get_iplayer 3.36-3.fc44 · GPL-3.0-or-later
- nixpkgs unstable: perl5.42.3-get_iplayer 3.36
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms