id          = "get-iplayer"
name        = "get_iplayer"
homepage    = "https://github.com/get-iplayer/get_iplayer"
description = "A utility for downloading TV and radio programmes from BBC iPlayer."
executables      = ["get_iplayer"]

[dotfiles]
paths       = ["~/.get_iplayer/options", "%USERPROFILE%/.get_iplayer/options"]
secret      = []

# The project's preferences documentation names the Unix and Windows options
# files used for default user preferences.
# https://github.com/get-iplayer/get_iplayer/wiki/prefs

[commands]
format = 1
label = "Search or record BBC programmes"
description = "Search the programme index, or record by index number. Unlisted options such as proxies, output directories and PVR presets are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.source]]
id = "readme"
kind = "help"
url = "https://github.com/get-iplayer/get_iplayer#examples"
revision = "2026-10-27"
evidence = """
get_iplayer --long ".*"
get_iplayer --type=radio ".*"
get_iplayer --type tv,radio "doctor who"
get_iplayer --channel="BBC One" ".*"
get_iplayer --get 208 --tv-quality=hd,sd,web,mobile
get_iplayer --get 208 --subtitles
get_iplayer --pid=b01sc0wf
"""

[[commands.field]]
id = "type"
label = "Programme type"
description = "Comma-separated types, for example tv,radio. TV is the default."
type = "string"
option = ["--type"]
suggestions = [{ value = "tv", label = "TV" }, { value = "radio", label = "Radio" }, { value = "tv,radio", label = "TV and radio" }]
sources = ["readme"]

[[commands.field]]
id = "channel"
label = "Channel"
type = "string"
option = ["--channel"]
sources = ["readme"]

[[commands.field]]
id = "long"
label = "Long descriptions"
type = "boolean"
option = ["--long"]
sources = ["readme"]

[[commands.field]]
id = "get"
label = "Record the listed index numbers"
description = "Put the index numbers from a previous search in the terms field."
type = "boolean"
option = ["--get"]
sources = ["readme"]

[[commands.field]]
id = "subtitles"
label = "Download subtitles"
type = "boolean"
option = ["--subtitles"]
sources = ["readme"]

[[commands.field]]
id = "tv_quality"
label = "TV quality order"
type = "string"
option = ["--tv-quality"]
suggestions = [{ value = "hd,sd,web,mobile", label = "HD with fallback" }, { value = "web", label = "Web (lower resolution)" }]
sources = ["readme"]

[[commands.field]]
id = "pid"
label = "Programme ID"
type = "string"
option = ["--pid"]
sources = ["readme"]

[[commands.field]]
id = "terms"
label = "Search terms or index numbers"
description = "Regular expression, such as .* for everything, or index numbers when recording."
type = "string"
position = 0
multiple = true
sources = ["readme"]

[[commands.task]]
id = "search"
label = "Search programmes"
fields = ["terms", "type", "channel", "long"]
required = ["terms"]

[[commands.task]]
id = "record"
label = "Record by index"
set = { get = [true] }
lock = ["get"]
fields = ["terms", "get", "tv_quality", "subtitles"]
required = ["terms"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["terms", "type", "channel", "long", "get"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["subtitles", "tv_quality", "pid"]