NAME

TagLib - a library for reading and editing audio meta data, commonly know as tags.

SYNOPSIS

  use TagLib;
  use warnings;
  use strict;

  my $f      = TagLib::FileRef->new("Latex Solar Beef.mp3");
  my $artist = $f->tag()->artist();
  print $artist->toCString(), "\n"; # got "Frank Zappa"

  $f->tag()->setAlbum(TagLib::String->new("Fillmore East"));
  $f->save();

  my $g      = TagLib::FileRef->new("Free City Rhymes.ogg");
  my $album  = $g->tag()->album();
  print $album->toCString(), "\n";  # got "NYC Ghosts & Flowers"

  $g->tag()->setTrack(1);
  $g->save();

Note that these high level functions work for Ogg, FLAC, MPC and MP3 (or any other formats supported in the future). For this high level API, which is suitable for most applications, the differences between tag and file formats can all be ignored.

DESCRIPTION

Some goals of TagLib: - A clean, high level, C++ API to handling audio meta data. - Support for at least ID3v1, ID3v2 and Ogg Vorbis comments. - A generic, simple API for the most common tagging related functions. - Binary compatibility between minor releases using the standard KDE/Qt techniques for C++ binary compatibility. - Make the tagging framework extensible by library users; i.e. it will be possible for libarary users to implement additional ID3v2 frames, without modifying the TagLib source (through the use of Abstract Factories and such.

Because TagLib desires to be toolkit agnostic, in hope of being widely adopted and the most flexible in licensing TagLib provides many of its own toolkit classes; in fact the only external dependancy that TagLib has, it a semi-sane STL implementation.

Why TagLib ?

 TagLib was written to fill a gap in the Open Source/Free Software
 community. Currently there is a lack in the OSS/FS for a homogenous
 API to the most common music types.

As TagLib will be initially injected into the KDE community, while it has not been linked to any of the KDE or Qt libraries Scott has tried to follow the coding style of those libraries. Again, this is in sharp contrast to id3lib, which basically provides a hybrid C/C++ API and uses a dubious object model.

Scott gets asked rather frequently why he is replacing id3lib (mostly by people that have never worked with id3lib), if you are concerned about this please email him; He can provide his lengthy standard rant. You can also email me if you like. I will talk to him :-)

EXPORT

None by default.

ENUM TYPE MAPPING

All over TagLib in Perl, ALL the enum value is mapped to a specific string. For instace, TagLib::String::UTF8 => "UTF8". Usually there will be a hash you can query all the available values.

NAMESPACE ISSUE

TagLib::Ogg::Vorbis and TagLib::Vorbis are normally the same.

In C/C++, namespace Ogg is controlled by the macro DOXYGEN. When defined, there will be TagLib::Ogg::Vorbis existing. Otherwize, they just import all the symbols from TagLib::Vorbis to TagLib::Ogg::Vorbis.

In Perl, nearly the same. It will make one stash be the alias of another. Refer to TagLib::Ogg::Vorbis::File.pm, for instance.

OTHER STUFF YOU SHOULD KNOW

some methods will often return certain internal structure of an instance, for example, tag() & audioProperties() in all subclasses of AudioProperties. In such case, a READONLY flag is set on for the returned structure to bypass DESTROY().

SEE ALSO

http://developer.kde.org/~wheeler/taglib.html

KNOWN BUGS

Refer to Bugs in the top level of the package

AUTHOR

C/C++ library by Scott Wheeler <wheeler@kde.org> Allan Sandfeld Jenson <kde@carewolf.org> and Ismael Orenstein <orenstein@kde.org>

Perl module by Dongxu Ma <dongxu.ma@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Dongxu Ma

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.