Metadata-Version: 1.1
Name: pytaglib
Version: 1.2.0
Summary: Python (2.6+/3.1+) bindings for the TagLib audio metadata library
Home-page: http://github.com/supermihi/pytaglib
Author: Michael Helmling
Author-email: michaelhelmling@posteo.de
License: GPLv3+
Description: ``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
        ------------
        
        Linux / Unix
        ~~~~~~~~~~~~
        
        | 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.
        
        Windows
        ~~~~~~~
        
        | **Note**: Windows installation was tested for Python 3.5 and Win64
          only. In theory, pytaglib
        | is compatible with any Python version and architecture, but
          compilation might not be
        | straightforward (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=".\install``
              to generate the Visual Studio project files.
           #. Type ``msbuild INSTALL.vcxproj /p:Configuration=Release`` which
              will "install" taglib into the ``install`` subdirectory.
        
        #. Still in the VS2015 command prompt, navigat 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``
        
           .. rubric:: Usage
              :name: 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>`__.
        
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
