Ben Summers presents
Spotlight, the way you've always wanted it!

SpotMeta for technical users

Metadata doesn't have to be applied by the SpotMeta user interface. You can apply it in your own scripts or programs, using any tool which can apply xattr extended attributes to files.

The only thing you need to be aware of is that you must run mdimport once you have modified the data to get it into the Spotlight store.

Once you've got the data into the store, you can use tools like mdfind and mdls to use the metadata in your scripts.

Application integration

As well as invoking the SpotMeta metadata editor from the Finder via the control+click menu or the keyboard shortcut, users can invoke SpotMeta on the file currently being edited in an application by using the shortcut with the application window selected.

To do this, SpotMeta uses AppleScript to query the file path from the application. Since the way to do this does vary somewhat between applications, the set of defaults built into SpotMeta may not always work.

If this is the case, then you can create a custom script and put it in ~/Library/SpotMeta/CurrentFileScripts. SpotMeta looks here for .scpt files with the name of the active application, for example, MyApplication.scpt.

The script must output a path or string containing the POSIX filename. As a rule of thumb, if you run it in Script Editor and the result is simply a / separated filename (like /path/to/file.ext), then it'll work. If the result has quotes around it, that's OK too, but absolutely nothing else.

Note that these scripts will only be loaded once per run, so you need to restart SpotMetaAgent if when you edit them -- type killall SpotMetaAgent in Terminal, then run the main SpotMeta application again to restart it.

SpotMeta for developers

SpotMeta is designed to be open and allow other developers to take advantage of the true capabilities of Spotlight.

You can add and manipulate your own metadata, independent of the SpotMeta user interface. The format of the data encodes type information, so metadata keys don't have to be registered with SpotMeta before you use them.

Or perhaps you want to extend the metadata in new and exciting ways for which xattr attributes just won't do. SpotMeta allows you to extend your own Spotlight Importers to add extra metadata onto any file, after the default importer has run. This could allow you to grab extra information from files which the default importers don't retrieve, without having to rewrite the original. Or you could get the metadata from somewhere even more exciting... and all this using the standard importer interface and simply adding another entry to your Info.plist file.

You needn't worry that your users will have to buy SpotMeta. Even though the final version will require paid registration, the essential bits which you need will keep working even after the free trial is over.

Technical details

The SpotMeta metadata is stored in xattr extended attribute records using the new HFS features in Mac OS X 10.4. These will be preserved as the file is copied to other computers, even if they are not running SpotMeta.

The attributes are stored under the org_spotmeta namespace. This encodes the type information of the metadata, so definition files are not strictly needed. The name of the attribute is a full unicode name, but encoded using the characters A-Z, a-z, 0-9 and the underscore -- the only characters Spotlight allows as a meta data key. It's reasonably compact, and for English names, reasonably human readable.

After a file has been read by a Spotlight importer, these attributes are read and added to to the importer's results. This is where the SpotMeta Bridging Importer comes in — it's the magic which bridges xattr and Spotlight.

Further reading

Please see our detailed information for developers




How SpotMeta helps you organise your files

Using SpotMeta

Information for Advanced Users


Contact the author

Project status


SpotMeta is an Open Source project, licensed under the GPL.

See note about development status on the contact page.