Metadata Tokens

Metadata Tokens are used to define the display of image metadata within albums. These may be used in designated places within album templates.

Our Publish Services plugin for Lightroom Classic supports all of the tokens defined on this page, while our web-based publisher supports a smaller subset of tokens. See Metadata Tokens in the Web-based Publisher for more information about that subset.

Tokens are set using curly brackets. For example:

{Title} shot with exposure {Exposure} on {D1}.

After changing metadata settings in a template, you will need to re-publish any affected photos via Lightroom's Publish Services, or re-upload images using the web-based publisher.

The Publish Services plugin provides a setting "Push metadata without updating existing photos" within the Publisher settings; if selected, this greatly speeds up re-publishing.

The following metadata tokens are supported by our Publish Services plugin:

Photo Date

TokenDescription
YYYYThe year the photo was taken, as a four-digit string
YYThe year the photo was taken, as a two-digit string
MMThe month the photo was taken, as a two-digit string
DDThe day of the month the photo was taken, as a two-digit string
HHThe hour value for the time the photo was taken, in 24-hour notation, as a two-digit string
MINThe minute value for the time the photo was taken, as a two-digit string
SSThe seconds value for the time the photo was taken, as a two-digit string
MonThe month the photo was taken, as a localized three-character string
MonthThe month the photo was taken, as a localized string
DateThe day of the month the photo was taken, as one- or two-digit string
D1The full date of the photo, in the system-localized short format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "2010-03-24". Available only in Lr3 or later.
D2The full date of the photo, in the system-localized medium format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "Mar 24, 2010". Available only in Lr3 or later.
D3The full date of the photo, in the system-localized long format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "March 24, 2010". Available only in Lr3 or later.
T1The full time-of-day of the photo, in the system-localized short format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "3:38 PM". Available only in Lr3 or later.
T2The full time-of-day of the photo, in the system-localized long format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "3:38:02 PM". Available only in Lr3 or later.
PhotoDaysSince=dateThe number of days from the given date and the date of the photo. This is intended for use along the lines of "My 2010 In Photos: Day {PhotoDaysSince=2009-12-31}".
The date argument is in the form "YYYY-MM-DD" but may also have an appended time, in HH:MM 24-hour notation, to delimit when dates start. If you're a night-owl who might want to include a photo taken late in the evening, after midnight, as being part of the previous day, you might want to use something like "My 2010 In Photos: Day {PhotoDaysSince=2009-12-31 04:00}" to have photo taken until 4am be considered part of the previous day.
One concern to watch out for with this date/time example is that photos taken during the first four hours of Jan 1 2010 would appear to still be part of the previous day, day "0".
PhotoDaysUntil=dateLike PhotoDaysSince, but in the counting-down-until sense.

Current Date

TokenDescription
yyyyThe current year as a four-digit string
yyThe current year as a two-digit string
mmThe current month as a two-digit string
ddThe current day of the month as a two-digit string
hhThe current hour value, as a two-digit string
minThe current minute value, as a two-digit string
ssThe current seconds value, as a two-digit string
monThe current month, as a localized three-character string
monthThe current month, as a localized string
dateThe current day of the month, as one- or two-digit string
d1The current full date, in the system-localized short format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "2010-03-23". Available only in Lr3 or later.
d2The current full date, in the system-localized medium format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "Mar 23, 2010". Available only in Lr3 or later.
d3The current full date, in the system-localized long format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "March 23, 2010". Available only in Lr3 or later.
t1The current full time-of-day, in the system-localized short format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "3:38 PM". Available only in Lr3 or later.
t2The current full time-of-day, in the system-localized long format that you can set in your operating system's preferences dialog. On my system this is something along the lines of "3:38:02 PM". Available only in Lr3 or later.
DaysSince=dateLike PhotoDaysSince, but measures the current date to the date (or date/time) given in the argument, without regard to any photo date. You might want to use this along with something like "My 2010 In Photos: Day {DaysSince=2009-12-31}" if you want to have the Day counter refer to when you do the upload, not when you took the shot. With this token, you'd want to use the date/time form if you're a night owl and want an upload done late in the evening, after midnight, to be considered as having been done the previous day.
DaysUntil=dateLike PhotoDaysUntil, but in the counting-down-until sense.

