Skip to content
notnac edited this page Oct 11, 2023 · 25 revisions

Metadata Tagging

Click here for all metadata tagging options (Return to ToC)

Tag Scheme

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
  1. Full list of substitution parameters may be found here.

  2. TV Show if MP4/M4V, Movie if MP4/M4V and <categories> contains "Film", Normal otherwise

  3. explicit if <guidance> non-empty, remove otherwise

  4. Year taken from <dldate>, e.g.: (C) 2023 BBC (programme data only)

  5. Use --tag-format-title="<title>" for full title

  6. BBC TV, BBC Radio

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

  8. If <firstbcast> is not valid date, current date is used

  9. <player> and <web> appended if present

  10. Not available with all AtomicParsley versions

  11. 2 if <quality> is fhd/1080p, 1 if <quality> is hd/720p, 0 otherwise

  12. --tag-podcast[-{tv,radio}] required (incompatible with Music/Podcasts/TV apps on macOS 10.15 and higher)

  13. Uses same rules as genre7

Re-tagging files

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

Notes

Obsolete AtomicParsley

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.

Character Encoding

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 &#x437;&#x43d;&#x430;&#x43b;&#x438;.

Clone this wiki locally