Header(3pm)
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
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).
SEE ALSO
- Ogg::Vorbis::Decoder, Inline::C, Audio::Ao.