Adding Your Own Custom Photo-Metadata Fields to Lightroom

Lightroom allows for a variety of metadata for each photo or video... capture date, caption, keywords, etc., and plugins can add further, custom fields, but sometimes what's offered by Lightroom or existing plugins just doesn't fulfill one's own specific needs. Luckily, it's actually fairly easy to make your very own Lightroom plugin to add your own metadata fields. In this post, I'll show you how.

It's fairly quick and simple. It will take far longer to read this post about how to do it than it takes to actually do it.

The kind of fields we can add this way are simple text fields, where you can enter whatever text you like. The example we'll use throughout this article is adding these three fields to track co-artists of a modeling shoot:

three data fields we will add via
our example Modeling Info plugin

Your plugin can have more or fewer fields, and of course you can make different plugins for different sets of data.

As I said, it's fairly simple to set up, but since it does involve editing program files, some things must be done exactly as described, so take care to follow instructions.

The outline of the process:

  1. Create a folder (with a special name, as I'll describe) for the plugin.
  2. Add two starter files into the folder.
  3. Personalize the first file.
  4. Personalize the second file.
  5. Point Lightroom at your new plugin and start using it.
  6. (Optional) Create a metadata-view template to ease access your new data fields.

Again, the process is pretty quick once you're used to it, but we'll go over the steps in detail below.

Steps three and four involves editing program files, and in doing so you must not use a document editor (e.g. Microsoft Word). Rather, you must use a simple text editor that adds no formatting or rich text.

Under OSX you can use TextEdit, so long as you remain in Plain Text mode.

Under Windows you can use Notepad.

Step 1: Create the Plugin Folder

You can take care of both this step and the next by downloading the starter sample plugin this article describes, modeling-info.lrplugin.zip. After unzipping, you'll be left with a folder named modeling-info.lrplugin. Move it to wherever on your system you want your plugin to reside.

(Don't make the mistake to double-click on the folder, as it'll invoke some copy of Lightroom — on my system, it inexplicably brings up Lightroom 3! — after which it brings up the Import Dialog to try to bring non-existent photos from the plugin into Lightroom.)

Or, manually create a folder somewhere on your system where you want your plugin files to reside, naming the folder so that it ends with .lrplugin. The example plugin uses the name modeling-info.lrplugin, but other example names might include My Archive Data.lrplugin or Extra Fields.lrplugin.

Choose a name that means something to you and your use of the data; the name doesn't matter too much to Lightroom, so long as it ends with .lrplugin.

We'll refer to this as your plugin folder; as mentioned above, our example plugin folder is modeling-info.lrplugin.

Mac-Only Note:

OSX treats a folder with this kind of name specially, as a single package rather than a collection of files, but for the next couple of steps we'll want to get inside so we can edit individual files. To do this, in Finder we invoke the Show Package Contents menu item...

This puts us inside our plugin folder. It'll have two files in it already if this is the sample downloaded from my site, but if you created it manually you'll be presented with the empty folder:

Step 2: Copy In Starter Files

If you're not using the sample download, then you'll need to create two text files within your plugin folder, one named Info.lua, and the other named CustomMetadata.lua. You can copy them from the sample download or just copy/paste their contents from below.

Step 3: Personalize the Info.lua File

The starter Info.lua file looks something like this:

return {
   LrPluginName        = "Modeling Info",
   LrToolkitIdentifier = "jeff.friedl.modeling",
   LrSdkVersion        = 2,
   LrMetadataProvider  = 'CustomMetadata.lua',
}

The parts shown in red should be edited to your taste using a raw-text editor (like Notepad or TextEdit). Don't change anything else... these are program files, so every little bit of punctuation matters.

The first bit of text to change (Modeling Info) is the name Lightroom should display when referencing this plugin in its UI. It's primarly used in the plugin manager. Put something here that's meaningful for you. It's best if it's short enough to display without being truncated, so Modeling Info is better than, for example, Extra metadata fields to help me track modeling sessions.

Regardless of what name you choose now, you can always return to this file to update this name later, if you like. It's used only as a display label.

The second item that must be changed, the plugin identifier (shown above as my.custom.modeling), is extremly important: it's the key identifier used by Lightroom behind the scenes to tie your plugin to your catalog, and each photo to its extra data.

You must pick something that's unique to this plugin (that is, something not used by any other plugin that you might ever use), and once you pick it and start using the plugin, it can not be changed.

It's standard practice to combine something with your name (of yourself or your business) and something about this particular plugin. It's standard practice to use a period instead of spaces.

For example, if you're Bob's Photo Studio and you make one plugin to handle modeling data, and another plugin to handle archive data, you might use bobs.photo.studio.modeling for one plugin's identifier, and bobs.photo.studio.archive.data for the other's.

Remember that all editing must be done as plain, bland, un-rich raw text. In particular, make sure not to use smart quotes...

Modeling Info this will fail
"Modeling Info" this is correct

Take a careful look at the punctuation above. See the difference?

Once you've picked the plugin label and internal identifier, save the file and move on to the other.

Step 4: Personalize the CustomMetadata.lua File

The other file contains your list of extra metadata fields that the plugin makes avaialble to each photo.

The starter file is the example defining our three modeling fields:

return {
 schemaVersion = 1, -- increment this value any time you make a change to the field definitions below

 metadataFieldsForPhotos = {
  -- You can have as many fields as you like (the example below shows three)... just make sure each 'id' and 'title' are unique.
  -- Set "searchable" to true to allow as a search criteria in smart collections.
  -- If both "searchable" and "browsable" are true, the field shows up under "Metadata" in Library's grid filter.
  { dataType="string", searchable=false, browsable=false, id="field1", title="Makeup Artist" },
  { dataType="string", searchable=false, browsable=false, id="field2", title="Wardrobe"      },
  { dataType="string", searchable=false, browsable=false, id="field3", title="Hair Stylist"  },
 }
}

This sample defines three data fields, so the first thing you'll want to do is update it to define the number of fields you actually want. If you need less than three, delete the extra { dataType... lines. If you need more than three, replicate one of the lines until you have as many such lines as fields you want.

The title for each metadata field is the label that Lightroom uses when displaying the metadata field to the user. You can use most any descriptive text you like, though shorter values have a better chance of fitting within Lightroom's cramped UI.

The id is the internal key used by Lightroom to tie a photo to its data for this field. The id value must be unique for each field within this plugin (so take extra care if you replicated lines to fill out the number of fields you needed; in doing so you also replicated the title and id, and while you probably want to update the title, the id must be changed).

For the ids, you can simply use field1, field2, etc., as is shown above, or pick short descriptive words such as makeup, wardrobe, hair. It doesn't matter too much to Lightroom so long as there are no repeats, but as illustrated here, there's a benefit to using descriptive ids over a simple field1 enumeration.

(Note: the plugin identifier in the Info.lua file that we edited first must be unique across all plugins, but the field ids in this file need be unique only within this particular plugin.)

You can turn on some options for how the fields work in Lightroom by updating the text shown in yellow above...

If you want a particular data field to be usable within smart-collection criteria, change the false after searchable= to true.

If you want the field to appear in the Library Grid Filter, change both false on the field's line to true.

If, after you've started to use the plugin, you need to return to this file to add or remove fields, or make any other change (e.g. toggling a true to false or vice-versa), increment (add one to) the schemaVersion value.

Step 5: Point Lightroom to your Plugin

Now you install the plugin just like any other: visit the plugin manager, use the Add button, and navigate to the .lrplugin folder you created in Step 1.

Now back in the Library Module, your new fields should appear in the Metatdata panel when you choose the All Plugin Metadata viewing preset:

1) click here to select a new view
2) select All Plugin Metadata