File Names and Paths

TokenDescription
FilenameThe filename – without path and without extension – of the exported copy
FILENAMELike Filename, but includes the extension
LibraryFilenameThe filename – without path and without extension – of the master file in the library (which is not necessarily the filename being generated for the exported copy)
LIBRARYFILENAMELike LibraryFilename, but includes the extension
FolderThe name of the folder (without path) in which the master image in the catalog resides
PathThe full path of the folder in which the master image in the catalog resides
NumericFilenameSuffixThe numeric portion of the exported filename, without leading zeros. For example Image-012.jpg would return 12
NUMERICFILENAMESUFFIXThe numeric portion of the exported filename, with leading zeros. For example Image-012.jpg would return 012
NumericLibraryFilenameSuffixThe numeric portion of the master filename, without leading zeros. For example Image-012.jpg would return 12
NUMERICLIBRARYFILENAMESUFFIXThe numeric portion of the master filename, with leading zeros. For example Image-012.jpg would return 012

Image

TokenDescription
FiletypeOne of: "JPEG", "RAW", "DNG", "TIFF", "PSD", "DNG", or "Video"
OriginalWidthThe width of the (possibly pre-crop) original master image (not the exported one), in pixels
OriginalHeightThe height of the (possibly pre-crop) original master image (not the exported one), in pixels
CroppedEither "cropped" or "uncropped".
CroppedWidthThe width of the (possibly post-crop) library image (not the exported one), in pixels
CroppedHeightThe height of the (possibly post-crop) library image (not the exported one), in pixels
AspectRatioThis becomes "Portrait" if the cropped image is more tall than wide, "Square" if the cropped with and height are the same, and "Landscape" if wider than tall. You can substitute your own phrases for each by using the form {AspectRatio=X,Y,Z}, where X, Y, and Z are used for Portrait, Square, and Landscape, respectively.

Lens / Camera / Exposure

TokenDescription
ApertureThe photo's aperture value, formatted like "f/4.5"
ApertureNumThe photo's aperture value, as a raw number
CameraMakeThe photo's "Make" metadata item in Lightroom's database.
CameraModelThe photo's "Model" metadata item in Lightroom's database.
CameraSerialNumberThe photo's "Serial Number" metadata item in Lightroom's database.
ExposureThe photo's exposure data, like "¹⁄₂₅₀ sec at f/5.0".
ExposureBiasThe photo's exposure-bias setting, like "-1 EV".
ExposureBiasNumThe photo's exposure-bias setting, as a raw number.
ExposureProgramThe photo's exposure-program setting, like "Aperture priority".
FlashOne of "no flash", "flash fired", or "unknown flash".
FocalLengthFocal Length, as a number
FocalLength35Focal Length in 35mm format, as a number
FocalLength35MMFocal Length in 35mm format (with locale-specific "mm" appended)
FocalLengthMMFocal Length (with locale-specific "mm" appended)
ISOThe photo's ISO (sensor sensitivity) number.
LensThe photo's lens information, like "24-70mm f/2.8".
MeteringModeThe photo's metering-mode setting, like "Pattern".
ShutterSpeedThe shutter speed, formatted like "¹⁄₂₅₀ sec".
ShutterSpeedNumThe shutter speed as a floating-point number of seconds; Use the "Places" filter to limit precision.
SubjectDistanceThe subject distance as reported by the lens, formatted like "1.2 m". Often wildly inaccurate.
SubjectDistanceNumThe subject distance as reported by the lens, as a floating-point number. Often wildly inaccurate.
  • TTG Publisher does not support Jeffrey's CameraName token.

Attributes

