Ogg::Vorbis::Header 0.03

Ogg::Vorbis::Header is an object-oriented interface to Ogg Vorbis information and comment fields.

SYNOPSIS

use Ogg::Vorbis::Header;
my $ogg = Ogg::Vorbis::Header->new("song.ogg");
while (my ($k, $v) = each %{$ogg->info}) {
print "$k: $vn";
}
foreach my $com ($ogg->comment_tags) {
print "$com: $_n" foreach $ogg->comment($com);
}
$ogg->add_comments("good", "no", "ok", "yes");
$ogg->delete_comment("ok");
$ogg->write_vorbis;

This module presents an object-oriented interface to Ogg Vorbis files which allows user to view Vorbis info and comments and to modify or add comments.

CONSTRUCTORS

new ($filename)

Partially opens an Ogg Vorbis file to ensure it exists and is actually a Vorbis stream. It then closes the filehandle. It does not fill in the objects data fields. These fields will be automatically filled the first time they are accessed using the objects instance methods. Returns undef if there is a problem opening the file or the file is not valid Ogg Vorbis.

load ([$filename])

Opens an Ogg Vorbis file, reads its information, and then closes the filehandle. Returns undef if there is a problem opening the file or the file is not valid Ogg Vorbis. This is both a constructor and an instance method. The filename is required in constructor context, but should be left out when you call this as an instance method on an object. When called as an instance method, it (re)loads the info and comment data from the file. This can be used to reset the state of the object if write_vorbis hasnt been called. Note that the path parameter is ignored in instance context.

INSTANCE METHODS

These methods may be called on actual Header objects, using the -> operator or indirect objects as you prefer.

info ([$key])

Returns a reference to a hash containing format information about the Vorbis file. Hash fields are: version, channels, rate, bitrate_upper, bitrate_nominal, bitrate_lower, and bitrate_window, length. The bitrate_window value is currently unused by the vorbis codec. You can modify the referenced hash if you want, but I wouldnt suggest it.

The optional key parameter allows you to extract a single value from the internal hash (passed by value, not reference). If the key is invalid, undef is returned.

comment_tags ()

Returns an array holding the key values of each comment field. You can then use these values to access specific fields using comment. This may seem somewhat clunky at first but it will speed up most programs. In addition, it makes it easier to support the Ogg Vorbis comment standard which allows multiple fields with the same key.

comment ($key)

Returns a list of comments given a key. If the key does not exist, returns undef.

add_comments ($key, $value, [$key, $value, ...])

Adds comments with the given keys and values. Takes an array of alternating keys and values as parameters. Keys and values should be valid ascii in the range 0x20 - 0x7D and the key should exclude 0x3D (=). This is a subset of the Vorbis standard which allows this range for the key field and all of utf8 for the value field. This will be fixed in future a release.

If an odd-length array is passed in the routine will fail and return undef. Key and value will be trimmed of characters which do not match the format requirement.

edit_comment ($key, $value, [$num])

Edits a given comment field. The optional num field is used to differentiate between two comments with the same key. If no num is supplied, the first value--as reported by comment--is modified. If the key or num are invalid, nothing is done and undef is returned. If all goes well, the old value is returned.

delete_comment ($key, [$num])

Deletes the comment given by key. The optional num value can be used to specify which comment to delete, given duplicate keys. Leaving num out will result in only the first instance being deleted. Returns undef if key or num are invalid. If all goes well, the value of the deleted comment is returned.

clear_comments ([@keys])

Deletes all of the comments which match keys in the input array or all of the comments in the stream if called with no arguments. Returns undef if any key is invalid, although all keys in the input array up until that key will be cleared. Returns true otherwise.

write_vorbis ()

Write object to its backing file. No comment modifications will be seen in the file until this operation is performed.

path ()

Returns the path/filename of the file the object represents.