And voilà, the three fields show up, empty and waiting to be filled in as appropriate for each photo:

Step 6: (Opgtional) Metadata Viewer Preset

The need to switch to the All Plugin Metadata view preset, as we did in the last step, can be inconvenient when you want access to both your new fields and other traditional metadata fields like capture date and photo title.

However, using my Metadata-Viewer Preset Editor plugin, you can create your own view of photo data, so that you see whatever fields you like (including the new ones you just added), in whatever order you like.

When using that plugin to create your own custom view, look for the import fields from plugin button at the bottom. That'll make your custom fields available in that plugin.

Accessing Your Custom Fields

The data you add to each photo in your custom fields is kept in your Lightroom catalog, and nowhere else. It's not saved in XMP sidecars, nor is it added to exported copies of photos.

However, you can have your custom data stuffed into certain standard metadata fields of exported copies, using my Metadata Wrangler plugin. It may seem a bit cryptic, especially if you're not used to the template tokens that many of my plugins understand, but here's an example showing the wardrobe-artist data being inserted into the caption of an exported image copy:


screenshot of the Metadata Wrangler as part of an export

Both the plugin id (from the Info.lua file) and the field id (from CustomMetadata.lua) are needed to reference the specific metadata field, tied together with an extra dot (period) character. Here's a breakdown on constructing a reference to a custom plugin field:

{PluginProperty= jeff.friedl.modeling
plugin id
.
field2
field id
}

Notice the extra period (marked with a green arrow) tying together the plugin id and the field id? Don't forget that, and don't let any extra spaces creep in. Also don't forget to wrap the whole reference in curly brackets.

References from afar like this are one reason to choose a descriptive plugin id, and descriptive field ids. The field2 field id seen in this example is a lot less enlightening than the wardrobe alternate suggestion.

You can also shuffle data around within the catalog with the Write Data Field feature of my Bag of Goodies plugin. Here's a screenshot showing Lightroom's Caption field about to be filled with text that includes data from a custom plugin field:

This might be useful in special cases, but I don't think it's all that useful for most workflows because the data movement happens only when you ask for it, as opposed to the Metadata-Wrangler example above that you can set up once (in a Publish Service or in an Export preset) to have happen automatically from then on.

Cleaning Custom Data from your Catalog

If you've been using a custom plugin to add custom fields that you no longer need, and you want to reclaim the space in your catalog database file, you can't just delete the plugin to have the plugin's data removed. This is a good thing, because you certainly don't want to lose valuable plugin data just because you accidentally deleted a plugin file.

The only way I know to actually delete all the data from the catalog is to select all photos in Grid mode, then clear out the data by selecting and deleting the < mixed > value shown in the data field.

A few caveats:

After selecting All Photographs (as seen at right) while in Library Grid mode, merely selecting all images (Command/Control-A) isn't necessarily sufficient.

First of all, you have to make sure that the Grid Filters are turned off... tap Command/Control-L to toggle them off. (If they had been off, you'll see a brief Library Filters On message, in which case you'll want to re-tap Command/Control-L to turn them back off.)

You'll want to re-select all after turning off the filters, then to make sure that nothing is hidden within a closed stack, invoke Photo > Stacking > Expand All Stacks. Then again select all one last time.

Now, before selecting one of the fields to update, make sure that the spinning metadata busy icon is not present. It looks like this:

This is an area of Lightroom's UI that I think is horrible, so you've got to be careful. When that icon is spinning, Lightroom might ignore anything you type into a text-input field, or it might treat it as keyboard shortcuts instead of text to be entered. It's all too easy to destroy lots about your images when working with many of them and typing the wrong thing at what for parts of Lightroom is the wrong time.

So, wait until the spinning icon goes away. Then select the first data field and delete the < mixed > placeholder value. Then wait again until the spinning icon is no more. Repeat for all your fields.

Then you can remove the plugin from Lightroom.


All 2 comments so far, oldest first...

Hi Jeffrey.

I am still using Rob Cole’s Custom Metadata plugin to manage custom metadata, but thanks for showing how it works under the hood.

Have you ever thought of adding Custom Metadata to your “Data Explorer” plugin? You do have Custom Metadata support in your “Metadata Presets” plugin, for which I thank you. But it would so great to, for instance, do searches on Beardy’s “Big Note” field (or any field with “browsable = false”) just like one can use your Data Explorer to explore Caption or Title. I have added a few free-form text fields like “Big Note”, and not being able to easily search them is an impediment to getting things done.

Alan in Oakland

I went ahead and added it (it’s been on my mind to add it for a while, and I’d already done most of the work), but I worry that it won’t be useful for Big Note and the like, because it doesn’t do a search inside the text, it just shows the text. —Jeffrey

— comment by Alan Harper on September 19th, 2016 at 5:59am JST (3 months, 29 days ago) comment permalink

Do you have a plugin that will allow me to be able to export / import the custom data that gets created using your Photo-Metadata Fields plugin .

i would like to have the option to work with the data in a excel spreadsheet

You can export metadata like this with Tim Armes’ Lr/Transporter plugin. See the “Metadata from 3rd party plugins” section on that page. In this case, you and your plugin (it’s not my plugin… I merely tell you how to make your own) are the “3rd party”. —Jeffrey

— comment by mark on October 18th, 2016 at 2:34pm JST (3 months ago) comment permalink
Leave a comment...


All comments are invisible to others until Jeffrey approves them.

Please mention what part of the world you're writing from, if you don't mind. It's always interesting to see where people are visiting from.


You can use basic HTML; be sure to close tags properly.

Subscribe without commenting