TokenDescription
CopyNameThe name of the copy (master or virtual) being exported, if any
RatingThe number of stars assigned to the image: "0" through "5". You can also use with an argument, e.g. {Rating=*} or {Rating=great} to have, for example, a three-star photo result in %%"**"%% or "great great great". In either case, a photo with a zero rating results in nothing, but you can combine tokens (as described below) along these lines: `{Rating=
ColorLabelThe "Label" metadata item
EditCountA number that goes up each time a change is made in Lightroom to the image or its data.
UUIDLightroom's internal unique identifier for the photo, an essentially-random 36-character sequence of letters, numbers, and hyphens, such as "FB4D3F92-455F-47CA-8B7B-7C885F7244FD".

Location

TokenDescription
GPSCoordinatesThe photo's geoencoded coordinates, like "35°1'11.51" N 135°46'16.05" E"
AltitudeThe photo's geoencoded altitude, as a number, in meters. Use "Places", e.g. {Altitude:Places=0}, to limit precision.
GPSAltitudeThe photo's geoencoded as a description, e.g. "27.3 m"
LatitudeLatitude, as a floating-point number. Use "Places", e.g. {Latitude:Places=4}, to limit precision.
LongitudeLongitude, as a floating-point number. Use "Places", e.g. {Longitude:Places=4}, to limit precision.
IfGeoencodedIf used in the form {IfGeoencoded=some text here}, the token is replaced by the text after the "=" if the photo is geoencoded, or replaced by nothing if not. If used in the form {IfGeoencoded=some text here;for non-geoencoded} with a semicolon, the text after the semicolon is used when the photo is not geoencoded.
LocationThe "Location" metadata item
CityThe "City" metadata item
StateThe "State" metadata item
ProvinceThe "State" metadata item
CountryThe "Country" metadata item
CountryCodeThe photo's "Image > ISO Country Code" metadata item in Lightroom's database.

Other Metadata

TokenDescription
ArtistThe "Artist" metadata item
CaptionThe "Caption" metadata string
CategoryThe photo's "IPTC > Category" metadata item in Lightroom's database.
CopyrightThe "Copyright" metadata item
CopyrightUrlThe photo's "Copyright Info Url" metadata item in Lightroom's database.
CreatorThe photo's "Contact > Creator" metadata item in Lightroom's database.
CreatorAddressThe photo's "Contact > Address" metadata item in Lightroom's database.
CreatorCityThe photo's "Contact > City" metadata item in Lightroom's database.
CreatorCountryThe photo's "Contact > Country" metadata item in Lightroom's database.
CreatorEmailThe photo's "Contact > E-Mail" metadata item in Lightroom's database.
CreatorJobTitleThe photo's "Contact > Job Title" metadata item in Lightroom's database.
CreatorPhoneThe photo's "Contact > Phone" metadata item in Lightroom's database.
CreatorStateThe photo's "Contact > State / Province" metadata item in Lightroom's database.
CreatorUrlThe photo's "Contact > Website" metadata item in Lightroom's database.
CreatorZipThe photo's "Contact > Postal Code" metadata item in Lightroom's database.
DescriptionWriterThe photo's "IPTC > Description Writer" metadata item in Lightroom's database.
GenreThe photo's "Image > Intellectual Genre" metadata item in Lightroom's database.
HeadlineThe "Headline" metadata item
InstructionsThe photo's "Workflow > Instructions" metadata item in Lightroom's database.
JobIdentifierThe photo's "Workflow > Job Identifier" metadata item in Lightroom's database.
KeywordsThe list of the photo's marked-for-export keywords, separated by commas. (Actually, there's a comma+space pair between each keyword, so it's "plant, rose, flower" and not "plant,rose,flower".)
IfKeywordIf used in the form {IfKeyword=keyword;some text here}, the token is replaced by the text after the "=" if the photo has been tagged with the named keyword (even if that keyword is not marked in Lightroom as one to be exported). If no text is given after the semicolon, the keyword itself is used: {IfKeyword=public;} becomes "public" or nothing.
If used in the form {IfKeyword=keyword;some text here;the not-keyworded text}, with an extra semicolon-separated phrase, the token becomes the not-keyworded if the photo is not tagged with the named keyword.
IfExportedKeywordLike IfKeyword, but considers only keywords that have been marked in Lightroom for export.
OtherCategoriesThe photo's "IPTC > Other Categories" metadata item in Lightroom's database.
ProviderThe photo's "Workflow > Provider" metadata item in Lightroom's database.
RightsUsageTermsThe photo's "Workflow > Rights Usage Terms" metadata item in Lightroom's database.
SceneThe "Scene" metadata item
SoftwareThe photo's "Software" metadata item in Lightroom's database.
SourceThe "Source" metadata item
SubjectCodeThe photo's "IPTC > IPTC Subject Code" metadata item in Lightroom's database.
TitleThe "Title" metadata item

Special

TokenDescription
PluginProperty=fieldAllows you to access the per-image custom metadata kept by a plugin, where field is the plugin's id and the metadata field id, joined with a dot. For example,
{PluginProperty=info.regex.lightroom.export.flickr2.url}
refers to the url field of the plugin with id info.regex.lightroom.export.flickr2 (Jeffrey's Flickr plugin). However, with PluginProperty, you can reference any plugin data for which you know the plugin id and field name. You can get these from the plugin author, or try digging around the plugin's Info.lua for the plugin id and a reference to its LrMetadataProvider, where you can find field ids.
EmptyAn empty string, perhaps useful for testing. Also, when placed between joining characters, it blocks their squelching.
" text "The text as provided. It may not contain the following characters: {
-Inserts a hyphen that is never squelched; essentially the same as {"-"}
,Inserts a comma that is never squelched; essentially the same as {","}
LUASee the section below for details on this advanced, complex token.

TTG Publisher Exclusive

These tokens are original additions to TTG Publisher, and will not cross over to Jeffrey's export plugins.

TokenDescription
CellNumberOutputs the sequential number of the image in the gallery. The first image is 1, the second image is 2, etc.
NumImagesOutputs the total number of images in the gallery.

Token Basics

As mentioned above, tokens are identified within a template by wrapping them with { ... }. The value generated by the token has leading and trailing spaces removed before being inserted into the result. For example, if the "Caption" metadata item is the string "My Vacation ", the value actually used for the Caption token (which appears as {Caption} in the template) is "My Vacation".

Combining Tokens

You may list multiple tokens within { ... }, separated by a pipe (|). In such a case, the first token that results in non-empty text is used. Tokens may result in an empty value if the photo is missing the associated metadata. For example, if a photo is missing the "date taken" metadata, the YYYY token is empty. Thus, the previous copyright example may be better written as:

Copyright {YYYY|yyyy} {Artist}

In this case, if the YYYY token is empty, the yyyy token (the current year, which can never be empty) is used.

Continuing with this example, because the Artist token results in an empty item if there is no artist metadata, this example might be written as:

Copyright {YYYY|yyyy} {Artist|"by the photographer"}

... to become:

Copyright 2008 by the photographer

... when there is no artist metadata.

Token Filters

TokenDescription
S2USpace to UnderscoreAny sequences of spaces (and/or underscores) are replaced by a single underscore
S2DSpace to DashAny sequences of spaces (and/or dashes) are replaced by a single dash
U2SUnderscore to SpaceAny sequences of underscores (and/or spaces) are replaced by a single space
D2SDash to SpaceAny sequences of dashes (and/or spaces) are replaced by a single space
DU2SDash/Underscore to SpaceAny sequences of dashes, underscores, and/or spaces are replaced by a single space
Places=numspecify numeric precisionIf the item is number, formats it to num decimal places. If the item is not a number, makes it empty.
After=textUse value to the right of textIf the given text is found in the value that the token generates, strip it and all that appeared before (to the left), leaving only what appears to the right of text in the value. If the text is not found in the value, the result of the token is empty.
For example, if you tend to use captions like "My trip to Paris" and "My trip to the Canadian Rockies", and you wanted shorter text, you might consider using {Caption:After=trip to} to result in values like "Paris" and "the Canadian Rockies".
If you wanted to implement an idea such as "Strip the '...trip to' text from the caption if it's there, and use the unadulterated caption if not", you would append an unadorned Caption token as described in the "Combining Tokens" section above, resulting in {Caption:After=trip to%%
UCUpper CaseCapitalizes the item
LCLower CaseEnsures the item is all lower case.
  • TTG Publisher does not support Jeffrey's Length=num, UCWords, UCFirst and LCFirst filters.

Squelching Superfluous Joining Characters

  • TTG Publisher does not support squelching superfluous joining characters.

The special {Empty} token

The {Empty} token produces no text, but has the side effect in that it interrupts the squelching of joining characters. Without it, the sequence <br><br> becomes <br> but with it, <br>{EMPTY}<br> becomes <br><br>.

The special {NOJOINERS} token

  • TTG Publisher does not support the {NOJOINERS} token.

The Special {LUA=...} Token

This advanced programming-like feature allows you to execute arbitrary Lua code, in an environment where the tokens above have been prepopulated into variables. For example:

{LUA=CreatorPhone}

... and ...

{LUA=return CreatorPhone}

... are exactly the same as the {CreatorPhone} token, but, for example:

{LUA= if CreatorPhone ~= '' then return sprintf("Contact: %s", CreatorPhone) end }

... becomes the string "Contact: text-from-CreatorPhone" if the CreatorPhone token is not empty, nothing if it is.

The special Lua environment, in the latest version of plugins running in the latest version of Lightroom, includes:

  • Variables exist for almost all of the tokens (except //DaysSince//, //IfGeoencoded//, etc. — tokens that require an extra argument). Each one is a string; if the token has no value, its variable in the special Lua environment is the empty string ''.
  • The standard Lua functions tonumber(), tostring(), type(), unpack(), ipairs(), and pairs().
  • The standard Lua name spaces string, table, and math. The os namespace is partially included: os.date(), os.time(), and os.tmpname().
  • The Lightroom SDK namespaces LrDate, LrPathUtils, and LrStringUtils. SDK docs can be downloaded [[http://www.adobe.com/devnet/photoshoplightroom.html|here]].
  • The Booleans WIN and MAC, which indicate the type of host operating system, and sprintf(), which is a synonym for string.format().
  • The function TBL(...), which returns a new table, populating it with any arguments provided. This is to help avoid curly braces in inlined Lua.
  • The function ne(item), meaning "non-empty". It returns nil if the item is nil or tostring(item) evaluates to a zero-length string.
  • The function nb(item), meaning "non-blank". It returns nil if the item is nil or tostring(item) evaluates to a string that has no non-whitespace characters.
  • The variable photoTime, which returns the Cocoa timestamp of the photo in question, if any. This is suitable for passing to Lightroom's LrDate.timestampToComponents() and LrDate.timeToUserFormat() functions, among others. Add 978307200 to get a Unix Time.
  • The variable currentTime, which returns the current Cocoa timestamp; identical to LrDate.currentTime().
  • A table KW that has keys for every keyword applied to the photo (the values are true), and a similar table KWE with keys for exported keywords. Thus, the code snippet KW.private is true if the keyword "private" has been applied to the photo, nil otherwise.
  • The function load(), which executes Lua code in a named file, as discussed below.

Here are some examples. Some have been broken into multiple lines for display, with pretty indenting, for easier reading one this page; when inputting into the plugin, you'll have to put it all on one big long (ugly) line ...

{LUA=if Artist ~= "" then return sprintf("Copyright %s", Artist) end}

Becomes "Copyright ..." with the name of the Artist if there is an Artist token.


{LUA=if Artist ~= "" and Copyright = "" then return sprintf("Copyright %s", Artist) end}

Like the one above, but only if there is no Copyright token.


{LUA=if Artist ~= "" then return sprintf("Copyright %s %s", yyyy, Artist) end}

Becomes "Copyright #### ...." with the current year and the name of the Artist, if there is an Artist token.


{LUA=if Artist ~= "" then
if yyyy == YYYY or YYYY == "" then
return sprintf("Copyright %s %s", yyyy, Artist)
else
return sprintf("Copyright %s-%s %s", YYYY, yyyy, Artist)
end
end}

Like the one above, but the reference to the year in the copyright statement becomes a range if the photo has a date associated with it and that date is not the current year, e.g. "Copyright 2006-2010 Jeffrey Friedl" for a photo taken in 2006 and being processed in 2010.


{LUA=if Artist ~= "" then
when = YYYY==yyyy or YYYY=="" and yyyy or YYYY.."-"..yyyy
return sprintf("Copyright %s %s", when, Artist)
end}

Exactly like the one just above.


{LUA=if GPSCoordinates ~= "" then return sprintf("geo:lat=%s;geo:lon=%s", Latitude, Longitude) end}

If the photo is geoencoded, becomes GPS machine tags.


{LUA=if KW.private and not KWE.private then return "private, but not reporting as such" end}

Becomes "private, but not reporting as such" if marked with the keyword "private", but that keyword is not marked for export.


Loading From a File

  • TTG Publisher does not support Loading Lua from a file.