Metadata ======== Vimiv provides optional metadata support. If enabled, then: #. The ``:metadata`` command and the corresponding ``i``-keybinding is available. It displays the metadata of the current image. #. The ``{exif-date-time}`` statusbar module is available. It displays the Exif creation time of the current image. #. Metadata is automatically copied from source to destination when writing images to disk. Vimiv provides full flexibility to users in terms of what metadata backend to use. Each backend comes with their advantages and disadvantages, and each user has different requirements, as well as different package support. Therefore, vimiv provides metadata backends as independent plugins, that can be loaded as one desires. In addition, users have the ability to extend vimiv's metadata capabilities using :ref:`custom plugins`, as described in :ref:`a later section`. Vimiv comes with two default plugins: * ``metadata_piexif`` is based on `piexif`_ * ``metadata_pyexiv2`` is based on `pyexiv2`_ In addition, there are the following user metadata plugins available: .. _user_metadata_plugins: .. table:: Overview of user plugins :widths: 20 80 ===================================================================== =========== Name Description ===================================================================== =========== `metadata_gexiv2 `_ Based on `gexiv2 `_ ===================================================================== =========== Enable Support -------------- Metadata plugins are loaded as any other vimiv plugin. To enable one of the default plugins, simply list its name in the ``PLUGINS`` section of the configuration file. In addition, you need to ensure that the required backend is installed on your system. To enable a user metadata plugin, first you need to download it, and put it into the plugin folder. Afterwards loading is equivalent to the default plugins. For more information on how to load plugins, please refer to the :ref:`plugin section`. If no metadata plugin is specified, vimiv will load one of the two default plugins, if the respective backend is installed. To disable this default behaviour, specify ``metadata = none`` in the ``PLUGINS`` section. .. warning:: Default loading may be dropped in a future version. If you rely on metadata support, we recommend to explicitly specify what backend you want. .. note:: Multiple metadata plugins can be registered at the same time. If they use distinct keys, the value of both is combined in the output of ``:metadata``. Comparison of Different Plugins ------------------------------- In short, ``metadata_pyexiv2`` is much more powerful than ``metadata_piexif``, though the dependencies are also more involved to install. .. table:: Comparison of the two libraries :widths: 20 15 20 45 ======================= =================== ==================== ===================================================================== PROPERTY ``metadata_piexif`` ``metadata_pyexiv2`` Note ======================= =================== ==================== ===================================================================== Backend `piexif`_ `pyexiv2`_ Exif Support True True pyexiv2 can potentially extract more data for the same image ICMP Support False True XMP Suppport False True Output Formatting False True e.g. ``FNumber: 63/10`` vs ``FNumber: F6.3`` Supported File Types JPEG, TIFF Many common types Ease of installation Simple More complicated pyexiv2 requires some dependencies including the C++ library `exiv2`_ ======================= =================== ==================== ===================================================================== We recommend to use ``metadata_pyexiv2`` if the installation of `pyexiv2`_ is not too involved on your system and ``metadata_piexif`` as a fallback solution or in case you don't need the full power of `pyexiv2`_ and prefer something more lightweight. Also consider the list of available :ref:`user metadata plugins`. Customize Keysets ----------------- You can configure the information displayed by the ``:metadata`` command by adding your own key sets to the ``METADATA`` section in your configfile like this:: keys2 = someKey,anotherOne,lastOne keys4 = newKey,oneMore where the values must be a comma-separated list of valid metadata keys. In case you are using `pyexiv2`_, you can find a complete overview of valid keys on the `exiv2 webpage `_. You can choose any of the Exif, IPTC, or XMP keys. `Piexif`_ uses a simplified form of the key. It does not use the ``Group.Subgroup`` prefix, which is present in each of `pyexiv2`_'s keys. However, ``metadata_piexif`` automatically does this truncation, if the provided keys are in the long form. The ``:metadata-list-keys`` command provides a list of all valid metadata keys, that the currently loaded metadata plugins can read. This serves as an easy way to see what keys are available in the image. .. _create_own_plugins: Create Own Plugins ------------------ One can extend vimiv's metadata capabilities by creating own metadata plugins. This is useful if you want to use a different metadata backend. The rough steps are the following: #. Create a plugin, that implements the abstract class ``vimiv.imutils.metadata.MetadataPlugin`` #. Implement all required methods #. Optionally, also implement the non-required methods #. In the plugin's init function, register the plugin using ``vimiv.imutils.metadata.register`` Please see the default metadata plugins for an example implementation. .. _exiv2: https://www.exiv2.org/index.html .. _pyexiv2: https://python3-exiv2.readthedocs.io .. _piexif: https://pypi.org/project/piexif/