tagging
Click here for all metadata tagging options (Return to ToC)
get_iplayer uses the AtomicParsley utility to add metadata tags to downloaded files in MP4 and M4A format. The table below describes the scheme used to convert get_iplayer metadata into tags for downloaded programmes. The tag names were selected to match AtomicParsley parameter names. Each tag is mapped, where possible, to the corresponding get_iplayer substitution parameter, AtomicParsley arg, MP4 atom. The list of iTunes fields indicate where each tag will appear in the iTunes Get Info dialog. Conversion rules specific to particular fields are indicated in the footnotes.
The TV* and hdvideo tags are written to video files only. The iTunes podcast-related tags are written when a --tag-podcast[-{tv,radio}] option is specified. All other tags are written to all files.
| Tag Name | Substitution Param1 | AtomicParsley arg | MP4 atom | iTunes Field |
|---|---|---|---|---|
| stik2 | <ext> |
--stik |
stik | Options:Media Kind |
| advisory3 | <guidance> |
--advisory |
rtng | Summary:Advisory |
| copyright4 | <dldate> |
--copyright |
cprt | Summary:Copyright |
| title |
<episode>5
|
--title |
©nam | Info:Song/Title |
| artist | <channel> |
--artist |
©ART | Info:Artist |
| albumArtist | BBC <type>6
|
--albumArtist |
aART | Info:Album Artist |
| album | <name> |
--album |
©alb | Info:Album/Programme |
| grouping | <categories> |
--grouping |
©grp | Info:Grouping |
| composer | BBC iPlayer (tv) BBC Sounds (radio) |
--composer |
©wrt | Info:Composer |
| comment | <descshort> |
--comment |
©cmt | Info:Comments |
| genre7 | <categories> |
--genre |
©gen | Info:Genre |
| year |
<firstbcast>8
|
--year |
©day | Info:Year |
| tracknum | <episodenum> |
--tracknum |
trkn | Info:Track Number |
| disk | <seriesnum> |
--disk |
disk | Info:Disc Number |
| lyrics |
<desc>9
|
--lyrics OR--lyricsFile10
|
©lyr | Lyrics |
| description | <descshort> |
--description |
desc | Video:Description |
| longDescription | <desc> |
--longDescription10 OR--longdesc10 OR--longdescFile10
|
ldes | (Hidden):Long Description |
| hdvideo11 | <quality> |
--hdvideo10
|
hdvd | (Browser):HD Icon |
| TVShowName | <name> |
--TVShowName |
tvsh | Video:Show |
| TVEpisode | <pid> |
--TVEpisode |
tven | Video:Episode ID |
| TVSeasonNum | <seriesnum> |
--TVSeasonNum |
tvsn | Video:Season Number |
| TVEpisodeNum | <episodenum> |
--TVEpisodeNum |
tves | Video:Episode Number |
| TVNetwork | <channel> |
--TVNetwork |
tvnn | (Hidden):TV Network |
| artwork | <thumbfile> |
--artwork |
covr | Artwork |
| podcastFlag12 | true | --podcastFlag |
pcst | Options:Media Kind |
| category12 |
<categories>13
|
--category |
catg | (Hidden):Podcast Category |
| keyword12 | <categories> |
--keyword |
keyw | (Hidden):Podcast Keywords |
| podcastGUID12 | <player> |
--podcastGUID |
egid | (Hidden):Podcast GUID |
-
Full list of substitution parameters may be found here.
-
TV Show if MP4/M4V, Movie if MP4/M4V and
<categories>contains "Film", Normal otherwise -
explicit if
<guidance>non-empty, remove otherwise -
Year taken from
<dldate>, e.g.: (C) 2023 BBC (programme data only) -
Use
--tag-format-title="<title>"for full title -
BBC TV, BBC Radio
-
First item in
<categories>used unless it is one of: ("Films", "Sign Zone", "Audio Described", "Northern Ireland", "Scotland", "Wales", "England"), in which case second item is used. If<categories>is empty, set to get_iplayer -
If
<firstbcast>is not valid date, current date is used -
<player>and<web>appended if present -
Not available with all AtomicParsley versions
-
2 if
<quality>is fhd/1080p, 1 if<quality>is hd/720p, 0 otherwise -
--tag-podcast[-{tv,radio}]required (incompatible with Music/Podcasts/TV apps on macOS 10.15 and higher) -
Uses same rules as genre7
Metadata tags can be added (or re-added) to existing files with the --tag-only option. Use --pid to identify the programme whose metadata is to be used and --tag-only-filename to identify the file to modify:
get_iplayer --pid=b08h31x5 --tag-only --tag-only-filename="Weather_for_the_Week_Ahead_-_2017-03-13_b08h31x5_original.mp4"
One or more files can be re-tagged if they are in the same locations recorded in your download history. For example, to re-tag all episodes of EastEnders in your download history:
get_iplayer --history "EastEnders" --skipdeleted --tag-only
You can use a regular expression to pick out specific PIDs from your download history for re-tagging:
get_iplayer --history --fields=pid "m000q6ch|m000q70d|m000qd6m" --skipdeleted --tag-only
Some Linux/BSD distros ship obsolete versions of AtomicParsley. Tagging will likely fail on large files (>4GB) if you are using AtomicParsley < 0.9.4, and there may be other problems. You may be able to install an alternate version of AtomicParsley - see manual installation. See the AtomicParsley repository for instructions on building your own up-to-date version. If you use Windows or macOS and follow the installation instructions, you will have an up-to-date build of AtomicParsley.
Windows only: The get_iplayer metadata is assumed to be encoded as UTF-8, but conversion to a single-byte character encoding can be forced with --tag-no-unicode. The default encoding for the system locale will be used, but it can be overridden with --tag-encoding. Characters that cannot be converted will be replaced by XML character references, e.g., "знали" becomes знали.