- add Spotlight searchable meta tags to any file or folder
- organise your files the way you want
- make smart folders even smarter
spotmeta.org
spotmeta.org is a domain registered for the purpose of adding structured metadata in xattr records and Spotlight.
This web site documents how the metdata keys and data are formatted, and presents example code to read and write them. It also documents how to integrate with the SpotMeta utility to add the fields to the Spotlight user interface.
Basic key structure
Keys, both in xattr records and Spotlight schemas, are of the form
org_spotmeta_type_name
where type is a two character type encoding, and name is a user presentable name encoded from 16 bit unicode to A-Z, a-z, 0-9 and the underscore character (the only allowed characters in a Spotlight attribute name.)
The type and the user's presentable name are encoded directly in the attribute for two reasons. Firstly, so it is easily transportable from one installation to another, and secondly, so the SpotMeta Bridging Importer does not need to have read a schema to be able to convert an attribute for use in Spotlight.
Given that this is the case, an external utility can just create the xattr records and then make Spotlight queries (from a program or the command line) without even informing anything of the schema definitions for these keys.
Types and data encodings
The type is encoded in two characters. The first specifies whether the value is a single item or multi-value.
| Character | Meaning |
|---|---|
| s | Single value |
| m | Multiple values |
Note that this part of the type does not encode whether there is currently one or more than one value in the value part, but whether it is possible at all. If the type was to change, it would be treated as a separate key.
The second character specifies the type of the data. All data is encoded as UTF-8 string representations. Multiple values are simply separated by the ASCII record separator control code, hex value 0x1E,
| Character | Meaning | Encoding |
|---|---|---|
| t | Text | Simple UTF-8 string |
| c | Choice | Simple UTF-8 string, but it is assumed that there are a limited number of possibilities. The distinction between this and text is mainly in the user interface. |
| n | Number | Decimal, optional floating point part |
| b | Boolean value | "0" = false, "1" = true |
| d | Date (and time) | GMT time encoded as YYYYMMDDHHMMSS |
The encoding is intended to be human readable, yet easy to parse.
Name encoding
Encoding of the name part of the metadata key is slightly complex. It is desirable to encode the full 16 bit unicode text, yet it should be as human readable as possible, and, given the 128 byte limitation on xattr key size, should be compact.
While xattr keys are UTF-8 encoded, Spotlight restricts them to A-Z, a-z, 0-9 and the underscore character.
The underscore character is used as the escape character. Other characters are passed untouched. A space is encoded as a double underscore.
Other characters are encoded as follows. If the value of the character is c
- If the character is in this C style string ".,:'\"!$%&(\n)-\[email protected]+;" replace it with its index in this string. (This aims to shorten the encoding of English names.)
- d1 = c MOD 20
- Integer divide c by 20, then d2 = c MOD 62
- Integer divide c by 62, then d3 = c MOD 62
- There are now three ordered integers. The length of the encoding is 1 character if d2 == 0 and d3 == 0, 2 characters if d3 == 0, and 3 characters otherwise.
- Add 20 * (length - 1) to d1
- Generate length bytes of encoding by using the d* values as indices in the string "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
This coding uses up to four characters (3 digits plus the _ escape character) but for English strings tends to use two or three characters.
You are encouraged to use the example code to encode and decode strings.
Implementation notes
After writing the metadata in xattr strings, run mdimport on the file, as the changes are not picked up by Spotlight automatically. The SpotMeta Bridging Importer will hopefully handle this properly in the future.
Note that running mdimport on a directory will re-import all the files in that directory and subdirectories, which is probably not a particular desirable operation.
Spotlight does not require that you register any metadata keys using importer schemas; for some application where it is not necessary for the end user to search on the metadata from the Finder interface, it may not be worth setting up a schema entry.
Example code
coming soon....
How SpotMeta helps you organise your files
Information for Advanced Users
Project status
SpotMeta is an Open Source project, licensed under the GPL.
See note about development status on the contact page.