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 Backlight 4 or Metadata Tokens in the Web-based Publisher for Backlight 2 or 3.
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
| Token | Description |
|---|---|
| YYYY | The year the photo was taken, as a four-digit string |
| YY | The year the photo was taken, as a two-digit string |
| MM | The month the photo was taken, as a two-digit string |
| DD | The day of the month the photo was taken, as a two-digit string |
| HH | The hour value for the time the photo was taken, in 24-hour notation, as a two-digit string |
| MIN | The minute value for the time the photo was taken, as a two-digit string |
| SS | The seconds value for the time the photo was taken, as a two-digit string |
| Mon | The month the photo was taken, as a localized three-character string |
| Month | The month the photo was taken, as a localized string |
| Date | The day of the month the photo was taken, as one- or two-digit string |
| D1 | The 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. |
| D2 | The 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. |
| D3 | The 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. |
| T1 | The 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. |
| T2 | The 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=date | The 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=date | Like PhotoDaysSince, but in the counting-down-until sense. |
Current Date
| Token | Description |
|---|---|
| yyyy | The current year as a four-digit string |
| yy | The current year as a two-digit string |
| mm | The current month as a two-digit string |
| dd | The current day of the month as a two-digit string |
| hh | The current hour value, as a two-digit string |
| min | The current minute value, as a two-digit string |
| ss | The current seconds value, as a two-digit string |
| mon | The current month, as a localized three-character string |
| month | The current month, as a localized string |
| date | The current day of the month, as one- or two-digit string |
| d1 | The 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. |
| d2 | The 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. |
| d3 | The 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. |
| t1 | The 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. |
| t2 | The 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=date | Like 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=date | Like PhotoDaysUntil, but in the counting-down-until sense. |
File Names and Paths
| Token | Description |
|---|---|
| Filename | The filename – without path and without extension – of the exported copy |
| FILENAME | Like Filename, but includes the extension |
| LibraryFilename | The 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) |
| LIBRARYFILENAME | Like LibraryFilename, but includes the extension |
| Folder | The name of the folder (without path) in which the master image in the catalog resides |
| Path | The full path of the folder in which the master image in the catalog resides |
| NumericFilenameSuffix | The numeric portion of the exported filename, without leading zeros. For example Image-012.jpg would return 12 |
| NUMERICFILENAMESUFFIX | The numeric portion of the exported filename, with leading zeros. For example Image-012.jpg would return 012 |
| NumericLibraryFilenameSuffix | The numeric portion of the master filename, without leading zeros. For example Image-012.jpg would return 12 |
| NUMERICLIBRARYFILENAMESUFFIX | The numeric portion of the master filename, with leading zeros. For example Image-012.jpg would return 012 |
Image
| Token | Description |
|---|---|
| Filetype | One of: "JPEG", "RAW", "DNG", "TIFF", "PSD", "DNG", or "Video" |
| OriginalWidth | The width of the (possibly pre-crop) original master image (not the exported one), in pixels |
| OriginalHeight | The height of the (possibly pre-crop) original master image (not the exported one), in pixels |
| Cropped | Either "cropped" or "uncropped". |
| CroppedWidth | The width of the (possibly post-crop) library image (not the exported one), in pixels |
| CroppedHeight | The height of the (possibly post-crop) library image (not the exported one), in pixels |
| AspectRatio | This 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
| Token | Description |
|---|---|
| Aperture | The photo's aperture value, formatted like "f/4.5" |
| ApertureNum | The photo's aperture value, as a raw number |
| CameraMake | The photo's "Make" metadata item in Lightroom's database. |
| CameraModel | The photo's "Model" metadata item in Lightroom's database. |
| CameraSerialNumber | The photo's "Serial Number" metadata item in Lightroom's database. |
| Exposure | The photo's exposure data, like "¹⁄₂₅₀ sec at f/5.0". |
| ExposureBias | The photo's exposure-bias setting, like "-1 EV". |
| ExposureBiasNum | The photo's exposure-bias setting, as a raw number. |
| ExposureProgram | The photo's exposure-program setting, like "Aperture priority". |
| Flash | One of "no flash", "flash fired", or "unknown flash". |
| FocalLength | Focal Length, as a number |
| FocalLength35 | Focal Length in 35mm format, as a number |
| FocalLength35MM | Focal Length in 35mm format (with locale-specific "mm" appended) |
| FocalLengthMM | Focal Length (with locale-specific "mm" appended) |
| ISO | The photo's ISO (sensor sensitivity) number. |
| Lens | The photo's lens information, like "24-70mm f/2.8". |
| MeteringMode | The photo's metering-mode setting, like "Pattern". |
| ShutterSpeed | The shutter speed, formatted like "¹⁄₂₅₀ sec". |
| ShutterSpeedNum | The shutter speed as a floating-point number of seconds; Use the "Places" filter to limit precision. |
| SubjectDistance | The subject distance as reported by the lens, formatted like "1.2 m". Often wildly inaccurate. |
| SubjectDistanceNum | The 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
| Token | Description |
|---|---|
| CopyName | The name of the copy (master or virtual) being exported, if any |
| Rating | The 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= |
| ColorLabel | The "Label" metadata item |
| EditCount | A number that goes up each time a change is made in Lightroom to the image or its data. |
| UUID | Lightroom'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
| Token | Description |
|---|---|
| GPSCoordinates | The photo's geoencoded coordinates, like "35°1'11.51" N 135°46'16.05" E" |
| Altitude | The photo's geoencoded altitude, as a number, in meters. Use "Places", e.g. {Altitude:Places=0}, to limit precision. |
| GPSAltitude | The photo's geoencoded as a description, e.g. "27.3 m" |
| Latitude | Latitude, as a floating-point number. Use "Places", e.g. {Latitude:Places=4}, to limit precision. |
| Longitude | Longitude, as a floating-point number. Use "Places", e.g. {Longitude:Places=4}, to limit precision. |
| IfGeoencoded | If 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. |
| Location | The "Location" metadata item |
| City | The "City" metadata item |
| State | The "State" metadata item |
| Province | The "State" metadata item |
| Country | The "Country" metadata item |
| CountryCode | The photo's "Image > ISO Country Code" metadata item in Lightroom's database. |
Other Metadata
| Token | Description |
|---|---|
| Artist | The "Artist" metadata item |
| Caption | The "Caption" metadata string |
| Category | The photo's "IPTC > Category" metadata item in Lightroom's database. |
| Copyright | The "Copyright" metadata item |
| CopyrightUrl | The photo's "Copyright Info Url" metadata item in Lightroom's database. |
| Creator | The photo's "Contact > Creator" metadata item in Lightroom's database. |
| CreatorAddress | The photo's "Contact > Address" metadata item in Lightroom's database. |
| CreatorCity | The photo's "Contact > City" metadata item in Lightroom's database. |
| CreatorCountry | The photo's "Contact > Country" metadata item in Lightroom's database. |
| CreatorEmail | The photo's "Contact > E-Mail" metadata item in Lightroom's database. |
| CreatorJobTitle | The photo's "Contact > Job Title" metadata item in Lightroom's database. |
| CreatorPhone | The photo's "Contact > Phone" metadata item in Lightroom's database. |
| CreatorState | The photo's "Contact > State / Province" metadata item in Lightroom's database. |
| CreatorUrl | The photo's "Contact > Website" metadata item in Lightroom's database. |
| CreatorZip | The photo's "Contact > Postal Code" metadata item in Lightroom's database. |
| DescriptionWriter | The photo's "IPTC > Description Writer" metadata item in Lightroom's database. |
| Genre | The photo's "Image > Intellectual Genre" metadata item in Lightroom's database. |
| Headline | The "Headline" metadata item |
| Instructions | The photo's "Workflow > Instructions" metadata item in Lightroom's database. |
| JobIdentifier | The photo's "Workflow > Job Identifier" metadata item in Lightroom's database. |
| Keywords | The 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".) |
| IfKeyword | If 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. | |
| IfExportedKeyword | Like IfKeyword, but considers only keywords that have been marked in Lightroom for export. |
| OtherCategories | The photo's "IPTC > Other Categories" metadata item in Lightroom's database. |
| Provider | The photo's "Workflow > Provider" metadata item in Lightroom's database. |
| RightsUsageTerms | The photo's "Workflow > Rights Usage Terms" metadata item in Lightroom's database. |
| Scene | The "Scene" metadata item |
| Software | The photo's "Software" metadata item in Lightroom's database. |
| Source | The "Source" metadata item |
| SubjectCode | The photo's "IPTC > IPTC Subject Code" metadata item in Lightroom's database. |
| Title | The "Title" metadata item |
Special
| Token | Description |
|---|---|
| PluginProperty=field | Allows 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. | |
| Empty | An 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 {","} |
| LUA | See 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.
| Token | Description |
|---|---|
| CellNumber | Outputs the sequential number of the image in the gallery. The first image is 1, the second image is 2, etc. |
| NumImages | Outputs 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
| Token | Description | |
|---|---|---|
| S2U | Space to Underscore | Any sequences of spaces (and/or underscores) are replaced by a single underscore |
| S2D | Space to Dash | Any sequences of spaces (and/or dashes) are replaced by a single dash |
| U2S | Underscore to Space | Any sequences of underscores (and/or spaces) are replaced by a single space |
| D2S | Dash to Space | Any sequences of dashes (and/or spaces) are replaced by a single space |
| DU2S | Dash/Underscore to Space | Any sequences of dashes, underscores, and/or spaces are replaced by a single space |
| Places=num | specify numeric precision | If the item is number, formats it to num decimal places. If the item is not a number, makes it empty. |
| After=text | Use value to the right of text | If 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%% | ||
| UC | Upper Case | Capitalizes the item |
| LC | Lower Case | Ensures 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.