README

TagPy
=====

TagPy is a Python crust (or a set of Python bindings) for Scott Wheeler's
TagLib [1]. It builds upon Boost.Python [2], a wrapper generation library which
is part of the Boost set of C++ libraries [3]. It has its own web site [4].

Just like TagLib, TagPy can:

- read and write ID3 tags of version 1 and 2, with many supported frame types
  for version 2 (in MPEG Layer 2 and MPEG Layer 3, FLAC and MPC),
- access Xiph Comments in Ogg Vorbis Files and Ogg Flac Files,
- access APE tags in Musepack and MP3 files.

All these have their own specific interfaces, but TagLib's generic tag
reading and writing mechanism is also supported. 

You can find examples in the test/ directory.

Andreas Kloeckner <inform@tiker.net>

[1] http://developer.kde.org/~wheeler/taglib.html
[2] http://www.boost.org/libs/python/doc/
[3] http://www.boost.org
[4] http://mathema.tician.de/software/tagpy

Acknowledgements
================

- Andreas Hemel <debian-bugs@daishan.de> sent a patch for a crash bug.
- Michal Čihař <nijel@debian.org> maintains the Debian package.
- Keith Packard wrote a UCS4 to UTF8 routine that I shamelessly stole.
- Christoph Burgmer wrote the initial version of the new Python-only
  FileRef.

Here's his copyright:

 * Copyright © 2000 Keith Packard
 *
 * Permission to use, copy, modify, distribute, and sell this software and its
 * documentation for any purpose is hereby granted without fee, provided that
 * the above copyright notice appear in all copies and that both that
 * copyright notice and this permission notice appear in supporting
 * documentation, and that the name of Keith Packard not be used in
 * advertising or publicity pertaining to distribution of the software without
 * specific, written prior permission.  Keith Packard makes no
 * representations about the suitability of this software for any purpose.  It
 * is provided "as is" without express or implied warranty.
 *
 * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.


Building TagPy
==============

Step 0: Verifying that you have the right dependencies
-------

TagPy works for me with

- TagLib 1.4
- Boost.Python 1.33
- gcc 4.0

I have reason to believe that slightly older versions of gcc and 
Boost.Python should be fine, but the 1.4 requirement for TagLib is
firm.

Step 1: Installing Boost.Python
-------

In Debian, it suffices to do "aptitude install libboost-python-dev".
The distribution is preconfigured for this case. You may skip to step
2.

For other distributions, you need to follow the steps at [5]. Roughly,
you must follow the following things:

- Download a Boost release.

- Download and install Boost.Jam, a build tool.

- Build Boost, such as by typing

  bjam -sPYTHON_ROOT=/usr -sPYTHON_VERSION=2.4 -sBUILD="release <runtime-link>dynamic <threading>multi"

  (You may have to adapt PYTHON_ROOT and PYTHON_VERSION depending on 
  your system.)

- Check the directory 

  boost/bin/boost/libs/python/build/libboost_python.so/gcc/release/shared-linkable-true/threading-multi

  and find libboost_python*.so. Copy these files to somewhere on your 
  dynamic linker path, for example:

  - /usr/lib
  - a directory on LD_LIBRARY_PATH
  - or something mentioned in /etc/ld.so.conf
  - /usr/local/lib (check that it is in /etc/ld.so.conf!)

  You should also create a symbolic link called "libboost_python.so"
  to the main .so file.

- Run "ldconfig".

Step 2: Installing TagLib
-------

In Debian, it suffices to do "aptitude install libtag1-dev".  The distribution
is preconfigured for this case. You may skip to step 3.

Install TagLib from [1], using the usual 

  configure; make; make install

For details, you may consult the file `INSTALL' in the TagLib distribution.

Step 3: Installing TagPy
-------

If necessary, edit the file `setup.py', namely the section labelled
"USER CUSTOMIZABLE SECTION" to make sure the compiler will find your
installations of Boost and TagLib.

Then, run 

  python setup.py build

After a little wait, TagPy should finish building (if not, try and
go back to tweaking `setup.py', depending on the error message).

Finally, typing

  su -c "python setup.py install"

will complete the installation. 

Congratulations! You are now ready to use TagPy.

Using TagPy
===========

Using TagPy is as simple as this:

>>> import tagpy
>>> f = tagpy.FileRef("la.mp3")
>>> f.tag().artist
u'Andreas'

The test/ directory contains a few more examples. 

In general, TagPy duplicates the TagLib API, with a few notable
exceptions:

- Namespaces (i.e. Python modules) are spelled in lower case.
  For example, "TagLib::Ogg::Vorbis" is now "taglib.ogg.vorbis".

- Enumerations form their own scope and are not part of any
  enclosing class scope, if any.

  For example, the value "TagLib::String::UTF16BE" from the 
  enum "TagLib::String::Type" is now "tagpy.StringType.UTF16BE".

- TagLib::String objects are mapped to and expected as Python
  unicode objects.

- TagLib::ByteVector objects are mapped to regular Python
  string objects.