NAME

Audio::TagLib::MPEG::File - An MPEG file class with some useful methods specific to MPEG

SYNOPSIS

  use Audio::TagLib::MPEG::File;
  
  my $i = Audio::TagLib::MPEG::File->new("sample file.mp3");
  print $i->tag()->artist()->toCString(), "\n"; # got artist

DESCRIPTION

This implements the generic Audio::TagLib::File API and additionally provides access to properties that are distinct to MPEG files, notably access to the different ID3 tags.

new(PV $file, BOOL $readProperties = TRUE, PV $propertiesStyle = "Average")

Constructs an MPEG file from $file. If $readProperties is true the file's audio properties will also be read using $propertiesStyle. If false, $propertiesStyle is ignored.

deprecated This constructor will be dropped in favor of the one below in a future version.

new(PV $file, ID3v2::FrameFactory $frameFactory, BOOL $readProperties = TRUE, PV $propertiesStyle = "Average")

Constructs an MPEG file from $file. If $readProperties is true the file's audio properties will also be read using $propertiesStyle. If false, $propertiesStyle is ignored. The frames will be created using $frameFactory.

DESTROY()

Destroys this instance of the File.

Tag tag()

Returns a tag that is the union of the ID3v2 and ID3v1 tags. The ID3v2 tag is given priority in reading the information -- if requested information exists in both the ID3v2 tag and the ID3v1 tag, the information from the ID3v2 tag will be returned.

If you would like more granular control over the content of the tags, with the concession of generality, use the tag-type specific calls.

NOTE As this tag is not implemented as an ID3v2 tag or an ID3v1 tag, but a union of the two this pointer may not be cast to the specific tag types.

see ID3v1Tag()

see ID3v2Tag()

see APETag()

Properties audioProperties()

Returns the MPEG::Properties for this file. If no audio properties were read then this will return undef.

BOOL save()

 Save the file. If at least one tag -- ID3v1 or ID3v2 -- exists this
 will duplicate its content into the other tag. This returns true if
 saving was successful.

If neither exists or if both tags are empty, this will strip the tags from the file.

This is the same as calling save(AllTags);

If you would like more granular control over the content of the tags, with the concession of generality, use paramaterized save call below.

see save(PV $tags)

BOOL save(PV $tags)

Save the file. This will attempt to save all of the tag types that are specified by TagTypes values. The save() method above uses AllTags. This returns true if saving was successful.

This strips all tags not included in the mask, but does not modify them in memory, so later calls to save() which make use of these tags will remain valid. This also strips empty tags.

BOOL save(PV $tags, BOOL $stripOthers)

Save the file. This will attempt to save all of the tag types that are specified by TagTypes values. The save() method above uses AllTags. This returns true if saving was successful.

If $stripOthers is true this strips all tags not included in the mask, but does not modify them in memory, so later calls to save() which make use of these tags will remain valid. This also strips empty tags.

ID3v2::Tag ID3v2Tag(BOOL $create = FALSE)

Returns the ID3v2 tag of the file.

If $create is false (the default) this will return undef if there is no valid ID3v2 tag. If $create is true it will create an ID3v2 tag if one does not exist.

NOTE The Tag is STILL owned by the MPEG::File and should not be deleted by the user. It will be deleted when the file (object) is destroyed.

ID3v1::Tag ID3v1Tag(BOOL $create = FALSE)

Returns the ID3v1 tag of the file.

If $create is false (the default) this will return undef if there is no valid ID3v1 tag. If $create is true it will create an ID3v1 tag if one does not exist.

NOTE The Tag is STILL owned by the MPEG::File and should not be deleted by the user. It will be deleted when the file (object) is destroyed.

APE::Tag APETag(BOOL $create = FALSE)

Returns the APE tag of the file.

If $create is false (the default) this will return undef if there is no valid APE tag. If $create is true it will create an APE tag if one does not exist.

NOTE The Tag is STILL owned by the MPEG::File and should not be deleted by the user. It will be deleted when the file (object) is destroyed.

BOOL strip(PV $tags = "AllTags")

This will strip tags that match the TagTypes from the file. By default it strips all tags. It returns true if the tags are successfully stripped.

This is equivalent to strip($tags, TRUE)

NOTE This will also invalidate pointers to the ID3 and APE tags as their memory will be freed.

BOOL strip(PV $tags, BOOL $freeMemory)

This will strip the tags that match the TagTypes from the file. By default it strips all tags. It returns true if the tags are successfully stripped.

If $freeMemory is true the ID3 and APE tags will be deleted and pointers to them will be invalidated.

void setID3v2FrameFactory(ID3v2::FrameFactory $factory)

Set the ID3v2::FrameFactory to something other than the default.

see ID3v2FrameFactory

IV firstFrameOffset()

Returns the position in the file of the first MPEG frame.

IV nextFrameOffset(IV $position)

Returns the position in the file of the next MPEG frame, using the current position as start

IV previousFrameOffset(IV $position)

Returns the position in the file of the previous MPEG frame, using the current position as start

IV lastFrameOffset()

 Returns the position in the file of the last MPEG frame.

%_TagTypes

This set of flags is used for various operations. keys %Audio::TagLib::MPEG::File::_TagTypes lists all available values used in Perl code.

WARNING The values are not allowed to be OR-ed together in Perl.

EXPORT

None by default.

SEE ALSO

Audio::TagLib File

AUTHOR

Dongxu Ma, <dongxu@cpan.org>

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.