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

        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;

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.

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 CWundef if there is a problem opening the file or the file is not valid Ogg Vorbis. Opens an Ogg Vorbis file, reads its information, and then closes the filehandle. Returns CWundef 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.

These methods may be called on actual Header objects, using the -> operator or indirect objects as you prefer. 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, CWundef is returned. Returns an array holding the key values of each comment field. You can then use these values to access specific fields using CWcomment. 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. Returns a list of comments given a key. If the key does not exist, returns CWundef. 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 CWundef. Key and value will be trimmed of characters which do not match the format requirement. 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 valueas reported by CWcomment--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. 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 CWundef if key or num are invalid. If all goes well, the value of the deleted comment is returned. 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 CWundef if any key is invalid, although all keys in the input array up until that key will be cleared. Returns true otherwise. Write object to its backing file. No comment modifications will be seen in the file until this operation is performed. Returns the path/filename of the file the object represents.

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

Dan Pemstein <dan@lcws.org>

Copyright (c) 2003, Dan Pemstein. All Rights Reserved.

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).

Ogg::Vorbis::Decoder, Inline::C, Audio::Ao.