NAME

Audio::TagLib::File - A file class with some useful methods for tag manipulation

DESCRIPTION

This class is a basic file class with some methods that are particularly useful for tag editors. It has methods to take advantage of ByteVector and a binary search method for finding patterns in a file.

DESTROY()

Destroys this File instance.

PV name()

Returns the file name in the local file system encoding.

Tag tag() [pure virtual]

Returns this file's tag. This should be reimplemented in the concrete subclasses.

AudioProperties audioProperties() [pure virtual]

Returns this file's audio properties. This should be reimplemented in the concrete subclasses. If no audio properties were read then this will return undef.

BOOL save() [pure virtual]

Save the file and its associated tags. This should be reimplemented in the concrete subclasses. Returns true if the save succeeds.

ByteVector readBlock(UV $length)

Reads a block of size $length at the current get pointer.

void writeBlock(ByteVector $data)

Attempts to write the block $data at the current get pointer. If the file is currently only opened read only -- i.e. readOnly() returns true -- this attempts to reopen the file in read/write mode.

IV find(ByteVector $pattern, IV $fromOffset = 0, ByteVector $before = ByteVector::null)

Returns the offset in the file that $pattern occurs at or -1 if it can not be found. If $before is set, the search will only continue until the pattern $before is found. This is useful for tagging purposes to search for a tag before the synch frame.

Searching starts at $fromOffset, which defaults to the beginning of the file.

This has the practial limitation that $pattern can not be longer than the buffer size used by readBlock(). Currently this is 1024 bytes.

IV rfind(ByteVector $pattern, IV $fromOffset = 0, ByteVector $before = ByteVector::null)

Returns the offset in the file that $pattern at or -1 if it can not be found. If $before is set, the search will only continue until the pattern $before is found. This is useful for tagging purposes to search for a tag before the synch frame.

Searching starts at $fromOffset and proceeds from the that point to the beginning of the file and defaults to the end of the file.

This has the practial limitation that $pattern can not be longer than the buffer size used by readBlock(). Currently this is 1024 bytes.

void insert(ByteVector $data, UV $start = 0, UV $replace = 0)

Insert $data at position $start in the file overwriting $replace bytes of the original content.

This method is slow since it requires rewriting all of the file after the insertion point.

void removeBlock(UV $start = 0, UV $length = 0)

Removes a block of the file starting a $start and continuing for $length bytes.

This method is slow since it involves rewriting all of the file after the removed portion.

BOOL readOnly()

Returns true if the file is read only (or if the file can not be opened).

BOOL isOpen()

Since the file can currently only be opened as an argument to the constructor (sort-of by design), this returns if that open succeeded.

BOOL isValid()

Returns true if the file is open and readble and valid information for the Tag and / or AudioProperties was found.

void seek(IV $offset, PV $p = "Beginning")

Move the I/O pointer to $offset in the file from position $p. This defaults to seeking from the beginning of the file.

void clear()

Reset the end-of-file and error flags on the file.

IV tell()

Returns the current offset withing the file.

IV length()

Returns the length of the file.

BOOL isReadable(PV $file) [static]

Returns true if $file can be opened for reading. If the file does not exist, this will return false.

BOOL isWritable(PV $file) [static]

Returns true if $file can be opened for writing.

%_Position

Depreciated. See position()

position

Position in the file used for seeking. C<keys
%Audio::TagLib::File::position()> returns a reference to an hash 
that lists all positioning codes.

EXPORT

None by default.

SEE ALSO

Audio::TagLib

AUTHOR

Dongxu Ma, <dongxu@cpan.org>

MAINTAINER

Geoffrey Leach GLEACH@cpan.org

COPYRIGHT AND LICENSE

Copyright (C) 2005-2010 by Dongxu Ma

Copyright (C) 2011 - 2012 Geoffrey Leach

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.