NAME

Ogg::Vorbis::Header - 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: $v\n";
  }
  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;

DESCRIPTION

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 object's data fields. These fields will be automatically filled the first time they are accessed using the object's 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 hasn't 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 wouldn't 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.

REQUIRES

Inline::C, libogg, libvorbis, libogg-dev, libvorbis-dev.

AUTHOR

Dan Pemstein <dan@lcws.org>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license is included with this module (LICENSE.GPL).

A library for editing Ogg Vorbis comments is distributed with this library as unmodified source code (inc/vcedit.h, inc/vcedit.c, inc/i18n.h). This library is Copyright (c) Michael Smith <msmith@labyrinth.net.au>. It is licensed under the GNU Library General Public License (LGPL). A copy of this license is included with this module (inc/LICENSE.LGPL).