Duplicates Plugin
=================

This plugin adds a new command, ``duplicates`` or ``dup``, which finds
and lists duplicate tracks or albums in your collection.

Installation
------------

Enable the plugin by putting ``duplicates`` on your ``plugins`` line in
your :doc:`config file </reference/config>`::

    plugins: duplicates

Configuration
-------------

By default, the ``beet duplicates`` command lists the names of tracks
in your library that are duplicates. It assumes that Musicbrainz track
and album ids are unique to each track or album. That is, it lists
every track or album with an ID that has been seen before in the
library.

You can customize the output format, count the number of duplicate
tracks or albums, and list all tracks that have duplicates or just the
duplicates themselves. These options can either be specified in the
config file::

    duplicates:
        format: $albumartist - $album - $title
        count: no
        album: no
        full: no
	keys:
	- mb_trackid
	- album

or on the command-line::

    -f FORMAT, --format=FORMAT
                          print with custom FORMAT
    -c, --count           count duplicate tracks or
                          albums
    -a, --album           show duplicate albums instead
                          of tracks
    -F, --full            show all versions of duplicate
                          tracks or albums
    -k KEYS, --keys=KEYS  report duplicates based on keys


format
~~~~~~

The ``format`` option (default: :ref:`list_format_item`) lets you
specify a specific format with which to print every track or
album. This uses the same template syntax as beets’ :doc:`path formats
</reference/pathformat>`.  The usage is inspired by, and therefore
similar to, the :ref:`list <list-cmd>` command.

count
~~~~~

The ``count`` option (default: false) prints a count of duplicate
tracks or albums, with ``format`` hard-coded to ``$albumartist -
$album - $title: $count`` or ``$albumartist - $album: $count`` (for
the ``-a`` option).

album
~~~~~

The ``album`` option (default: false) lists duplicate albums instead
of tracks.

full
~~~~

The ``full`` option (default: false) lists every track or album that
has duplicates, not just the duplicates themselves.

keys
~~~~

The ``keys`` option (default: ``mb_trackid``) defines in which track
or album fields duplicates are to be searched. By default, the plugin
only uses the musicbrainz track or album ID for this purpose. Using the
``keys`` option (as a YAML list in the configuration file, or a
comma-delimited string in the command-line), you can extend this behavior
to consider other attributes.


Examples
--------

List all duplicate tracks in your collection::

  beet duplicates

List all duplicate tracks from 2008::

  beet duplicates year:2008

Print out a unicode histogram of duplicate track years using `spark`_::

  beet duplicates -f '$year' | spark
  ▆▁▆█▄▇▇▄▇▇▁█▇▆▇▂▄█▁██▂█▁▁██▁█▂▇▆▂▇█▇▇█▆▆▇█▇█▇▆██▂▇

Print out a listing of all albums with duplicate tracks, and respective counts::

  beet duplicates -ac

The same as the above but include the original album, and show the path::

  beet duplicates -acf '$path'


Get rid of false positives arising from the same track existing in different albums::

  beet duplicates -k mb_trackid,album

TODO
----

- Allow deleting duplicates.
- Provide option to invert key selection
- Provide additional strategies for duplicate finding (fingerprint, hash, etc.)  

.. _spark: https://github.com/holman/spark