Metadata-Version: 2.0
Name: pytaglib
Version: 1.4.2
Summary: cross-platform, Python 2.x/3.x audio metadata ("tagging") library based on TagLib
Home-page: http://github.com/supermihi/pytaglib
Author: Michael Helmling
Author-email: michaelhelmling@posteo.de
License: GPLv3+
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: Cython

**pytaglib**
============

|Build Status| |PyPI version|

pytaglib is a `Python <http://www.python.org>`__ audio tagging library.
It is cross-platform, works with all Python versions, and is very simple
to use yet fully featured:

-  `supports more than a dozen file formats <http://taglib.github.io>`__
   including mp3, flac, ogg, wma, and mp4,
-  support arbitrary, non-standard tag names,
-  support multiple values per tag.

pytaglib is a very thin wrapper (<150 lines of code) around the fast and
rock-solid `TagLib <http://taglib.github.io>`__ C++ library.

Get it
------

In most cases, you should install pytaglib with
`pip <https://pip.pypa.io/en/stable/>`__:

::

        pip install pytaglib

See `installation notes <#installnotes>`__ below for requirements and
manual compilation.

Usage
-----

.. code:: python

    >>> import taglib
    >>> song = taglib.File("/path/to/my/file.mp3")
    >>> song.tags
    {'ARTIST': ['piman', 'jzig'], 'ALBUM': ['Quod Libet Test Data'], 'TITLE': ['Silence'], 'GENRE': ['Silence'], 'TRACKNUMBER': ['02/10'], 'DATE': ['2004']}

    >>> song.length
    239
    >>> song.tags["ALBUM"] = ["White Album"] # always use lists, even for single values
    >>> del song.tags["DATE"]
    >>> song.tags["GENRE"] = ["Vocal", "Classical"]
    >>> song.tags["PERFORMER:HARPSICHORD"] = ["Ton Koopman"] 
    >>> song.save()

For detailed API documentation, use the docstrings of the
``taglib.File`` class or view the `source code <src/taglib.pyx>`__
directly.

**Note:** pytaglib uses unicode strings (type ``str`` in Python 3 and
``unicode`` in Python 2) for both tag names and values. The library
converts byte-strings to unicode strings on assignment, but it is
recommended to provide unicode strings only to avoid encoding problems.

Installation Notes #installnotes
--------------------------------

The most recommended installation method is

::

        pip install pytaglib

subject to the following notes:

-  Ensure that ``pip`` points to the correct Python version; you might
   need to use, e.g., ``pip-3.5`` if you want to install ``pytaglib``
   for Python 3.5 and your system's default is Python 2.7.
-  You may need administrator rights to install a package, i.e.,
   ``sudo pip install pytaglib`` on Unix or running the command on a
   Admin console on windows
-  Alternatively, install locally into your user home with
   ``pip install --user pytaglib``.
-  You need to have ``taglib`` installed with development headers
   (package ``libtag1-dev`` for debian-based linux,
   ``brew install taglib`` on OS X).
-  If ``taglib`` is installed at a non-standard location, you can tell
   ``pip`` where to look for its include (``-I``) and library (``-L``)
   files:

   ::

         pip install --global-option=build_ext --global-option="-I/usr/local/include/" --global-option="-L/usr/local/lib" pytaglib

If the above does not work, continue reading for alternative methods of
installation.

Linux / Unix
~~~~~~~~~~~~

Distribution-Specific Packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  Debian- and Ubuntu-based linux flavors have binary packages for the
   Python 3 version, called ``python3-taglib``. Unfortunatelly, they are
   heavily outdated, so you should use the above "pip" method whenever
   possible.
-  For Arch users, there is a
   `package <https://aur.archlinux.org/packages/python-pytaglib/>`__ in
   the user repository (AUR) which I try to keep up-to-date.

   .. rubric:: Manual Compilation

   Alternatively, you can download / checkout the sources and compile
   manually:

   ::

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

You can manually specify ``taglib``'s include and library directories:

::

    python setup.py build --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.

Windows
~~~~~~~

Currently, the PyPI archive contains a binary version only for
Python3.5/x64. For different combinations of Python version and
architecture, you need to build yourself.

**Note**: The following procedure was tested for Python 3.5 on x64 only.
Other python versions probably require some more work; see e.g.
`this <https://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/>`__
page.

#. Install `Microsoft Visual Studio 2015 Community
   Edition <https://www.visualstudio.com/downloads/download-visual-studio-vs>`__.
   In the installation process, be sure to enable C/C++ support.
#. Download and build taglib:

   #. Download the current `taglib
      release <https://github.com/taglib/taglib/releases>`__ and extract
      it somewhere on your computer.
   #. Start the VS2015 x64 Native Tools Command Prompt. On Windows 8/10,
      it might not appear in your start menu, but you can find it here:
      ``C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2015\Visual Studio Tools\Windows Desktop Command Prompts``
   #. Navigate to the extracted taglib folder and type:
      ``cmake -G "Visual Studio 14 2015 Win64" -DCMAKE_INSTALL_PREFIX=".\taglib-install"``
      to generate the Visual Studio project files.
   #. Type ``msbuild INSTALL.vcxproj /p:Configuration=Release`` which
      will "install" taglib into the ``taglib-install`` subdirectory.

#. Still in the VS2015 command prompt, navigate to the pytaglib
   directory.
#. Tell pytaglib where to find taglib:
   ``set TAGLIB_HOME=C:\Path\To\taglib-install``
#. Build pytaglib: ``python setup.py build`` and install:
   ``python setup.py install``

``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>`__.

.. |Build Status| image:: https://travis-ci.org/supermihi/pytaglib.svg?branch=master
   :target: https://travis-ci.org/supermihi/pytaglib
.. |PyPI version| image:: https://badge.fury.io/py/pytaglib.svg
   :target: https://badge.fury.io/py/pytaglib


