package Audio::TagLib::Ogg::XiphComment;

use 5.008003;
use strict;
use warnings;

our $VERSION = '1.41';

use Audio::TagLib;

our @ISA = qw(Audio::TagLib::Tag);

# Preloaded methods go here.

1;
__END__
# Below is stub documentation for your module. You'd better edit it!

=head1 NAME

Audio::TagLib::Ogg::XiphComment - Ogg Vorbis comment implementation

=head1 SYNOPSIS

  use Audio::TagLib::Ogg::XiphComment;
  
  my $i = Audio::TagLib::Ogg::XiphComment->new();
  $i->setGenre(Audio::TagLib::String->new("genre"));
  print $i->genre()->toCString(), "\n"; # got "genre"

=head1 DESCRIPTION

This class is an implementation of the Ogg Vorbis comment
specification, to be found in section 5 of the Ogg Vorbis
specification. Because this format is also used in other (currently
unsupported) Xiph.org formats, it has been made part of a generic
implementation rather than being limited to strictly Vorbis.

Vorbis comments are a simple vector of keys and values, called
fields. Multiple values for a given key are supported.

see I<fieldListMap()>

=over

=item I<new()>

Constructs an empty Vorbis comment.

=item I<new(L<ByteVector|Audio::TagLib::ByteVector> $data)>

Constructs a Vorbis comment from $data.

=item I<DESTROY()>

Destroys this instance of the XiphComment.

=item I<L<String|Audio::TagLib::String> title()>

=item I<L<String|Audio::TagLib::String> artist()>

=item I<L<String|Audio::TagLib::String> album()>

=item I<L<String|Audio::TagLib::String> comment()>

=item I<L<String|Audio::TagLib::String> genre()>

=item I<UV year()>

=item I<UV track()>

=item I<void setTitle(L<String|Audio::TagLib::String> $s)>

=item I<void setArtist(L<String|Audio::TagLib::String> $s)>

=item I<void setAlbum(L<String|Audio::TagLib::String> $s)>

=item I<void setComment(L<String|Audio::TagLib::String> $s)>

=item I<void setYear(UV $i)>

=item I<void setTrack(UV $i)>

=item I<BOOL isEmpty()>

see L<Tag|Audio::TagLib::Tag>

=item I<UV fieldCount()>

Returns the number of fields present in the comment.

=item I<L<FieldListMap|Audio::TagLib::Ogg::FieldListMap> fieldListMap()>

Returns a reference to the map of field lists. Because Xiph comments
support multiple fields with the same key, a pure Map would not
work. As such this is a Map of string lists, keyed on the comment
field name. 

The standard set of Xiph/Vorbis fields (which may or may not be
 contained in any specific comment) is:

qw(TITLE VERSION ALBUM ARTIST PERFORMER COPYRIGHT ORGRAIZATION
   DESCRIPTION GENRE DATE LOCATION CONTACT ISRC)

For a more detailed description of these fields, please see the Ogg
 Vorbis specification, section 5.2.2.1.

B<NOTE> The Ogg Vorbis comment specification does allow these key
 values to be either upper or lower case. However, it is conventional
 for them to be upper case. As such, Audio::TagLib, when parsing a
 Xiph/Vorbis comment, converts all fields to uppercase. When you are
 using this data structure, you will need to specify the field name in
 upper case. 

B<WARNING> You should not modify this data structure directly, instead
 use addField() and removeField().

=item I<L<String|Audio::TagLib::String> vendorID()>

Returns the vendor ID of the Ogg Vorbis encoder. libvorbis 1.0 as the
most common case always returns "Xiph.Org libVorbis I 20020717".

=item I<void addField(L<String|Audio::TagLib::String> $key,
L<String|Audio::TagLib::String> $value, BOOL $replace = TRUE)>

Add the field specified by $key with the data $value. If $replace is
true, then all of the other fields with the same key will be removed
frist. 

If the field value is empty, the field will be removed.

=item I<void removeField(L<String|Audio::TagLib::String> $key,
L<String|Audio::TagLib::String> $value = String::null)>

Remove the field specified by $key with the data $value. If $value is
null, all of the fields with the given key will be removed.

=item I<L<ByteVector|Audio::TagLib::ByteVector> render()>

Renders the comment to a ByteVector suitable for inserting into a
 file. 

=item I<L<ByteVector|Audio::TagLib::ByteVector> render(BOOL $addFramingBit)>

Renders the comment to a ByteVector suitable for inserting into a
file. If $addFramingBit is true the standard Vorbis comment framing
bit will be appended. However some formats (notably FLAC) do not work
with this in place.


=back

=head2 EXPORT

None by default.



=head1 SEE ALSO

L<Audio::TagLib|Audio::TagLib> L<Tag|Audio::TagLib::Tag>

=head1 AUTHOR

Dongxu Ma, E<lt>dongxu@cpan.orgE<gt>

=head1 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.


=cut