1.. image:: images/logo.svg
2   :align: center
3   :width: 400px
4
5|
6
7.. toctree::
8    :hidden:
9    :titlesonly:
10    :maxdepth: 3
11
12    changelog
13    user/index
14    api/index
15    man/index
16    contact
17
18.. title:: Overview
19
20.. include:: ../README.rst
21    :start-after: |
22
23----
24
25There is a :doc:`brief tutorial with several API examples.
26<user/index>`
27
28
29Installing
30----------
31
32::
33
34    pip install mutagen
35
36or
37
38::
39
40    sudo apt-get install python-mutagen python3-mutagen
41
42
43Where do I get it?
44------------------
45
46Mutagen is hosted on `GitHub <https://github.com/quodlibet/mutagen>`_. The
47`download page <https://github.com/quodlibet/mutagen/releases>`_ or `PyPI
48<https://pypi.org/project/mutagen>`_ will have the latest version or check out
49the git repository::
50
51    $ git clone https://github.com/quodlibet/mutagen.git
52
53
54Why Mutagen?
55------------
56
57Quod Libet has more strenuous requirements in a tagging library than most
58programs that deal with tags. Therefore we felt it was necessary to write our
59own.
60
61* Mutagen has a simple API, that is roughly the same across all tag formats
62  and versions and integrates into Python's builtin types and interfaces.
63* New frame types and file formats are easily added, and the behavior of the
64  current formats can be changed by extending them.
65* Freeform keys, multiple values, Unicode, and other advanced features were
66  considered from the start and are fully supported.
67* All ID3v2 versions and all ID3v2.4 frames are covered, including rare ones
68  like POPM or RVA2.
69* We take automated testing very seriously. All bug fixes are committed with a
70  test that prevents them from recurring, and new features are committed with
71  a full test suite.
72
73
74Real World Use
75--------------
76
77Mutagen can load nearly every MP3 we have thrown at it (when it hasn't, we
78make it do so). Scripts are included so you can run the same tests on your
79collection.
80
81The following software projects are using Mutagen for tagging:
82
83* `Ex Falso and Quod Libet <https://quodlibet.readthedocs.org>`_, a flexible tagger and player
84* `Beets <http://beets.radbox.org/>`_, a music library manager and MusicBrainz tagger
85* `Picard <https://picard.musicbrainz.org/>`_, cross-platform MusicBrainz tagger
86* `Puddletag <http://puddletag.net/>`_, an audio tag editor
87* `Exaile <http://www.exaile.org/>`_, a media player aiming to be similar to KDE's AmaroK, but for GTK+
88