``pytaglib`` – TagLib bindings for Python
=========================================

Overview
--------

| ``pytaglib`` is a package of `Python <http://www.python.org>`__
  (2.6+/3.1+) bindings for
| `Taglib <http://taglib.github.io>`__. It provides a full-featured
  audio metadata ("tag") library supporting
| all current versions of Python.

| The package gives you complete freedom over the tag names – you are
  not limited to common tags like
| ``ARTIST``, ``ALBUM`` etc.; instead you may use any string as key as
  long as the underlying metadata
| format supports it (most of them do, including *mp3*, *ogg*, and
  *FLAC*). Moreover, you can even
| use multiple values of the same tag, in order to e.g. store two
  artists, several genres, and so on.

Requirements
------------

| ``pytaglib`` uses Taglib features that have been added in version
  1.8-BETA, so you need at least that
| version along with development headers to compile ``pytaglib``. The
  recent releases of all linux
| flavours nowadays ship taglib ≥ 1.8.

| The use of taglib ≥ 1.9 is recommended, since that release fixes some
  bugs that may affect
| ``pytaglib`` in less common circumstances.

| In theory, ``pytaglib`` should also compile and run on Windows, though
  I did not succeed when I last
| tried. Any help with that issue is appreciated!

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

| Debian sid and Ubuntu trusty have binary packages for the Python 3
  version, called ``python3-taglib``.
| At time of writing they are outdated, but should work nevertheless.
  For Arch users, there is a
| `package <https://aur.archlinux.org/packages/python-pytaglib/>`__ in
  the user repository (AUR).

| If your distribution does not ship ``pytaglib``, it can easily be
  installed by one of the following
| methods.

-  Install from `PyPI <pypi.python.org>`__ using
   `pip <https://pip.pypa.io>`__:

   ::

       sudo pip install pytaglib

   | Be careful to call ``pip`` for the correct Python version; you
     might need
   | something like

   ::

       sudo pip3 pytaglib

   | to build the package for Python 3 (the exact command depends on
     your distribution). The command
   | can also be run with the ``--user`` option (and without ``sudo``)
     which will install everything
   | into your home directory.

-  Alternatively, you can download the source tarball and compile
   manually:

   ::

       python setup.py build
       python setup.py test  # optional
       sudo python setup.py install

   Again, replace ``python`` by the interpreter executable of the
   desired Python version.

| The compiler must be able to find headers and dynamic library of
  TagLib. Usually, they should be
| installed at standard places. If not, you can manually specify include
  and lib directories, e.g.:

::

    python setup.py build_ext --include-dirs /usr/local/include --library-dirs /usr/local/lib

| **Note**: The ``taglib`` Python extension is built from the file
  ``taglib.cpp`` which in turn is
| auto-generated by `Cython <http://www.cython.org>`__ from
  ``taglib.pyx``. To re-cythonize this file
| instead of using the shipped ``taglib.cpp``, invoke ``setup.py`` with
  the ``--cython`` option.

Usage
-----

The use of the library is pretty straightforward:

#. Load the library: ``import taglib``
#. Open a file: ``f = taglib.File("/path/to/file.mp3")``
#. Read tags from the dict ``f.tags`` which maps uppercase tag names to
   lists of tag values (note
   that even single values are stored as list in order to be
   consistent).
#. Some other information about the file is available as well:
   ``f.length``,
   ``f.sampleRate``, ``f.channels``, ``f.bitrate``, and ``f.readOnly``.
#. Alter the tags by manipulating the dictionary ``f.tags``. You should
   always
   use uppercase tag names and lists of strings for the values.
#. Store your changes: ``retval = f.save()``.
#. If some tags could not be saved because they are not supported by the
   underlying format, those will be contained in the list returned from
   ``f.save()``.

| The following snippet should show the most relevant features. For a
  complete
| reference confer the online help via ``help(taglib.File)``.

::

    $ python
    Python 3.3.0 (default, Sep 29 2012, 15:50:43)
    [GCC 4.7.1 20120721 (prerelease)] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import taglib
    >>> f = taglib.File("x.flac")
    >>> f
    File('x.flac')
    >>> f.tags
    {'ARTIST': ['piman', 'jzig'], 'ALBUM': ['Quod Libet Test Data'], 'TITLE': ['Silence'], 'GENRE': ['Silence'], 'TRACKNUMBER': ['02/10'], 'DATE': ['2004']}
    >>> f.tags["ALBUM"] = ["Always use lists even for single values"]
    >>> del f.tags["GENRE"]
    >>> f.tags["ARTIST"].remove("jzig")
    >>> retval = f.save()
    >>> retval
    {}
    >>>

| **Note:** As ``pytaglib`` was designed mainly for Python 3, all string
  values returned are unicode
| strings (type ``str`` in Python 3 and ``unicode`` in Python 2). On the
  input side, however, the library
| is rather permissive and supports both byte- and unicode-strings.
  Internally, ``pytaglib`` converts
| all strings to ``UTF-8`` before storing them in the files.

``pyprinttags``
---------------

| This package also installs the small script ``pyprinttags``. It takes
  one or more files as
| command-line parameters and will display all known metadata of that
  files on the terminal.
| If unsupported tags (a.k.a. non-textual information) are found, they
  can optionally be removed
| from the file.

``Contact``
-----------

| For bug reports or feature requests, please use the
| `issue tracker <https://github.com/supermihi/pytaglib/issues>`__ on
  GitHub. For anything else, contact
| me by `email <mailto:michaelhelmling@posteo.de>`__.
