Tutorial: adding MIME information to the database

This tutorial is for application authors and users who want to extend the database. For example, the Gimp may wish to add:

• image/png can be edited using the Gimp.
• image/png should be described in English as "Portable Network Graphics file".
• Files whose names end in .png should have the type image/png. Users should normally use a graphical editor application, such as MIME-Editor, to edit the database (although ideally no user-editing should be required at all). If you really want to do it manually, create a file called $XDG_DATA_HOME/mime/packages/Override.xml in the format described below.

(see the Base Directory Specification for information about the XDG_ variables)

When your application is installed, it should install a file with the application's name in $XDG_DATA_DIRS/mime/packages. For example, doing ./configure && make install with Gimp should create /usr/local/share/mime/packages/gimp.xml.

This file has the following format:

<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
  <mime-type type="image/png">
         <comment xml:lang="en">PNG image</comment>
         <comment xml:lang="af">png beeld</comment>
         ...
         <magic priority="50">
                <match type="string" value="\x89PNG" offset="0"/>
         </magic>
         <glob pattern="*.png"/>
  </mime-type>
</mime-info>

This provides a comment (in two languages), a rule to recognise PNG files by their contents, and a rule to recognise them by their names. You can provide information about several types in the single gimp.xml file. You do not need to provide any information which is also in the base package (in fact, all the information above is already present; this is just an example!).

You can also add extra elements, provided they are namespaced to avoid conflicts. For example:

<desktop:can-edit-with>gimp.desktop</desktop:can-edit-with>

This indicates that the named desktop entry file describes an application that can edit image/png files. Note that the above is just an example; the desktop entry specification does not currently define this element. See the ?MIME actions specification for more details.

Note also that information added to the database should be static ("gimp can edit PNG files"), not configuration ("gimp is the preferred editor for PNG files"). See the shared configuration system for storing configuration information.

Once you have installed the gimp.xml file, run the update-mime-database command to rebuild the output files. This program checks that the syntax of your file is correct and merges the information in it with that in the other XML files in the packages directory. It then puts the rules for recognising files into one set of files, and the information about each type into other files (eg $XDG_DATA_DIR/mime/image/png.xml), where other programs can access it easily.

When the Gimp is uninstalled, it should remove the gimp.xml file and run update-mime-database again to remove the information from the database.

Submitting patches for the main package

If you have added types that should go in the common freedesktop.org base list of types, you should create an enhancement request on the MIME bugtracker following the instructions in the HACKING file (note that sending the created XML file will not be enough).