LastGenre Plugin
================

The MusicBrainz database `does not contain genre information`_. Therefore, when
importing and autotagging music, beets does not assign a genre.  The
``lastgenre`` plugin fetches *tags* from `Last.fm`_ and assigns them as genres
to your albums and items. The plugin is included with beets as of version
1.0b11.

.. _does not contain genre information:
    http://musicbrainz.org/doc/General_FAQ#Why_does_MusicBrainz_not_support_genre_information.3F
.. _Last.fm: http://last.fm/

The plugin requires `pylast`_, which you can install using `pip`_ by typing::

    pip install pylast

After you have pylast installed, enable the plugin by putting ``lastgenre`` on
your ``plugins`` line in :doc:`/reference/config`, like so::

    [beets]
    plugins: lastgenre

The plugin chooses genres based on a *whitelist*, meaning that only certain tags
can be considered genres. This way, tags like "my favorite music" or "seen live"
won't be considered genres. The plugin ships with a fairly extensive internal
whitelist, but you can set your own in the config file using the ``whitelist``
configuration value::

    [lastgenre]
    whitelist: /path/to/genres.txt

The genre list file should contain one genre per line. Blank lines are ignored.
For the curious, the default genre list is generated by a `script that scrapes
Wikipedia`_.

.. _pip: http://www.pip-installer.org/
.. _pylast: http://code.google.com/p/pylast/
.. _script that scrapes Wikipedia: https://gist.github.com/1241307

If no genre is found, you have the opportunity to specify a fixed string instead
(declare *fallback_str* with no value to blank the genre field)::

    [lastgenre]
    fallback_str:


Canonicalization
----------------

The plugin can also *canonicalize* genres, meaning that more obscure genres can
be turned into coarser-grained ones that are present in the whitelist. This
works using a tree of nested genre names, represented using `YAML`_, where the
leaves of the tree represent the most specific genres.

To enable canonicalization, first install the `pyyaml`_ module (``pip install
pyyaml``). Then set the ``canonical`` configuration value::

    [lastgenre]
    canonical:

Leaving this value blank will use a built-in canonicalization tree. You can also
set it to a path, just like the ``whitelist`` config value, to use your own
tree.

.. _YAML: http://www.yaml.org/
.. _pyyaml: http://pyyaml.org/
